Status Updates

The Inkeep Agent Framework provides intelligent, AI-powered status updates that automatically generate contextual progress messages during agent execution. These updates give users ChatGPT-style feedback about what's happening behind the scenes without exposing internal technical details.

Overview

Status updates are automatically generated summaries that:

Track Progress: Monitor agent operations, tool calls, and task completions
Provide Context: Generate user-friendly descriptions of what's happening
Hide Complexity: Abstract away internal agent names and technical operations
Stream Real-time: Send updates via the same streaming interface as responses

Status updates use your Agent's summarizer model to generate contextual, intelligent progress messages that feel natural to users.

How It Works

The status updater operates through three main components:

1. Agent Session Event Tracking

Every agent operation is tracked as events:

agent_generate: Text generation or structured output
transfer: Agent-to-agent transfers
delegation_sent/returned: Task delegation between agents
tool_call: When a tool is called with arguments
tool_result: When a tool execution completes (success or failure)
error: System-level errors and configuration issues
artifact_saved: Document or data artifacts created

2. Intelligent Triggering

Status updates are triggered by:

Event Count: After N events (tool calls, generations, etc.)
Time Intervals: Every N seconds of processing
Smart Detection: Avoids updates during text streaming

3. AI-Powered Summarization

The summarizer model:

Analyzes recent events and progress
Generates user-friendly status messages
Maintains context across multiple updates
Focuses on user-visible outcomes

Configuration

Configure status updates in your agent:

export const myAgent = agent({
  id: "my-agent",
  defaultSubAgent: myAgent,
  subAgents: () => [myAgent],

  // Model Settings with summarizer
  models: {
    base: { model: "claude-3-5-sonnet-20241022" },
    summarizer: { model: "claude-3-5-sonnet-20241022" }, // Model for status updates
  },

  // Status updates configuration
  statusUpdates: {
    numEvents: 3, // Trigger after 3 events
    timeInSeconds: 15, // Trigger every 15 seconds
    prompt: "Custom prompt for status updates", // Optional
  },
});

Configuration Options

Option	Type	Default	Description
`numEvents`	number	10	Trigger update after N events
`timeInSeconds`	number	30	Trigger update every N seconds
`model`	string	agent default	Override model for summaries
`prompt`	string	undefined	Custom prompt appended to base system prompt (max 2000 chars)
`statusComponents`	array	undefined	Structured status components (advanced)

Basic Example

const searchAgent = subAgent({
  id: "search-agent",
  name: "Search Agent",
  prompt: "Help users search and analyze information.",
  canUse: () => [searchTool],
});

export const searchDemo = agent({
  id: "search-demo",
  defaultSubAgent: searchAgent,
  subAgents: () => [searchAgent],

  models: {
    base: { model: "claude-3-5-sonnet-20241022" },
    summarizer: { model: "claude-3-5-sonnet-20241022" },
  },

  // Enable status updates
  statusUpdates: {
    numEvents: 2, // Update every 2 operations
    timeInSeconds: 10, // Or every 10 seconds
  },
});

User Experience: When a user asks "What's the weather in Paris?", they might see:

"Searching for current weather information..."
"Found weather data, analyzing conditions..."
"Preparing detailed weather report..."

Custom Prompts

You can customize how status updates are generated by providing a custom prompt that gets appended to the base system prompt. Custom prompts are limited to 2000 characters to ensure optimal performance:

export const myAgent = agent({
  id: "my-agent",
  defaultSubAgent: myAgent,
  subAgents: () => [myAgent],
  models: {
    summarizer: { model: "claude-3-5-sonnet-20241022" },
  },
  statusUpdates: {
    numEvents: 3,
    timeInSeconds: 15,
    // Custom prompt is appended to the base system prompt
    prompt: "KEEP ALL STATUS UPDATES SHORT AND CONCISE. Use bullet points and focus only on user-visible progress.",
  },
});

Custom Prompt Examples

Concise Updates:

statusUpdates: {
  prompt: 'Keep responses to 5 words maximum. Use present tense verbs.',
}
// Results in: "Searching documentation", "Processing data", "Generating report"

Detailed Progress:

statusUpdates: {
  prompt: 'Provide specific details about what was found or accomplished. Include relevant numbers or names when available.',
}
// Results in: "Found 12 API endpoints in authentication docs", "Retrieved user profile for john@example.com"

Branded Tone:

statusUpdates: {
  prompt: 'Use a friendly, helpful tone. Start updates with action words like "Discovering", "Exploring", "Analyzing".',
}
// Results in: "Discovering relevant documentation...", "Analyzing search results for best matches"

Default vs Structured Status Updates

