Timeouts and Agent Modes

The problem: An agent run that calls slow tools, waits for human approval, or hits an LLM provider delay can hang indefinitely. For interactive apps, that means a frozen UI. For background pipelines, it means a stuck job that never retries or terminates. The solution: Bound every run with a deadline, choose an agent mode that matches your use case (interactive vs autonomous), and set explicit approval timeouts. When a limit fires the SDK fails the run cleanly with a typed error — no silent hangs.

Run timeouts

Two ways to limit how long a run waits:

Option 1 — Context deadline (per call)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

agentRun, err := a.Run(ctx, "Hello", nil)
if err != nil {
    // handle start error
}
result, err := agentRun.Get(ctx)

Works with Run and Stream. A deadline on the Run / Stream context bounds (and cancels) the agent run. Cancelling Get’s context only unblocks the waiter; cancelling Events’ context only stops that subscriber (Temporal) — use Cancel() on the handle if you need to stop the run without cancelling the Stream ctx.

Option 2 — WithTimeout (agent default)

a, _ := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithTimeout(5 * time.Minute),
)

agentRun, err := a.Run(context.Background(), "Hello", nil)
if err != nil {
    // handle start error
}
result, err := agentRun.Get(context.Background())

Used when the context has no deadline. Agent-only — ignored by NewAgentWorker.

Precedence

Rule	Behavior
`Run` / `Stream` context deadline	Wins over `WithTimeout` — if that ctx expires in 2 min but `WithTimeout` is 10 min, the run ends at 2 min
`WithTimeout`	Used when the `Run` / `Stream` context has no deadline
Default when unset	Follows agent mode — see below

What each context does

Call	Cancelling its `ctx`…
`Run(ctx, …)` / `Stream(ctx, …)`	Stops the agent run
`Get(ctx)`	Only stops waiting for the result — run keeps going
`Events(ctx)`	Only stops this subscriber (Temporal) — run keeps going
`GetAgentRun(ctx, id)` / `GetAgentStream(ctx, id)`	Only bounds the reconnect lookup — run keeps going
`handle.Cancel(ctx)`	Stops the agent run (explicit stop)

How context affects reconnect

Keep Run / Stream on a long-lived ctx (context.Background(), process-lifetime, or context.WithoutCancel(r.Context())) so the Temporal workflow can keep running after HTTP disconnect or API restart.
Bound run length with WithTimeout, not the request ctx.
Use a separate Get / Events ctx to detach the subscriber; call handle.Cancel only when you intend to stop the run.
Cancelling Run / Stream ctx stops the workflow — reconnect cannot resume that run.

See Durable Execution. Common case — pass the same ctx to both Run and Get:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
run, err := a.Run(ctx, prompt, nil)
result, err := run.Get(ctx) // unblocks when the run finishes or the timeout fires

When the ctx fires, driveRun cancels the workflow and Get returns context.DeadlineExceeded. If the run finishes first, Get returns the result. Either way the behaviour is correct and predictable. Advanced — separate wait ctx (reconnect / partial wait): use a different, shorter ctx on Get only when you want to stop waiting and reconnect later while leaving the run alive.

run, err := a.Run(runCtx, prompt, nil) // runCtx owns the run lifetime

// Stop waiting after 30 s but leave the run alive.
waitCtx, cancelWait := context.WithTimeout(context.Background(), 30*time.Second)
defer cancelWait()
result, err := run.Get(waitCtx) // returns context.DeadlineExceeded if still running
// ... reconnect later with GetAgentRun(runID)

Timeouts after reconnect (Temporal)

GetAgentRun / GetAgentStream do not take over the original Run / Stream context.

Cancelling the reconnect ctx does not stop the run.
If the agent has WithTimeout, that limit applies again from the moment you reconnect — it is a fresh timeout, not “time left” from the original start. A run that executed for 4 minutes before a crash gets a full fresh timeout window after reconnect. If you need a hard ceiling across the full run lifetime, call Cancel() on the handle after reconnect instead of relying on WithTimeout.
To stop the run after reconnect, call Cancel() on the handle.

Agent modes

Set with WithAgentMode:

Mode	Default timeout	Worker check (Temporal)	Best for
`AgentModeInteractive` (default)	5 minutes	When `DisableLocalWorker` is set, checks for available workers before submitting — returns a clear error if none are ready	Chat, REPL, web apps where a human is waiting
`AgentModeAutonomous`	60 minutes	Skipped — Temporal queues the workflow until a worker is available	Background jobs, pipelines, long-running tasks

// Interactive (default) — 5 min timeout, worker pre-check
a, _ := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithAgentMode(agent.AgentModeInteractive),
)

// Autonomous — 60 min timeout, no worker pre-check
a, _ := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithAgentMode(agent.AgentModeAutonomous),
)

Agent mode is included in the Temporal agent fingerprint — caller and worker must agree. Interactive worker check: in AgentModeInteractive with DisableLocalWorker, the agent checks for available workers before submitting the workflow. If no worker is ready within the check window, the call returns a clear error immediately — so a user waiting at a chat prompt gets an error rather than a frozen spinner. In AgentModeAutonomous, this check is skipped; Temporal queues the workflow and waits for a worker naturally, which is correct for background jobs. Worker-check and queueing behavior apply to the Temporal runtime only. In-process agents use the same default timeouts but do not perform worker pre-checks.

Approval timeout

WithApprovalTimeout limits how long the user has to approve or reject each tool call. Agent-only.

Setting	Default
`WithApprovalTimeout`	Agent timeout − 30 seconds
Maximum	31 days (`MaxApprovalTimeout`)

