# Agent Sdk Go

> AI agents in Go — Temporal for durable, crash-resilient execution or run in-process with zero setup. OpenAI, Anthropic, Gemini, tools, MCP, A2A, RAG, memory, conversations, AG-UI, streaming, sub-agents & human-in-the-loop.

- **Type:** MCP server
- **Install:** `agentstack add mcp-agenticenv-agent-sdk-go`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agenticenv](https://agentstack.voostack.com/s/agenticenv)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [agenticenv](https://github.com/agenticenv)
- **Source:** https://github.com/agenticenv/agent-sdk-go
- **Website:** https://docs.agenticenv.ai/

## Install

```sh
agentstack add mcp-agenticenv-agent-sdk-go
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent SDK for Go

**Build production-grade AI agents in Go** — extensible and pluggable by design, backed by [Temporal](https://temporal.io) for durable, crash-resilient execution, or run in-process with zero setup. See [Capabilities](#capabilities) for the full feature set.

[](https://github.com/agenticenv/agent-sdk-go/actions)
[](https://github.com/agenticenv/agent-sdk-go/releases)
[](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go)
[](https://goreportcard.com/report/github.com/agenticenv/agent-sdk-go)
[](LICENSE)
[](https://github.com/avelino/awesome-go)

> **Versioning:** [Semantic versioning](https://semver.org/); published lines are **git tags** (e.g. `v0.1.2`). See the **[latest release](https://github.com/agenticenv/agent-sdk-go/releases/latest)** — 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](#overview)
- [Capabilities](#capabilities)
- [Reference apps](#reference-apps)
- [Runtimes](#runtimes)
  - [Temporal](#temporal-runtime)
  - [In-Process](#in-process-runtime)
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Create an agent and run](#create-an-agent-and-run)
  - [Temporal connection](#temporal-connection)
  - [LLM providers](#create-an-llm-client-openai-anthropic-or-gemini)
  - [Stream events](#stream-events-stream)
  - [Token usage](#token-usage-llmusage)
  - [Tools](#tools)
  - [Conversation](#conversation)
  - [Memory](#memory)
  - [Retrieval (RAG)](#retrieval-rag)
  - [MCP](#mcp-model-context-protocol)
  - [A2A](#a2a-agent-to-agent)
  - [Sub-agents](#sub-agents)
  - [Managing Capabilities at Runtime](#managing-capabilities-at-runtime)
  - [Approvals](#approvals)
  - [Hooks](#hooks)
  - [Timeouts and deadlines](#timeouts-and-deadlines)
  - [Custom tools](#custom-tools)
  - [Response format](#response-format)
  - [Reasoning / extended thinking](#reasoning--extended-thinking)
  - [Multiple agents](#multiple-agents)
  - [Agent and worker in separate processes](#agent-and-worker-in-separate-processes)
  - [AG-UI Protocol](#ag-ui-protocol)
- [Telemetry](#telemetry)
- [Observability](#observability)
  - [Wire OTLP](#wire-otlp-traces--metrics--logs-in-one-block)
  - [Bring your own tracer / metrics](#bring-your-own-tracer--metrics)
  - [Traces](#traces-spans)
  - [Metrics](#metrics)
  - [Logs](#logs)
- [Configuration](#configuration)
- [Development](#development)
  - [Code Coverage](#code-coverage)
- [Setup and run examples](#setup-and-run-examples)
- [Benchmarks](#benchmarks)
- [Eval Harness](#eval-harness)
- [Production Readiness Checklist](#production-readiness-checklist)
- [Disclaimer](#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](#getting-started) or [Runtimes](#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](https://github.com/a2aproject/A2A) 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](https://docs.ag-ui.com); agents work out of the box with any AG-UI compatible frontend such as [CopilotKit](https://copilotkit.ai).
- **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](https://github.com/agenticenv/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.

```mermaid
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](#temporal-connection), [Sub-agents](#sub-agents), [Agent and worker in separate processes](#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](examples/durable_agent)** walks through this split across two terminals, including crash and retry scenarios. Step-by-step exercises: **[examples/durable_agent/README.md](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](temporal-setup.md)**.

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

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

### Create an agent and run

**Local runtime** (no Temporal required):

```go
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):

```go
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](examples/simple_agent)