Status updates can be generated in two ways:

Default Status Components

When no statusComponents are configured, the system uses built-in default status components that generate structured labels with contextual details:

label: AI-generated user-friendly description (e.g., "Searching documentation for API examples")
details: Optional structured data with context about the operation

The default status components are defined in packages/agents-sdk/src/default-status-schemas.ts:

// Error loading local file from agents-run-api/src/utils/default-status-schemas.ts
// ENOENT: no such file or directory, open '/vercel/agents-run-api/src/utils/default-status-schemas.ts'

Custom Structured Components

For complete control over status format, define custom structured status components using Zod schemas with the statusComponent helper:

import { z } from 'zod';
import { statusComponent } from '@inkeep/agents-sdk';

const toolSummary = statusComponent({
  type: 'tool_summary',
  description: 'Summary of tool calls and their purpose',
  detailsSchema: z.object({
    tool_name: z.string().describe('Name of tool used'),
    purpose: z.string().describe('Why this tool was called'),
    outcome: z.string().describe('What was discovered or accomplished'),
  }),
});

const progressUpdate = statusComponent({
  type: 'progress_update',
  description: 'Progress information with metrics',
  detailsSchema: z.object({
    current_step: z.string(),
    items_processed: z.number().optional(),
    status: z.enum(['in_progress', 'completed', 'pending']),
  }),
});

export const myAgent = agent({
  id: "my-agent",
  defaultSubAgent: myAgent,
  subAgents: () => [myAgent],
  models: {
    summarizer: { model: "claude-3-5-sonnet-20241022" },
  },
  statusUpdates: {
    numEvents: 3,
    timeInSeconds: 15,
    statusComponents: [
      toolSummary.config,
      progressUpdate.config,
    ],
  },
});

The statusComponent helper provides type-safe status component definitions with automatic schema validation. Zod schemas are automatically converted to JSON Schema format at runtime.

Status Component API

The statusComponent function accepts:

Property	Type	Required	Description
`type`	string	Yes	Unique identifier for this status component type
`description`	string	No	Description of when/why this status is used
`detailsSchema`	`z.ZodObject<any>`	No	Zod schema defining the structure of status details

Note: Use .config when passing status components to the agent configuration

Frontend Integration

Status updates arrive as data-summary events with AI-generated labels and contextual details:

// In your message processing
message.parts.forEach((part) => {
  if (part.type === "data-summary") {
    const { type, label, details } = part.data;

    // Display the user-friendly status label
    displayStatusUpdate(label);

    // Handle optional structured details
    if (details) {
      // For default status components: contextual operation details
      // For custom components: your defined schema structure
      displayStructuredDetails(details);
    }

    // The 'type' field indicates the summary category
    console.log(`Status update type: ${type}`);
  }
});

Data Structure Examples

Custom Status Components:

{
  "type": "tool_summary",
  "label": "Search completed successfully",
  "details": {
    "tool_name": "search_knowledge_base",
    "purpose": "Find API authentication documentation",
    "outcome": "Found 5 relevant articles with code examples"
  }
}

Best Practices

Timing Configuration

Quick Operations: Use higher event counts (5-10) to avoid too many updates
Long Operations: Use shorter time intervals (10-15 seconds) for responsiveness
Mixed Workloads: Combine both triggers for balanced updates

Model Selection

Faster Model: Use a faster/cheaper model for status updates to reduce latency
Specialized Model: Use a model optimized for summarization tasks

User Experience

// Good: Descriptive and actionable
"Searching through documentation to find API authentication methods...";
"Found OAuth2 setup prompt, now checking for code examples...";

// Avoid: Too technical or vague
"Agent thinking...";
"Processing data-operation with tool_invocation type...";

Troubleshooting

Updates Not Appearing

Check that:

Status updates are configured in your Agent
The summarizer model is specified
Events are being triggered (tool calls, generations)
The session hasn't ended prematurely

Too Many/Few Updates

Adjust thresholds:

statusUpdates: {
  numEvents: 5,        // Increase for fewer updates
  timeInSeconds: 20,   // Increase for less frequent updates
}

Poor Update Quality

Improve with custom prompts:

statusUpdates: {
  numEvents: 3,
  timeInSeconds: 15,
  prompt: `Generate a brief, user-friendly status update that explains what has been accomplished and what is currently happening. Focus on user-visible progress, not internal operations. Be specific about findings, not just actions.`
}

Status updates are automatically paused during text streaming to avoid interrupting the response flow.

Performance Considerations

Status updates use additional model calls - consider costs for high-volume applications
Updates are generated asynchronously and won't block main agent operations

Status Updates

On this page