In-Process Runtime

The in-process runtime is the default. When you call NewAgent without Temporal or Restate options, the agent loop runs directly inside your Go process — no external orchestration server. It is also durable by default: every LLM call and tool execution is journaled to disk via durable-go, so a process crash can resume instead of losing the in-flight run. Tune the journal or opt out entirely with local.WithLocalConfig — see Durability below.

Enable

Omit all Temporal and Restate configuration:

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
)
if err != nil {
    return err
}
defer a.Close()

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

See Quickstart for a complete example.

How it works

When you call Run or Stream, the SDK executes the full agent loop in your process:

Load conversation history and recalled memory (when configured)
Call the LLM with the merged tool list
Execute tool calls and append results
Repeat until the model finishes or the iteration limit is reached
Return the result or stream events back to your caller

Everything happens in-process — no network hops, no external orchestration.

Capabilities

All SDK capabilities are available on the in-process runtime:

LLM providers (OpenAI, Anthropic, Gemini, custom)
Tools, MCP, A2A, sub-agents
Conversation (in-memory), memory, retrieval (RAG)
Streaming, AG-UI events, hooks
Human-in-the-loop approvals
Budget (WithBudget)
OpenTelemetry observability
Durable execution and reconnect (GetAgentRun / GetAgentStream) — on by default, see Durability

Horizontal worker scaling (NewAgentWorker / multiple registered endpoint deployments) requires Temporal or Restate.

Durability

The in-process runtime journals every LLM call and tool execution to disk via durable-go — no WithLocalConfig call needed. If the process crashes mid-run, restart it (from the same working directory) and reconnect with GetAgentRun or GetAgentStream; already-completed steps are not re-executed. Unlike Temporal/Restate, GetAgentStream’s Events does not accept WithOffset(n) for n > 0 here — reconnect always replays full step history first (see Reconnect fidelity below), then continues live. Same split as Temporal: LocalConfig knobs build a default engine (like WithTemporalConfig); LocalConfig.Engine is a caller-owned engine for security and custom options (like WithTemporalClient).

SDK-built engine (default)

The SDK constructs a durable-go engine and manages its lifecycle. Import pkg/agent/runtime/local to tune the journal or opt out:

import "github.com/agenticenv/agent-sdk-go/pkg/agent/runtime/local"

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
    local.WithLocalConfig(&local.LocalConfig{
        DataDir:      "./agent_data/my-agent", // default: "./agent_data/<agent_name>"
        AutoPurgeAge: 24 * time.Hour,           // default: 7 days; negative disables purge
        Timeout:      2 * time.Minute,          // default: none — set this in production
    }),
)

Field	Default	Notes
`Durability`	`true` (`nil`)	`local.DurabilityOff()` opts out entirely — pure in-memory, pre-durability behavior
`Engine`	none	Leave unset for the SDK-built engine. See Caller-owned Engine
`DataDir`	`./agent_data/<agent_name>`	Exclusive-locked per process — distinct `DataDir` per replica in multi-instance deployments
`AutoPurgeAge`	7 days	Running/Waiting runs (e.g. a pending approval) are never purged regardless of age. Negative disables age-based purge; max-run/max-byte caps still apply if set
`AutoPurgeMaxRuns`	none	Cap on Completed/Failed runs kept on disk. 0 = no count cap
`AutoPurgeMaxBytes`	none	Cap on Completed/Failed run directory size. 0 = no size cap
`Timeout`	none	Unbounded by default — a stuck approval or a cancelled-but-uncancelled run can run forever; set this in production

DataDir is exclusive-locked (in-process + OS flock). Running more than one process/replica against the same DataDir fails the second one’s engine creation. Give each replica a distinct DataDir (e.g. derived from hostname/pod name).

The default journal is plaintext JSON (input.json, step results). The SDK does not invent encryption or step-token keys.

a.Close() cancels in-flight local runs — this is not the same as a crash. Close closes the durable-go engine it owns, which cancels every in-flight run on that engine (not just the calling agent’s) and waits for that cancellation to be journaled before returning. Those runs become terminal (not resumable) — GetAgentStream / GetAgentRun return ErrRunAlreadyCompleted for them afterward, the same as a run that finished normally. On Temporal/Restate, closing the client does not affect server-side runs. Practically: a graceful shutdown handler that calls a.Close() while runs are in flight finalizes them; only an unclean process exit that skips Close (kill -9, OOM, panic before defer runs) leaves a run genuinely resumable via reconnect on the next process start.

Caller-owned Engine (payload codec, journal MAC, step-token key)

Use when you need at-rest encryption, a tamper-evident journal, or approval tokens that survive a process restart. You create and own the durable-go engine — the same pattern as Temporal Cloud / TLS via WithTemporalClient:

import (
    "encoding/hex"
    "os"
    "time"

    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/agent/runtime/local"
    durable "github.com/agenticenv/durable-go"
)

payloadKey, err := hex.DecodeString(os.Getenv("DURABLE_PAYLOAD_KEY"))
if err != nil {
    return err
}
codec, err := durable.NewAESGCMCodec(payloadKey)
if err != nil {
    return err
}
macKey, err := hex.DecodeString(os.Getenv("DURABLE_JOURNAL_MAC_KEY"))
if err != nil {
    return err
}
tokenKey, err := hex.DecodeString(os.Getenv("DURABLE_STEP_TOKEN_KEY"))
if err != nil {
    return err
}

