Skip to main content
The handleEvent callback receives events throughout the agent’s execution lifecycle. Use these events to track progress, display UI updates, or log agent activity.

​
Event Types

All events are discriminated by the type field. 
type PrintModeEvent =
  | PrintModeStart
  | PrintModeError
  | PrintModeDownloadStatus
  | PrintModeToolCall
  | PrintModeToolResult
  | PrintModeText
  | PrintModeFinish
  | PrintModeSubagentStart
  | PrintModeSubagentFinish
  | PrintModeReasoningDelta

​
Start Event

Emitted when the agent begins execution.
​
type
'start'
required
Event type identifier
​
agentId
string
Unique identifier for the agent instance
​
messageHistoryLength
number
required
Number of messages in the conversation history
Example: 
{
  type: 'start',
  agentId: 'agent-abc123',
  messageHistoryLength: 5
}

​
Error Event

Emitted when an error occurs during execution.
​
type
'error'
required
Event type identifier
​
message
string
required
Error message describing what went wrong
Example: 
{
  type: 'error',
  message: 'Failed to connect to API: Network timeout'
}

​
Download Status Event

Emitted during model or dependency downloads.
​
type
'download'
required
Event type identifier
​
version
string
required
Version being downloaded
​
status
'complete' | 'failed'
required
Download completion status
Example: 
{
  type: 'download',
  version: '1.2.0',
  status: 'complete'
}

​
Tool Call Event

Emitted when the agent calls a tool.
​
type
'tool_call'
required
Event type identifier
​
toolCallId
string
required
Unique identifier for this tool call
​
toolName
string
required
Name of the tool being called (e.g., write_file, run_terminal_command)
​
input
Record<string, any>
required
Input parameters passed to the tool
​
agentId
string
ID of the agent making the call
​
parentAgentId
string
ID of the parent agent (if this is a subagent)
​
includeToolCall
boolean
Whether to include this tool call in the message history
Example: 
{
  type: 'tool_call',
  toolCallId: 'call_123',
  toolName: 'write_file',
  input: {
    path: 'src/index.ts',
    content: 'console.log("Hello")'
  },
  agentId: 'agent-abc123'
}

​
Tool Result Event

Emitted when a tool call completes.
​
type
'tool_result'
required
Event type identifier
​
toolCallId
string
required
ID matching the original tool call
​
toolName
string
required
Name of the tool that executed
​
output
ToolResultOutput[]
required
Array of output results from the tool execution
​
parentAgentId
string
ID of the parent agent (if this is a subagent)
Example: 
{
  type: 'tool_result',
  toolCallId: 'call_123',
  toolName: 'write_file',
  output: [
    {
      type: 'json',
      value: { success: true, path: 'src/index.ts' }
    }
  ]
}

​
Text Event

Emitted when the agent generates text output.
​
type
'text'
required
Event type identifier
​
text
string
required
Text content generated by the agent
​
agentId
string
ID of the agent generating the text
Example: 
{
  type: 'text',
  text: 'I will now create the file...',
  agentId: 'agent-abc123'
}

​
Finish Event

Emitted when the agent completes execution.
​
type
'finish'
required
Event type identifier
​
agentId
string
ID of the agent that finished
​
totalCost
number
required
Total cost in credits for this execution
Example: 
{
  type: 'finish',
  agentId: 'agent-abc123',
  totalCost: 0.05
}

​
Subagent Start Event

Emitted when a subagent begins execution.
​
type
'subagent_start'
required
Event type identifier
​
agentId
string
required
Unique identifier for the subagent instance
​
agentType
string
required
Type of the subagent (e.g., file_picker, researcher)
​
displayName
string
required
Human-readable name for the subagent
​
onlyChild
boolean
required
Whether this is the only subagent in the current step
​
parentAgentId
string
ID of the parent agent
​
params
Record<string, any>
Parameters passed to the subagent
​
prompt
string
Prompt given to the subagent
Example: 
{
  type: 'subagent_start',
  agentId: 'subagent-xyz',
  agentType: 'file_picker',
  displayName: 'File Picker',
  onlyChild: true,
  parentAgentId: 'agent-abc123',
  prompt: 'Find relevant test files'
}

​
Subagent Finish Event

Emitted when a subagent completes execution.
​
type
'subagent_finish'
required
Event type identifier
​
agentId
string
required
ID of the subagent that finished
​
agentType
string
required
Type of the subagent
​
displayName
string
required
Human-readable name for the subagent
​
onlyChild
boolean
required
Whether this was the only subagent in the step
​
parentAgentId
string
ID of the parent agent
​
params
Record<string, any>
Parameters that were passed to the subagent
​
prompt
string
Prompt that was given to the subagent
Example: 
{
  type: 'subagent_finish',
  agentId: 'subagent-xyz',
  agentType: 'file_picker',
  displayName: 'File Picker',
  onlyChild: true,
  parentAgentId: 'agent-abc123'
}

​
Reasoning Delta Event

Emitted during the agent’s reasoning process (streaming chunks).
​
type
'reasoning_delta'
required
Event type identifier
​
text
string
required
Chunk of reasoning text
​
ancestorRunIds
string[]
required
Array of ancestor agent run IDs
​
runId
string
required
ID of the current agent run
Example: 
{
  type: 'reasoning_delta',
  text: 'I need to check the file first...',
  ancestorRunIds: ['run-parent'],
  runId: 'run-abc123'
}

​
Usage Example

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: 'cb_xxx',
  handleEvent: (event) => {
    switch (event.type) {
      case 'start':
        console.log('Agent started with', event.messageHistoryLength, 'messages')
        break
      
      case 'tool_call':
        console.log('Calling tool:', event.toolName, 'with input:', event.input)
        break
      
      case 'tool_result':
        console.log('Tool result for', event.toolName, ':', event.output)
        break
      
      case 'text':
        process.stdout.write(event.text)
        break
      
      case 'error':
        console.error('Error:', event.message)
        break
      
      case 'finish':
        console.log('Agent finished. Cost:', event.totalCost)
        break
    }
  }
})

const result = await client.run({
  agent: 'base',
  prompt: 'Create a hello world script'
})

​
Tool Result Output

The output field in tool result events contains an array of output objects:
​
type
'json' | 'media'
required
Type of the output content

​
JSON Output

​
value
any
required
JSON value returned by the tool
Example: 
{
  type: 'json',
  value: { success: true, filesWritten: 3 }
}

​
Media Output

​
data
string
required
Base64-encoded media data
​
mediaType
string
required
MIME type of the media (e.g., image/png, application/pdf)
Example: 
{
  type: 'media',
  data: 'iVBORw0KGgoAAAANSUhEUgA...',
  mediaType: 'image/png'
}

Build docs developers (and LLMs) love

Get started for freeTalk to us