Configuration

Configure agents by passing functional options to NewAgent. The same options apply to NewAgentWorker when running a separate worker process. Key defaults: in-process runtime (no Temporal or Restate options), 5 max iterations, parallel tool execution, 5-minute timeout on interactive mode. All options can be overridden at construction time; per-run overrides use AgentRunOptions.

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithMaxIterations(10),
    // ... more options
)

A durable runtime connection is optional. Omit Temporal and Restate options to use the in-process runtime; import pkg/agent/runtime/temporal or pkg/agent/runtime/restate and add the matching config option for durable execution. All other options work identically across runtimes.

Core options

Option	Description
`WithName(name)`	Unique identity for this agent (letters, digits, `-`, `_`; max 64 chars). Two agents with the same name are treated as the same logical agent and will collide at runtime — always pick a distinct name per agent
`WithDescription(desc)`	Agent description — used in A2A agent card
`WithSystemPrompt(prompt)`	System message prepended to every LLM call
`WithLLMClient(client)`	LLM client — required. See LLM Providers
`WithLLMSampling(s)`	Temperature, max tokens, top-p/top-k, reasoning. See Reasoning
`WithResponseFormat(rf)`	Text or JSON schema output. See Response Format
`WithLogger(l)`	Custom structured logger
`WithLogLevel(level)`	SDK log level: `debug`, `info`, `warn`, `error`

Runtime options

Option	Description
`temporal.WithTemporalConfig(cfg)`	Simple Temporal connection — host, port, namespace, task queue. Agent manages client lifecycle
`temporal.WithTemporalClient(tc, taskQueue)`	Pre-built Temporal client — use for TLS, API keys, Temporal Cloud. You own the client lifecycle. Mutually exclusive with `WithTemporalConfig`
`restate.WithRestateConfig(cfg)`	Restate ingress + embedded SDK endpoint. Mutually exclusive with Temporal options
`WithAgentMode(mode)`	`AgentModeInteractive` (default, 5 min timeout, worker precheck) or `AgentModeAutonomous` (60 min timeout, skips worker precheck)
`DisableLocalWorker()`	Temporal — agent process does not poll the task queue; pair with `NewAgentWorker`
`WithDisableFingerprintCheck(disable)`	Skip agent config fingerprint check — break-glass option, not for production use

See Runtimes, Temporal runtime, and Restate runtime for connection details.

Provide either Temporal options or restate.WithRestateConfig, not both.

TemporalConfig fields

temporal.WithTemporalConfig(&temporal.TemporalConfig{
    Host:      "localhost",
    Port:      7233,        // default Temporal gRPC port
    Namespace: "default",
    TaskQueue: "my-app",
})

RestateConfig fields

restate.WithRestateConfig(&restate.RestateConfig{
    Ingress: restate.IngressConfig{
        URL:     "http://localhost:8080", // required
        AuthKey: "",                      // optional (Restate Cloud)
    },
    Endpoint: restate.EndpointConfig{
        ListenAddress: ":9080",                 // default
        AdminURL:      "http://localhost:9070", // optional auto-register
        DeploymentURL: "",                      // override when Restate is in Docker
    },
})

Restate embeds the SDK endpoint in NewAgent. When Restate runs in Docker and the agent on the host, set DeploymentURL to something Restate can reach (e.g. http://host.docker.internal:9080). See Restate runtime and restate-setup.md.

Execution options

Option	Description
`WithMaxIterations(n)`	Max LLM rounds per run (default: 5). Each round is one LLM call; tool execution doesn’t count separately. Increase for complex agents, multi-tool sequences, or runs with sub-agent delegation. See Timeouts & Modes
`WithTimeout(d)`	Default run timeout when the context has no deadline
`WithApprovalTimeout(d)`	Max wait per approval — defaults to timeout minus 30s
`WithApprovalHandler(fn)`	Callback for tool and delegation approvals on `Run`
`WithAgentToolExecutionMode(mode)`	`Parallel` (default) or `Sequential` per LLM turn

Context deadlines always take precedence over WithTimeout. See Timeouts & Modes.

Tools and approval

Option	Description
`WithTools(tools...)`	Register tools inline at creation
`WithToolRegistry(reg)`	Attach a tool registry — supports dynamic add/remove after `NewAgent`
`WithToolApprovalPolicy(policy)`	`RequireAllToolApprovalPolicy` (default), `AutoToolApprovalPolicy()`, or custom. See Approvals

Use the same WithAgentToolExecutionMode on NewAgent, NewAgentWorker, and all sub-agents in a deployment.

Features

Option	Guide
`WithConversation(cfg)`	Conversation
`WithMemory(cfg)`	Memory
`WithRetrievers(r...)` + `WithRetrieverMode(mode)`	Retrieval
`WithMCPConfig(servers)` / `WithMCPClients(clients...)`	MCP
`WithA2AConfig(servers)` / `WithA2AClients(clients...)`	A2A client
`WithA2ADefaultServer()` / `WithA2AServer(cfg)`	A2A server
`WithSubAgents(agents...)` + `WithMaxSubAgentDepth(n)`	Sub-agents
`WithHooks(name, hooks)`	Hooks

Observability

Option	Description
`WithObservabilityConfig(cfg)`	Wire OTLP traces, metrics, and logs in one block
`WithTracer(tracer)`	Bring your own `interfaces.Tracer`
`WithMetrics(metrics)`	Bring your own `interfaces.Metrics`
`WithLogs(logs)`	Bring your own OTLP logs exporter

See Tracing and Observability example.

Per-run options

Pass AgentRunOptions as the third argument to Run. For Stream, use AgentStreamOptions (same conversation fields):

opts := &agent.AgentRunOptions{
    ConversationOptions: &agent.ConversationOptions{
        ID: "session-1",
    },
}
agentRun, err := a.Run(ctx, "Hello", opts)
if err != nil {
    // handle start error
}
result, err := agentRun.Get(ctx)

When conversation is enabled, pass the same ID on every call in a session to share history across turns.

Runtime registries

After NewAgent, mutate registered capabilities without restarting. Each run picks up the current registry state:

Accessor	Methods
`a.ToolRegistry()`	`Register(tool)`, `Unregister(name)`
`a.MCPRegistry()`	`Register(name, config)`, `RegisterClient(cl)`, `Unregister(name)`
`a.A2ARegistry()`	`Register(name, config)`, `RegisterClient(cl)`, `Unregister(name)`
`a.SubAgentRegistry()`	`Register(sub)`, `Unregister(name)`

See Dynamic capabilities.

Agent and worker alignment

When splitting client and worker across processes, NewAgent and NewAgentWorker must share identical configuration — the SDK validates this with a fingerprint check at activity entry. See Distributed execution.

Token usage

There is no separate token usage option. Read LLMUsage from AgentRunResult after Run, or from AgentRunFinishedEvent.Result.LLMUsage after Stream.

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Core options

Runtime options

TemporalConfig fields

RestateConfig fields

Execution options

Tools and approval

Features

Observability

Per-run options

Runtime registries

Agent and worker alignment

Token usage

​Core options

​Runtime options

​TemporalConfig fields

​RestateConfig fields

​Execution options

​Tools and approval

​Features

​Observability

​Per-run options

​Runtime registries

​Agent and worker alignment

​Token usage

Core options

Runtime options

TemporalConfig fields

RestateConfig fields

Execution options

Tools and approval

Features

Observability

Per-run options

Runtime registries

Agent and worker alignment

Token usage