examples/

README

中文 | English

agentsdk-go Examples

Eight examples. Run everything from the repo root.

Environment Setup

1. Copy .env.example to .env and set your API key:

cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY=sk-ant-your-key-here

1. Load environment variables:

source .env

Alternatively, export directly:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Learning path

• 01-basic (32 lines): single API call, minimal surface, prints one response.
• 02-cli (73 lines): CLI REPL with session history and optional config loading.
• 03-http (~300 lines): REST + SSE server on :8080, production-ready wiring.
• 04-advanced (~1400 lines): full stack with middleware, hooks, MCP, sandbox, skills, subagents.
• 05-custom-tools (~150 lines): selective built-in tools and custom tool registration.
• 05-multimodel (~120 lines): multi-model support with model pool and tier-based routing.
• 06-v0.4.0-features (~280 lines): v0.4.0 feature tour (offline-safe).
• 08-askuserquestion (~150 lines): AskUserQuestion tool integration with build-tag demos.

01-basic — minimal entry

• Purpose: fastest way to see the SDK loop in action with one request/response.
• Run:

source .env
go run ./examples/01-basic

02-cli — interactive REPL

• Key features: interactive prompt, per-session history, optional .claude/settings.json load.
• Run:

source .env
go run ./examples/02-cli --session-id demo --settings-path .claude/settings.json

03-http — REST + SSE

• Key features: /health, /v1/run (blocking), /v1/run/stream (SSE, 15s heartbeat); defaults to :8080. Fully thread-safe runtime handles concurrent requests automatically.
• Run:

source .env
go run ./examples/03-http

04-advanced — full integration

• Key features: end-to-end pipeline with middleware chain, hooks, MCP client, sandbox controls, skills, subagents, streaming output.
• Run:

source .env
go run ./examples/04-advanced --prompt "安全巡检" --enable-mcp=false

05-custom-tools — custom tool registration

• Key features: selective built-in tools (EnabledBuiltinTools), custom tool implementation (CustomTools), demonstrates tool filtering and registration.
• Run:

source .env
go run ./examples/05-custom-tools

• See 05-custom-tools/README.md for detailed usage and custom tool implementation guide.

05-multimodel — multi-model support

• Key features: model pool configuration, tier-based model routing (low/mid/high), subagent-model mapping, cost optimization.
• Run:

source .env
go run ./examples/05-multimodel

• See 05-multimodel/README.md for configuration examples and best practices.

06-v0.4.0-features — v0.4.0 feature tour (offline-safe)

• Key features: rules loader, token tracking, auto-compact, async bash, disallowed tools, OTEL (via build tag).
• Run:

go run ./examples/06-v0.4.0-features

• See 06-v0.4.0-features/README.md for details and online mode notes.

08-askuserquestion — AskUserQuestion tool

• Key features: three demo modes selected by build tags.
• Run:

source .env
(cd examples/08-askuserquestion && go run .)                 # full agent scenarios
(cd examples/08-askuserquestion && go run -tags demo_llm .)  # LLM integration test
(cd examples/08-askuserquestion && go run -tags demo_simple .) # tool-only test (no API key needed)

• See 08-askuserquestion/README.md for detailed usage and implementation patterns.