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, prompt, ...opts)- Send a single prompt and receive streaming responsesQueryStream(ctx, messages, ...opts)- Send multiple messages viaiter.Seq[StreamingMessage]
These are ideal for:
- Simple question/answer interactions
- 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 instanceclient.Start(ctx, ...opts)- Initialize the connectionclient.Query(ctx, prompt)- Send a message (conversation context preserved)client.ReceiveMessages(ctx)/client.ReceiveResponse(ctx)- Receive responsesclient.Interrupt(ctx)- Interrupt an ongoing responseclient.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] |
client_multi_turn |
Client API with multi-turn conversations, interrupts, and advanced patterns |
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 |
mcp_calculator |
MCP server integration |
mcp_status |
Querying MCP server connection status |
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 |
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 |
Checking AssistantMessage.Error for API errors |
cancellation |
Context cancellation and signal handling |
parallel_queries |
Running concurrent Query() calls with errgroup |
pipeline |
Multi-step LLM orchestration with Go control flow |
Running Examples
# Run a specific example
go run ./examples/quick_start
# 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. |
Click to show internal directories.
Click to hide internal directories.