Go Examples & Task Cookbook
Use these runnable Go examples when you want to see how a task works in practice. Each guide connects the example to the related product documentation, so you can start with a small working path and then explore the relevant configuration.
Find a Guide by Task
| Goal | Guide / Demo |
|---|---|
| Start building | Go SDK Quickstart · Standalone Gateway Quickstart · Docker Compose |
| Connect Python/TS SDKs & Coding IDEs | Integrations Overview · OpenAI SDKs · Anthropic SDKs · Claude Code · Cursor & IDEs |
| Configure routing, fallbacks & caching | Routing & Load Balancing · Resiliency & Fallbacks · Exact-Match Cache |
| Enforce Virtual Keys, RBAC & Guardrails | Virtual Keys · RBAC & Vault · Guardrails · SSRF & Network Security |
| Track FinOps spend & rate limits | Micro-Dollar Ledger · Sliding-Window Rate Limits · Pre-Flight Tokenization |
| Monitor telemetry & troubleshoot | Observability & Health Probes · OpenTelemetry & Prometheus · Operator Web UI · Troubleshooting |
| Run MCP tool hubs & A2A agent networks | MCP Overview · A2A Overview · Autonomous Tool Loop |
| Deploy to production | Configuration · Deployment & Storage · Kubernetes & Kustomize · Production Checklist |
Running Any Demo
Run an example from the examples/ module after its Go dependencies are available:
cd examples
go run ./hello_gateway
Most examples enable the built-in mock provider when credentials are missing, so they can demonstrate the request flow without contacting a model provider. Examples that require a local service, such as Ollama or an HTTP server, still need that service running. To test a live provider, export the matching key before running its example:
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIzaSy... or AQ.Ab8..."
The examples module declares its Go toolchain version in examples/go.mod. See each example's source for the provider, local service, or environment variables it needs.
Examples by task
Fundamentals
- Hello Gateway: Minimal in-process gateway setup and synchronous chat.
- System Prompts: Persona steering using
gateway.WithSystem(...). - Streaming Tokens: Zero-buffer SSE token streaming via
StreamChat. - Sampling & Limits: Deterministic outputs and minimal token capping.
- Structured JSON: Guaranteed machine-readable JSON object output.
- Multi-Turn Memory: Maintaining conversation history across multiple turns.
Multi-Provider Integrations
- OpenAI Direct: Connecting to OpenAI with
openai/gpt-4o-mini. - Anthropic Direct: Connecting to Anthropic with
anthropic/claude-haiku-4-5-20251001. - Google Gemini Direct: Connecting to Gemini with
gemini/gemini-2.5-flash-lite. - Local Ollama: Self-hosted offline inference on port 11434.
- Unified Model Aliases: Logical aliases decoupling callers from specific vendors.
Tool Calling & Autonomous Agents
- Tool Definition: Registering tool schemas via Model Context Protocol (MCP).
- Tool Execution: In-process tool execution and result returning.
- Multi-Tool Inventory: Aggregating multiple tool servers into a single schema.
- Autonomous Agent Loop: Multi-turn self-orchestrating loop with zero human intervention.
Traffic Routing & Outage Resiliency
- Outage Fallback Chains: Automatic 503 outage recovery with secondary models.
- Round-Robin Balancer: Uniform stateless load balancing.
- Weighted Shuffle Routing: Proportionate canary and cost-steered traffic splitting.
- Least-Latency EWMA: Peak-EWMA routing favoring lowest latency endpoints.
- Circuit Breakers: Fast-failing broken backends to protect caller latency.
Enterprise FinOps, Protocols & Microservices
- Exact-Match Cache: Sub-millisecond SHA-256 caching for identical prompts.
- Sliding-Window Rate Limits: Strict RPM and TPM quota enforcement.
- Virtual Keys & Budgets: Department keys, micro-dollar tracking, and revocation.
- MCP Virtual Hub: Model Context Protocol Virtual Hub & REST bridge.
- A2A Agent Network: Cryptographic Agent-to-Agent discovery and dispatch.
- Embedded Microservice: Production HTTP server with Kubernetes probes.