config

Examples

These programs exercise agent-sdk-go (github.com/agenticenv/agent-sdk-go). By default examples run on the local runtime (in-process, no external services). Set AGENT_RUNTIME=temporal in .env for durable Temporal execution.

Runtime

When using Temporal the examples read TEMPORAL_HOST, TEMPORAL_PORT, and TEMPORAL_NAMESPACE from .env (default: localhost, 7233, default).

Examples overview

From examples/, use Task and Taskfile.yml for infra in the table below, then go run ./<example>. Install task, infra targets, and batch runs: Setup. Third-party MCP/A2A servers stay manual — see each example’s README.

Works with both runtimes

These examples run with AGENT_RUNTIME=local (default) or AGENT_RUNTIME=temporal.

Temporal runtime: set AGENT_RUNTIME=temporal in .env, then run task infra:temporal:up and task infra:temporal:wait before go run (for every row below, in addition to the infra in the third column).

Temporal only

Set AGENT_RUNTIME=temporal. Start task infra:temporal:up and task infra:temporal:wait before go run.

Setup

.env.defaults is loaded automatically: valid values for local Task infra (stdio MCP, A2A on :9999, Weaviate/pgvector ports, OTLP to LGTM). Create optional examples/.env (gitignored) for secrets and overrides:

# From examples/ — at minimum set keys; override anything else as needed
cat >> .env <<'EOF'
LLM_APIKEY=your-key
EMBEDDING_OPENAI_APIKEY=your-openai-embeddings-key
EOF

Override LLM_PROVIDER / LLM_MODEL, MCP_TRANSPORT=streamable_http + MCP_STREAMABLE_HTTP_URL, a remote A2A_URL, or retriever vars when not using the default local stack. Process environment (export / root Taskfile.yml dotenv) wins over both files. See env vars and examples/.env.defaults.

Task — not installed by default; install via Task installation (platform-specific). Not needed for go run ./<example> when the overview table has no infra. Compose infra also needs Docker. From examples/: task infra:status, infra:deps:up / down, infra:*:up / down. From repo root: task examples:local, task examples:temporal, task examples:all. Contributors: run task examples:all before any PR to catch regressions across local and Temporal runtimes. New examples that can run non-interactively (one-shot, no REPL, no separate worker) should be listed in taskfiles/examples.yml (EXAMPLES, EXAMPLES_WITH_PROMPTS, or EXAMPLES_TEMPORAL as appropriate). task --dry only prints commands (no report file). To preview the report layout without running examples or infra, use task examples:local:plan, task examples:temporal:plan, or task examples:all:plan.

Run examples

Minimal agent (no tools)

go run ./simple_agent "Hello, what can you do?"

Agent with conversation (multi-turn)

Uses Redis (REDIS_ADDR, default localhost:6379). Start Redis first: task infra:redis:up. Run interactive mode (no args) for multi-turn in one process—history is shared across turns. With args, runs a single turn (useful for testing).

task infra:redis:up
# Interactive: type prompts, get responses; history shared. Type 'exit' to end.
go run ./agent_with_conversation

# Single turn (new process each run; no shared history)
go run ./agent_with_conversation "Hello, remember I'm Alice"

Agent with tools

go run ./agent_with_tools/basic "What's the weather in Tokyo?"
go run ./agent_with_tools/approval "What is 15 + 27?"
go run ./agent_with_tools/authorizer "Get the protected note for roadmap."
go run ./agent_with_tools/custom "Reverse 'hello world'"
go run ./agent_with_tools/dynamic_registry

Agent with workflows

# in-process runner (default — no infrastructure needed)
go run ./agent_with_workflows "Run the onboarding workflow for user Alice"

# Temporal runner — durable execution
task infra:temporal:up && task infra:temporal:wait
ORCHESTRATION_ENGINE=temporal go run ./agent_with_workflows "Run the onboarding workflow for user Alice"

Agent with code execution

# local sandbox (default — needs Python or Node installed)
go run ./agent_with_code_execution "Write a Python script that prints the first 10 Fibonacci numbers"

# Docker sandbox — isolated execution
SANDBOX_ENV=docker go run ./agent_with_code_execution "Write a Python script that prints the first 10 Fibonacci numbers"

Agent with hooks

Middleware hooks across LLM, tools, retrieval, and memory. Hook activity is logged to stderr ([hooks] prefix).

go run ./agent_with_hooks
go run ./agent_with_hooks "My email is alice@example.com. What is the return policy?"

See agent_with_hooks/README.md. When using AGENT_RUNTIME=temporal, register the same hook groups on both the agent starter and the worker.

Streaming (partial content as tokens arrive)

go run ./agent_with_stream "What's the current time and what's 17 * 23?"

AG-UI / CopilotKit (agent_with_agui)

Go SSE server + Next.js frontend. Two processes:

# Terminal 1: Go agent server (listens on :8787)
go run ./agent_with_agui/server

# Terminal 2: Next.js UI
cd agent_with_agui/ui && npm install && npm run dev

See agent_with_agui/README.md for curl testing and UI setup.

Structured JSON response (WithResponseFormat)

go run ./agent_with_json_response
go run ./agent_with_json_response "What is the capital of Japan?"

Reasoning / thinking (WithLLMSampling + LLMReasoning)

go run ./agent_with_reasoning
go run ./agent_with_reasoning "Why is the sky blue? One short paragraph."

