Anthropic SDK
The Anthropic SDK is the official library for building AI agents with Claude in your applications. By routing your SDK requests through Shinzo, you gain observability into agent behavior, including conversation traces, tool usage, token consumption, and performance metrics.How It Works
Shinzo acts as a proxy between your application and the Anthropic API. You point the Anthropic SDK at Shinzo’s proxy endpoint and use your Shinzo API key for authentication. Shinzo retrieves your stored Anthropic key, forwards the request, and records all analytics data automatically. What’s captured:- Conversation flow (prompts, responses, context)
- Tool calls and results
- Token usage and costs (including cache usage)
- Performance metrics (latency)
- Error traces
Prerequisites
Before you begin, ensure you have:- A Shinzo account - Sign up at app.shinzo.ai
- Your Anthropic API key stored in Shinzo - Add it in Settings > API Keys > Provider Keys
- A Shinzo API key - Create one in Settings > API Keys > Shinzo Keys
- The Anthropic SDK installed:
Setup Guide
Add your Anthropic API key to Shinzo
- Go to app.shinzo.ai
- Navigate to Settings > API Keys
- Click the Provider Keys tab
- Click Add Provider Key
- Select Anthropic as the provider
- Paste your Anthropic API key from the Anthropic Console
- Click Save
Your key will be validated and encrypted before storage.
Create a Shinzo API key
- In the API Keys page, click the Shinzo Keys tab
- Click Create Key
- Give your key a descriptive name (e.g., “Production Agent”)
- Copy the generated key
Configure the Anthropic SDK
Point the SDK at Shinzo’s proxy endpoint using your Shinzo API key. You can configure this with environment variables or directly in code.Option 1: Environment Variables (Recommended)Option 2: Library ParametersPass the Shinzo API key and base URL directly when initializing the SDK client:
- macOS / Linux
- Windows (PowerShell)
Add to your shell configuration file (Then reload your shell:The SDK will automatically pick up these environment variables:
~/.bashrc, ~/.zshrc, etc.):Verify the configuration
Run your application and make a test request. Then check the Shinzo Dashboard to see your conversation appear.
If you see your conversation in Analytics > Agent Analytics, you’re all set!
Building an Agent with Observability
Here’s a complete example of building an agent with tool use. All analytics are captured automatically by the proxy — no additional instrumentation is needed.All conversation data, tool calls, token usage, and latency metrics are automatically captured by the Shinzo proxy. No additional instrumentation code is needed.
What Data is Collected?
When you route Anthropic SDK requests through Shinzo, the following data is automatically captured:Conversation Data
- User messages and agent responses
- Full conversation context and history
- Model configuration (model, temperature, max_tokens, etc.)
- Timestamps and latency for each message
Tool Usage
- Tool definitions and schemas
- Tool invocations with parameters
- Tool results and outputs
Performance Metrics
- Response time: Latency from request to response
- Token counts: Input and output tokens per message
- Cache usage: Cache creation and cache read tokens
- Costs: Estimated cost based on model pricing
Error Tracking
- Error messages and error types
- Failed requests and status codes
Troubleshooting
Conversations not appearing in dashboard
Conversations not appearing in dashboard
-
Verify configuration:
- Check that
baseURL/base_urlis set tohttps://api.app.shinzo.ai/spotlight/anthropic - Verify your Shinzo API key is valid
- Ensure your Anthropic key is stored in Shinzo (Settings > API Keys > Provider Keys)
- Check that
-
Test connectivity:
Authentication errors
Authentication errors
- 401 Unauthorized: Your Shinzo API key is invalid or revoked.
- 403 Forbidden - Invalid provider key: Your Anthropic key stored in Shinzo is invalid. Update it in Settings > API Keys > Provider Keys.
Performance overhead
Performance overhead
The Shinzo proxy adds minimal overhead (~10-30ms per request). If you experience significant slowdowns, check network latency to
api.app.shinzo.ai.Disabling Shinzo observability
Disabling Shinzo observability
To stop routing through Shinzo, point the SDK back to the Anthropic API directly:Or unset the environment variables:
Next Steps
Agent Analytics Dashboard
Explore your agent conversation data and metrics
Claude Code
Set up analytics and observability for Claude Code CLI
MCP Analytics
Add observability to your MCP servers
Contact Support
Get help or contact us about your use case

