examples/

README ¶

Examples

This directory contains runnable examples for github.com/ethpandaops/openrouter-agent-sdk-go.

API Overview

The SDK supports two primary styles:

Top-level one-shot APIs:

Query(ctx, content, ...opts)
QueryStream(ctx, messages, ...opts)

Stateful client API:

NewClient() + Start()
Query() + ReceiveResponse() / ReceiveMessages()
Interrupt() / SetModel() / SetPermissionMode()

Environment

Required:

OPENROUTER_API_KEY

Optional model overrides:

OPENROUTER_MODEL (default: openrouter/free)
OPENROUTER_IMAGE_MODEL (default: google/gemini-2.5-flash-image)
OPENROUTER_VISION_MODEL (defaults to OPENROUTER_MODEL, then OPENROUTER_IMAGE_MODEL)
OPENROUTER_IMAGE_OUTPUT_DIR (optional directory for saving generated images)

Cost Defaults

Examples intentionally default to low-cost/free models where possible. Use OPENROUTER_MODEL to pin a stricter tool-capable or paid model when you need deterministic capability coverage.

Core SDK Examples

These focus on the sibling-style SDK contract that downstream code consumes directly.

Example	Description
`quick_start`	Basic one-shot query with low-cost model defaults.
`query_stream`	Streaming input via `QueryStream` and `MessagesFromSlice`.
`client_multi_turn`	Stateful `Client` usage over multiple turns.
`model_discovery`	List models and inspect free/tool/structured-output/image capabilities.
`structured_output`	Structured JSON output with `WithOutputFormat`.
`sdk_tools`	In-process SDK tools via `WithSDKTools(...)`.
`on_user_input`	SDK-owned user input prompts via `WithOnUserInput(...)`.
`permissions`	Tool permission denial handling via `WithCanUseTool(...)`.
`hooks`	Hook callbacks around tool execution.
`sessions_local`	Local session persistence, listing, stats, and message inspection.
`interrupt`	Client cancellation via `Interrupt()`.
`error_handling`	Typed `UnsupportedControlError` and `ErrSessionNotFound` handling.
`system_prompt`	System prompt configuration (default vs custom string vs preset).
`extended_thinking`	Extended thinking with `WithThinking` and `WithEffort`.
`include_partial_messages`	Real-time streaming of partial message deltas.
`max_budget_usd`	API cost control with `WithMaxBudgetUSD`.
`cancellation`	Context cancellation and graceful client shutdown.
`parallel_queries`	Concurrent `Query()` calls with `errgroup`.
`pipeline`	Multi-step LLM orchestration (Generate → Evaluate → Refine).
`mcp_calculator`	In-process MCP server with calculator tools via `CreateSdkMcpServer`.
`mcp_status`	Query MCP server connection status via `GetMCPStatus`.
`memory_tool`	Filesystem-backed persistent memory via MCP tools.
`custom_logger`	Bridge any logging library (logrus) to `WithLogger` via `slog.Handler`.

OpenRouter-Native Advanced Examples

These focus on OpenRouter-specific routing and request-shape controls.

Example	Description
`openrouter_chat_controls`	Sampling/tool controls (`top_p`, penalties, seed, stop, logprobs).
`openrouter_routing`	Provider/plugins/route/session/trace controls.
`openrouter_responses`	`/responses` mode with instructions/text config/service tier/truncation.
`openrouter_responses_chaining`	Responses chaining with `previous_response_id` and prompt cache key.
`openrouter_multimodal_input`	Multimodal chat-completions input with block-based text + image parts.
`openrouter_multimodal_image`	Multimodal/image generation with generated image blocks saved to disk.
`openrouter_extra`	Escape-hatch payload overrides via `WithOpenRouterExtra`.

Running

# Run any example
go run ./examples/quick_start
go run ./examples/openrouter_responses
go run ./examples/openrouter_multimodal_input

# Examples with sub-examples accept a name argument
go run ./examples/extended_thinking all
go run ./examples/cancellation graceful_shutdown

Testing

# Run all examples and verify output with OpenRouter
scripts/test_examples.sh

# Run specific examples
scripts/test_examples.sh -f quick_start,pipeline

# Keep going on failure
scripts/test_examples.sh -k

# Override the model if you need stricter capability coverage
OPENROUTER_MODEL=google/gemma-3-4b-it:free scripts/test_examples.sh

# Or force a paid/pinned model explicitly
OPENROUTER_MODEL=openai/gpt-4o-mini scripts/test_examples.sh

# Image-generation example with explicit image model and output directory
OPENROUTER_IMAGE_MODEL=google/gemini-2.5-flash-image \
OPENROUTER_IMAGE_OUTPUT_DIR=/tmp/or-images \
go run ./examples/openrouter_multimodal_image

# Multimodal input example with a vision-capable model
OPENROUTER_VISION_MODEL=openai/gpt-4o-mini \
go run ./examples/openrouter_multimodal_input

Directories ¶

Path	Synopsis
cancellation Package main demonstrates cancellation and graceful shutdown patterns.	Package main demonstrates cancellation and graceful shutdown patterns.
client_multi_turn
error_handling
extended_thinking Package main demonstrates extended thinking capabilities with OpenRouter.	Package main demonstrates extended thinking capabilities with OpenRouter.
hooks
include_partial_messages Package main demonstrates partial message streaming where incremental assistant updates are received as the model generates responses.	Package main demonstrates partial message streaming where incremental assistant updates are received as the model generates responses.
internal
exampleutil
interrupt
max_budget_usd Package main demonstrates API cost control with budget limits.	Package main demonstrates API cost control with budget limits.
mcp_calculator Package main demonstrates how to create calculator tools using MCP servers.	Package main demonstrates how to create calculator tools using MCP servers.
mcp_status Package main demonstrates querying MCP server connection status.	Package main demonstrates querying MCP server connection status.
memory_tool Package main demonstrates a filesystem-backed memory tool for agent state persistence.	Package main demonstrates a filesystem-backed memory tool for agent state persistence.
model_discovery
on_user_input
openrouter_chat_controls
openrouter_extra
openrouter_multimodal_image
openrouter_multimodal_input
openrouter_responses
openrouter_responses_chaining
openrouter_routing
parallel_queries Package main demonstrates running multiple Query() calls concurrently.	Package main demonstrates running multiple Query() calls concurrently.
permissions
pipeline Package main demonstrates multi-step LLM orchestration with Go control flow.	Package main demonstrates multi-step LLM orchestration with Go control flow.
prometheus_metrics Example prometheus_metrics demonstrates how to expose SDK metrics via a Prometheus /metrics endpoint using WithPrometheusRegisterer.	Example prometheus_metrics demonstrates how to expose SDK metrics via a Prometheus /metrics endpoint using WithPrometheusRegisterer.
query_stream
quick_start
sdk_tools
sessions_local
structured_output
system_prompt Package main demonstrates configuring system prompts.	Package main demonstrates configuring system prompts.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL