Turn an AgentDeployment artifact into a self-hosted, protocol-native agent service — no agent infrastructure to build.
Agentgo is a generic deployment runtime for local multi-agent graphs. An
AgentDeployment artifact declares the root agent, delegated sub-agents, model
settings, and allowlisted MCP tools. The runtime executes root-to-subagent
delegation as a local ADK graph and serves the result over AG-UI and A2A + Agent
Card.
Applications integrate Agentgo as an external service, so they do not embed Go agent code or protocol plumbing. Calling applications keep ownership of users, business context, durable conversations, and user experience.
flowchart TB
browser["Browser / caller gateway"]
machine["Machine client / remote agent"]
subgraph runtime["agentgo runtime"]
direction TB
agui["AG-UI"]
a2a["A2A server"]
card["Agent Card"]
subgraph agentGraph["Local ADK multi-agent graph"]
root["Root agent"]
subagents["Subagents"]
root -->|"local delegation"| subagents
end
agui -->|"run"| agentGraph
a2a -->|"run"| agentGraph
card --- a2a
agentGraph -->|"LLM API"| provider
agentGraph -->|"MCP"| tools
end
provider["LLM provider"]
tools["MCP tools"]
browser -->|"AG-UI SSE"| agui
machine -->|"A2A JSON-RPC"| a2a
machine -.->|"discover"| card
classDef client fill:#fff7ed,stroke:#ea580c,stroke-width:2px,color:#7c2d12
classDef protocol fill:#eef2ff,stroke:#4f46e5,stroke-width:2px,color:#312e81
classDef core fill:#ecfeff,stroke:#0891b2,stroke-width:2px,color:#164e63
classDef dependency fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d
class browser,machine client
class agui,a2a,card protocol
class agentGraph core
class provider,tools dependency
Building a production agent system from scratch means implementing, testing, and maintaining all of this yourself:
| Concern | What you'd build | What agentgo gives you |
|---|---|---|
| Protocol serving | A2A JSON-RPC server, AG-UI SSE stream, Agent Card discovery | Standard protocol adapters over one shared runtime |
| Agent orchestration | Multi-agent delegation graph, tool routing, model selection | ADK Agent tree from your deployment artifact |
| Tool access | MCP client, tool allowlist, deny-by-default authorization | Server-scoped MCP allowlists; denied unless explicitly listed |
| Security | Bearer auth, OIDC verification, mutual TLS, identity mapping | Built-in, fail-closed, with explicit per-channel trust |
| Structured output | JSON Schema validation, provider-specific wire formats, text extraction | Declare a schema + JSON Pointer; agentgo handles the rest |
| Audit evidence | Immutable execution records with digests and error codes | Append-only audit with hashes, provenance, durations, and error codes; raw prompts and tool/model payloads are not stored |
| Observability | Metrics, tracing, structured logs, health probes | Prometheus, OpenTelemetry, log/slog with stable event names |
agentgo is not a framework you import into your code. It is a runtime you deploy: write the artifact, point it at your LLM and MCP tools, and it serves.
Agentgo is a generic self-hosted runtime for deploying agent services. It is not a mini chat platform and does not try to replace user-facing AI workspaces. The comparison below is an explicit boundary, not a feature backlog:
| Concern | Chat UI platform | agentgo |
|---|---|---|
| Primary input | An application workspace and UI | An AgentDeployment artifact |
| Users and groups | Application-level user management and access control | Caller-owned identity, mapped at runtime boundaries |
| Conversations | Durable application state | Caller-owned; bundled examples are in-memory demos |
| Knowledge and RAG | Often built into the workspace | Caller-owned content and MCP-provided tools |
| Tools | Platform extensions and plugins | External MCP services under explicit allowlists |
| UI | The application | Examples only; production callers own their UX |
Use agentgo when your application needs a self-hosted runtime for protocol serving, agent orchestration, tool authorization, audit evidence, and observability. Use your own application—or a platform like Open WebUI—when you need a full user-facing workspace.
The examples are self-contained agentgo consumers. They demonstrate the public runtime surface without adding application capabilities to Agentgo.
| Example | Purpose | Port |
|---|---|---|
simple-chat |
Smallest browser-to-agent AG-UI path | 8080 |
agentgo-assistant |
Caller-owned embedded page-aware assistant | 8081 |
Both examples require Docker Compose and GNU Make; no local Go or Node.js setup is needed. Provider credentials stay inside agentgo; the browser consumes only public protocols.
git clone https://github.com/ml8s/agentgo.git
cd agentgoThis is the smallest browser-to-agent path. Use it to see:
- one
AgentDeploymentserved over AG-UI; - streaming assistant text through SSE;
- runtime task state mapped to
RunStarted, streaming,RunFinished, and errors; - an in-memory browser conversation with no localStorage or session management.
cd examples/simple-chat
make setup
# Edit .env: set AGENTGO_LLM_API_KEY.
make runOpen http://localhost:8080/.
This demonstrates a caller-owned embedded assistant. Use it to see:
- a floating assistant opening beside normal page content;
- click-to-explain interaction without activating links or buttons;
- only the visible selected page content and explicit browser response language;
- explicit
responseLanguagefrom the browser, shown as Browser language; - follow-up conversation through the same AG-UI endpoint.
cd examples/agentgo-assistant
make setup
# Edit .env: set AGENTGO_LLM_API_KEY.
make runOpen http://localhost:8081/.
For local runtime development with MCP fixtures, run:
cd ../..
cp .env.example .env
# Edit .env: set AGENTGO_LLM_API_KEY and MCP endpoint/token variables.
make dev
curl -sS http://127.0.0.1:8085/readyz | jqCopy dev/agent-deployment/ as a starting point. The artifact declares:
- one or more agents (instruction file, optional output schema, tool allowlist);
- logical MCP servers bound to environment variables;
- delegation edges (
sub_agents) for multi-agent trees.
MCP allowlists use logical tool names. At runtime, ADK namespaces exposed tools
as <server>_<name> so two servers can safely expose the same name; audit
records map those model-facing names back to their logical server.
The unique root agent is the entrypoint. Prompts are external files; plain text is the default. Typed output declares a JSON Schema plus a JSON Pointer to the user-facing string.
AGENTGO_LLM_PROVIDER selects the model implementation. The provider value
determines both the SDK adapter and the structured-output wire mode:
| Provider | Value | Structured output |
|---|---|---|
| OpenAI (and any backend that supports json_schema) | openai |
json_schema (native) |
| Anthropic Claude | anthropic |
native (ADK translates genai.Schema) |
| Google Gemini | gemini |
native (ADK translates genai.Schema) |
| Other OpenAI-compatible (e.g. DeepSeek, Zhipu) | any other value | json_object (compatibility shim) |
The structured-output mode is derived automatically from the provider; no operator override is needed.
For example, DeepSeek exposes an OpenAI-compatible endpoint. Set
AGENTGO_LLM_PROVIDER=openai with
AGENTGO_LLM_BASE_URL=https://api.deepseek.com/v1 when its endpoint and model
support OpenAI JSON Schema; use AGENTGO_LLM_PROVIDER=deepseek for the
OpenAI-compatible json_object fallback. When an Agent has no output schema,
agentgo does not send a structured-output request.
Per-Agent artifact settings (model, temperature, maxOutputTokens) override
the environment defaults. Priority: per-agent artifact > env default > provider default.
| Consumer | Protocol | Endpoint | Purpose |
|---|---|---|---|
| Machine client | A2A JSON-RPC | POST /a2a |
discovery, invocation, streaming |
| Browser / gateway | AG-UI SSE | POST /ag-ui |
chat, tool events, sub-agent lifecycle |
| Machine discovery | A2A Agent Card | GET /.well-known/agent-card.json |
standard capability metadata |
| Tool server | MCP Streamable HTTP | outbound | externally owned tools |
Internal root-to-subagent delegation is local ADK graph execution, not A2A. A2A is reserved for external machine clients and remote agents across a runtime or trust boundary.
Official specifications: A2A, AG-UI, and MCP.
Operational endpoints: /livez, /readyz, /metrics, /debug/pprof
(opt-in via AGENTGO_PPROF_ENABLED=1).
- Deny-by-default tool access — a tool call succeeds only if the tool is
listed in the Agent's server-scoped
tools.allow. - Trusted-header mode — production requires
Authorization: Bearer <AGENTGO_PROTOCOL_TOKEN>; AG-UI additionally requires a gateway-verified user identity header. - OIDC mode — set
AGENTGO_IDENTITY_SOURCE=oidcto verify standard ID tokens on both AG-UI and A2A. - Mutual TLS — optional listener maps identity from client certificates.
- Audit evidence — append-only records with deployment digests, durations, and error codes; raw prompts and tool/model payloads are not stored.
- No direct public exposure — the runtime sits behind your gateway.
See SECURITY.md for the full security policy.
agentgo is not an Agent management control plane. It does not provide Agent CRUD APIs, deployment registries, tenant management, quota enforcement, approval workflows, or a management console.
It is also not a chat platform or mini AI workspace. It does not own product users, durable conversations, chat history, document libraries, RAG pipelines, model catalogs, plugins, calendars, notes, or a user-facing workspace.
caller owns users, products, entitlements, quotas, and durable product
conversations. A domain content repository owns prompts, skills, workflow
policy, and tool semantics; external MCP tool services own MCP tool
implementations.
.env.example is the complete configuration surface. Key groups:
| Prefix / variable | Purpose |
|---|---|
AGENTGO_* |
service address, token, audit DB path, topology, deployment file, ops address |
AGENTGO_PROTOCOL_TOKEN |
internal service credential for production callers |
AGENTGO_MCP_* |
endpoint/token bindings for logical MCP servers |
AGENTGO_MAX_CONCURRENT_RUNS |
bounded concurrent executions (1–1024) |
AGENTGO_LLM_* |
provider, base URL, model, API key, temperature, max output tokens, timeout |
AGENTGO_IDENTITY_SOURCE |
trusted_header (default) or oidc |
AGENTGO_MTLS_IDENTITY_SOURCE |
mutual-TLS identity mapping |
AGENTGO_OIDC_* |
OIDC issuer, audience, and verified claim mapping |
OTEL_* |
standard OpenTelemetry tracing settings |
Use make dev for Compose; make dev-down removes the workload. The ops
surface (/livez, /readyz, /metrics) listens on AGENTGO_OPS_ADDR
(default :8085). Release images probe /readyz via the built-in
healthcheck subcommand.
Prometheus metrics cover protocol latency, active streams, model calls, tool
calls, delegation activity, and dependency readiness. Logs use log/slog
with stable event names. Distributed tracing uses W3C context propagation and
OTLP export (disabled unless configured).
SQLite stores append-only audit events. On startup the runtime closes
interrupted lifecycles with synthetic runtime_interrupted failures, never
editing history.
| Document | Purpose |
|---|---|
docs/ARCHITECTURE.md |
runtime architecture and protocol mapping |
docs/DOMAIN.md |
stable runtime domain invariants |
docs/STANDARDS.md |
protocol and infrastructure review standards |
examples/simple-chat |
minimal in-memory browser chat with AG-UI task state |
examples/agentgo-assistant |
minimal click-to-explain assistant example |
dev/agent-deployment/deployment.json |
runtime validation fixture |
SECURITY.md |
security policy and required controls |
Install Node.js from .nvmrc; Go resolves its toolchain from go.mod. Run
npm ci once so Markdown linting uses the locked local development dependency.
Run make setup-hooks once so every push runs the local gate. Then use make check, make test, make gate, and make build.
Use make test-local for local integration and smoke testing. It builds the
local runtime image, starts the runtime, and verifies that it becomes live. CI
runs static checks only; keep image integration workloads local. Run
make gate before pushing to cover both CI and the scheduled security scan.
make gate is the pre-push gate. It runs documentation linting, Go static
checks, race tests with the coverage floor, the Go vulnerability scan, and the
local image smoke.
go run ./cmd/agentgo validate -deployment ./path/to/deployment.jsonFollow CONTRIBUTING.md and run make check/make gate
before submitting a change.
Released under the MIT License.