Streaming + conversation (event handling pattern)

go run ./agent_with_stream_conversation
go run ./agent_with_stream_conversation "What is 5 * 8?"

Sub-agents (main agent + specialist)

go run ./agent_with_subagents "What is 987 times 654?"

RunAsync + concurrent runs + multiple agents

go run ./agent_with_run_async "What is 15 + 27?"
go run ./agent_with_concurrent_runs
go run ./agent_with_concurrent_runs "Who wrote Hamlet?" "What is sqrt(144)?" "Name a primary color."
go run ./multiple_agents "What is 7 times 8?"
go run ./multiple_agents concurrent "What is 7 times 8?"

MCP (agent_with_mcp_config, agent_with_mcp_client)

Same MCP_* env (see .env.defaults); differs only in WithMCPConfig vs mcpclient.NewClient + WithMCPClients.

go run ./agent_with_mcp_config
go run ./agent_with_mcp_config "List tools you can call."
go run ./agent_with_mcp_client
go run ./agent_with_mcp_client "List tools you can call."

Configure transports, test against real MCP servers: agent_with_mcp_config/README.md.

A2A client (agent_with_a2a_config, agent_with_a2a_client)

Outbound A2A tools — set A2A_URL (and optional A2A_* in .env.defaults).

go run ./agent_with_a2a_config
go run ./agent_with_a2a_config "What tools do you have available?"
go run ./agent_with_a2a_client
go run ./agent_with_a2a_client "What tools do you have available?"

Run a sample remote agent, curl checks: agent_with_a2a_config/README.md.

A2A server (agent_with_a2a_server)

Inbound JSON-RPC server — A2A_SERVER_*, optional bearer tokens.

go run ./agent_with_a2a_server

curl, a2a CLI, testing with agent_with_a2a_config: agent_with_a2a_server/README.md.

Observability OTLP (agent_with_observability)

Requires a reachable OTLP collector (OTEL_EXPORTER_OTLP_ENDPOINT, typically localhost:4317 for gRPC or localhost:4318 for HTTP).

go run ./agent_with_observability/config/
go run ./agent_with_observability/objects/

Details and collector notes: agent_with_observability/README.md.

Vector retriever (agent_with_retriever)

Requires a running vector store (Weaviate or Postgres with pgvector). Set backend-specific vars in .env.defaults.

# Weaviate (task infra:weaviate:up first; task infra:weaviate:down when done)
go run ./agent_with_retriever/weaviate "What is the return policy?"

# pgvector (task infra:pgvector:up first; task infra:pgvector:down when done)
go run ./agent_with_retriever/pgvector "What is the return policy?"

RETRIEVER_MODE=prefetch go run ./agent_with_retriever/weaviate "What are the return and shipping rules?"

Setup guides: agent_with_retriever/README.md.

Long-term memory (agent_with_memory)

Same vector infra as retriever (task infra:weaviate:up or task infra:pgvector:up). Weaviate uses always store (run-end extract); pgvector uses on-demand store (save_memory). No CLI args runs a two-turn demo (store, then recall).

go run ./agent_with_memory/weaviate
go run ./agent_with_memory/pgvector

Setup guide: agent_with_memory/README.md.

Temporal-only examples

These require AGENT_RUNTIME=temporal and a running Temporal server.

Caller-owned Temporal client

Creates and manages the Temporal client directly — for TLS, Temporal Cloud API keys, or custom connection options.

AGENT_RUNTIME=temporal go run ./agent_with_temporal_client "Hello, what can you do?"

Agent + worker in separate processes (agent_with_worker)

AGENT_RUNTIME=temporal go run ./agent_with_worker/worker    # terminal 1: worker
AGENT_RUNTIME=temporal go run ./agent_with_worker/agent "Hello from remote agent!"   # terminal 2: agent

Durable agent — workflow replay and failure scenarios (durable_agent)

AGENT_RUNTIME=temporal go run ./durable_agent/worker       # terminal 1
AGENT_RUNTIME=temporal go run ./durable_agent/agent "Hello from remote agent!"   # terminal 2

See durable_agent/README.md for durability and failure scenarios.

Logging

Examples send conversation (user prompt, assistant response) to stdout and internal logs to stderr. By default only errors are logged.

• See logs while evaluating: Set LOG_LEVEL=info or LOG_LEVEL=debug in .env, or run:

  LOG_LEVEL=debug go run ./simple_agent "Hello, what can you do?"
  

• Save logs to a file: Redirect stderr to a file:

  LOG_LEVEL=info go run ./simple_agent "Hello" 2>debug.log
  

• Suppress logs: Show only conversation output:

  go run ./simple_agent "Hello" 2>/dev/null
  

Run output

All examples call shared.PrintRunFooters after each run. Set these in examples/.env (defaults in .env.defaults) to print formatted footers:

SHOW_LLM_USAGE=true go run ./simple_agent "Hello, what can you do?"
SHOW_TELEMETRY=true go run ./simple_agent "Hello, what can you do?"
SHOW_LLM_USAGE=true SHOW_TELEMETRY=true go run ./agent_with_stream "What's 17 * 23?"

For retriever examples, SHOW_TELEMETRY=true also prints prefetch/agentic search breakdowns — see agent_with_retriever/README.md.

For memory examples, SHOW_TELEMETRY=true also prints total_memory_recalls and total_memory_stores — see agent_with_memory/README.md.

Env vars