### Temporal connection

Provide **either** `WithTemporalConfig` or `WithTemporalClient`, not both.

**Option 1 — WithTemporalConfig** (simple, local dev):

```go
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 client yourself and pass it. You must also call `WithTaskQueue`. The agent does not close the client; you own its lifecycle.

```go
import "go.temporal.io/sdk/client"

tc, _ := client.Dial(client.Options{
    HostPort:  "namespace-id.tmprl.cloud:7233",
    Namespace: "my-namespace",
    Credentials: client.NewAPIKeyStaticCredentials(apiKey),
    // Or: ConnectionOptions for mTLS, etc.
})
defer tc.Close()

a, _ := agent.NewAgent(
    agent.WithTemporalClient(tc),
    agent.WithTaskQueue("my-app"),
    agent.WithLLMClient(llmClient),
)
defer a.Close()
```

[examples/agent_with_temporal_client](examples/agent_with_temporal_client) demonstrates the full pattern.

### Create an LLM client (OpenAI, Anthropic, or Gemini)

```go
// OpenAI
llmClient, err := openai.NewClient(
    llm.WithAPIKey("sk-..."),
    llm.WithModel("gpt-4o"),
    llm.WithBaseURL("https://api.openai.com/v1"),  // optional
)

// Anthropic
llmClient, err := anthropic.NewClient(
    llm.WithAPIKey("..."),
    llm.WithModel("claude-3-5-sonnet-20241022"),
)

// Gemini
llmClient, err := gemini.NewClient(
    llm.WithAPIKey("..."),  // or GOOGLE_API_KEY
    llm.WithModel("gemini-2.5-flash"),
)
```

### Supported LLMs

| Provider      | Package             | Notes                     |
| ------------- | ------------------- | ------------------------- |
| **OpenAI**    | `pkg/llm/openai`    | GPT-4o, GPT-4o-mini, etc. |
| **Anthropic** | `pkg/llm/anthropic` | Claude models             |
| **Gemini**    | `pkg/llm/gemini`    | gemini-2.5-flash, etc.    |

Other providers: implement `[interfaces.LLMClient](pkg/interfaces/llm.go)` (`Generate`, `GenerateStream`, metadata). Copy patterns from `pkg/llm/`.

### Stream events (Stream)

`Stream` returns a channel of `AgentEvent`. Use `agent.WithStream(true)` for partial tokens as they arrive. For **AG-UI** clients, see [AG-UI Protocol](#ag-ui-protocol); for **Temporal** vs. live delivery, see [Streaming and approvals](#streaming-and-approvals).

Lifecycle events include `**RUN_STARTED`**, `**RUN_FINISHED**`, `**RUN_ERROR**`, and (for some flows) `**STEP_STARTED**` / `**STEP_FINISHED**`. Step events bracket a sub-agent child workflow; see [Sub-agents](#sub-agents).

```go
a, _ := agent.NewAgent(
    agent.WithTemporalConfig(...),
    agent.WithLLMClient(...),
    agent.WithStream(true),
)
defer a.Close()

eventCh, err := a.Stream(ctx, "What's 17 * 23?", nil)
for ev := range eventCh {
    if ev == nil {
        continue
    }
    switch ev.Type() {
    case agent.AgentEventTypeText

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agenticenv](https://github.com/agenticenv)
- **Source:** [agenticenv/agent-sdk-go](https://github.com/agenticenv/agent-sdk-go)
- **License:** Apache-2.0
- **Homepage:** https://docs.agenticenv.ai/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agenticenv-agent-sdk-go
- Seller: https://agentstack.voostack.com/s/agenticenv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.