Agent SDK for Go

Build production-grade AI agents in Go — extensible and pluggable by design, backed by Temporal for durable, crash-resilient execution, or run in-process with zero setup. See Capabilities for the full feature set.

Versioning: Semantic versioning; published lines are git tags (e.g. v0.1.2). See the latest release — the README does not pin a patch number so it stays accurate after each tag.

Note: Independent community library — not affiliated with Temporal Technologies.

Table of Contents

• Overview
• Capabilities
• Reference apps
• Runtimes
• Temporal
• In-Process
• Getting Started
• Prerequisites
• Create an agent and run
• Temporal connection
• LLM providers
• Stream events
• Token usage
• Tools
• Conversation
• Memory
• Retrieval (RAG)
• MCP
• A2A
• Sub-agents
• Managing Capabilities at Runtime
• Approvals
• Hooks
• Timeouts and deadlines
• Custom tools
• Response format
• Reasoning / extended thinking
• Multiple agents
• Agent and worker in separate processes
• AG-UI Protocol
• Telemetry
• Observability
• Wire OTLP
• Bring your own tracer / metrics
• Traces
• Metrics
• Logs
• Configuration
• Development
• Code Coverage
• Setup and run examples
• Benchmarks
• Eval Harness
• Production Readiness Checklist
• Disclaimer

Overview

agent-sdk-go is a Go SDK for production AI agents — tools, MCP, A2A, human-in-the-loop approvals, and multi-agent delegation.

Every agent run on the Temporal runtime is a durable workflow: it survives process crashes and deploys, supports horizontal scaling, and is observable as a real service operation. This is the recommended runtime for production workloads where run durability matters. A running Temporal server is required.

The in-process runtime runs the agent loop directly in your process with no external dependencies — ideal for development, testing, and deployments where Temporal is not available. It has full feature parity: tools, MCP, A2A, sub-agents, streaming, AG-UI, approvals, conversation, and observability.

pkg/agent exposes three entry points — Run, Stream, and RunAsync. Add WithTemporalConfig or WithTemporalClient for the Temporal runtime; omit it for in-process. See Getting Started or Runtimes.

Capabilities

• LLM providers — OpenAI, Anthropic, and Gemini out of the box; bring your own via interfaces.LLMClient.
• Tools — Register built-in or custom tools via interfaces.Tool; optional parallel vs sequential execution for multiple tool calls in one LLM round (WithAgentToolExecutionMode).
• Human-in-the-loop — Approval gates on tool calls and delegation across Run, RunAsync, and Stream.
• Conversation — Persist multi-turn message history via WithConversation and conversation.Config; in-memory store for in-process; Redis for remote workers. Bring your own backend via interfaces.Conversation.
• Sub-agents — Delegate to specialist agents via WithSubAgents; recursive delegation with depth limiting; all sub-agent events fan in to the parent stream on both runtimes.
• MCP — Extend agent capabilities by connecting any MCP server as a tool source via WithMCPConfig or WithMCPClients.
• A2A — Connect remote Agent-to-Agent agents as tool providers via WithA2AConfig or WithA2AClients; or expose the agent itself as an A2A server via WithA2ADefaultServer / WithA2AServer and RunA2A.
• Memory — Store and recall scoped facts and preferences across runs via WithMemory and memory.Config; built-in Weaviate and pgvector backends; same config on agent and worker for remote deployments.
• Retrieval (RAG) — Ground agent responses in external knowledge bases via a pluggable Retriever interface with built-in Weaviate and pgvector support; extend with your own implementation.
• Streaming — Partial tokens and events via Stream and WithStream.
• AG-UI — Stream events conform to the AG-UI protocol; agents work out of the box with any AG-UI compatible frontend such as CopilotKit.
• Reasoning — Extended thinking / chain-of-thought where supported (Anthropic, Gemini).
• Token usage — Track input, output, and reasoning token counts per run.
• Observability — OpenTelemetry traces, metrics, and structured logs; export to any OTLP-compatible backend.
• Durable execution ★ — Runs survive process crashes and restarts; Temporal workflow history ensures no step is lost.
• Scale ★ — Add Temporal workers to scale agent execution horizontally; split agent and worker across separate processes.

★ Temporal runtime only.

Reference apps

Demo applications that use agent-sdk-go end-to-end:

• Agent Chat — Web chat demo with durable conversations; a good reference for wiring the SDK into an HTTP-backed app.

Runtimes

Temporal

Temporal powers agents through three moving parts: a Temporal client that launches agent workflows, workers (typically NewAgentWorker) that poll task queues and execute workflow and activity code, and workflow history that makes each run durable. Workers are stateless — they replay and advance history, not hold state themselves.

