Skip to main content

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:
  1. A Shinzo account - Sign up at app.shinzo.ai
  2. Your Anthropic API key stored in Shinzo - Add it in Settings > API Keys > Provider Keys
  3. A Shinzo API key - Create one in Settings > API Keys > Shinzo Keys
  4. The Anthropic SDK installed:
Subscription-Based Support: Due to current platform architecture, agent observability has limitations with subscription-based Anthropic accounts (Claude Pro/Team with OAuth tokens).For best results:

Setup Guide

1

Add your Anthropic API key to Shinzo

  1. Go to app.shinzo.ai
  2. Navigate to Settings > API Keys
  3. Click the Provider Keys tab
  4. Click Add Provider Key
  5. Select Anthropic as the provider
  6. Paste your Anthropic API key from the Anthropic Console
  7. Click Save
Your key will be validated and encrypted before storage.
2

Create a Shinzo API key

  1. In the API Keys page, click the Shinzo Keys tab
  2. Click Create Key
  3. Give your key a descriptive name (e.g., “Production Agent”)
  4. Copy the generated key
3

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)
Add to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):
export ANTHROPIC_API_KEY="sk_shinzo_live_your_key_here"
export ANTHROPIC_BASE_URL="https://api.app.shinzo.ai/spotlight/anthropic"
Then reload your shell:
source ~/.zshrc  # or source ~/.bashrc
The SDK will automatically pick up these environment variables:
import Anthropic from "@anthropic-ai/sdk";

// SDK reads from ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL env vars
const anthropic = new Anthropic();

const message = await anthropic.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1000,
  messages: [
    { role: "user", content: "Hello, Claude!" }
  ]
});
Option 2: Library ParametersPass the Shinzo API key and base URL directly when initializing the SDK client:
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: "sk_shinzo_live_your_key_here",
  baseURL: "https://api.app.shinzo.ai/spotlight/anthropic"
});

const message = await anthropic.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1000,
  messages: [
    { role: "user", content: "Hello, Claude!" }
  ]
});
Replace sk_shinzo_live_your_key_here with your actual Shinzo API key.
4

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.
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: process.env.SHINZO_API_KEY,
  baseURL: "https://api.app.shinzo.ai/spotlight/anthropic"
});

// Define tools for the agent
const tools: Anthropic.Messages.Tool[] = [
  {
    name: "search_knowledge_base",
    description: "Search the knowledge base for answers to customer questions",
    input_schema: {
      type: "object" as const,
      properties: {
        query: {
          type: "string",
          description: "The search query"
        }
      },
      required: ["query"]
    }
  }
];

// Agent conversation loop
async function runAgent(userMessage: string) {
  const messages: Anthropic.Messages.MessageParam[] = [
    { role: "user", content: userMessage }
  ];

  let response = await anthropic.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 2000,
    tools,
    messages
  });

  // Handle tool calls
  while (response.stop_reason === "tool_use") {
    const toolUse = response.content.find(
      (block): block is Anthropic.Messages.ToolUseBlock =>
        block.type === "tool_use"
    );

    if (!toolUse) break;

    // Execute tool (searchKnowledgeBase is your implementation)
    const toolResult = await searchKnowledgeBase(
      (toolUse.input as { query: string }).query
    );

    // Add assistant response and tool result to messages
    messages.push({ role: "assistant", content: response.content });
    messages.push({
      role: "user",
      content: [
        {
          type: "tool_result",
          tool_use_id: toolUse.id,
          content: JSON.stringify(toolResult)
        }
      ]
    });

    // Continue conversation
    response = await anthropic.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 2000,
      tools,
      messages
    });
  }

  return response;
}

const response = await runAgent("How do I reset my password?");
console.log(response.content[0]);
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

  1. Verify configuration:
    • Check that baseURL / base_url is set to https://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)
  2. Test connectivity:
    curl -I https://api.app.shinzo.ai/health
    
  • 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.
The Shinzo proxy adds minimal overhead (~10-30ms per request). If you experience significant slowdowns, check network latency to api.app.shinzo.ai.
To stop routing through Shinzo, point the SDK back to the Anthropic API directly:
const anthropic = new Anthropic({
  apiKey: "your-anthropic-api-key",
  // Remove baseURL to use default Anthropic endpoint
});
Or unset the environment variables:
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL

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