# Show HN: Agent-SDK-go – Build crash-resilient AI agents in Go

> Source: <https://github.com/agenticenv/agent-sdk-go>
> Published: 2026-10-02 17:41:45+00:00

**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](https://github.com/agenticenv/durable-go) with zero setup, or switch to [Temporal](https://temporal.io) / [Restate](https://restate.dev) for crash-resilient, distributed execution. Every core component is a pluggable interface, so you're never locked in.

📖 [Documentation](https://docs.agenticenv.ai)  ·  [Quickstart](https://docs.agenticenv.ai/getting-started/quickstart)  ·  [Examples](https://docs.agenticenv.ai/examples/running-examples)

Releases follow [Semantic Versioning](https://semver.org/); see the [latest release](https://github.com/agenticenv/agent-sdk-go/releases/latest).

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

- **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
- **Lifecycle hooks** — middleware at LLM, tool, retrieval, and memory lifecycle points
- **Error control** — fallback LLM after a classified failure, one extra-iteration grant, per-tool circuit breaker
- **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

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

Go 1.26+. Agents are durable by default, no infrastructure required. Add a [Temporal](https://temporal.io) or [Restate](https://restate.dev) server only when you want distributed, multi-process execution — see [temporal-setup.md](https://github.com/agenticenv/agent-sdk-go/blob/main/temporal-setup.md) and [restate-setup.md](https://github.com/agenticenv/agent-sdk-go/blob/main/restate-setup.md).

**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](https://github.com/agenticenv/agent-sdk-go/blob/main/examples/durable_agent/local) (single process, zero infrastructure), [durable_agent/temporal](https://github.com/agenticenv/agent-sdk-go/blob/main/examples/durable_agent/temporal) (split worker), and [durable_agent/restate](https://github.com/agenticenv/agent-sdk-go/blob/main/examples/durable_agent/restate) (single process). For the stream reconnect protocol (`GetAgentStream` + `WithOffset`), see the [reconnect example](https://github.com/agenticenv/agent-sdk-go/blob/main/examples/agent_with_reconnect) and [Durable Execution](https://docs.agenticenv.ai/advanced/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.

Download a binary from [GitHub Releases](https://github.com/agenticenv/agent-sdk-go/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](https://docs.agenticenv.ai/getting-started/cli) for commands, config, and env vars.

- **[Agent Chat](https://github.com/agenticenv/agent-chat)** — web chat demo with durable conversations; reference for wiring the SDK into an HTTP-backed app.

Runnable examples in [examples/](https://github.com/agenticenv/agent-sdk-go/blob/main/examples) — see [examples/README.md](https://github.com/agenticenv/agent-sdk-go/blob/main/examples/README.md) for setup and run instructions.

Config-driven benchmark runner — see [benchmarks/README.md](https://github.com/agenticenv/agent-sdk-go/blob/main/benchmarks/README.md)

Evaluate agent quality with Promptfoo and DeepEval — locally or in CI. See [eval-harness/README.md](https://github.com/agenticenv/agent-sdk-go/blob/main/eval-harness/README.md)

See [CONTRIBUTING.md](https://github.com/agenticenv/agent-sdk-go/blob/main/CONTRIBUTING.md) for setup, workflow, and guidelines.
Project policies: [SECURITY.md](https://github.com/agenticenv/agent-sdk-go/blob/main/SECURITY.md) · [CODE_OF_CONDUCT.md](https://github.com/agenticenv/agent-sdk-go/blob/main/CODE_OF_CONDUCT.md)

Quick commands (requires [Task](https://taskfile.dev)): `task check` | `task test` | `task lint` | `task fmt` | `task tidy` | `task test-coverage`

Coverage reports (PR and default branch) are on **[Codecov](https://app.codecov.io/gh/agenticenv/agent-sdk-go)**. Run `task test-coverage` locally to produce `coverage.out` and `coverage.html`.

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](https://github.com/agenticenv/agent-sdk-go/blob/main/SECURITY.md).