Event Types

The SDK emits structured events throughout the lifecycle of an agent run. Each event is stored in Postgres and displayed in the run detail view.

Event schema

Every event sent to POST /api/ingest uses this structure:

{
  "event_type": "step",
  "sdk_run_id": "run_a1b2c3",
  "payload": { ... },
  "occurred_at": "2026-04-02T10:00:00Z"
}

Field	Type	Description
`event_type`	`string`	One of the 7 types below
`sdk_run_id`	`string`	Unique run identifier
`payload`	`object`	Event-specific data
`occurred_at`	`string`	ISO-8601 timestamp (optional)

Lifecycle events

`run_start`

Emitted when a graph invocation begins.

{
  "event_type": "run_start",
  "sdk_run_id": "run_a1b2c3",
  "agent_name": "research-agent",
  "payload": {
    "framework": "langgraph",
    "input": { "query": "What is the weather in Zurich?" }
  }
}

`run_end`

Emitted when the graph completes successfully.

{
  "event_type": "run_end",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "output": { "answer": "It is 12°C and cloudy." },
    "prompt_tokens": 150,
    "completion_tokens": 45,
    "total_tokens": 195,
    "cost_usd": 0.0023,
    "model": "gpt-4"
  }
}

`error`

Emitted when an unhandled exception terminates the run.

{
  "event_type": "error",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "error_type": "ValueError",
    "error_message": "API rate limit exceeded",
    "traceback": "Traceback (most recent call last):\n  ..."
  }
}

Node events

`step`

Emitted for each node execution (start and end).

{
  "event_type": "step",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "node_name": "search_web",
    "phase": "end",
    "duration_ms": 890,
    "output": { "results": ["..."] }
  }
}

Tool events

`tool_call`

Emitted for each tool invocation (start and end).

{
  "event_type": "tool_call",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "tool_name": "web_search",
    "phase": "end",
    "input_preview": "Zurich weather today",
    "output_preview": "12°C, cloudy in Zurich",
    "duration_ms": 740
  }
}

Tool input and output are truncated to 500 characters in the preview fields.

Human-in-the-Loop events

`human_input_requested`

Emitted when the agent is waiting for human input.

{
  "event_type": "human_input_requested",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "question": "Should we deploy to production?",
    "context": { "target": "prod", "changes": 5 },
    "channel": "slack"
  }
}

`human_input_received`

Emitted when human input has been provided.

{
  "event_type": "human_input_received",
  "sdk_run_id": "run_a1b2c3",
  "payload": {
    "response": "yes",
    "responded_by": "tobias"
  }
}

Summary table

Event type	Value	When	Run status after
`RUN_START`	`run_start`	Graph invocation begins	`running`
`RUN_END`	`run_end`	Graph completes successfully	`success`
`ERROR`	`error`	Exception raised	`error`
`STEP`	`step`	Node starts/ends	unchanged
`TOOL_CALL`	`tool_call`	Tool invoked	unchanged
`HUMAN_INPUT_REQUESTED`	`human_input_requested`	Waiting for human	`waiting_for_input`
`HUMAN_INPUT_RECEIVED`	`human_input_received`	Human responded	`running`