Claude Agent SDK

Set environment variables#

TCC_API_KEY="your-api-key"

Instrument Claude Agent SDK#

TypeScript — install @contextcompany/claude @anthropic-ai/claude-agent-sdk, then wrap the SDK with instrumentClaudeAgent:

import { instrumentClaudeAgent } from "@contextcompany/claude";
import * as claudeSDK from "@anthropic-ai/claude-agent-sdk";
 
const { query, tool, createSdkMcpServer } = instrumentClaudeAgent(claudeSDK);
 
// Now use query, tool, and createSdkMcpServer as you normally would

That's it — all agent runs are automatically tracked.

Python — install contextcompany[claude], call instrument_claude_agent() once at startup, then use the returned object's query() in place of claude_agent_sdk.query():

from contextcompany.claude import instrument_claude_agent, TCCConfig
from claude_agent_sdk import ClaudeAgentOptions, AssistantMessage, TextBlock
 
agent = instrument_claude_agent()
 
async for message in agent.query(
    prompt="What is 2 + 2?",
    options=ClaudeAgentOptions(system_prompt="You are helpful."),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

Adding custom metadata#

TypeScript — pass a metadata object within the tcc parameter:

const result = query({
  tcc: {
    metadata: {
      userId: "4a6b111c-b53a-4d00-a877-67185022ab9e",
    },
  },
});

Python — pass metadata via TCCConfig:

async for message in agent.query(
    prompt="Hello!",
    tcc_config=TCCConfig(
        metadata={"userId": "4a6b111c-b53a-4d00-a877-67185022ab9e"},
    ),
):
    ...

Agent runs are automatically indexed by custom metadata and filterable in the dashboard. The tcc.* namespace itself is reserved — only the keys documented in Concepts are recognized (tcc.runId, tcc.sessionId, tcc.conversational, tcc.agent, tcc.userId, tcc.userName, tcc.orgId, tcc.orgName); any other tcc.* key is ignored and never appears in your custom metadata.

Tracking sessions, conversational runs, agents, and identity#

Same reserved metadata contract as every TCC integration — tcc.sessionId groups runs into a session, tcc.conversational: true marks a real user interaction, tcc.agent scopes the run to a named agent, tcc.userId/tcc.orgId attach first-class identity. See Concepts for the full reference and REST API / MCP for how to query on these fields later.