agent-sdk-go

Agent SDK for Go

AI agents that keep running even when your process doesn't — powered by Temporal.

Open-source Go SDK for building AI agents — run in-process with zero setup, or on Temporal for crash-resilient, distributed execution that survives restarts and deploys. Every core component is a pluggable interface, so nothing is locked in.

📖 Documentation  ·  Quickstart  ·  Examples

Versioning: Semantic versioning; releases are git tags. See the latest release.

Independent community library — not affiliated with Temporal Technologies.

Install

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

Go 1.26+. No infrastructure required for in-process mode. A running Temporal server is required for durable execution.

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),
)
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 (durable execution):

a, _ := agent.NewAgent(
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithLLMClient(llmClient),
    agent.WithTemporalConfig(&agent.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)

// --- 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)
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
}

// --- Reconnect after a process crash ---
// replace with last persisted offset from your storage
savedOffset := int64(0)
s, _ := a.GetAgentStream(context.Background(), savedRunID)
ch, _ := s.Events(context.Background(), agent.WithOffset(savedOffset))
for event := range ch {
    _ = event
}

Crashes and process restarts don't have to mean lost work or missed approvals — the durable agent example shows how a run keeps executing durably even if your process crashes, and how to reconnect to an active run and stream its remaining events once it's back. For the stream reconnect protocol (GetAgentStream + WithOffset), see the reconnect example.

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
• 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 via Temporal; reconnect to active runs and resume event streams after a restart
• Distributed execution — leverage Temporal to decouple client triggers from worker execution, scaling agent workloads horizontally across separate processes or nodes.
• Observability — OpenTelemetry traces, metrics, and structured logs

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/](examples/) — see [examples/README.md](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.