Status Components

The Visual Builder provides powerful tools for configuring status updates across your agent graphs. These features keep users informed during long-running operations with either generic text summaries or structured component data.

Default Status Updates

By default, status updates provide generic text summaries of what's happening:

• "Searching for information about your query..."
• "Found 3 relevant documents, analyzing content..."
• "Preparing detailed response based on findings..."

These are generated automatically by your graph's summarizer model based on recent agent activity.

Custom Status Components

Status components allow you to define structured data formats for your status updates instead of generic text. This enables richer, more interactive status displays in your UI.

Creating Status Components

1. Navigate to your Graph in the Visual Builder
2. Open Graph Settings and find the "Status Updates" section
3. Enable Status Updates by configuring trigger conditions
4. Add Status Components to define structured update formats

Example: Tool Call Status Component

Here's an example of a custom status component that provides structured information about tool executions:

// Tool Call Summary Component
{
  type: 'tool_call_summary',
  description: 'Summary of a tool execution and its results',
  detailsSchema: {
    type: 'object',
    properties: {
      tool_name: {
        type: 'string',
        description: 'Name of the tool that was executed'
      },
      summary: {
        type: 'string',
        description: 'Brief description of what was accomplished'
      },
      duration: {
        type: 'number',
        description: 'Execution time in milliseconds'
      }
    },
    required: ['tool_name', 'summary']
  }
}

With this component, instead of generic text, you get structured data like:

{
  "tool_name": "search_knowledge_base",
  "summary": "Found 5 relevant articles about API authentication",
  "duration": 1250
}

AI-Powered Status Generation

Status updates are generated using your graph's configured summarizer model, which analyzes recent agent activity and creates contextual progress messages.

How It Works

1. Event Tracking: The system monitors all agent operations (tool calls, transfers, generations)
2. Intelligent Triggering: Updates are sent based on event count or time intervals
3. AI Analysis: The summarizer model analyzes recent events and conversation context
4. Output Generation: Creates either generic text summaries or structured component data

Summarizer Model Settings

The summarizer model is configured in your graph's model settings:

// Graph-level model settings
models: {
  base: {
    model: 'anthropic/claude-4-sonnet-20250514' // Primary model
  },
  summarizer: {
    model: 'openai/gpt-4o-mini-2024-07-18', // Dedicated summarizer
    providerOptions: {
      temperature: 0.3, // Lower temperature for consistent summaries
      maxTokens: 1024
    }
  }
}

Visual Builder Configuration

Graph-Level Setup

1. Select your Graph in the Visual Builder

2. Open Model Settings:

   • Set base model for agent conversations
   • Configure summarizer model for status updates
   • Adjust provider options (temperature, tokens)

3. Configure Status Updates:

   • Trigger Events: Number of operations before sending update
   • Time Interval: Seconds between time-based updates
   • Custom Status Updates Prompt: Additional context for the summarizer (max 2000 characters)

Status Updates Prompt

You can provide a custom prompt that gets appended to the base system prompt for status generation. This allows you to:

• Customize the tone and style of status messages
• Add domain-specific context
• Guide the summarizer to focus on particular aspects

statusUpdates: {
  numEvents: 3,
  timeInSeconds: 15,
  prompt: `Focus on user-visible progress and avoid technical details.
Keep messages encouraging and professional.
Always mention what information is being found or processed.`
}

Status Component Designer

Use the visual component designer to create structured status updates:

1. Component Properties: Define the data structure
2. Schema Validation: Ensure consistent output format
3. Preview Mode: Test how components will appear
4. Template Customization: Style the component display

Inheritance and Configuration

Graph-Level Defaults

Status components, summarizer models, and status update prompts are configured at the graph level and apply to all agents in that graph.

Best Practices

Model Selection

• Summarizer Model: Faster, efficient models (GPT-4o-mini, Claude-3-Haiku) work well for status generation
• Consistency: Use the same summarizer across related agents for consistent status updates

Status Component Design

• Specific Schemas: Define precise data structures for reliable output
• Required Fields: Mark essential properties as required
• Descriptive Names: Use clear component IDs and descriptions

Custom Prompts

• Keep it Concise: Status update prompts are limited to 2000 characters
• Be Specific: Guide the model toward the type of information you want highlighted
• User-Focused: Emphasize user-visible progress over technical details

Performance Optimization

• Event Thresholds: Balance responsiveness with API usage (3-5 events typically work well)
• Time Intervals: Adjust based on typical operation duration (10-30 seconds)
• Model Efficiency: Choose cost-effective models for high-frequency status generation

Next Steps

• Configure Data Components for structured agent outputs
• Set up Artifact Components for rich content handling
• Manage Credentials for external tool access