Skip to main content
Claude Agent SDK is Anthropic’s Python SDK for building AI agents powered by Claude. It wraps the Claude Code CLI, providing a programmatic interface for creating agents with tools, hooks, and MCP servers. Add Portkey to get:
  • Multiple Claude Providers - Route through Anthropic, Bedrock, or Vertex AI
  • Observability - Track costs, tokens, and latency for every agent interaction
  • Reliability - Automatic fallbacks, retries, and caching
  • Governance - Budget limits, usage tracking, and team access controls

Claude Agent SDK Documentation

Learn more about Claude Agent SDK’s core concepts and features

​
Quick Start

1

Install the SDK

pip install claude-agent-sdk
2

Add Provider in Portkey

Go to Model Catalog → Add Provider.Select Anthropic, Bedrock, or Vertex AI as your provider and configure your credentials.
3

Get Portkey API Key

Go to API Keys and generate your Portkey API key.
4

Configure Environment Variables

Set the following environment variables before running your agent:
export ANTHROPIC_BASE_URL="https://api.portkey.ai"
export ANTHROPIC_AUTH_TOKEN="dummy"
export ANTHROPIC_CUSTOM_HEADERS="x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-provider: @anthropic-prod"
Replace @anthropic-prod with your provider slug from the Model Catalog.
There are multiple ways to configure models, you can use the provider header, attach config directly to the API key, specify config header, etc.

​
Basic Usage

​
Simple Query

import os
import anyio
from claude_agent_sdk import query

# Set environment variables for Portkey
os.environ["ANTHROPIC_BASE_URL"] = "https://api.portkey.ai"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "dummy"
os.environ["ANTHROPIC_CUSTOM_HEADERS"] = """x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-provider: @anthropic-prod"""

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)

​
Using ClaudeAgentOptions

import os
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

os.environ["ANTHROPIC_BASE_URL"] = "https://api.portkey.ai"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "dummy"
os.environ["ANTHROPIC_CUSTOM_HEADERS"] = """x-portkey-api-key: YOUR_PORTKEY_API_KEY x-portkey-provider: @anthropic-prod"""

async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are a helpful coding assistant",
        max_turns=5
    )

    async for message in query(prompt="Write a Python function to sort a list", options=options):
        print(message)

anyio.run(main)

​
Interactive Client with Tools

import os
import anyio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

os.environ["ANTHROPIC_BASE_URL"] = "https://api.portkey.ai"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "dummy"
os.environ["ANTHROPIC_CUSTOM_HEADERS"] = """x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-provider: @anthropic-prod"""

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode='acceptEdits'
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Create a hello.py file that prints 'Hello, World!'")

        async for msg in client.receive_response():
            print(msg)

anyio.run(main)

​
Adding Observability

​
Trace IDs for Request Tracking

Add trace IDs to group related requests in Portkey’s dashboard: 
os.environ["ANTHROPIC_CUSTOM_HEADERS"] = """x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-provider: @anthropic-prod
x-portkey-trace-id: agent-session-123"""

​
Custom Metadata

Add metadata for filtering and analytics: 
import json

metadata = json.dumps({
    "agent_type": "code_assistant",
    "environment": "production",
    "_user": "user_123"
})

os.environ["ANTHROPIC_CUSTOM_HEADERS"] = f"""x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-provider: @anthropic-prod
x-portkey-metadata: {metadata}"""

​
Using Portkey Configs

For advanced routing, fallbacks, and caching, create a Portkey Config and reference it: 
os.environ["ANTHROPIC_CUSTOM_HEADERS"] = """x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-config: YOUR_CONFIG_ID"""

​
Example: Fallback Configuration

Create a config in the Portkey Dashboard with fallback logic: 
{
  "strategy": {
    "mode": "fallback"
  },
  "targets": [
    { "provider": "@anthropic-prod" },
    { "provider": "@bedrock-prod" }
  ]
}
This automatically switches to Bedrock if the primary Anthropic provider fails.

​
Switch Providers

Change providers by updating the x-portkey-provider header:
ProviderHeader Value
Anthropic@anthropic-prod
AWS Bedrock@bedrock-prod
Google Vertex AI@vertex-prod
Replace with your actual provider slugs from the Model Catalog.

​
Custom Tools with MCP Servers

Claude Agent SDK supports custom tools via MCP servers. All tool calls are tracked in Portkey: 
import os
import anyio
from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    ClaudeAgentOptions,
    ClaudeSDKClient
)

os.environ["ANTHROPIC_BASE_URL"] = "https://api.portkey.ai"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "dummy"
os.environ["ANTHROPIC_CUSTOM_HEADERS"] = """x-portkey-api-key: YOUR_PORTKEY_API_KEY
x-portkey-provider: @anthropic-prod
x-portkey-trace-id: mcp-tools-session"""

@tool("get_weather", "Get weather for a city", {"city": str})
async def get_weather(args):
    return {
        "content": [
            {"type": "text", "text": f"Weather in {args['city']}: 72°F, Sunny"}
        ]
    }

server = create_sdk_mcp_server(
    name="weather-tools",
    version="1.0.0",
    tools=[get_weather]
)

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"weather": server},
        allowed_tools=["mcp__weather__get_weather"]
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("What's the weather in San Francisco?")

        async for msg in client.receive_response():
            print(msg)

anyio.run(main)
Last modified on January 28, 2026