examples/

directory
v0.0.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 24, 2026 License: GPL-3.0

README

Examples

This directory contains examples demonstrating the Claude Agent SDK for Go.

API Overview

The SDK provides two main APIs for interacting with Claude:

Top-Level Functions (One-Shot)

Simple, stateless functions for single queries:

  • Query(ctx, content, ...opts) - Send UserMessageContent and receive streaming responses
  • QueryStream(ctx, messages, ...opts) - Send multiple messages via iter.Seq[StreamingMessage]

These are ideal for:

  • Simple question/answer interactions
  • Multimodal prompts using images, PDFs, or @/absolute/path mentions
  • Batch processing where each query is independent
  • Scripts and CLI tools
Client API (Stateful)

A stateful client for multi-turn conversations and advanced control:

  • NewClient() - Create a new client instance
  • client.Start(ctx, ...opts) - Initialize the connection
  • client.Query(ctx, content) - Send user content (conversation context preserved)
  • client.ReceiveMessages(ctx) / client.ReceiveResponse(ctx) - Receive responses
  • client.Interrupt(ctx) - Soft-interrupt an ongoing response
  • client.Close() - Clean up resources

This is ideal for:

  • Multi-turn conversations with context
  • Interactive applications
  • Scenarios requiring interrupt capability

Examples

Example Description
quick_start Basic usage of the Query() function
query_stream Using QueryStream() with iter.Seq[StreamingMessage], including message priority and BudgetTracker observation
client_multi_turn Client API with multi-turn conversations, interrupts, typed server info, dynamic control operations, and turn-complete callbacks
turn_complete One-shot query with WithOnTurnComplete(...) and aggregate cost summaries
sessions Managing conversation sessions
agents Building custom agents
filesystem_agents File system operations with agents
hooks Using lifecycle hooks
compaction_hook Monitoring context compaction with the PreCompact hook and checking context-pressure tiers
mcp_calculator MCP server integration
mcp_status Querying MCP server connection status
fast_mode Opting into fast mode for headless SDK sessions and observing fast-mode state
context_pressure Evaluating multi-tier context pressure and compact-failure breaker state
elicitation Handling MCP elicitation requests with WithOnElicitation
multimodal_input Images, PDFs, and local file-path mentions with UserMessageContent
memory_tool Filesystem-backed memory tool for agent state persistence
plugin_example Plugin system usage
system_prompt Customizing system prompts
tools_option Configuring allowed tools
tool_permission_callback Custom tool permission handling
user_input_callback Auto-answer AskUserQuestion prompts with WithOnUserInput
stderr_callback Capturing CLI stderr output
custom_logger Custom logging configuration
max_budget_usd Setting cost limits and observing near-budget turns with BudgetTracker
task_budget Setting task-level token budgets
session_mutations Session lifecycle operations: rename, tag, fork, delete
setting_sources Configuration sources
include_partial_messages Handling partial/streaming messages
structured_output Using WithOutputFormat() for structured JSON responses
extended_thinking Extended thinking capabilities for complex reasoning
error_handling Classifying assistant, retry, rate-limit, and result errors
cancellation Context cancellation and signal handling
parallel_queries Running concurrent Query() calls with errgroup
pipeline Multi-step LLM orchestration with Go control flow
traceparent_propagation Propagating an active W3C trace context to the CLI subprocess (requires CLI ≥ 2.1.110)
prometheus_metrics Exposing SDK metrics via a Prometheus /metrics endpoint

Running Examples

# Run a specific example
go run ./examples/quick_start
go run ./examples/multimodal_input /absolute/path/to/image.png /absolute/path/to/spec.pdf

# Run client_multi_turn with a specific sub-example
go run ./examples/client_multi_turn basic_streaming
go run ./examples/client_multi_turn all

Directories

Path Synopsis
Package main demonstrates context compaction monitoring using the PreCompact hook.
 Package main demonstrates context compaction monitoring using the PreCompact hook.
Package main demonstrates extended thinking capabilities with Claude.
 Package main demonstrates extended thinking capabilities with Claude.
Package main demonstrates how to create calculator tools using MCP servers.
 Package main demonstrates how to create calculator tools using MCP servers.
Package main demonstrates querying MCP server connection status.
 Package main demonstrates querying MCP server connection status.
Package main demonstrates a filesystem-backed memory tool for agent state persistence.
 Package main demonstrates a filesystem-backed memory tool for agent state persistence.
Package main demonstrates how to use plugins with Claude Code SDK.
 Package main demonstrates how to use plugins with Claude Code SDK.
Example prometheus_metrics demonstrates how to expose SDK metrics via a Prometheus /metrics endpoint using the contrib/prometheus helper.
 Example prometheus_metrics demonstrates how to expose SDK metrics via a Prometheus /metrics endpoint using the contrib/prometheus helper.
Example traceparent_propagation demonstrates that the SDK propagates an active W3C OpenTelemetry trace context to the Claude CLI subprocess as TRACEPARENT/TRACESTATE env vars, so the CLI's spans parent under the caller's distributed trace.
 Example traceparent_propagation demonstrates that the SDK propagates an active W3C OpenTelemetry trace context to the Claude CLI subprocess as TRACEPARENT/TRACESTATE env vars, so the CLI's spans parent under the caller's distributed trace.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.