AgentConfig

Configuration for the LLM agent loop. Passed to ctx.useAgent().

Source: @electric-ax/agents-runtime

interface AgentConfig {
  systemPrompt: string
  model: string | Model<any>
  provider?: KnownProvider
  tools: AgentTool[]
  streamFn?: StreamFn
  getApiKey?: (
    provider: string
  ) => Promise<string | undefined> | string | undefined
  onPayload?: SimpleStreamOptions["onPayload"]
  testResponses?: string[] | TestResponseFn
}

Fields

Field	Type	Required	Description
systemPrompt	string	Yes	System prompt sent to the LLM on each step.
model	string | Model<any>	Yes	Model identifier (e.g. "claude-sonnet-4-5-20250929") or a resolved model object.
provider	KnownProvider	No	Provider to use when model is a string. Defaults to "anthropic".
tools	AgentTool[]	Yes	Tools available to the LLM. Spread ctx.electricTools when your runtime host provides runtime-level tools. See AgentTool.
streamFn	StreamFn	No	Optional streaming callback passed to the underlying agent.
getApiKey	(provider) => string | Promise<string> | undefined	No	Optional API-key resolver passed through to the model layer.
onPayload	SimpleStreamOptions["onPayload"]	No	Optional callback for raw streaming payloads from the model layer.
testResponses	string[] | TestResponseFn	No	Mock LLM responses for testing. When set, no real LLM calls are made.

TestResponseFn

type TestResponseFn = (
  message: string,
  bridge: OutboundBridgeHandle
) => Promise<string | undefined>

A function that receives the current trigger message and an outbound bridge, then returns a mock response string. Returning undefined emits no automatic text response.

AgentHandle

Returned by ctx.useAgent(). Also available as ctx.agent.

interface AgentHandle {
  run(input?: string): Promise<AgentRunResult>
}

Method	Return Type	Description
run(input?)	Promise<AgentRunResult>	Execute the agent loop. Runs until the LLM stops or all tool calls complete.

Parameters:

Parameter	Type	Required	Description
input	string	No	Optional user message appended to the conversation before the agent loop starts.

AgentRunResult

interface AgentRunResult {
  result?: unknown
  writes: ChangeEvent[]
  toolCalls: Array<{ name: string; args: unknown; result: unknown }>
  usage: { tokens: number; duration: number }
}

Field	Type	Description
result	unknown	Optional final result from the underlying agent adapter.
writes	ChangeEvent[]	Currently returned as an empty array placeholder.
toolCalls	Array<{ name, args, result }>	Currently returned as an empty array placeholder.
usage	{ tokens: number; duration: number }	Currently returned as { tokens: 0, duration: 0 } until usage aggregation is wired in.