agent-sdk-go

Agent SDK for Go

Build durable Go AI agents that pick up right where they left off.

Open-source Go SDK for building durable AI agents. Runs in-process with crash-resilient execution via durable-go with zero setup, or switch to Temporal / Restate for crash-resilient, distributed execution. Every core component is a pluggable interface, so you're never locked in.

📖 Documentation  ·  Quickstart  ·  Examples

Releases follow Semantic Versioning; see the latest release.

Independent community library — not affiliated with Temporal Technologies or Restate.

Features

• LLM providers — OpenAI, Anthropic, Gemini, DeepSeek, Ollama (local) + custom via interfaces.LLMClient
• Tools & MCP — built-in and custom tools; MCP servers over stdio or streamable HTTP
• A2A — expose agents as A2A servers or connect remote A2A agents as tools
• Sub-agents — delegate to specialist agents with independent LLMs, tools, and task queues
• Human-in-the-loop approvals — gate tool calls, MCP invocations, and delegation
• Conversation history — multi-turn sessions via in-memory or Redis backends
• Memory & RAG — long-term scoped memory and retrieval-augmented generation
• Streaming & AG-UI — partial token streaming; AG-UI protocol for frontend integration
• Reasoning — extended thinking on Anthropic, Gemini, DeepSeek, and OpenAI reasoning models
• Token usage — aggregate prompt, completion, and reasoning token counts per run
• Budget control — cap token spend per run; stop execution or require human-in-the-loop approval when the limits are reached
• Hooks & guardrails — middleware at LLM, tool, retrieval, and memory lifecycle points
• Execution config — per-operation timeouts and max attempts via With*ExecutionConfig
• Durable execution — crash-resilient runs on every runtime; reconnect to active runs and resume event streams after a restart
• Distributed execution — with Temporal, decouple client triggers from worker execution across processes; with Restate, scale via registered endpoint deployments
• Observability — OpenTelemetry traces, metrics, and structured logs

Install

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

Go 1.26+. Agents are durable by default, no infrastructure required. Add a Temporal or Restate server only when you want distributed, multi-process execution — see temporal-setup.md and restate-setup.md.

Quick Start

In-process (zero setup):

import (
    "context"
    "fmt"
    "time"

    "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"
)

// errors omitted for brevity
llmClient, _ := openai.NewClient(
    llm.WithAPIKey("sk-..."),
    llm.WithModel("gpt-4o"),
)

a, _ := agent.NewAgent(
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithLLMClient(llmClient),
    // Durable by default (journals to ./agent_data/<agent_name>). To tune the journal or opt
    // out, import "github.com/agenticenv/agent-sdk-go/pkg/agent/runtime/local" and add:
    // local.WithLocalConfig(&local.LocalConfig{
    //     DataDir:      "./agent_data/my-agent", // default: "./agent_data/<agent_name>"
    //     AutoPurgeAge: 24 * time.Hour,           // default: 7 days
    //     Timeout:      2 * time.Minute,          // default: none — bound long-running/stuck runs
    //     Durability:   local.DurabilityOff(),    // or opt out entirely — pure in-memory, no journal
    // }),
)
defer a.Close()

// --- Run ---
run, _ := a.Run(context.Background(), "Reply with a short greeting.", nil)
result, _ := run.Get(context.Background())
fmt.Println(result.Content)

// --- Non-blocking ---
run, _ = a.Run(context.Background(), "Explain durable agents in two short paragraphs.", nil)
select {
case <-run.Done():
    result, _ = run.Get(context.Background())
    fmt.Println(result.Content)
case <-time.After(5 * time.Second):
    fmt.Println("still running, check back later")
}

// --- Stream (AG-UI events: text deltas, tools, approvals, lifecycle, …) ---
stream, _ := a.Stream(context.Background(), "Write a four-line poem about the ocean.", nil)
events, _ := stream.Events(context.Background())
for event := range events {
    switch e := event.(type) {
    case *agent.AgentTextMessageContentEvent:
        fmt.Print(e.Delta)
    case *agent.AgentToolCallStartEvent:
        fmt.Println("\n[tool call]", e.ToolCallName)
    case *agent.AgentCustomEvent:
        // tool / delegation approval (when approval policy requires it)
        if e.Name == string(agent.AgentCustomEventNameToolApproval) {
            if v, err := agent.ParseCustomEventApproval(e); err == nil {
                // replace with real approval logic — this auto-approves for demonstration
                _ = stream.Approve(context.Background(), v.ApprovalToken, agent.ApprovalStatusApproved)
            }
        }
    // also RunFinished, ToolCallResult, …
    }
}

Temporal (distributed execution) — import pkg/agent/runtime/temporal:

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

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

// --- Run ---
run, _ := a.Run(context.Background(), "Reply with a short greeting.", nil)
result, _ := run.Get(context.Background())
fmt.Println(result.Content)

// --- Stream + reconnect ---
stream, _ := a.Stream(context.Background(), "Write a four-line poem about the ocean.", nil)
savedRunID := stream.ID() // persist before consuming events
events, _ := stream.Events(context.Background())
for event := range events {
    // persist event.Offset() before handling — needed for WithOffset on reconnect
    _ = event
}
savedOffset := int64(0)
s, _ := a.GetAgentStream(context.Background(), savedRunID)
ch, _ := s.Events(context.Background(), agent.WithOffset(savedOffset))
for event := range ch {
    _ = event
}

Restate (durable execution) — import pkg/agent/runtime/restate (mutually exclusive with Temporal):

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

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

// Same Run / Stream / GetAgentStream + WithOffset APIs as Temporal

Crashes and process restarts don't have to mean lost work or missed approvals — see durable_agent/local (single process, zero infrastructure), durable_agent/temporal (split worker), and durable_agent/restate (single process). For the stream reconnect protocol (GetAgentStream + WithOffset), see the reconnect example and Durable Execution. Local has no WithOffset(n>0) — only replay from the start, with completed steps coalesced into one message each (step granularity), not the original token-by-token stream.

CLI (agctl)

Download a binary from GitHub Releases, extract it, and put agctl on your PATH.

export AGCTL_LLM_APIKEY=sk-your-key
agctl run --model gpt-4o --prompt "hello"
# or interactive
agctl chat

See the CLI docs for commands, config, and env vars.

Reference Apps

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

Examples

Runnable examples in examples/ — see examples/README.md for setup and run instructions.

Benchmarks

Config-driven benchmark runner — see benchmarks/README.md

Eval Harness

Evaluate agent quality with Promptfoo and DeepEval — locally or in CI. See eval-harness/README.md

Development

See CONTRIBUTING.md for setup, workflow, and guidelines. Project policies: SECURITY.md · CODE_OF_CONDUCT.md

Quick commands (requires Task): task check | task test | task lint | task fmt | task tidy | task test-coverage

Coverage reports (PR and default branch) are on Codecov. Run task test-coverage locally to produce coverage.out and coverage.html.

License

Apache 2.0

Disclaimer

This project is provided "as is" under the Apache License 2.0. When building AI agents that execute real-world actions, ensure appropriate safeguards, validation, and human-in-the-loop approval workflows are in place. You are responsible for compliance, access control, and operational safety in your deployment. For security issues, follow SECURITY.md.