Agent SDK API reference

This engineering reference summarizes the official TypeScript/Python APIs. Consult the complete reference for details; start by choosing between one-shot query(), persistent clients, custom tools, session management, settings resolution and migration behavior.

For custom tools, streaming, structured output, tool search and approvals, see runtime patterns. For multitenancy and deployment, see production deployment.

#Official pages covered

#Installation

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

For Passion8, configure the subprocess environment:

export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_PASSION8_API_KEY"

The TypeScript env option replaces the subprocess environment. Usually spread ...process.env when supplying custom variables.

#Choose an entry point

#Minimal query() example

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Explain this repository's entry points",
  options: {
    cwd: process.cwd(),
    maxTurns: 5,
    permissionMode: "dontAsk",
    allowedTools: ["Read", "Grep", "Glob"],
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://passion8.cc",
      ANTHROPIC_AUTH_TOKEN: process.env.PASSION8_API_KEY ?? ""
    }
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, query


async def main() -> None:
    options = ClaudeAgentOptions(
        cwd=".",
        max_turns=5,
        permission_mode="dontAsk",
        allowed_tools=["Read", "Grep", "Glob"],
        env={
            "ANTHROPIC_BASE_URL": "https://passion8.cc",
            "ANTHROPIC_AUTH_TOKEN": "sk-YOUR_PASSION8_API_KEY",
        },
    )

    async for message in query(prompt="Explain this repository's entry points", options=options):
        if getattr(message, "type", None) == "result":
            print(message.result)


asyncio.run(main())

#Python query() versus ClaudeSDKClient

For a continuously conversational agent panel, prefer Python ClaudeSDKClient. For one run per queued job, query() is simpler.

#Common functions

#Permission modes at a glance

allowedTools preapproves tools; it does not limit the complete tool inventory. Remove definitions with disallowedTools or narrow tools.

#Session API

Typical UI usage:

const sessions = await listSessions({ dir: "/repo", limit: 50 });
const current = await getSessionInfo(sessions[0].sessionId, { dir: "/repo" });
const messages = await getSessionMessages(sessions[0].sessionId, { dir: "/repo", limit: 100 });

Do not treat a local transcript as the sole durable store. For cross-host restoration, see SessionStore in production deployment.

#Settings resolution

TypeScript resolveSettings() lets a host display effective configuration before startup.

Suggested multitenant defaults:

{
  settingSources: [],
  env: {
    ...process.env,
    CLAUDE_CONFIG_DIR: `/srv/claude-config/${tenantId}`,
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"
  }
}

#Migrate from older SDKs

To retain CLI-like behavior when migrating, set:

systemPrompt: {
  type: "preset",
  preset: "claude_code"
}

#Cache effects

See production deployment for observability fields.

#Official references

• Agent SDK overview
• Agent SDK quickstart
• TypeScript reference
• Python reference
• Migration guide
• TypeScript V2 session API removed