features/

README

SDK Feature Examples

These examples show focused usage of individual SDK features. They are intentionally smaller than the SDK-wide integration suite. Some packages are deterministic and offline; many packages run live provider calls through examples/features/internal/liverunner when credentials are present, so the same examples can exercise real provider adapters.

For the SDK-wide live OpenAI OAuth integration suite using gpt-5.5, run:

OPENAI_OAUTH_AUTH_JSON_PATH=$HOME/.codex/auth.json go test ./test/integration/openai_oauth -count=1 -v

Run every feature example:

go test ./examples/features/...

Missing live credentials skip by default. Set GRATEFUL_LIVE_TESTS=required when a live example run should fail instead.

Run only the offline-safe pass:

GRATEFUL_LIVE_TESTS=skip go test ./examples/features/...

Run a single feature:

go test ./examples/features/tools
go test ./examples/features/tools_registry
go test ./examples/features/guardrails

Feature Map

Feature	README	Runnable package
Agent runtime	agent_runtime	go test ./examples/features/agent_runtime
Model abstraction	model_abstraction	go test ./examples/features/model_abstraction
Providers	providers	go test ./examples/features/providers
Tools	tools	go test ./examples/features/tools
Tool registry	tools_registry	go test ./examples/features/tools_registry
MCP	mcp	go test ./examples/features/mcp
Sandbox	sandbox	go test ./examples/features/sandbox
ChatLoop	chatloop	go test ./examples/features/chatloop
Handoffs and sub-agents	handoffs_subagents	go test ./examples/features/handoffs_subagents
Guardrails	guardrails	go test ./examples/features/guardrails
Structured output	structured_output	go test ./examples/features/structured_output
Streaming	streaming	go test ./examples/features/streaming
Context compaction	context_compaction	go test ./examples/features/context_compaction
Settings and routing	settings_routing	go test ./examples/features/settings_routing
Observability	observability	go test ./examples/features/observability
Errors and retries	errors_retries	go test ./examples/features/errors_retries
Costs	costs	go test ./examples/features/costs
Policy primitives	policy	go test ./examples/features/policy
Memory	memory	go test ./examples/features/memory
Trace store	tracestore	go test ./examples/features/tracestore

The helper packages under internal/live* and internal/liverunner are test dispatch helpers only. Application code should provide its own agentsdk.Model, use the provider packages directly, or assemble providers through agentsdk.MultiProvider.

Feature Coverage Summary

The SDK is organized around a small runtime core plus host adapters. The core features are the agent runner, model/provider abstraction, tool execution, guardrails, structured output, streaming, handoffs, sub-agents, compaction, retries, usage, costs, hooks, traces, and event streams. Host-oriented packages add runtime bundle construction, file-backed mode/role config, policy and permission mapping, MCP integration, sandboxed command execution, memory stores, conversation helpers, mode/phase helpers, built-in tools, and trace persistence.

Use these folders when you want a short example for one feature. Use ../../test/integration/openai_oauth when you want the SDK-wide live OAuth integration test.