Docs contents
Events reference
Events are the real-time signal stream for a run. They appear in the run detail view and feed into alerts and reports.
Emit events via run.emit(type, payload, level) or the built-in helpers. In Python, the helpers are snake_case: emit_llm_request, emit_llm_response, emit_tool_call, emit_tool_return, emit_tool_error.
Event levels
| Level | When to use |
|---|---|
debug | Verbose tracing, internal state |
info | Normal progress (default) |
warn | Something unexpected but recoverable |
error | A failure occurred |
Built-in event types
These types are understood by AgentOS and rendered with dedicated UI in the run detail view. Hosted agents emit the LLM and tool events automatically; for non-hosted agents, use the helpers below.
LLM events
run.emitLLMRequest("claude-sonnet-4-6", "Summarise this document...");
run.emitLLMResponse("claude-sonnet-4-6", "The document covers...", {
inputTokens: 512,
outputTokens: 128,
cacheReadTokens: 2048,
});
| Type | Payload fields |
|---|---|
llm.request | model, prompt, any extras |
llm.response | model, response, input_tokens?, output_tokens?, cache_read_tokens?, cache_creation_tokens? |
Tool events
run.emitToolCall("search_web", { query: "latest AI news" });
run.emitToolReturn("search_web", { results: [...] });
run.emitToolError("search_web", "Timeout after 5s");
| Type | Payload fields |
|---|---|
tool.called | tool, input |
tool.returned | tool, output |
tool.failed | tool, error (emitted at level error) |
Run lifecycle events
AgentOS records these on every run. Don't emit them yourself. The prefix names what ran: an agent's run records agent.run.*, a script's run records the same events as script.run.* (script.run.started, script.run.completed, and so on).
| Type | When |
|---|---|
agent.run.started | The run starts |
agent.run.completed | The run completes |
agent.run.failed | The run fails |
agent.run.cancelled | The run is cancelled |
agent.run.awaiting_approval | A hosted run pauses on an approval-gated tool |
agent.run.awaiting_input | A hosted run pauses to ask a person a question |
agent.run.awaiting_child | A hosted run waits for the child runs it started |
agent.run.resumed | A paused run continues |
A script run also records script.started (its version and tools), a script.log per console.log line, script.retried when the sandbox is retried before any tool call, and script.error (with the line) when it fails. Script runs recorded before scripts had their own lifecycle events carry agent.run.*.
Custom event types
A type is any string of 1 to 128 characters. Dot-separated noun.verb names are a convention, not a requirement.
run.emit("invoice.validated", { invoiceId: "INV-001", amount: 1250.00 });
run.emit("retry.attempted", { attempt: 2, maxAttempts: 3 }, "warn");
run.emit("external_api.failed", { endpoint: "/payments", status: 503 }, "error");
Good naming examples:
document.parsedstep.started/step.completedcache.hit/cache.missemail.sent
The payload must be a JSON object. The SDK stamps each event with occurred_at (when it happened); over raw HTTP it's optional and defaults to when AgentOS receives it. Events can also carry span fields (span_id, parent_span_id, kind, started_at, ended_at, duration_ms) to form a trace tree. See Tracing & spans.
Event batching
The SDK buffers events and sends them in the background. By default it flushes every 500 ms or when 50 events are queued. You don't need to manage this: run.complete(), run.fail(), and run.cancel() always flush before closing the run.
| Option | Default | Purpose |
|---|---|---|
batchInterval | 500 | Milliseconds between flushes |
batchSize | 50 | Max events per request (the server accepts up to 500) |
maxQueueSize | 1000 | Events held per run; when full, the oldest debug and info events are dropped first |
Python takes the same options in snake_case (batch_interval_ms, batch_size, max_queue_size).
Call run.flush() to force a flush mid-run (for example, before a long blocking operation). In serverless functions, call client.flush() (or its alias client.shutdown()) before the function returns, so queued events aren't lost when the runtime freezes.