Skip to content
Browse documentation
reference

Errors and events

Find capability-owned error and event contracts without confusing SDK results, transport messages and CLI diagnostics.

Look up the owning error contract

There is no universal Framework error envelope. Narrow the result or catch the error defined by the capability you called; do not branch on message text.

service/clientServiceClientRequestError: local validation. ServiceClientResponseError: HTTP/response failure. ServiceClientTransportError: transport, abort or timeout.
runtime/modelModelInvocationError carries code, classification and retryable, with invocation/attempt IDs and available HTTP metadata. Use modelErrorDetails(error) for safe log fields.
model-typesafeTypeSafeError carries code, status, retry delay, classification and correlation IDs. retryable is advice; the client does not retry automatically.
runtime/agentAgentRunResult uses status and, on failure, an AgentRunError. Contract and lifecycle errors can also reject before a Run result exists.
runtime/toolsToolModelVisibleError carries application-authored safe feedback. ToolExecutionUncertainError means an effect needs reconciliation, not blind redispatch.
runtime/workerWorkerErrorInfo is carried in failed result envelopes. Suspension, cancellation and timeout have distinct runtime signals.

Keep event formats separate

DiagnosticRecordStructured server log record: schemaVersion, timestamp, event, level and flat attributes. Delivery is bounded and can lose records.
InferenceLifecycleEventModel routing/attempt lifecycle hook; not the provider's raw wire format or a durable audit store.
Model stream chunksDiscriminated by type. Provisional output is not a validated terminal application result.
TimelineEvent / AgentEventRun-scoped eventId, eventType, emittedAt, attempt and JSON payload; AgentEvent narrows known payloads by eventType.
WorkerEventEnvelopeWorker transport event with Run context; not interchangeable with a stored TimelineEvent.
HTTP/SSE messagesApplication-owned projections with explicit validation, authorization and reconnect rules.

To configure provider logs and correlate errors, see provider diagnostics. Keep raw exception messages, stacks and response bodies out of customer responses.

For durable vocabulary and storage, use Timeline and usage records. For browser delivery, use Agent streaming and recovery. Not every capability emits every event, and seeing an event does not establish a durable commit across stores.

Cancellation is not rollback

A cancelled request or disconnected stream does not prove that remote work stopped. A retryable failure is not permission to repeat a side effect. Reconcile uncertain writes and use application idempotency before retrying. Cancellation and timeouts cannot undo committed effects or guarantee that a provider made no charge.

CLI diagnostics are a separate interface

  • Commands and structured output owns one-shot status, diagnostics, effects, check results and exit codes. MCP search/invocation use their own schemas.
  • CI and troubleshooting owns investigation and redacted handoff evidence. Never expose arbitrary exceptions, provider bodies or script logs as safe user messages.