> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticenv.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure NewAgent options — runtime, LLM, streaming, approvals, timeouts and workers

Configure agents by passing functional options to [`NewAgent`](/getting-started/quickstart). The same options apply to [`NewAgentWorker`](/advanced/distributed-execution) 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`](#per-run-options).

```go theme={null}
a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithMaxIterations(10),
    // ... more options
)
```

A Temporal or Restate connection is **optional**. Omit Temporal and Restate options to use the in-process runtime, which is already durable by default (via `pkg/agent/runtime/local`'s durable-go journal, no config needed); import `pkg/agent/runtime/temporal` or `pkg/agent/runtime/restate` and add the matching config option only when you need distributed, horizontally-scaled 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](/getting-started/llm-providers) |
| `WithNamedLLMClients(clients)` | Extra LLM clients by name. See [Error Control](/features/error-control) |
| `WithLLMSampling(s)` | Temperature, max tokens, top-p/top-k, reasoning. See [Reasoning](/features/reasoning) |
| `WithResponseFormat(rf)` | Text or JSON schema output. See [Response Format](/features/response-format) |
| `WithLogger(l)` | Custom structured logger |
| `WithLogLevel(level)` | SDK log level: `debug`, `info`, `warn`, `error` |

## Runtime options

| Option | Description |
| - | - |
| `local.WithLocalConfig(cfg)` | In-process durable-go knobs (`DataDir`, purge, timeout). Omit for defaults. Set `Engine` for payload codec, journal MAC, or a stable step-token key — you own that engine's lifecycle. See [In-Process durability](/runtimes/in-process#durability) |
| `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](/runtimes/overview), [In-Process](/runtimes/in-process), [Temporal runtime](/runtimes/temporal), and [Restate runtime](/runtimes/restate) for connection details.

<Warning>
  Provide **either** Temporal options **or** `restate.WithRestateConfig`, not both.
</Warning>

### LocalConfig fields

Omit `local.WithLocalConfig` for durable-by-default with SDK-built engine defaults. Knobs are the simple path; `Engine` is the production/security path (same idea as `WithTemporalConfig` vs `WithTemporalClient`):

```go theme={null}
local.WithLocalConfig(&local.LocalConfig{
    DataDir:      "./agent_data/my-agent",
    AutoPurgeAge: 24 * time.Hour,
    Timeout:      2 * time.Minute,
})
```

```go theme={null}
engine, err := durable.NewEngine(ctx, dataDir, durable.WithPayloadCodec(codec) /* ... */)
// you own engine.Close()
local.WithLocalConfig(&local.LocalConfig{Engine: engine})
```

Incompatible with Temporal or Restate options — those runtimes do not use LocalRuntime.

### TemporalConfig fields

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

### RestateConfig fields

```go theme={null}
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
    },
})
```

<Note>
  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](/runtimes/restate) and [restate-setup.md](https://github.com/agenticenv/agent-sdk-go/blob/main/restate-setup.md).
</Note>

## 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](/advanced/timeouts-and-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, delegation, and budget approvals on `Run` |
| `WithBudget(cfg)` | Token and cost cap for each run. See [Budget](/features/budget) |
| `WithAgentToolExecutionMode(mode)` | `Parallel` (default) or `Sequential` per LLM turn |

Context deadlines always take precedence over `WithTimeout`. See [Timeouts & Modes](/advanced/timeouts-and-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](/features/approvals) |

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

## Features

| Option | Guide |
| - | - |
| `WithConversation(cfg)` | [Conversation](/features/conversation) |
| `WithMemory(cfg)` | [Memory](/features/memory) |
| `WithRetrievers(r...)` + `WithRetrieverMode(mode)` | [Retrieval](/features/retrieval) |
| `WithMCPConfig(servers)` / `WithMCPClients(clients...)` | [MCP](/features/mcp) |
| `WithA2AConfig(servers)` / `WithA2AClients(clients...)` | [A2A client](/features/a2a) |
| `WithA2ADefaultServer()` / `WithA2AServer(cfg)` | [A2A server](/features/a2a) |
| `WithSubAgents(agents...)` + `WithMaxSubAgentDepth(n)` | [Sub-agents](/features/sub-agents) |
| `WithHooks(name, hooks)` | [Hooks](/features/hooks) |
| `WithErrorControl(cfg)` | [Error Control](/features/error-control) |

## 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](/observability/tracing) and [Observability example](/examples/observability).

## Per-run options

Pass [`AgentRunOptions`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/agent#AgentRunOptions) as the third argument to `Run`. For `Stream`, use [`AgentStreamOptions`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/agent#AgentStreamOptions) (same conversation fields):

```go theme={null}
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](/advanced/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 (including named LLM clients and error-control slots). See [Distributed execution](/advanced/distributed-execution).

## Token usage

There is no separate token usage option. Read [`LLMUsage`](/features/token-usage) from `AgentRunResult` after `Run`, or from `AgentRunFinishedEvent.Result.LLMUsage` after `Stream`.

To **cap** tokens or estimated cost for each run, use [`WithBudget`](/features/budget).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.