• Workflows — Durable, replay-safe orchestration: the agent “loop” (model rounds, tool routing, when to delegate). Workflow code must stay deterministic; long work happens in activities.
• Activities — LLM calls, tool execution (including MCP tool calls), conversation updates, approval steps—side effects and I/O. Retries, timeouts, and failure handling apply here.
• Child workflows — Sub-agent delegation is modeled as child workflows so specialists can run on their own task queues with their own workers.
• Workers & task queues — Processes poll a queue and run scheduled workflow and activity tasks; scale horizontally by adding workers. Each agent / sub-agent typically has its own task queue name.
• Long runs — Very long agent sessions and high-volume event pipelines automatically trigger continue-as-new internally, starting a fresh run under the same workflow ID while preserving all state; retry transient update or delivery failures as usual.

graph TD
    A[Agent] --> WF[Workflow: agent loop]
    W[Agent Worker] --> WF
    WF --> LLM[Activity: LLM call]
    WF --> Appr[Activity: approval]
    WF --> Child[Child Workflow: sub-agent loop]
    WF --> Tool[Activity: tool execution]
    WF --> Mem[Activity: save memory]
    Child --> LLM2[Activity: LLM call]
    Child --> Tool2[Activity: tool execution]
    Child --> Mem2[Activity: save memory]

Details: Temporal connection, Sub-agents, Agent and worker in separate processes.

Durable agents: survive crashes, restarts, and deploys

Because every agent run is a Temporal workflow, the process can crash and restart without losing a single step — tool calls already made are not replayed, approvals already given are not re-requested, and the agent resumes exactly where it left off. DisableLocalWorker and NewAgentWorker let you split the client and execution across OS processes or machines while the cluster holds all state.

examples/durable_agent walks through this split across two terminals, including crash and retry scenarios. Step-by-step exercises: examples/durable_agent/README.md.

Streaming and approvals

Stream events and approval events cross two boundaries: Temporal (durable workflow) and your hosts and subscribers. The guarantees differ on each side. These constraints matter most in interactive, user-facing scenarios — autonomous backend agents are largely unaffected since they do not depend on live event delivery.

• Agent runs are durable. After a worker restart or deploy, the run resumes from recorded progress in Temporal. You do not need a single process alive for the entire run.
• Live stream is not backfilled. Incremental stream traffic — tokens, tool updates — is delivered as produced. If your client was disconnected, you may miss chunks even though the agent completed successfully in Temporal.
• Approvals degrade gracefully. If an approval event cannot be delivered, the run continues rather than hanging — the tool is skipped with a clear message. This is intentional for autonomous backend execution; for interactive scenarios, design your UX so users are not silently blocked.
• Your responsibility. Keep worker processes supervised and restarting on crash, maintain a stable connection to your Temporal cluster, and ensure stream subscribers can reconnect.
• Client reconnection and UX. For interactive apps, if the process serving Stream crashes, the workflow continues in Temporal but your client loses the connection. Once a stream is lost, reconnecting to that specific run is not supported — the recommended approach is to block the user from sending a new prompt until the current one completes, then fetch the final response and display it. This keeps conversation turns sequential and avoids out-of-order state. For autonomous agents, this is a non-issue since the caller waits for completion and the workflow finishes regardless.

In-Process

Runs the agent loop directly in your process — zero setup, zero infrastructure.

When to use: - Development, testing, and prototyping - Deployments where Temporal is not needed - Short-lived runs where crash recovery is not required

All capabilities listed above apply except ★ items. Conversation uses the in-memory store only. If the process crashes, the run is lost — no replay, no remote workers.

Switching to Temporal: add WithTemporalConfig (or WithTemporalClient) to any NewAgent call — no other code changes required.

Getting Started

How to use the SDK—agents, LLMs, Temporal connection, examples.

Prerequisites

Go 1.26+ (see go.mod) and credentials for your LLM provider are always required.

• In-process runtime (default): no additional setup — just go get and an LLM API key.
• Temporal runtime: a running Temporal server is required. See Temporal setup.

Module: github.com/agenticenv/agent-sdk-go

go get github.com/agenticenv/agent-sdk-go@latest

Create an agent and run

Local runtime (no Temporal required):

import (
    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/llm"
    "github.com/agenticenv/agent-sdk-go/pkg/llm/openai"
)

llmClient, _ := openai.NewClient(
    llm.WithAPIKey("sk-..."),
    llm.WithModel("gpt-4o"),
)

a, _ := agent.NewAgent(
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithLLMClient(llmClient),
)
defer a.Close()

result, err := a.Run(ctx, "Hello", nil)
// result.Content, result.AgentName, result.Model

Temporal runtime (durable execution):

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

result, err := a.Run(ctx, "Hello", nil)

examples/simple_agent

Temporal connection

Provide either WithTemporalConfig or WithTemporalClient, not both.

Option 1 — WithTemporalConfig (simple, local dev):

agent.WithTemporalConfig(&agent.TemporalConfig{
    Host: "localhost", Port: 7233,
    Namespace: "default", TaskQueue: "my-app",
})

Option 2 — WithTemporalClient (TLS, API key auth, Temporal Cloud):

Use when you need mTLS, Temporal Cloud API keys, or other connection options. Create the cli