Skip to main content

RunContext

The RunContext object is available inside tool execute functions, hooks, guardrails, and dynamic instructions. It carries run identity, scoped state, cancellation, and the execution boundary. This page explains selected core contracts; use the generated core reference for exact declarations. Harness types have a separate complete package reference.

Methods

Example: Using RunContext in a tool

Example: Using RunContext in dynamic instructions


ChatMessage

Represents a single message in a conversation.

Content formats

Plain text — most common:
Multi-modal — images, audio, files:
Tool result — response to a tool call:

ContentPart

Multi-modal content is an array of ContentPart objects. Each part has a type discriminant.

TextPart

ImagePart

AudioPart

FilePart


ModelResponse

Returned by ModelProvider.generate(). Contains the full LLM response.

finishReason values


StreamChunk

Yielded by ModelProvider.stream() and agent.stream(). A discriminated union — check the type field.

Example: Processing a stream


TokenUsage

Token consumption breakdown from an LLM call.

RunOutput

The object returned by agent.run().

RunOpts

Per-run options passed to agent.run() or agent.stream(). All fields are optional. See the Agent run guide.

Example

Jev questions on run()


AgentHooks

Lifecycle hooks called during an agent run.

Example


LoopHooks

Per-roundtrip hooks for fine-grained control over the LLM loop. More granular than AgentHooks.

Example: Cost auto-stop


Guardrails

InputGuardrail

OutputGuardrail

GuardrailResult

A discriminated union:

Example


RetryConfig

Configuration for automatic retries on transient LLM API failures. Default retryable errors: HTTP 429 (rate limit), 5xx (server errors), ECONNRESET, ETIMEDOUT, ENOTFOUND, and messages containing “rate limit” or “overloaded”.

ApprovalConfig

Human-in-the-loop approval for tool calls.

SandboxConfig

Run tools in isolated subprocesses with resource limits.

ToolDef

The tool definition interface. Created with defineTool().

EventBus

A mailbox of things that happened. Watch here. Steer with hooks / loopHooks. Full guide: Events. Prefer LIFECYCLE_EVENTS (run.start, tool.call, subagent.complete, …). AgentEventMap only lists events that actually fire — a typo is a type error. Voice and browser events live on the same map but are not in LIFECYCLE_EVENTS.

Example

Common events

Full list: Events.

ReasoningConfig

Enable extended thinking / chain-of-thought for models that support it.
Full mapping: Reasoning.

ProviderOptions

Per-provider request extras. Set on the agent; each field is ignored by providers that do not use it.

ContextCompactorConfig

Automatic context compaction to prevent context window overflow.

ToolResultLimitConfig

Prevent prompt token explosion from large tool results.

UnifiedMemoryConfig

Passed as memory on Agent. storage is required. Everything else is optional. Guide: Memory.

FileMemoryConfig / AgentFileSystemConfig / LoadContextFilesOptions


SubagentSpec

Passed to agent.spawnSubagent(task, spec?, runOpts?).

HandoffConfig

HandoffResult extends RunOutput with handoffChain: string[] and finalAgent: string.

ToolRouterConfig


ReflectionConfig


ArtifactsConfig


SemanticCacheConfig


WebhookConfig


CostTrackerConfig

Construct with new CostTracker({ pricing?, budget? }) and pass as costTracker on the agent.

ToolCallResult

One row in RunOutput.toolCalls.