Architecture

This page gives you the mental model: which components exist, how they connect, and what happens during a request. Feature details live in the individual feature pages.

​

Components

Agent — the public handle you create with NewAgent. Holds the configuration and capability registries. Receives your Run/Stream call and hands it to the Runtime. Runtime — executes the agent loop. Three implementations: in-process (default, no infra), Temporal (durable workflows + workers), and Restate (durable invocations + embedded endpoint). All run the same loop; only the execution environment differs. Capabilities — plugged into the Runtime at construction. Tools, MCP servers, and A2A agents form the tool surface the LLM can call. Memory, Conversation, and Retrieval shape the context the LLM receives. Hooks — middleware callbacks that fire before and after LLM calls, tool execution, retrieval, and memory operations. Use them for logging, PII scrubbing, guardrails, and cost tracking without modifying agent logic. See Hooks.

​

Request lifecycle

What happens from the moment your code calls a.Run(ctx, prompt, nil): Each iteration is one LLM round-trip. The loop repeats until the LLM returns a final answer or the iteration limit is reached. On Stream, events are emitted at each step as they happen.

​

Runtimes

Run agents locally for development, or with Temporal or Restate for production-grade durability and fault tolerance. The same agent code runs on all three — the SDK picks the backend based on which options you pass to NewAgent. Add temporal.WithTemporalConfig / temporal.WithTemporalClient (from pkg/agent/runtime/temporal) or restate.WithRestateConfig (from pkg/agent/runtime/restate) to switch. Everything else stays the same.

​

Temporal process topology

With Temporal, client and worker are separate concerns — the client starts workflows, the worker runs the loop: By default NewAgent embeds a local Temporal worker in the same process. For production, split client and worker — see Distributed execution.

​

Restate process topology

With Restate, the agent process embeds the SDK endpoint. Your app submits through ingress; Restate calls back into the endpoint to run the loop: Restate uses an embedded SDK endpoint in NewAgent. See Restate runtime. For Temporal workers, see Distributed Execution.

​

Related