Must be less than the agent run timeout. Validation fails at NewAgent if approvalTimeout >= timeout.

a, _ := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithTimeout(10 * time.Minute),
    agent.WithApprovalTimeout(9 * time.Minute),
    agent.WithApprovalHandler(approvalHandler),
)

On approval timeout

Method	Behavior
`Run`	`Get` returns error
`Stream`	Emits `AgentEventTypeRunError`

If you use a long context deadline but omit WithTimeout, approval still expires at ~4.5 minutes (interactive default 5 min − 30s). Set WithTimeout or WithApprovalTimeout explicitly for longer approval windows.

See Approvals.

Max iterations

WithMaxIterations caps LLM rounds per run (default 5). Each round is one LLM call — the model generates either a final answer or tool calls, tools execute, and then the next round begins with those results. Separate from wall-clock timeout — a run can hit max_iterations before any timeout fires. When the limit is reached the run returns normally with FinishReason: max_iterations on AgentRunResult.Telemetry — it is not an error. Use ErrMaxIterationsReached if you need to detect it programmatically. When to increase from the default of 5:

Agent type	Rough starting point
Simple Q&A, one or two tools	5 (default)
Multi-tool research or coding agents	10–15
Agents with sub-agent delegation	add ~2 per expected delegation hop
Long autonomous background pipelines	20+ (combine with `AgentModeAutonomous`)

a, _ := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithMaxIterations(15),
)

If finish_reason: max_iterations appears in telemetry but the task wasn’t complete, increase WithMaxIterations. If you see it frequently on simple tasks, your system prompt or tools may not be guiding the model to terminate — review your prompt before just raising the limit.

Behavior under failure

Failure	`Run` (`Get`)	`Stream`
Context deadline exceeded	On `Run`/`Stream` ctx: cancels the run. On `Get` ctx only: unblocks waiter (run continues)	On `Stream` ctx: cancels run, emits `AgentEventTypeRunError`. On `Events` ctx only: subscriber stops (Temporal; run continues)
Agent timeout fires	`Get` returns `context.DeadlineExceeded`	Emits `AgentEventTypeRunError` with message `"context deadline exceeded"`
Explicit `Cancel()` / Run or Stream ctx cancelled	`Get` returns `context.Canceled`	Emits `AgentEventTypeRunError` with message `"context canceled"`
Approval timeout	`Get` returns error after approval window expires	Emits `AgentEventTypeRunError`
Max iterations reached	`Get` returns result with `FinishReason: max_iterations`	Emits `RUN_FINISHED` with reason set
LLM provider error	`Get` returns the provider error	Emits `AgentEventTypeRunError`

On the Temporal runtime, process crashes and worker restarts do not appear as failures — the workflow resumes from the last recorded step. Only deadline expiry, max iterations, and provider errors surface as run failures. See Temporal runtime.

Practical combinations

Chat UI with Temporal split processes:

a, _ := agent.NewAgent(
    temporal.WithTemporalConfig(cfg),
    agent.WithLLMClient(llmClient),
    agent.DisableLocalWorker(),
    agent.WithAgentMode(agent.AgentModeInteractive),
    agent.WithTimeout(5 * time.Minute),
)

Background pipeline:

a, _ := agent.NewAgent(
    temporal.WithTemporalConfig(cfg),
    agent.WithLLMClient(llmClient),
    agent.WithAgentMode(agent.AgentModeAutonomous),
    agent.WithTimeout(45 * time.Minute),
    agent.WithToolApprovalPolicy(agent.AutoToolApprovalPolicy()),
)

Per-request override:

ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
agentRun, err := a.Run(ctx, quickPrompt, nil) // 30s cap regardless of agent timeout
if err != nil {
    // handle start error
}
result, err := agentRun.Get(ctx)

Execution config

WithTimeout sets a ceiling on the entire run. For finer control — giving the LLM call a different deadline from tool execution, or tuning retry budgets per operation — use With*ExecutionConfig:

a, _ := agent.NewAgent(
    agent.WithTimeout(15 * time.Minute),          // ceiling on entire run

    agent.WithLLMExecutionConfig(agent.ExecutionConfig{
        Timeout:     10 * time.Minute,            // per LLM attempt
        MaxAttempts: 3,
    }),
    agent.WithToolExecutionConfig(agent.ExecutionConfig{
        Timeout:     2 * time.Minute,             // per tool attempt
        MaxAttempts: 1,
    }),
)

See Execution config for the full defaults table and usage guide.

Execution config

Timeout and retry budget per operation

Approvals

Approval handler and AgentStream.Approve flows

Distributed Execution

Interactive worker pre-check with DisableLocalWorker

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Run timeouts

Option 1 — Context deadline (per call)

Option 2 — WithTimeout (agent default)

Precedence

What each context does

How context affects reconnect

Timeouts after reconnect (Temporal)

Agent modes

Approval timeout

On approval timeout

Max iterations

Behavior under failure

Practical combinations

Execution config

Execution config

Approvals

Distributed Execution

​Run timeouts

​Option 1 — Context deadline (per call)

​Option 2 — WithTimeout (agent default)

​Precedence

​What each context does

​How context affects reconnect

​Timeouts after reconnect (Temporal)

​Agent modes

​Approval timeout

​On approval timeout

​Max iterations

​Behavior under failure

​Practical combinations

​Execution config

​Related

Execution config

Approvals

Distributed Execution

Run timeouts

Option 1 — Context deadline (per call)

Option 2 — WithTimeout (agent default)

Precedence

What each context does

How context affects reconnect

Timeouts after reconnect (Temporal)

Agent modes

Approval timeout

On approval timeout

Max iterations

Behavior under failure

Practical combinations

Execution config

Related