Temporal Runtime

The Temporal runtime executes agent runs as durable workflows. Tool calls, LLM rounds, and approvals survive process crashes and deploys — Temporal replays workflow history and resumes from the last recorded step. Enable it by importing pkg/agent/runtime/temporal and passing temporal.WithTemporalConfig or temporal.WithTemporalClient to NewAgent. A running Temporal server or Temporal Cloud namespace is required. For the Restate durable backend instead, see Restate runtime.

Prerequisites

Local development — pick one:

Approach	Command
Docker	`docker run --rm -p 7233:7233 -p 8233:8233 temporalio/temporal:latest server start-dev --ip 0.0.0.0`
Temporal CLI	Install via Set up the Temporal CLI, then `temporal server start-dev`

Both expose gRPC at localhost:7233 and a Web UI at http://localhost:8233. Production — use Temporal Cloud or a self-hosted cluster. Connect with WithTemporalClient — see the section below.

Enable

WithTemporalConfig (simple, local dev)

The SDK dials Temporal and manages the client lifecycle:

import (
    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/agent/runtime/temporal"
)

a, err := agent.NewAgent(
    temporal.WithTemporalConfig(&temporal.TemporalConfig{
        Host:      "localhost",
        Port:      7233,
        Namespace: "default",
        TaskQueue: "my-app",
    }),
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
)
if err != nil {
    return err
}
defer a.Close()

Field	Purpose
`Host`	Temporal server hostname
`Port`	gRPC port (default 7233)
`Namespace`	Temporal namespace
`TaskQueue`	Task queue this agent’s worker polls — must be unique per agent type

By default, NewAgent also starts an embedded local worker that polls the task queue in your process.

WithTemporalClient (Temporal Cloud, TLS, custom options)

Use when you need mTLS, Temporal Cloud API keys, or connection options not covered by TemporalConfig. You create and own the Temporal client:

import (
    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/agent/runtime/temporal"
    "go.temporal.io/sdk/client"
)

tc, err := client.Dial(client.Options{
    HostPort:    "namespace-id.tmprl.cloud:7233",
    Namespace:   "my-namespace",
    Credentials: client.NewAPIKeyStaticCredentials(apiKey),
})
if err != nil {
    return err
}
defer tc.Close()

a, err := agent.NewAgent(
    temporal.WithTemporalClient(tc, "my-app"),  // pass taskQueue as second arg
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
)

Provide either WithTemporalConfig or WithTemporalClient, not both. The agent does not close a client passed via WithTemporalClient — you own its lifecycle and must call tc.Close() yourself.

See Temporal Client example for the full pattern.

Architecture

Temporal splits agent execution into three parts:

Component	Role
Temporal client	Your application uses this to start runs via `Run` or `Stream`
Workflow	Replay-safe orchestration — the agent loop (LLM rounds, tool routing, delegation). Must stay deterministic
Activities	Side effects and I/O — LLM calls, tool execution, MCP calls, memory I/O, approval steps. Retries and timeouts apply here
Worker	Polls a task queue and executes workflow and activity code. Scale horizontally by adding workers
Child workflows	Sub-agent delegation runs as child workflows on separate task queues

Workers are stateless — they replay and advance workflow history; Temporal holds all state.

Very long runs automatically trigger continue-as-new internally — starting a fresh workflow under the same workflow ID while preserving state. This is transparent to your application code.

Durable execution

Because every agent run is a Temporal workflow:

Process crashes do not lose progress — completed tool calls are not replayed, given approvals are not re-requested
Deploys are safe — restart workers; the workflow resumes from recorded history
Runs outlive the client process — the workflow continues in Temporal even if your application exits
Close does not terminate workflows — stopping a worker or calling Agent.Close() only shuts down the local worker poll loop and owned client connections; in-flight workflows keep running and any restarted worker picks them up automatically

See Durable Agent (Temporal) for crash and retry scenarios.

Split client and worker

For production, split the agent client and worker into separate processes. Worker process — polls the task queue and executes runs:

w, err := agent.NewAgentWorker(
    temporal.WithTemporalConfig(&temporal.TemporalConfig{
        Host: "localhost", Port: 7233,
        Namespace: "default", TaskQueue: "my-app",
    }),
    agent.WithLLMClient(llmClient),
)
go w.Start(ctx)

Agent process — starts runs, handles approvals and streaming in your UI:

a, err := agent.NewAgent(
    temporal.WithTemporalConfig(&temporal.TemporalConfig{
        Host: "localhost", Port: 7233,
        Namespace: "default", TaskQueue: "my-app",
    }),
    agent.WithLLMClient(llmClient),
    agent.DisableLocalWorker(),
)

