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 graph'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. GraphSession 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_execution: Tool calls and results
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 graph:

export const graph = agentGraph({
  id: "my-graph",
  defaultAgent: myAgent,
  agents: () => [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	graph 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

import { agent, agentGraph, tool } from "@inkeep/agents-manage-api/builders";

const searchAgent = agent({
  id: "search-agent",
  name: "Search Agent",
  prompt: "Help users search and analyze information.",
  tools: {
    search: tool({
      id: "search",
      name: "Web Search",
      description: "Search for information",
      parameters: { query: "string" },
      execute: async ({ query }) => {
        // Search implementation
        return `Results for: ${query}`;
      },
    }),
  },
});

export const graph = agentGraph({
  id: "search-demo",
  defaultAgent: searchAgent,
  agents: () => [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 graph = agentGraph({
  id: "my-graph",
  defaultAgent: myAgent,
  agents: () => [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"

Advanced: Structured Status Updates

For more control over status format, use structured status components:

Schema Update: The status components schema has been simplified. Use type instead of id and name, and detailsSchema instead of schema. The detailsSchema is now optional.

statusUpdates: {
  numEvents: 3,
  timeInSeconds: 15,
  // Custom prompt also works with structured components
  prompt: 'Focus on actionable insights. Be specific about what was found.',
  statusComponents: [
    {
      type: 'tool_summary',
      description: 'Summary of tool calls and their purpose',
      detailsSchema: {
        type: 'object',
        properties: {
          tool_name: {
            type: 'string',
            description: 'Name of tool used'
          },
          purpose: {
            type: 'string',
            description: 'Why this tool was called'
          },
          outcome: {
            type: 'string',
            description: 'What was discovered or accomplished'
          },
        },
        required: ['tool_name', 'purpose', 'outcome'],
      },
    },
    {
      type: 'progress_update',
      description: 'Current progress and next steps',
      detailsSchema: {
        type: 'object',
        properties: {
          current_task: {
            type: 'string',
            description: 'What is currently being worked on'
          },
          completion_percentage: {
            type: 'number',
            description: 'Estimated completion percentage (0-100)'
          },
          next_steps: {
            type: 'string',
            description: 'What will happen next'
          },
        },
        required: ['current_task'],
      },
    },
  ],
}

Frontend Integration

Status updates arrive as data-operation parts with type: 'status_update':

// In your message processing
message.parts.forEach((part) => {
  if (part.type === "data-operation" && part.data.type === "status_update") {
    const { summary, components } = part.data.ctx;

    // Display the status update
    displayStatusUpdate(summary);

    // Handle structured components if present
    if (components) {
      components.forEach((component) => {
        displayStructuredStatus(component);
      });
    }
  }
});

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

Same Model: Use the same model for agents and status updates for consistency
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 graph
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
The system automatically prevents duplicate updates during concurrent operations

Examples

See working examples in the repository:

examples/status-updates-example.graph.ts - Basic configuration
examples/agent-configurations/basic_fact_agent/ - Structured status updates

Status Updates

On this page