engine, err := durable.NewEngine(ctx, "./agent_data/my-agent",
    durable.WithPayloadCodec(codec),
    durable.WithJournalMACKey(macKey),
    durable.WithStepTokenKey(tokenKey), // required for CompleteStep after a restart
    durable.WithDefaultStepTokenTTL(24*time.Hour),
    durable.WithAutoPurge(7*24*time.Hour),
)
if err != nil {
    return err
}
defer engine.Close()

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
    local.WithLocalConfig(&local.LocalConfig{Engine: engine}),
)

The agent does not close a caller-supplied Engine — you own its lifecycle and must call engine.Close() yourself. DataDir, AutoPurgeAge, Timeout, LockTimeout, and the other knobs are ignored when Engine is set (set them on NewEngine instead). Use the same codec and journal MAC key (or none) every time you open that directory — turning them on later against an existing plaintext tree is not a migrate. Step IDs, errors, and panic traces stay plaintext even with a codec. See durable-go data privacy.

See Durable Engine example for the full pattern.

Limitations

Limitation	Detail
Reconnect fidelity	No `WithOffset(n>0)` — `Events` only accepts `fromOffset` 0 (`ErrStreamOffsetNotSupported` otherwise). `GetAgentStream` replays already-completed steps as one coalesced message each (`step_replayed` custom events), not the original token-by-token stream. Live tokens resume once reconnect reaches the in-flight step. Temporal/Restate support `WithOffset` and replay the original AG-UI events instead
Single process	No horizontal worker scaling
In-memory conversation only	Redis works technically, but Temporal split-process deployments require Redis for shared conversation
Split client/worker	Available on Temporal via `DisableLocalWorker` and `NewAgentWorker`

Handles from Run / Stream are same-process only in the sense that AgentRun/AgentStream values themselves don’t survive a restart — but the underlying run does (it’s journaled). Reconnect via GetAgentRun / GetAgentStream + the saved runID, the same public API used on Temporal/Restate. See Durable Execution.

Error handling

On in-process, errors are returned directly to the caller:

Run

run, err := a.Run(ctx, prompt, nil)
if err != nil {
    // Start error (context cancelled, config issue)
    // If nil, the run started; check result via Get
}

result, err := run.Get(ctx)
if err != nil {
    // Run error (LLM failure, tool panic, timeout, context cancelled)
    // result may be nil or partially populated
}

Stream

stream, err := a.Stream(ctx, prompt, nil)
if err != nil {
    // Start error
}

events, err := stream.Events(ctx)
if err != nil {
    // Events subscribe error — including ErrStreamOffsetNotSupported
    // when WithOffset(n) is used with n > 0
}

for ev := range events {
    // Channel closes after RUN_FINISHED or RUN_ERROR.
    // Cancelling Stream's ctx cancels the run (terminal event still delivered).
}

Any panic inside a tool call is caught and returned as a RUN_ERROR event / error result, with the panic message included. The run does not propagate the panic to your caller.

When to use

Scenario	In-process fit
Local development and unit testing	Ideal (`local.DurabilityOff()` to skip journal files in tests)
CI pipelines and integration tests	Ideal (same)
Simple API or script with short runs	Good
Production chat, single process, crash recovery required	Good — this is the default, no extra runtime needed
Multi-process or horizontally scaled execution	Use Temporal (`NewAgentWorker`) or Restate (multiple endpoint deployments)
Reconnect needs token-level fidelity, not coalesced steps	Use Temporal or Restate

Switch to a distributed runtime

Import a distributed runtime package and add its config option — no other code changes. (Crash recovery alone is not a reason to switch — in-process already has it; do this for horizontal scale, a client/worker split, or token-level reconnect fidelity.) 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."),
)

Restate:

a, err := agent.NewAgent(
    restate.WithRestateConfig(&restate.RestateConfig{
        Ingress:  restate.IngressConfig{URL: "http://localhost:8080"},
        Endpoint: restate.EndpointConfig{ListenAddress: ":9080", AdminURL: "http://localhost:9070"},
    }),
    agent.WithLLMClient(llmClient),
    agent.WithSystemPrompt("You are a helpful assistant."),
)

A running Temporal or Restate server is required. See Temporal or Restate.

Examples

Simple Agent

Minimal in-process agent with Run()

Stream

Streaming tokens and tool events in-process

Durable Agent (Local)

Zero-infrastructure crash/reconnect lab — kill and restart the process

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Enable

How it works

Capabilities

Durability

SDK-built engine (default)

Caller-owned Engine (payload codec, journal MAC, step-token key)

Limitations

Error handling

Run

Stream

When to use

Switch to a distributed runtime

Examples

Simple Agent

Stream

Durable Agent (Local)

​Enable

​How it works

​Capabilities

​Durability

​SDK-built engine (default)

​Caller-owned Engine (payload codec, journal MAC, step-token key)

​Limitations

​Error handling

​Run

​Stream

​When to use

​Switch to a distributed runtime

​Examples

Simple Agent

Stream

Durable Agent (Local)

Enable

How it works

Capabilities

Durability

SDK-built engine (default)

Caller-owned Engine (payload codec, journal MAC, step-token key)

Limitations

Error handling

Run

Stream

When to use

Switch to a distributed runtime

Examples