Both processes must share identical configuration — task queue, tools, conversation backend (Redis for remote workers), memory, approval policy, and hook groups. See Distributed execution. Streaming and approvals work across processes with no extra configuration — the agent subscribes to the run’s event stream directly through the Temporal client, independent of which process executes the workflow task.

Streaming and approvals

Events are delivered through Temporal Workflow Streams — a durable, ordered event log hosted inside the AgentWorkflow. Every published event is appended to the log with a monotonic offset; subscribers receive the same events in the same order regardless of which process or worker executes the workflow. Workflow Streams delivery model:

Property	Value
Durability	Event log lives in the Temporal workflow; survives worker crashes and restarts
Delivery	Events forwarded to the subscriber process via a long-poll `Subscribe` call through the Temporal client
Terminal events	A terminal `RUN_FINISHED` or `RUN_ERROR` event is always delivered before the channel closes, even on stream connection failures
Offset	Each event carries an `Offset()` accessible via the stream forwarder; use it to resume after disconnect
Reconnect	After a process crash or disconnect: `GetAgentStream` + `WithOffset` for streams, or `GetAgentRun` for non-stream `Run`
Sub-agents	All child workflow events fan into the root workflow’s stream; a single subscriber sees every event

After a disconnect — stream reconnect with GetAgentStream:

// Save runID and offset during normal streaming.
agentStream, err := a.Stream(ctx, prompt, nil)
runID := agentStream.ID()
eventCh, err := agentStream.Events(ctx)
for ev := range eventCh {
    if ob, ok := ev.(interface{ Offset() (int64, bool) }); ok {
        if off, has := ob.Offset(); has {
            saveOffset(runID, off) // persist before processing each event
        }
    }
    handleEvent(ev)
}

// On process restart: reconnect from last saved offset.
savedRunID, savedOffset := loadSavedRun()
agentStream, err = a.GetAgentStream(ctx, savedRunID)
resumeCh, err := agentStream.Events(ctx, agent.WithOffset(savedOffset))

Always persist the runID and offset before processing each event. If your process crashes between reading an event and saving its offset, you will replay only that event on reconnect, never lose progress beyond it.

After a disconnect — run reconnect with GetAgentRun:

// Save runID immediately after Run — before Get / Done.
agentRun, err := a.Run(ctx, prompt, nil)
saveRunID(agentRun.ID())

// On process restart: reconnect and wait for the result.
run, err := a.GetAgentRun(ctx, loadSavedRunID())
if errors.Is(err, agent.ErrRunAlreadyCompleted) {
    // Workflow finished while disconnected — use conversation/memory.
    return
}
result, err := run.Get(ctx) // or <-run.Done() then Get

See Reconnect example for the stream protocol, Durable Execution for run + stream recovery, and Approvals for approval events on stream.

Agent mode

WithAgentMode tells the runtime how to treat the run. AgentModeInteractive (default) is for user-facing apps with short, bounded sessions. AgentModeAutonomous is for background jobs and long-running pipelines. See Timeouts & Modes.

Configuration alignment

Client and worker processes must share identical configuration — task queue, tools, memory, conversation backend, approval policy, and hook groups. The SDK validates this with a fingerprint check at activity entry; a mismatch aborts the run with a clear error. See Distributed execution for the full list and production setup guide.

Sub-agents on Temporal

Sub-agent delegation runs as a child workflow. The child workflow is independently durable and tracked by Temporal. See Sub-agents for configuration and stream fan-in behaviour.

Examples

Durable Agent (Temporal)

Crash recovery and split-process durability

Agent Worker

Client and worker in separate processes

Reconnect

Resume a stream from a saved offset

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Prerequisites

Enable

WithTemporalConfig (simple, local dev)

WithTemporalClient (Temporal Cloud, TLS, custom options)

Architecture

Durable execution

Split client and worker

Streaming and approvals

Agent mode

Configuration alignment

Sub-agents on Temporal

Examples

Durable Agent (Temporal)

Agent Worker

Reconnect

​Prerequisites

​Enable

​WithTemporalConfig (simple, local dev)

​WithTemporalClient (Temporal Cloud, TLS, custom options)

​Architecture

​Durable execution

​Split client and worker

​Streaming and approvals

​Agent mode

​Configuration alignment

​Sub-agents on Temporal

​Examples

Durable Agent (Temporal)

Agent Worker

Reconnect

Prerequisites

Enable

WithTemporalConfig (simple, local dev)

WithTemporalClient (Temporal Cloud, TLS, custom options)

Architecture

Durable execution

Split client and worker

Streaming and approvals

Agent mode

Configuration alignment

Sub-agents on Temporal

Examples