Referensi Agent SDK - Python

Referensi API lengkap untuk Python Agent SDK, termasuk semua fungsi, tipe, dan kelas.

Instalasi

Instal paket ke dalam lingkungan virtual. Pada instalasi Python Debian, Ubuntu, dan Homebrew terbaru, menjalankan pip install terhadap Python sistem gagal dengan error: externally-managed-environment.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Untuk uv, Windows PowerShell, dan pengaturan kunci API, lihat Pengaturan dalam panduan cepat Agent SDK.

Memilih antara `query()` dan `ClaudeSDKClient`

Python SDK menyediakan dua cara untuk berinteraksi dengan Claude Code:

Gunakan ClaudeSDKClient untuk aplikasi interaktif seperti antarmuka obrolan, atau ketika tindakan berikutnya bergantung pada respons Claude.

Fungsi

`query()`

Membuat sesi baru untuk setiap interaksi dengan Claude Code secara default. Mengembalikan async iterator yang menghasilkan pesan saat tiba. Setiap panggilan ke query() dimulai segar tanpa memori interaksi sebelumnya kecuali Anda melewatkan continue_conversation=True atau resume dalam ClaudeAgentOptions. Lihat Sessions.

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeAgentOptions | None = None,
    transport: Transport | None = None
) -> AsyncIterator[Message]

Parameter

Pengembalian

Mengembalikan AsyncIterator[Message] yang menghasilkan pesan dari percakapan.

Contoh - Dengan opsi

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode="acceptEdits",
    )

    async for message in query(prompt="Create a Python web server", options=options):
        print(message)


asyncio.run(main())

`tool()`

Dekorator untuk mendefinisikan tools MCP dengan keamanan tipe.

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any],
    annotations: ToolAnnotations | None = None
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

Parameter

Opsi skema input

1. Pemetaan tipe sederhana (direkomendasikan):

   {"text": str, "count": int, "enabled": bool}
   

2. Format JSON Schema (untuk validasi kompleks):

   {
       "type": "object",
       "properties": {
           "text": {"type": "string"},
           "count": {"type": "integer", "minimum": 0},
       },
       "required": ["text"],
   }
   

Pengembalian

Fungsi dekorator yang membungkus implementasi tool dan mengembalikan instance SdkMcpTool.

Contoh

from claude_agent_sdk import tool
from typing import Any


@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

`ToolAnnotations`

Petunjuk perilaku untuk tool, diteruskan sebagai argumen annotations dari tool(). ToolAnnotations memperluas mcp.types.ToolAnnotations SDK MCP dengan field maxResultSizeChars, dan Anda dapat menulis setiap petunjuk dalam camelCase atau snake_case: ToolAnnotations(readOnlyHint=True) dan ToolAnnotations(read_only_hint=True) adalah setara. Anda juga dapat melewatkan mcp.types.ToolAnnotations biasa di mana pun SDK menerima anotasi.

Nama snake_case dan field maxResultSizeChars yang diketik memerlukan Python Agent SDK 0.2.140 atau lebih baru. Versi 0.1.31 hingga 0.2.139 mengekspor ulang mcp.types.ToolAnnotations tanpa perubahan. Pada versi 0.1.55 hingga 0.2.139 Anda masih dapat melewatkan maxResultSizeChars sebagai argumen kata kunci: kelas MCP menerima field tambahan, dan SDK meneruskan nilai ke Claude Code.

Semua field bersifat opsional. Klien tidak boleh mengandalkan petunjuk untuk keputusan keamanan.

from claude_agent_sdk import tool, ToolAnnotations
from typing import Any


@tool(
    "search",
    "Search the web",
    {"query": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
)
async def search(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}

`create_sdk_mcp_server()`

Buat server MCP dalam proses yang berjalan dalam aplikasi Python Anda.

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

Parameter

Pengembalian

Mengembalikan objek McpSdkServerConfig yang dapat diteruskan ke ClaudeAgentOptions.mcp_servers.

Contoh

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions


@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}


@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args):
    return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}


calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply],  # Pass decorated functions
)

# Use with Claude
options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
)

`list_sessions()`

Mencantumkan sesi masa lalu dengan metadata. Filter berdasarkan direktori proyek atau cantumkan sesi di semua proyek. Sinkron; mengembalikan segera.

def list_sessions(
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    include_worktrees: bool = True
) -> list[SDKSessionInfo]

Parameter

Tipe pengembalian: `SDKSessionInfo`

Contoh

Cetak 10 sesi terbaru untuk proyek. Hasil diurutkan berdasarkan last_modified menurun, jadi item pertama adalah yang terbaru. Hilangkan directory untuk mencari di semua proyek.

from claude_agent_sdk import list_sessions

for session in list_sessions(directory="/path/to/project", limit=10):
    print(f"{session.summary} ({session.session_id})")

`get_session_messages()`

Mengambil pesan dari sesi masa lalu. Sinkron; mengembalikan segera.

def get_session_messages(
    session_id: str,
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0
) -> list[SessionMessage]

Parameter

Tipe pengembalian: `SessionMessage`

Contoh

from claude_agent_sdk import list_sessions, get_session_messages

sessions = list_sessions(limit=1)
if sessions:
    messages = get_session_messages(sessions[0].session_id)
    for msg in messages:
        print(f"[{msg.type}] {msg.uuid}")

`get_session_info()`

Membaca metadata untuk sesi tunggal berdasarkan ID tanpa memindai direktori proyek lengkap. Sinkron; mengembalikan segera.

def get_session_info(
    session_id: str,
    directory: str | None = None,
) -> SDKSessionInfo | None

Parameter

Mengembalikan SDKSessionInfo, atau None jika sesi tidak ditemukan.

Contoh

Cari metadata sesi tunggal tanpa memindai direktori proyek. Berguna ketika Anda sudah memiliki ID sesi dari run sebelumnya.

from claude_agent_sdk import get_session_info

info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
if info:
    print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")

`rename_session()`

Mengganti nama sesi dengan menambahkan entri judul kustom. Panggilan berulang aman; judul terbaru menang. Sinkron.

def rename_session(
    session_id: str,
    title: str,
    directory: str | None = None,
) -> None

Parameter

Menimbulkan ValueError jika session_id bukan UUID yang valid atau title kosong; FileNotFoundError jika sesi tidak dapat ditemukan.

Contoh

Ganti nama sesi terbaru sehingga lebih mudah ditemukan nanti. Judul baru muncul di SDKSessionInfo.custom_title pada pembacaan berikutnya.

from claude_agent_sdk import list_sessions, rename_session

sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    rename_session(sessions[0].session_id, "Refactor auth module")

`tag_session()`

Menandai sesi. Teruskan None untuk menghapus tag. Panggilan berulang aman; tag terbaru menang. Sinkron.

def tag_session(
    session_id: str,
    tag: str | None,
    directory: str | None = None,
) -> None

Parameter

Menimbulkan ValueError jika session_id bukan UUID yang valid atau tag kosong setelah sanitasi; FileNotFoundError jika sesi tidak dapat ditemukan.

Contoh

Tandai sesi, kemudian filter berdasarkan tag itu pada pembacaan nanti. Teruskan None untuk menghapus tag yang ada.

from claude_agent_sdk import list_sessions, tag_session

# Tag the most recent session
sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    tag_session(sessions[0].session_id, "needs-review")

# Later: find all sessions with that tag
for session in list_sessions(directory="/path/to/project"):
    if session.tag == "needs-review":
        print(session.summary)

Kelas

`ClaudeSDKClient`

Mempertahankan sesi percakapan di beberapa pertukaran. Ini adalah setara Python dari cara fungsi query() SDK TypeScript bekerja secara internal - ia membuat objek klien yang dapat melanjutkan percakapan. Lihat perbandingan dengan query().

class ClaudeSDKClient:
    def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)
    async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
    async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
    async def receive_messages(self) -> AsyncIterator[Message]
    async def receive_response(self) -> AsyncIterator[Message]
    async def interrupt(self) -> None
    async def set_permission_mode(self, mode: PermissionMode) -> None
    async def set_model(self, model: str | None = None) -> None
    async def rewind_files(self, user_message_id: str) -> None
    async def get_mcp_status(self) -> McpStatusResponse
    async def reconnect_mcp_server(self, server_name: str) -> None
    async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
    async def stop_task(self, task_id: str) -> None
    async def get_server_info(self) -> dict[str, Any] | None
    async def disconnect(self) -> None

Metode

Dukungan Context Manager

Klien dapat digunakan sebagai async context manager untuk manajemen koneksi otomatis:

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def main():
    async with ClaudeSDKClient() as client:
        await client.query("Hello Claude")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Penting: Saat mengulangi pesan, hindari menggunakan break untuk keluar lebih awal karena ini dapat menyebabkan masalah pembersihan asyncio. Sebaliknya, biarkan iterasi selesai secara alami atau gunakan flag untuk melacak kapan Anda menemukan apa yang Anda butuhkan.

Contoh - Melanjutkan percakapan

import asyncio
from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage


async def main():
    async with ClaudeSDKClient() as client:
        # First question
        await client.query("What's the capital of France?")

        # Process response
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Follow-up question - the session retains the previous context
        await client.query("What's the population of that city?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Another follow-up - still in the same conversation
        await client.query("What are some famous landmarks there?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")


asyncio.run(main())

Contoh - Streaming input dengan ClaudeSDKClient

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def message_stream():
    """Generate messages dynamically."""
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Analyze the following data:"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "What patterns do you see?"},
    }


async def main():
    async with ClaudeSDKClient() as client:
        # Stream input to Claude
        await client.query(message_stream())

        # Process response
        async for message in client.receive_response():
            print(message)

        # Follow-up in same session
        await client.query("Should we be concerned about these readings?")

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


asyncio.run(main())

Contoh - Menggunakan interrupts

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage


async def interruptible_task():
    options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")

    async with ClaudeSDKClient(options=options) as client:
        # Start a long-running task
        await client.query("Count from 1 to 100 slowly, using the bash sleep command")

        # Let it run for a bit
        await asyncio.sleep(2)

        # Interrupt the task
        await client.interrupt()
        print("Task interrupted!")

        # Drain the interrupted task's messages (including its ResultMessage)
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Interrupted task: terminal_reason={message.terminal_reason!r}")
                # terminal_reason is "aborted_streaming" or "aborted_tools"
                # for interrupted turns

        # Send a new command
        await client.query("Just say hello instead")

        # Now receive the new response
        async for message in client.receive_response():
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(f"New result: {message.result}")


asyncio.run(interruptible_task())

Contoh - Kontrol izin lanjutan

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def custom_permission_handler(
    tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    """Custom logic for tool permissions."""

    # Block writes to system directories
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(
            message="System directory write not allowed", interrupt=True
        )

    # Redirect sensitive file operations
    if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
        safe_path = f"./sandbox/{input_data['file_path']}"
        return PermissionResultAllow(
            updated_input={**input_data, "file_path": safe_path}
        )

    # Allow everything else
    return PermissionResultAllow(updated_input=input_data)


async def main():
    # Jangan juga daftarkan tools yang dibatasi dalam allowed_tools: aturan izin menyetujui panggilan sebelum can_use_tool berjalan
    options = ClaudeAgentOptions(can_use_tool=custom_permission_handler)

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Update the system config file")

        async for message in client.receive_response():
            # Will use sandbox path instead
            print(message)


asyncio.run(main())

Tipe

`SdkMcpTool`

Definisi untuk tool SDK MCP yang dibuat dengan dekorator @tool.

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]
    annotations: ToolAnnotations | None = None

`Transport`

Kelas dasar abstrak untuk implementasi transport kustom. Gunakan ini untuk berkomunikasi dengan proses Claude melalui saluran kustom (misalnya, koneksi jarak jauh alih-alih subprocess lokal).

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from typing import Any


class Transport(ABC):
    @abstractmethod
    async def connect(self) -> None: ...

    @abstractmethod
    async def write(self, data: str) -> None: ...

    @abstractmethod
    def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...

    @abstractmethod
    async def close(self) -> None: ...

    @abstractmethod
    def is_ready(self) -> bool: ...

    @abstractmethod
    async def end_input(self) -> None: ...

Impor: from claude_agent_sdk import Transport

`ClaudeAgentOptions`

Dataclass konfigurasi untuk query Claude Code.

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | SystemPromptCustom | SystemPromptFile | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    strict_mcp_config: bool = False
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    session_id: str | None = None
    max_turns: int | None = None
    max_budget_usd: float | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    fallback_model: str | None = None
    betas: list[SdkBeta] = field(default_factory=list)
    output_format: dict[str, Any] | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    cli_path: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)
    max_buffer_size: int | None = None
    debug_stderr: Any = sys.stderr  # Deprecated
    stderr: Callable[[str], None] | None = None
    can_use_tool: CanUseTool | None = None
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
    user: str | None = None
    include_partial_messages: bool = False
    include_hook_events: bool = False
    forward_subagent_text: bool = False
    fork_session: bool = False
    resume_session_at: str | None = None
    resume_drops_turn: str | None = None
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    skills: list[str] | Literal["all"] | None = None
    sandbox: SandboxSettings | None = None
    plugins: list[SdkPluginConfig] = field(default_factory=list)
    max_thinking_tokens: int | None = None  # Deprecated: use thinking instead
    thinking: ThinkingConfig | None = None
    effort: EffortLevel | None = None
    enable_file_checkpointing: bool = False
    session_store: SessionStore | None = None
    session_store_flush: SessionStoreFlushMode = "batched"
    load_timeout_ms: int = 60_000
    task_budget: TaskBudget | None = None

Menangani respons API yang lambat atau terhenti

Subprocess CLI membaca beberapa variabel lingkungan yang mengontrol timeout API dan deteksi stall. Teruskan melalui ClaudeAgentOptions.env:

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    env={
        "API_TIMEOUT_MS": "120000",
        "CLAUDE_CODE_MAX_RETRIES": "2",
        "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",
    },
)

• API_TIMEOUT_MS: timeout per-permintaan pada klien Anthropic, dalam milidetik. Default 600000. Berlaku untuk loop utama dan semua subagent.

• CLAUDE_CODE_MAX_RETRIES: maksimal retry API. Default 10, dibatasi pada 15. Setiap retry mendapat jendela API_TIMEOUT_MS sendiri, jadi waktu dinding terburuk kira-kira API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) ditambah backoff. Untuk run tanpa pengawasan yang perlu menunggu melalui pemadaman yang lebih lama, atur CLAUDE_CODE_RETRY_WATCHDOG=1: itu retry error kapasitas transien tanpa batas dan, pada Claude Code v2.1.199 atau lebih baru, menaikkan default untuk error transien lainnya menjadi 300 dan menghapus batas pada variabel ini.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog stall untuk subagent. Sementara watchdog stream aktif, default adalah CLAUDE_STREAM_IDLE_TIMEOUT_MS ditambah 5 menit, yang menjadi 600000 kecuali Anda menaikkan variabel itu. Dengan watchdog stream mati, default adalah 600000. Sebelum v2.1.257, default selalu 600000.

  Timer direset pada setiap event stream. Pada stall, Claude Code membatalkan subagent dan melaporkan stall ke parent. Untuk subagent latar belakang, itu juga menandai tugas gagal dan melampirkan hasil parsial apa pun.

• CLAUDE_ENABLE_STREAM_WATCHDOG dengan CLAUDE_STREAM_IDLE_TIMEOUT_MS: watchdog stream yang membatalkan permintaan ketika header telah tiba tetapi badan respons berhenti streaming. Watchdog aktif secara default untuk semua penyedia; atur CLAUDE_ENABLE_STREAM_WATCHDOG=0 untuk menonaktifkannya. CLAUDE_STREAM_IDLE_TIMEOUT_MS default ke 300000 dan diklem ke minimum itu. Setelah pembatalan, Automatic retries mencakup apa yang Claude Code lakukan, berdasarkan seberapa jauh respons telah maju.

  Sementara watchdog menunggu respons yang gateway di belakang ANTHROPIC_BASE_URL tahan terbuka dengan keep-alive pings, host yang mengatur include_partial_messages terus menerima pesan ping StreamEvent. Baca frame tersebut sebagai liveness daripada timeout sesi pada keheningan. Sebelum v2.1.257, frame berhenti 5 menit setelah event stream nyata terakhir.

`OutputFormat`

Konfigurasi untuk validasi output terstruktur. Teruskan ini sebagai dict ke field output_format pada ClaudeAgentOptions:

# Expected dict shape for output_format
{
    "type": "json_schema",
    "schema": {...},  # Your JSON Schema definition
}

`SystemPromptPreset`

Konfigurasi untuk menggunakan preset system prompt Claude Code dengan penambahan opsional.

class SystemPromptPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]
    append: NotRequired[str]
    exclude_dynamic_sections: NotRequired[bool]
    snapshot: NotRequired[bool]

`SystemPromptCustom`

Prompt system kustom dalam bentuk objek, setara dengan melewatkan string sebagai system_prompt, yang juga dapat mengatur snapshot. Memerlukan claude-agent-sdk v0.2.153 atau lebih baru.

class SystemPromptCustom(TypedDict):
    type: Literal["custom"]
    prompt: str
    snapshot: NotRequired[bool]

`SystemPromptFile`

Konfigurasi untuk memuat system prompt kustom dari file alih-alih meneruskannya sebagai string. SDK memetakan ini ke flag CLI --system-prompt-file. Gunakan bentuk file ketika prompt besar: SDK meneruskan string system_prompt pada argv subprocess CLI, yang tunduk pada batas panjang command-line OS sebelum SDK mengirim permintaan API apa pun. Di Linux satu argumen lebih panjang dari kira-kira 128 KB gagal pada spawn proses dengan Argument list too long. Di Windows seluruh command line dibatasi pada kira-kira 32 KB, jadi bentuk string gagal pada ambang yang lebih rendah.

class SystemPromptFile(TypedDict):
    type: Literal["file"]
    path: str

`SettingSource`

Mengontrol sumber konfigurasi berbasis filesystem mana yang dimuat pengaturan SDK.

SettingSource = Literal["user", "project", "local"]

Perilaku default

Ketika setting_sources dihilangkan atau None dan skills tidak diatur, query() memuat pengaturan filesystem yang sama seperti CLI Claude Code: pengguna, proyek, dan lokal. Dengan skills diatur, baris setting_sources menjelaskan default saat ini. Pengaturan kebijakan terkelola endpoint dimuat dalam semua kasus; pengaturan yang dikelola server diambil ketika sesi mengautentikasi dengan kredensial organisasi pada konfigurasi yang memenuhi syarat. Untuk informasi lebih lanjut, lihat What settingSources does not control.

Mengapa menggunakan setting\_sources

Nonaktifkan pengaturan filesystem:

# Do not load user, project, or local settings from disk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Analyze this code",
        options=ClaudeAgentOptions(
            setting_sources=[]
        ),
    ):
        print(message)


asyncio.run(main())

Muat hanya sumber pengaturan tertentu:

# Load only project settings, ignore user and local
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Run CI checks",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Only .claude/settings.json
        ),
    ):
        print(message)


asyncio.run(main())

Aplikasi SDK-only:

# Define everything programmatically.
# Pass [] to opt out of filesystem setting sources.
import asyncio
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Review this PR",
        options=ClaudeAgentOptions(
            setting_sources=[],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Reviews code changes",
                    prompt="You are a code reviewer. Report issues in the diff.",
                ),
            },
            allowed_tools=["Read", "Grep", "Glob"],
        ),
    ):
        print(message)


asyncio.run(main())

Untuk memuat instruksi proyek CLAUDE.md, sertakan "project" dalam setting_sources. Lihat Modify system prompts untuk cara loading CLAUDE.md berinteraksi dengan opsi system prompt.

Preseden pengaturan

Ketika beberapa sumber dimuat, pengaturan digabungkan dengan preseden ini (tertinggi ke terendah):

1. Pengaturan lokal (.claude/settings.local.json)
2. Pengaturan proyek (.claude/settings.json)
3. Pengaturan pengguna (~/.claude/settings.json)

Opsi programatis seperti agents, allowed_tools, dan settings mengganti pengaturan filesystem pengguna, proyek, dan lokal. Pengaturan kebijakan terkelola mengambil prioritas atas opsi programatis.

`AgentDefinition`

Konfigurasi untuk subagent yang didefinisikan secara programatis.

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    disallowedTools: list[str] | None = None
    model: str | None = None
    skills: list[str] | None = None
    memory: Literal["user", "project", "local"] | None = None
    mcpServers: list[str | dict[str, Any]] | None = None
    initialPrompt: str | None = None
    maxTurns: int | None = None
    background: bool | None = None
    effort: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

`PermissionMode`

Mode izin untuk mengontrol eksekusi tool.

PermissionMode = Literal[
    "default",  # Standard permission behavior
    "acceptEdits",  # Auto-accept file edits
    "plan",  # Planning mode - explore without editing
    "dontAsk",  # Deny anything not pre-approved instead of prompting
    "bypassPermissions",  # Bypass permission checks; explicit ask rules still prompt (use with caution)
    "auto",  # Model classifier approves or denies permission prompts
]

`EffortLevel`

Tingkat usaha untuk membimbing kedalaman thinking.

EffortLevel = Literal[
    "low",  # Minimal thinking, fastest responses
    "medium",  # Moderate thinking
    "high",  # Deep reasoning
    "xhigh",  # Extended reasoning; falls back to "high" on models that don't support it
    "max",  # Maximum effort
]

`CanUseTool`

Type alias untuk fungsi callback izin tool.

CanUseTool = Callable[
    [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
]

Callback menerima:

• tool_name: Nama tool yang sedang dipanggil
• input_data: Parameter input tool
• context: ToolPermissionContext dengan informasi tambahan

Mengembalikan PermissionResult (baik PermissionResultAllow atau PermissionResultDeny).

Callback adalah pengganti SDK untuk prompt izin interaktif: dipanggil hanya ketika alur evaluasi izin diselesaikan ke prompt. Panggilan tool yang sudah disetujui oleh entri allowed_tools, aturan allow pengaturan, atau mode izin, seperti acceptEdits atau bypassPermissions, tidak pernah memanggilnya. Untuk gating setiap panggilan tool, gunakan hook PreToolUse sebagai gantinya.

Aturan allow tidak pre-approve tindakan yang tidak ada mode auto-approve; lihat How permissions are evaluated untuk mana dari mereka yang mencapai callback dan apa yang terjadi dalam mode dontAsk dan auto.

`ToolPermissionContext`

Informasi konteks yang diteruskan ke callback izin tool.

@dataclass
class ToolPermissionContext:
    signal: Any | None = None  # Future: abort signal support
    suggestions: list[PermissionUpdate] = field(default_factory=list)
    tool_use_id: str | None = None
    agent_id: str | None = None
    blocked_path: str | None = None
    decision_reason: str | None = None
    title: str | None = None
    display_name: str | None = None
    description: str | None = None

`PermissionResult`

Tipe union untuk hasil callback izin.

PermissionResult = PermissionResultAllow | PermissionResultDeny

`PermissionResultAllow`

Hasil yang menunjukkan panggilan tool harus diizinkan.

@dataclass
class PermissionResultAllow:
    behavior: Literal["allow"] = "allow"
    updated_input: dict[str, Any] | None = None
    updated_permissions: list[PermissionUpdate] | None = None

`PermissionResultDeny`

Hasil yang menunjukkan panggilan tool harus ditolak.

@dataclass
class PermissionResultDeny:
    behavior: Literal["deny"] = "deny"
    message: str = ""
    interrupt: bool = False

`PermissionUpdate`

Konfigurasi untuk memperbarui izin secara programatis.

@dataclass
class PermissionUpdate:
    type: Literal[
        "addRules",
        "replaceRules",
        "removeRules",
        "setMode",
        "addDirectories",
        "removeDirectories",
    ]
    rules: list[PermissionRuleValue] | None = None
    behavior: Literal["allow", "deny", "ask"] | None = None
    mode: PermissionMode | None = None
    directories: list[str] | None = None
    destination: (
        Literal["userSettings", "projectSettings", "localSettings", "session"] | None
    ) = None

`PermissionRuleValue`

Aturan untuk ditambahkan, diganti, atau dihapus dalam pembaruan izin.

@dataclass
class PermissionRuleValue:
    tool_name: str
    rule_content: str | None = None

`ToolsPreset`

Konfigurasi preset tools untuk menggunakan set tool default Claude Code.

class ToolsPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]

`ThinkingConfig`

Mengontrol perilaku extended thinking. Union dari tiga konfigurasi:

ThinkingDisplay = Literal["summarized", "omitted"]


class ThinkingConfigAdaptive(TypedDict):
    type: Literal["adaptive"]
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigEnabled(TypedDict):
    type: Literal["enabled"]
    budget_tokens: int
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigDisabled(TypedDict):
    type: Literal["disabled"]


ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

Field opsional display mengontrol apakah teks thinking dikembalikan "summarized" atau "omitted". Pada Claude Opus 4.7 dan lebih baru, default API adalah "omitted", jadi atur "summarized" untuk menerima konten thinking dalam output ThinkingBlock. Claude Code tidak mengirim display ke Amazon Bedrock atau Google Cloud's Agent Platform, jadi pada penyedia tersebut Opus 4.7 dan lebih baru mengembalikan output ThinkingBlock kosong bahkan ketika Anda mengatur display ke "summarized".

Karena ini adalah kelas TypedDict, mereka adalah dict biasa saat runtime. Baik buatlah sebagai dict literal atau panggil kelas seperti konstruktor; keduanya menghasilkan dict. Akses field dengan config["budget_tokens"], bukan config.budget_tokens:

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# Option 1: dict literal (recommended, no import needed)
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# Option 2: constructor-style (returns a plain dict)
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens would raise AttributeError

`TaskBudget`

Budget tugas sisi API dalam token, digunakan dengan field task_budget dalam ClaudeAgentOptions.

class TaskBudget(TypedDict):
    total: int

Karena ini adalah TypedDict, teruskan sebagai dict biasa, seperti ClaudeAgentOptions(task_budget={"total": 50000}).

`SdkBeta`

Tipe literal untuk fitur beta SDK.

SdkBeta = Literal["context-1m-2025-08-07"]

Gunakan dengan field betas dalam ClaudeAgentOptions untuk mengaktifkan fitur beta.

`McpSdkServerConfig`

Konfigurasi untuk server MCP SDK yang dibuat dengan create_sdk_mcp_server().

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # MCP Server instance

`McpServerConfig`

Tipe union untuk konfigurasi server MCP.

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
    command: str
    args: NotRequired[list[str]]
    env: NotRequired[dict[str, str]]

`McpSSEServerConfig`

class McpSSEServerConfig(TypedDict):
    type: Literal["sse"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpHttpServerConfig`

class McpHttpServerConfig(TypedDict):
    type: Literal["http"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpServerStatusConfig`

Konfigurasi server MCP seperti yang dilaporkan oleh get_mcp_status(). Ini adalah union dari semua varian transport McpServerConfig ditambah varian output-only claudeai-proxy untuk server yang di-proxy melalui claude.ai.

McpServerStatusConfig = (
    McpStdioServerConfig
    | McpSSEServerConfig
    | McpHttpServerConfig
    | McpSdkServerConfigStatus
    | McpClaudeAIProxyServerConfig
)

McpSdkServerConfigStatus adalah bentuk yang dapat diserialisasi dari McpSdkServerConfig dengan hanya field type ("sdk") dan name (str); instance dalam proses dihilangkan. McpClaudeAIProxyServerConfig memiliki field type ("claudeai-proxy"), url (str), dan id (str).

`McpStatusResponse`

Respons dari ClaudeSDKClient.get_mcp_status(). Membungkus daftar status server di bawah kunci mcpServers.

class McpStatusResponse(TypedDict):
    mcpServers: list[McpServerStatus]

`McpServerStatus`

Status server MCP yang terhubung, terdapat dalam McpStatusResponse.

class McpServerStatus(TypedDict):
    name: str
    status: McpServerConnectionStatus  # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
    serverInfo: NotRequired[McpServerInfo]
    error: NotRequired[str]
    config: NotRequired[McpServerStatusConfig]
    scope: NotRequired[str]
    tools: NotRequired[list[McpToolInfo]]

`SdkPluginConfig`

Konfigurasi untuk memuat plugins dalam SDK.

class SdkPluginConfig(TypedDict):
    type: Literal["local"]
    path: str

Contoh:

plugins = [
    {"type": "local", "path": "./my-plugin"},
    {"type": "local", "path": "/absolute/path/to/plugin"},
]

Untuk informasi lengkap tentang membuat dan menggunakan plugins, lihat Plugins.

Tipe Pesan

`Message`

Tipe union dari semua pesan yang mungkin.

Message = (
    UserMessage
    | AssistantMessage
    | SystemMessage
    | ResultMessage
    | StreamEvent
    | RateLimitEvent
    | ConversationResetMessage
)

`UserMessage`

Pesan input pengguna.

@dataclass
class UserMessage:
    content: str | list[ContentBlock]
    uuid: str | None = None
    parent_tool_use_id: str | None = None
    tool_use_result: dict[str, Any] | None = None
    origin: MessageOrigin | None = None

SDK melewatkan tool_use_result melalui dari CLI tanpa modifikasi. Untuk tool pada server MCP eksternal yang hasilnya berisi blok resource_link, dict memiliki kunci resourceLinks yang menyimpan daftar dict dengan kunci dari tipe TypeScript SDKMcpResourceLink. Claude menerima setiap link sebagai baris teks dalam hasil tool. Untuk merender file yang dikembalikan server, baca resourceLinks alih-alih mengurai teks itu. Kunci resourceLinks memerlukan Python Agent SDK 0.2.150 atau lebih baru dan Claude Code v2.1.257 atau lebih baru; CLI yang dibundel dengan versi SDK itu memenuhi persyaratan Claude Code.

CLI menghilangkan kunci ketika hasil tidak memiliki link dan pada hasil dari subagent. CLI menyimpan paling banyak 50 link per hasil dan berhenti menambahkan link setelah daftar mencapai 64 KiB JSON yang diserialisasi. Tool yang Anda tentukan dalam proses dengan tool() tidak pernah menghasilkan kunci, karena SDK meratakan blok resource_link menjadi teks sebelum CLI melihat hasil.

`AssistantMessage`

Pesan respons asisten dengan blok konten.

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None
    usage: dict[str, Any] | None = None
    message_id: str | None = None
    stop_reason: str | None = None
    session_id: str | None = None
    uuid: str | None = None

`AssistantMessageError`

Tipe error yang mungkin untuk pesan asisten.

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "unknown",
]

Proses CLI yang mendasar dapat memancarkan tipe error yang Literal ini tidak daftar, seperti max_output_tokens. SDK melewatkan nilai tanpa modifikasi, jadi perlakukan string di luar daftar ini seperti Anda memperlakukan unknown. Tipe TypeScript SDKAssistantMessageError mencantumkan set lengkap nilai yang dapat dipancarkan CLI.

`SystemMessage`

Pesan sistem dengan metadata.

@dataclass
class SystemMessage:
    subtype: str
    data: dict[str, Any]

`ResultMessage`

Pesan hasil akhir dengan informasi biaya dan penggunaan.

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    stop_reason: str | None = None
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None
    structured_output: Any = None
    model_usage: dict[str, ModelUsage] | None = None
    permission_denials: list[Any] | None = None
    deferred_tool_use: DeferredToolUse | None = None
    errors: list[str] | None = None
    api_error_status: int | None = None
    uuid: str | None = None
    terminal_reason: str | None = None
    origin: MessageOrigin | None = None

Field subtype menentukan field mana yang lainnya diisi. Ini adalah salah satu dari "success", "error_during_execution", "error_max_turns", "error_max_budget_usd", atau "error_max_structured_output_retries". Dataclass Python meratakan semua varian menjadi satu bentuk, jadi field yang tidak berlaku untuk subtype yang dikembalikan adalah None.

Beberapa field membawa detail diagnostik tentang bagaimana percakapan berakhir:

• is_error: True ketika percakapan berakhir dalam status error. Selalu True pada subtype error_*. Pada subtype="success" ini adalah True ketika permintaan model terakhir gagal, berarti loop agen selesai tetapi panggilan API terakhir mengembalikan error.
• api_error_status: kode status HTTP dari error API yang mengakhiri. None ketika putaran berakhir tanpa satu. Diisi hanya pada subtype="success".
• result: teks pesan asisten terakhir pada subtype="success", atau None pada subtype error_*. Ketika subtype="success" dan is_error=True, ini menyimpan string error API jika tersedia tetapi dapat kosong, jadi periksa api_error_status dan konten AssistantMessage sebelumnya untuk detail.
• errors: string error tingkat loop seperti pesan max-turns. Diisi hanya pada subtype error_*.
• terminal_reason: mengapa loop query berakhir, seperti "completed", "max_turns", "api_error", "aborted_streaming", atau "aborted_tools". Nilai "aborted_streaming" atau "aborted_tools" berarti putaran dibatalkan sebelum selesai. Penyebab umum adalah interrupt() dan callback izin mengembalikan PermissionResultDeny dengan interrupt=True. None pada versi CLI yang mendahului field, pada hasil dari perintah lokal seperti /voice atau /usage, yang melewati loop query, atau pada hasil error yang disintesis yang dipancarkan ketika sesi gagal secara fatal. Mencerminkan SDKResultMessage.terminal_reason SDK TypeScript, yang mencantumkan set lengkap nilai.
• origin: asal pesan pengguna yang memicu putaran ini. Dalam mode input streaming, periksa ini untuk membedakan hasil prompt Anda sendiri, di mana origin adalah None atau {"kind": "human"}, dari hasil putaran yang disuntikkan seperti notifikasi tugas latar belakang. Memerlukan Python Agent SDK 0.2.137 atau lebih baru.

Dict usage mencakup loop agen utama saja dan mengecualikan subagent dan panggilan model bersarang atau tambahan lainnya. Dalam mode input streaming, nilainya per-putaran. Lebih suka model_usage untuk akuntansi token dan biaya. Dict usage berisi kunci berikut ketika ada:

Dict model_usage memetakan nama model ke penggunaan per-model. Ini mencakup setiap panggilan model yang dibuat melalui pipeline query: loop utama, subagent, dan panggilan internal seperti compaction dan Workflow agents. Panggilan helper di luar pipeline itu, seperti classifier izin dan permintaan penghitungan token, dikecualikan dari model_usage. Perlakukan model_usage sebagai perkiraan, bukan pernyataan penagihan.

Dalam mode input streaming, model_usage dan total_cost_usd adalah kumulatif di seluruh putaran, jadi baca hasil terbaru daripada menjumlahkan di seluruh hasil. Panggilan yang melanjutkan sesi juga menghitung total yang dipulihkan dari panggilan sebelumnya sesi. Lihat Track costs in streaming input mode untuk reset dan Recover totals after a session crash untuk hasil yang dinolkan.

Setiap nilai dalam model_usage adalah TypedDict ModelUsage, diimpor melalui from claude_agent_sdk.types import ModelUsage. Kuncinya menggunakan camelCase karena SDK melewatkan nilai tanpa modifikasi dari proses CLI yang mendasar, cocok dengan tipe TypeScript ModelUsage:

`StreamEvent`

Event stream untuk pembaruan pesan parsial selama streaming. Hanya diterima ketika include_partial_messages=True dalam ClaudeAgentOptions. Impor melalui from claude_agent_sdk.types import StreamEvent.

@dataclass
class StreamEvent:
    uuid: str
    session_id: str
    event: dict[str, Any]  # The raw Claude API stream event
    parent_tool_use_id: str | None = None

`RateLimitEvent`

Dipancarkan ketika status rate limit berubah (misalnya, dari "allowed" ke "allowed_warning"). Gunakan ini untuk memperingatkan pengguna sebelum mereka mencapai batas keras, atau untuk mundur ketika status adalah "rejected".

@dataclass
class RateLimitEvent:
    rate_limit_info: RateLimitInfo
    uuid: str
    session_id: str

`RateLimitInfo`

Status rate limit yang dibawa oleh RateLimitEvent.

RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
RateLimitType = Literal[
    "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
]


@dataclass
class RateLimitInfo:
    status: RateLimitStatus
    resets_at: int | None = None
    rate_limit_type: RateLimitType | None = None
    utilization: float | None = None
    overage_status: RateLimitStatus | None = None
    overage_resets_at: int | None = None
    overage_disabled_reason: str | None = None
    raw: dict[str, Any] = field(default_factory=dict)

`ConversationResetMessage`

Dipancarkan ketika percakapan diganti tanpa mengakhiri koneksi, seperti setelah /clear. Lihat Track costs in streaming input mode untuk bagaimana reset mempengaruhi total yang berjalan pada objek ResultMessage berikutnya. Memerlukan Python Agent SDK 0.2.137 atau lebih baru.

@dataclass
class ConversationResetMessage:
    new_conversation_id: str
    uuid: str
    session_id: str

`TaskStartedMessage`

Dipancarkan ketika tugas latar belakang dimulai. Tugas latar belakang adalah apa pun yang dilacak di luar putaran utama: perintah Bash yang di-background, Monitor watch, subagent yang dihasilkan melalui tool Agent, atau agent jarak jauh. Field task_type memberi tahu Anda yang mana. Penamaan ini tidak terkait dengan penggantian nama tool Task-ke-Agent.

@dataclass
class TaskStartedMessage(SystemMessage):
    task_id: str
    description: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    task_type: str | None = None

`TaskUsage`

Data token dan timing untuk tugas latar belakang.

class TaskUsage(TypedDict):
    total_tokens: int
    tool_uses: int
    duration_ms: int

`TaskProgressMessage`

Dipancarkan secara berkala dengan pembaruan kemajuan untuk tugas latar belakang yang sedang berjalan.

@dataclass
class TaskProgressMessage(SystemMessage):
    task_id: str
    description: str
    usage: TaskUsage
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    last_tool_name: str | None = None

`TaskNotificationMessage`

Dipancarkan ketika tugas latar belakang selesai, gagal, atau dihentikan. Tugas latar belakang termasuk perintah Bash run_in_background, Monitor watches, dan subagent latar belakang.

@dataclass
class TaskNotificationMessage(SystemMessage):
    task_id: str
    status: TaskNotificationStatus  # "completed" | "failed" | "stopped"
    output_file: str
    summary: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    usage: TaskUsage | None = None

Ketika CLI memindahkan panggilan tool MCP yang panjang ke latar belakang, hasil tool untuk panggilan itu hanya menyimpan placeholder dan hasil nyata panggilan tiba dalam pesan ini. Pada notifikasi "completed" untuk panggilan seperti itu, CLI menambahkan kunci resource_links yang mencantumkan file yang dikembalikan tool dengan referensi, dengan entri dan batas yang sama seperti kunci resourceLinks pada UserMessage.tool_use_result. Kunci resource_links memerlukan Python Agent SDK 0.2.150 atau lebih baru dan Claude Code v2.1.257 atau lebih baru; CLI yang dibundel dengan versi SDK itu memenuhi persyaratan Claude Code.

Dataclass tidak memiliki field untuk resource_links. Bacanya dari dict data yang diwariskan pesan dari SystemMessage: message.data.get("resource_links"). Cocokkan notifikasi dengan panggilan menggunakan tool_use_id. CLI menghilangkan kunci ketika hasil tidak memiliki link dan pada notifikasi untuk tugas yang bukan panggilan tool MCP.

Tipe Blok Konten

`ContentBlock`

Tipe union dari semua blok konten.

ContentBlock = (
    TextBlock
    | ThinkingBlock
    | ToolUseBlock
    | ToolResultBlock
    | ServerToolUseBlock
    | ServerToolResultBlock
)

`TextBlock`

Blok konten teks.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Blok konten thinking (untuk model dengan kemampuan thinking).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Blok permintaan penggunaan tool.

@dataclass
class ToolUseBlock:
    id: str
    name: str
    input: dict[str, Any]

`ToolResultBlock`

Blok hasil eksekusi tool.

@dataclass
class ToolResultBlock:
    tool_use_id: str
    content: str | list[dict[str, Any]] | None = None
    is_error: bool | None = None

Tipe Error

Tipe-tipe di bawah ini mendefinisikan apa yang ditangkap kode Anda. Untuk entri yang dikunci ke pesan error yang diangkat tipe-tipe ini, dengan penyebab dan perbaikan untuk masing-masing, lihat Troubleshooting.

`ClaudeSDKError`

Kelas exception dasar untuk semua error SDK.

class ClaudeSDKError(Exception):
    """Base error for Claude SDK."""

Ketika query() single-shot berakhir dengan hasil error, misalnya error turn-limit, SDK mengangkat ResultError setelah menghasilkan pesan hasil akhir. Versi Python Agent SDK sebelum 0.2.140 mengangkat Exception biasa yang bukan subkelas ClaudeSDKError.

`CLINotFoundError`

Diangkat ketika Claude Code CLI tidak diinstal atau tidak ditemukan.

class CLINotFoundError(CLIConnectionError):
    def __init__(
        self, message: str = "Claude Code not found", cli_path: str | None = None
    ):
        """
        Args:
            message: Error message (default: "Claude Code not found")
            cli_path: Optional path to the CLI that was not found
        """

`CLIConnectionError`

Diangkat ketika koneksi ke Claude Code gagal.

class CLIConnectionError(ClaudeSDKError):
    """Failed to connect to Claude Code."""

`ProcessError`

Diangkat ketika proses Claude Code gagal.

class ProcessError(ClaudeSDKError):
    def __init__(
        self, message: str, exit_code: int | None = None, stderr: str | None = None
    ):
        self.exit_code = exit_code
        self.stderr = stderr

`ResultError`

Diangkat setelah ResultMessage akhir ketika proses Claude Code keluar karena run berakhir dengan hasil error, seperti error turn-limit atau error API. ResultError adalah subkelas ProcessError, jadi handler except ProcessError yang sudah ada juga menangkapnya. Atributnya membawa bidang-bidang dari pesan hasil tersebut, sehingga Anda dapat membuat cabang tentang mengapa run gagal tanpa mengurai teks pesan. Memerlukan Python Agent SDK 0.2.140 atau lebih baru.

class ResultError(ProcessError):
    subtype: str | None  # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
    errors: list[str]  # an empty list when the result message reported none
    result: str | None
    api_error_status: int | None
    terminal_reason: str | None  # "max_turns", "api_error", ...; check this before subtype
    session_id: str | None
    data: dict[str, Any]  # the raw result message payload

Untuk membedakan kegagalan, periksa terminal_reason sebelum subtype. Ketika permintaan akhir gagal, seperti pada error API, Claude Code melaporkan subtype "success" dengan penyebab dalam terminal_reason, misalnya "api_error"; ketika batas yang Anda tetapkan mengakhiri run, seperti max_turns atau max_budget_usd, itu melaporkan subtype error_*.

`CLIJSONDecodeError`

Diangkat ketika parsing JSON gagal.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: The line that failed to parse
            original_error: The original JSON decode exception
        """
        self.line = line
        self.original_error = original_error

Tipe Hook

Untuk panduan komprehensif tentang menggunakan hooks dengan contoh dan pola umum, lihat Hooks guide.

`HookEvent`

Tipe event hook yang didukung.

HookEvent = Literal[
    "PreToolUse",  # Called before tool execution
    "PostToolUse",  # Called after tool execution
    "PostToolUseFailure",  # Called when a tool execution fails
    "UserPromptSubmit",  # Called when user submits a prompt
    "Stop",  # Called when stopping execution
    "SubagentStop",  # Called when a subagent stops
    "PreCompact",  # Called before message compaction
    "Notification",  # Called for notification events
    "SubagentStart",  # Called when a subagent starts
    "PermissionRequest",  # Called when a permission decision is needed
]

`HookCallback`

Definisi tipe untuk fungsi callback hook.

HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]

Parameter:

• input: Input hook yang kuat dengan union yang dibedakan berdasarkan hook_event_name (lihat HookInput)
• tool_use_id: Pengenal penggunaan tool opsional (untuk hook terkait tool)
• context: Konteks hook dengan informasi tambahan

Mengembalikan HookJSONOutput.

`HookContext`

Informasi konteks yang diteruskan ke callback hook.

class HookContext(TypedDict):
    signal: Any | None  # Future: abort signal support

`HookMatcher`

Konfigurasi untuk mencocokkan hooks ke event atau tools tertentu.

@dataclass
class HookMatcher:
    matcher: str | None = (
        None  # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
    )
    hooks: list[HookCallback] = field(
        default_factory=list
    )  # List of callbacks to execute
    timeout: float | None = (
        None  # Timeout in seconds. When omitted, the per-event default applies:
        # 600 for most events, 30 for UserPromptSubmit
    )

`HookInput`

Tipe union dari semua tipe input hook. Tipe aktual bergantung pada field hook_event_name.

HookInput = (
    PreToolUseHookInput
    | PostToolUseHookInput
    | PostToolUseFailureHookInput
    | UserPromptSubmitHookInput
    | StopHookInput
    | SubagentStopHookInput
    | PreCompactHookInput
    | NotificationHookInput
    | SubagentStartHookInput
    | PermissionRequestHookInput
)

`BaseHookInput`

Field dasar yang ada di semua tipe input hook.

class BaseHookInput(TypedDict):
    session_id: str
    transcript_path: str
    cwd: str
    permission_mode: NotRequired[str]

`PreToolUseHookInput`

Data input untuk event hook PreToolUse.

class PreToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PreToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseHookInput`

Data input untuk event hook PostToolUse.

class PostToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_response: Any
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseFailureHookInput`

Data input untuk event hook PostToolUseFailure. Dipanggil ketika eksekusi tool gagal.

class PostToolUseFailureHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUseFailure"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    error: str
    is_interrupt: NotRequired[bool]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`UserPromptSubmitHookInput`

Data input untuk event hook UserPromptSubmit.

class UserPromptSubmitHookInput(BaseHookInput):
    hook_event_name: Literal["UserPromptSubmit"]
    prompt: str

`StopHookInput`

Data input untuk event hook Stop.

class StopHookInput(BaseHookInput):
    hook_event_name: Literal["Stop"]
    stop_hook_active: bool

`SubagentStopHookInput`

Data input untuk event hook SubagentStop.

class SubagentStopHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStop"]
    stop_hook_active: bool
    agent_id: str
    agent_transcript_path: str
    agent_type: str

`PreCompactHookInput`

Data input untuk event hook PreCompact.

class PreCompactHookInput(BaseHookInput):
    hook_event_name: Literal["PreCompact"]
    trigger: Literal["manual", "auto"]
    custom_instructions: str | None

`NotificationHookInput`

Data input untuk event hook Notification.

class NotificationHookInput(BaseHookInput):
    hook_event_name: Literal["Notification"]
    message: str
    title: NotRequired[str]
    notification_type: str

`SubagentStartHookInput`

Data input untuk event hook SubagentStart.

class SubagentStartHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStart"]
    agent_id: str
    agent_type: str

`PermissionRequestHookInput`

Data input untuk event hook PermissionRequest. Memungkinkan hooks untuk menangani keputusan izin secara programatis.

class PermissionRequestHookInput(BaseHookInput):
    hook_event_name: Literal["PermissionRequest"]
    tool_name: str
    tool_input: dict[str, Any]
    permission_suggestions: NotRequired[list[Any]]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`HookJSONOutput`

Tipe union untuk nilai pengembalian callback hook.

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

`SyncHookJSONOutput`

Output hook sinkron dengan field kontrol dan keputusan.

class SyncHookJSONOutput(TypedDict):
    # Control fields
    continue_: NotRequired[bool]  # Whether to proceed (default: True)
    suppressOutput: NotRequired[bool]  # Hide stdout from transcript
    stopReason: NotRequired[str]  # Message when continue is False

    # Decision fields
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]  # Warning message for user
    reason: NotRequired[str]  # Feedback for Claude

    # Hook-specific output
    hookSpecificOutput: NotRequired[HookSpecificOutput]

`HookSpecificOutput`

Union yang dibedakan dari tipe output spesifik event TypedDict. Field hookEventName menentukan field mana yang valid. Untuk detail lengkap tentang field yang tersedia per event hook, lihat Control execution with hooks.

class PreToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PreToolUse"]
    permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]
    permissionDecisionReason: NotRequired[str]
    updatedInput: NotRequired[dict[str, Any]]
    additionalContext: NotRequired[str]


class PostToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUse"]
    additionalContext: NotRequired[str]
    updatedToolOutput: NotRequired[Any]
    updatedMCPToolOutput: NotRequired[Any]  # Deprecated: use updatedToolOutput, which works for all tools


class PostToolUseFailureHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUseFailure"]
    additionalContext: NotRequired[str]


class UserPromptSubmitHookSpecificOutput(TypedDict):
    hookEventName: Literal["UserPromptSubmit"]
    additionalContext: NotRequired[str]


class NotificationHookSpecificOutput(TypedDict):
    hookEventName: Literal["Notification"]
    additionalContext: NotRequired[str]


class SubagentStartHookSpecificOutput(TypedDict):
    hookEventName: Literal["SubagentStart"]
    additionalContext: NotRequired[str]


class PermissionRequestHookSpecificOutput(TypedDict):
    hookEventName: Literal["PermissionRequest"]
    decision: dict[str, Any]


HookSpecificOutput = (
    PreToolUseHookSpecificOutput
    | PostToolUseHookSpecificOutput
    | PostToolUseFailureHookSpecificOutput
    | UserPromptSubmitHookSpecificOutput
    | NotificationHookSpecificOutput
    | SubagentStartHookSpecificOutput
    | PermissionRequestHookSpecificOutput
)

`AsyncHookJSONOutput`

Output hook async yang menunda eksekusi hook.

class AsyncHookJSONOutput(TypedDict):
    async_: Literal[True]  # Set to True to defer execution
    asyncTimeout: NotRequired[int]  # Timeout in milliseconds

Contoh Penggunaan Hook

Contoh ini mendaftarkan dua hooks: satu yang memblokir perintah bash berbahaya seperti rm -rf /, dan satu lagi yang mencatat semua penggunaan tool untuk audit. Hook keamanan hanya berjalan pada perintah Bash (melalui matcher), sementara hook logging berjalan pada semua tools.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
from typing import Any


async def validate_bash_command(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Validate and potentially block dangerous bash commands."""
    if input_data["tool_name"] == "Bash":
        command = input_data["tool_input"].get("command", "")
        if "rm -rf /" in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": "Dangerous command blocked",
                }
            }
    return {}


async def log_tool_use(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log all tool usage for auditing."""
    print(f"Tool used: {input_data.get('tool_name')}")
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash", hooks=[validate_bash_command], timeout=120
            ),  # 2 min for validation
            HookMatcher(
                hooks=[log_tool_use]
            ),  # Applies to all tools (per-event default timeout)
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

async def main():
    async for message in query(prompt="Analyze this codebase", options=options):
        print(message)


asyncio.run(main())

Tipe Input/Output Tool

Dokumentasi skema input/output untuk semua tools Claude Code bawaan. Meskipun Python SDK tidak mengekspor ini sebagai tipe, mereka mewakili struktur input dan output tool dalam pesan.

Agent

Nama tool: Agent. Nama sebelumnya Task masih diterima sebagai alias, dan daftar tools dalam init SystemMessage melaporkan tool ini sebagai Task untuk kompatibilitas mundur.

Input:

{
    "description": str,  # Deskripsi singkat tugas (3-5 kata)
    "prompt": str,  # Tugas untuk dijalankan oleh agen
    "subagent_type": str | None,  # Jenis agen khusus yang digunakan
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Penggantian model untuk agen ini
    "run_in_background": bool | None,  # Agen berjalan di latar belakang secara default; atur ke False untuk menjalankan secara sinkron
    "name": str | None,  # Nama untuk agen yang dihasilkan
    "team_name": str | None,  # Tidak digunakan lagi; diabaikan
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # Tidak digunakan lagi; diabaikan. Aturan pewarisan subagen memutuskan mode izin subagen
    "isolation": "worktree" | "remote" | None,  # Mode isolasi untuk perubahan agen
}

Meluncurkan agen baru untuk menangani tugas kompleks multi-langkah secara otonom.

Output (status: "completed"):

{
    "status": "completed",
    "agentId": str,  # ID agen yang berjalan
    "agentType": str | None,  # Jenis subagen yang menangani tugas
    "content": [  # Blok konten hasil
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # Model yang dimulai subagen
    "modelsUsed": list[str] | None,  # Model yang digunakan secara berurutan, dengan pengulangan berturut-turut yang runtuh
    "totalToolUseCount": int,  # Jumlah panggilan tool yang dibuat agen
    "totalDurationMs": int,  # Durasi eksekusi dalam milidetik
    "totalTokens": int,  # Jumlah token dari permintaan API final, bukan seluruh run
    "usage": {  # Statistik penggunaan token
        "input_tokens": int,
        "output_tokens": int,
        "cache_creation_input_tokens": int | None,
        "cache_read_input_tokens": int | None,
        "server_tool_use": {"web_search_requests": int, "web_fetch_requests": int} | None,
        "service_tier": str | None,
        "cache_creation": {"ephemeral_1h_input_tokens": int, "ephemeral_5m_input_tokens": int} | None,
        "inference_geo": str | None,
        "speed": str | None,
        "iterations": Any | None,
        "output_tokens_details": {"thinking_tokens": int | None} | None,
    },
    "toolStats": {  # Aktivitas tool agregat untuk run
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # Prompt yang dijalankan agen
    "worktreePath": str | None,  # Hadir ketika Claude Code menyimpan worktree subagen
    "worktreeBranch": str | None,  # Hadir ketika Claude Code membuat worktree itu dengan git
}

Output (status: "async_launched"):

{
    "status": "async_launched",
    "isAsync": bool | None,  # True pada peluncuran latar belakang
    "agentId": str,  # ID agen yang diluncurkan
    "description": str,  # Deskripsi tugas
    "resolvedModel": str | None,  # Model yang digunakan pada transisi backgrounding
    "modelsUsed": list[str] | None,  # Model yang digunakan sebelum backgrounding, secara berurutan, dengan pengulangan berturut-turut yang runtuh
    "prompt": str,  # Prompt yang dijalankan agen
    "outputFile": str,  # Jalur file tempat output agen ditulis
    "canReadOutputFile": bool | None,  # Apakah file output dapat dibaca secara langsung
}

Output (status: "remote_launched"):

{
    "status": "remote_launched",
    "taskId": str,  # ID tugas yang dikirimkan
    "sessionUrl": str,  # Tautan ke sesi cloud
    "description": str,  # Deskripsi tugas
    "prompt": str,  # Prompt yang dijalankan agen
    "outputFile": str,  # Jalur file tempat output agen ditulis
}

Mengembalikan hasil dari subagen. Output dibedakan pada bidang status: "completed" untuk tugas yang selesai, "async_launched" untuk tugas latar belakang, dan "remote_launched" untuk tugas yang Claude Code kirimkan ke sesi cloud, di mana sessionUrl menautkan ke sesi itu dan taskId mengidentifikasinya. Jika Claude Code menyimpan worktree subagen yang terisolasi, worktreePath pada varian completed adalah tempat menemukannya, dan worktreeBranch adalah cabangnya ketika Claude Code membuat worktree dengan git.

Pada varian completed, resolvedModel menamai model yang dimulai subagen, yang dapat berbeda dari input model yang diminta ketika availableModels atau penggantian lain berlaku. Bidang ini memerlukan Claude Code v2.1.174 atau lebih baru. Pada varian async_launched, resolvedModel menamai model yang digunakan ketika agen pindah ke latar belakang, jadi swap yang terjadi sebelum backgrounding tercermin di sana. Bidang modelsUsed pada kedua varian mencantumkan model yang digunakan secara berurutan, dengan pengulangan berturut-turut yang runtuh; itu diatur hanya ketika model ditukar di tengah-run. modelsUsed dan perilaku resolvedModel saat backgrounding memerlukan Claude Code v2.1.212 atau lebih baru.

Claude Code mengisi usage dan totalTokens dari permintaan API final subagen, bukan dari seluruh run. Ketika ada, thinking_tokens di bawah output_tokens_details dalam usage adalah jumlah token output permintaan itu yang merupakan token pemikiran. Kunci output_tokens_details memerlukan Python SDK v0.2.136 atau lebih baru, yang menggabungkan Claude Code v2.1.228.

AskUserQuestion

Nama tool: AskUserQuestion

Mengajukan pertanyaan klarifikasi kepada pengguna selama eksekusi. Lihat Handle approvals and user input untuk detail penggunaan.

Input:

{
    "questions": [  # Pertanyaan untuk ditanyakan kepada pengguna (1-4 pertanyaan)
        {
            "question": str,  # Pertanyaan lengkap untuk ditanyakan kepada pengguna
            "header": str,  # Label sangat singkat ditampilkan sebagai chip/tag (maks 12 karakter)
            "options": [  # Pilihan yang tersedia (2-4 opsi)
                {
                    "label": str,  # Teks tampilan untuk opsi ini (1-5 kata)
                    "description": str,  # Penjelasan tentang arti opsi ini
                    "preview": str | None,  # Konten pratinjau yang dirender ketika opsi difokuskan
                }
            ],
            "multiSelect": bool,  # Atur ke true untuk memungkinkan beberapa pilihan
        }
    ],
    "answers": dict[str, str] | None,
    # Jawaban pengguna diisi oleh sistem izin. Jawaban multi-pilih
    # adalah string yang digabungkan dengan koma dari label yang dipilih; daftar
    # label diterima pada input dan dipaksa ke bentuk itu
    "annotations": dict[str, dict] | None,
    # Anotasi per-pertanyaan dari pengguna, dikunci oleh teks pertanyaan.
    # Setiap nilai dapat membawa "preview" (konten pratinjau opsi yang dipilih)
    # dan "notes" (catatan teks bebas tentang pilihan)
    "metadata": dict | None,  # Metadata analitik, seperti {"source": "remember"}; tidak ditampilkan kepada pengguna
}

Output:

{
    "questions": [  # Pertanyaan yang diajukan
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # Memetakan teks pertanyaan ke string jawaban
    # Jawaban multi-pilih dipisahkan dengan koma
    "response": str | None,
    # Balasan bentuk bebas yang diketik alih-alih menjawab pertanyaan; ketika diatur,
    # Claude menerima "The user responded: ..." sebagai pengganti daftar jawaban
    "annotations": dict[str, dict] | None,  # "preview" dan "notes" per-pertanyaan dari pilihan pengguna
    "afkTimeoutMs": int | None,  # Diatur ketika dialog auto-resolved setelah banyak milidetik ketidakaktifan pengguna; tidak ada ketika pengguna menjawab
}

Bash

Nama tool: Bash

Input:

{
    "command": str,  # Perintah yang akan dijalankan
    "timeout": int | None,  # Waktu tunggu opsional dalam milidetik (maks 600000; nilai yang lebih tinggi dijepit ke maks)
    "description": str | None,  # Deskripsi jelas dan ringkas (5-10 kata)
    "run_in_background": bool | None,  # Atur ke true untuk menjalankan di latar belakang
}

Output:

{
    "stdout": str,  # Output perintah; stdout dan stderr tiba digabungkan ke dalam satu aliran yang saling terkait
    "stderr": str,  # Pemberitahuan yang ditambahkan tool itu sendiri, bukan stderr perintah
    "interrupted": bool,  # Apakah perintah terputus
    "isImage": bool | None,  # Apakah stdout berisi data gambar
    "backgroundTaskId": str | None,  # ID tugas latar belakang jika perintah berjalan di latar belakang
}

Monitor

Nama tool: Monitor

Menjalankan sumber latar belakang dan mengirimkan setiap event ke Claude sehingga dapat bereaksi tanpa polling: command menjalankan skrip dan mengeluarkan satu event per baris stdout, dan ws membuka WebSocket dan mengeluarkan satu event per frame teks. Berikan tepat satu dari command atau ws.

Ketika Monitor menjalankan perintah, ia mengikuti aturan izin yang sama seperti Bash; pengawasan WebSocket meminta persetujuan secara terpisah. Sumber ws memerlukan Claude Code v2.1.195 atau lebih baru. Lihat Monitor tool reference untuk perilaku dan ketersediaan penyedia.

Input:

{
    "command": str | None,  # Skrip shell; setiap baris stdout adalah event, keluar mengakhiri pengawasan
    "ws": dict | None,  # Sumber WebSocket: {"url": str, "protocols": list[str] | None}; setiap frame teks adalah event
    "description": str,  # Deskripsi singkat ditampilkan dalam notifikasi
    "timeout_ms": int | None,  # Batas waktu dalam milidetik (default 300000, maks 3600000; batas waktu efektif paling banyak 1800000)
}

Output:

{
    "taskId": str,  # ID tugas monitor latar belakang
    "timeoutMs": int,  # Batas waktu efektif pengawasan dalam milidetik
    "persistent": bool | None,  # False: setiap pengawasan memiliki batas waktu
}

Edit

Nama tool: Edit

Input:

{
    "file_path": str,  # Jalur absolut ke file yang akan dimodifikasi
    "old_string": str,  # Teks yang akan diganti
    "new_string": str,  # Teks untuk menggantinya
    "replace_all": bool | None,  # Ganti semua kemunculan (default False)
}

Output:

{
    "message": str,  # Pesan konfirmasi
    "replacements": int,  # Jumlah penggantian yang dilakukan
    "file_path": str,  # Jalur file yang diedit
}

Read

Nama tool: Read

Input:

{
    "file_path": str,  # Jalur absolut ke file yang akan dibaca
    "offset": int | None,  # Nomor baris untuk mulai membaca dari
    "limit": int | None,  # Jumlah baris yang akan dibaca
}

Output (File teks):

{
    "content": str,  # Isi file dengan nomor baris
    "total_lines": int,  # Total jumlah baris dalam file
    "lines_returned": int,  # Baris yang benar-benar dikembalikan
}

Output (Gambar):

{
    "image": str,  # Data gambar yang dikodekan Base64
    "mime_type": str,  # Tipe MIME gambar
    "file_size": int,  # Ukuran file dalam byte
}

Write

Nama tool: Write

Input:

{
    "file_path": str,  # Jalur absolut ke file yang akan ditulis
    "content": str,  # Konten yang akan ditulis ke file
}

Output:

{
    "message": str,  # Pesan sukses
    "bytes_written": int,  # Jumlah byte yang ditulis
    "file_path": str,  # Jalur file yang ditulis
}

Glob

Nama tool: Glob

Input:

{
    "pattern": str,  # Pola glob untuk mencocokkan file
    "path": str | None,  # Direktori untuk dicari (default ke cwd)
}

Output:

{
    "matches": list[str],  # Array jalur file yang cocok
    "count": int,  # Jumlah kecocokan yang ditemukan
    "search_path": str,  # Direktori pencarian yang digunakan
}

Grep

Nama tool: Grep

Input:

{
    "pattern": str,  # Pola ekspresi reguler
    "path": str | None,  # File atau direktori untuk dicari
    "glob": str | None,  # Pola glob untuk menyaring file
    "type": str | None,  # Jenis file untuk dicari
    "output_mode": str | None,  # "content", "files_with_matches", atau "count"
    "-i": bool | None,  # Pencarian tidak peka huruf besar-kecil
    "-n": bool | None,  # Tampilkan nomor baris
    "-B": int | None,  # Baris untuk ditampilkan sebelum setiap kecocokan
    "-A": int | None,  # Baris untuk ditampilkan setelah setiap kecocokan
    "-C": int | None,  # Baris untuk ditampilkan sebelum dan sesudah
    "head_limit": int | None,  # Batasi output ke N baris/entri pertama
    "multiline": bool | None,  # Aktifkan mode multiline
}

Output (content mode):

{
    "matches": [
        {
            "file": str,
            "line_number": int | None,
            "line": str,
            "before_context": list[str] | None,
            "after_context": list[str] | None,
        }
    ],
    "total_matches": int,
}

Output (files_with_matches mode):

{
    "files": list[str],  # File yang berisi kecocokan
    "count": int,  # Jumlah file dengan kecocokan
}

NotebookEdit

Nama tool: NotebookEdit

Input:

{
    "notebook_path": str,  # Jalur absolut ke notebook Jupyter
    "cell_id": str | None,  # ID sel yang akan diedit
    "new_source": str,  # Sumber baru untuk sel
    "cell_type": "code" | "markdown" | None,  # Jenis sel
    "edit_mode": "replace" | "insert" | "delete" | None,  # Jenis operasi edit
}

Output:

{
    "message": str,  # Pesan sukses
    "edit_type": "replaced" | "inserted" | "deleted",  # Jenis edit yang dilakukan
    "cell_id": str | None,  # ID sel yang terpengaruh
    "total_cells": int,  # Total sel dalam notebook setelah edit
}

WebFetch

Nama tool: WebFetch

Input:

{
    "url": str,  # URL untuk mengambil konten dari
    "prompt": str,  # Prompt untuk dijalankan pada konten yang diambil
}

Output:

{
    "bytes": int,  # Ukuran konten yang diambil dalam byte
    "code": int,  # Kode respons HTTP
    "codeText": str,  # Teks kode respons HTTP
    "result": str,  # Hasil yang diproses dari menerapkan prompt ke konten
    "durationMs": int,  # Waktu untuk mengambil dan memproses konten, dalam milidetik
    "url": str,  # URL yang diambil
}

WebSearch

Nama tool: WebSearch

Input:

{
    "query": str,  # Kueri pencarian yang digunakan
    "allowed_domains": list[str] | None,  # Hanya sertakan hasil dari domain ini
    "blocked_domains": list[str] | None,  # Jangan pernah sertakan hasil dari domain ini
}

Output:

{
    "query": str,  # Kueri pencarian
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # Durasi pencarian dalam detik
}

TodoWrite

Nama tool: TodoWrite

Input:

{
    "todos": [
        {
            "content": str,  # Deskripsi tugas
            "status": "pending" | "in_progress" | "completed",  # Status tugas
            "activeForm": str,  # Bentuk aktif deskripsi
        }
    ]
}

Output:

{
    "message": str,  # Pesan sukses
    "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
}

TaskCreate

Nama tool: TaskCreate

Input:

{
    "subject": str,  # Judul tugas singkat
    "description": str,  # Badan tugas terperinci
    "activeForm": str | None,  # Label bentuk present-tense ditampilkan saat sedang berlangsung
    "metadata": dict | None,  # Metadata pemanggil arbitrer
}

Output:

{
    "task": {"id": str, "subject": str},  # Tugas yang dibuat dengan ID yang ditugaskan
}

TaskUpdate

Nama tool: TaskUpdate

Input:

{
    "taskId": str,  # ID tugas yang akan dipatch
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # ID tugas yang sekarang diblokir oleh tugas ini
    "addBlockedBy": list[str] | None,  # ID tugas yang sekarang memblokir tugas ini
    "owner": str | None,
    "metadata": dict | None,
}

Output:

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # Nama bidang yang berubah
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

Nama tool: TaskGet

Input:

{
    "taskId": str,  # ID tugas yang akan dibaca
}

Output:

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # None saat ID tidak ditemukan
}

TaskList

Nama tool: TaskList

Input:

{}

Output:

{
    "tasks": [
        {
            "id": str,
            "subject": str,
            "status": Literal["pending", "in_progress", "completed"],
            "owner": str | None,
            "blockedBy": list[str],
        }
    ],
}

TaskOutput

Dihapus dalam Claude Code v2.1.277. Sebelumnya mengambil output dari tugas latar belakang yang sedang berjalan atau selesai, dengan BashOutput diterima sebagai alias; Claude membaca file output tugas latar belakang dengan Read sebagai gantinya.

Entri disallowed_tools atau aturan deny yang masih menamai salah satu nama diabaikan tanpa peringatan.

TaskStop

Nama tool: TaskStop. Nama sebelumnya KillShell dan KillBash masih diterima sebagai alias.

Input:

{
    "task_id": str | None,  # ID tugas latar belakang yang akan dihentikan
    "shell_id": str | None,  # Tidak digunakan lagi: gunakan task_id sebagai gantinya
}

Output:

{
    "message": str,  # Pesan status tentang operasi
    "task_id": str,  # ID tugas yang dihentikan
    "task_type": str,  # Jenis tugas yang dihentikan
    "command": str | None,  # Perintah atau deskripsi tugas yang dihentikan
}

ExitPlanMode

Nama tool: ExitPlanMode

Input:

{
    "plan": str  # Rencana yang akan dijalankan oleh pengguna untuk persetujuan
}

Output:

{
    "message": str,  # Pesan konfirmasi
    "approved": bool | None,  # Apakah pengguna menyetujui rencana
}

ListMcpResources

Nama tool: ListMcpResourcesTool

Input:

{
    "server": str | None  # Nama server opsional untuk menyaring sumber daya
}

Output:

{
    "resources": [
        {
            "uri": str,
            "name": str,
            "description": str | None,
            "mimeType": str | None,
            "server": str,
        }
    ],
    "total": int,
}

ReadMcpResource

Nama tool: ReadMcpResourceTool

Input:

{
    "server": str,  # Nama server MCP
    "uri": str,  # URI sumber daya yang akan dibaca
}

Output:

{
    "contents": [
        {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}
    ],
    "server": str,
}

Membangun antarmuka percakapan berkelanjutan

Contoh berikut menjaga satu ClaudeSDKClient tetap terhubung di seluruh giliran, sehingga Claude mengingat pesan-pesan sebelumnya. Ketik new untuk memutuskan dan menghubungkan kembali untuk sesi baru, atau exit untuk mengakhiri percakapan.

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
)
import asyncio


class ConversationSession:
    """Maintains a single conversation session with Claude."""

    def __init__(self, options: ClaudeAgentOptions | None = None):
        self.client = ClaudeSDKClient(options)
        self.turn_count = 0

    async def start(self):
        await self.client.connect()
        print("Starting conversation session. Claude will remember context.")
        print(
            "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
        )

        while True:
            user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")

            if user_input.lower() == "exit":
                break
            elif user_input.lower() == "interrupt":
                await self.client.interrupt()
                print("Task interrupted!")
                continue
            elif user_input.lower() == "new":
                # Disconnect and reconnect for a fresh session
                await self.client.disconnect()
                await self.client.connect()
                self.turn_count = 0
                print("Started new conversation session (previous context cleared)")
                continue

            # Send message - the session retains all previous messages
            await self.client.query(user_input)
            self.turn_count += 1

            # Process response
            print(f"[Turn {self.turn_count}] Claude: ", end="")
            async for message in self.client.receive_response():
                if isinstance(message, AssistantMessage):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print()  # New line after response

        await self.client.disconnect()
        print(f"Conversation ended after {self.turn_count} turns.")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
    )
    session = ConversationSession(options)
    await session.start()


# Example conversation:
# Turn 1 - You: "Create a file called hello.py"
# Turn 1 - Claude: "I'll create a hello.py file for you..."
# Turn 2 - You: "What's in that file?"
# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
# Turn 3 - You: "Add a main function to it"
# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)

asyncio.run(main())

Penanganan error

Contoh berikut membungkus panggilan query() dalam penanganan untuk empat dari jenis error yang dimunculkan SDK.

Contoh ini menangkap ResultError, yang memerlukan Python Agent SDK 0.2.140 atau lebih baru.

import asyncio

from claude_agent_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    ResultError,
    CLIJSONDecodeError,
)


async def main():
    try:
        async for message in query(prompt="Hello"):
            print(message)
    except CLINotFoundError:
        print(
            "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
        )
    # Catch ResultError before ProcessError, which it subclasses. Its message
    # carries the error text. A failed final request, such as an API error,
    # arrives with subtype "success", so branch on terminal_reason first.
    except ResultError as e:
        if e.terminal_reason == "api_error":
            print(f"API request failed: {e}")
        else:
            print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
    except ProcessError as e:
        print(f"Process failed with exit code: {e.exit_code}")
    except CLIJSONDecodeError as e:
        print(f"Failed to parse response: {e}")


asyncio.run(main())

Konfigurasi Sandbox

`SandboxSettings`

Konfigurasi untuk perilaku sandbox. Gunakan ini untuk mengaktifkan sandboxing perintah dan mengonfigurasi pembatasan jaringan secara terprogram.

class SandboxSettings(TypedDict, total=False):
    enabled: bool
    autoAllowBashIfSandboxed: bool
    excludedCommands: list[str]
    allowUnsandboxedCommands: bool
    network: SandboxNetworkConfig
    ignoreViolations: SandboxIgnoreViolations
    enableWeakerNestedSandbox: bool

Contoh penggunaan

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

sandbox_settings = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "failIfUnavailable": True,
    "network": {"allowLocalBinding": True},
}


async def main():
    try:
        async for message in query(
            prompt="Build and test my project",
            options=ClaudeAgentOptions(sandbox=sandbox_settings),
        ):
            print(message)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # such as when failIfUnavailable is set and the sandbox can't start.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

`SandboxNetworkConfig`

Konfigurasi khusus jaringan untuk mode sandbox. Pengaturan ini berlaku untuk perintah Bash yang di-sandbox ketika enabled adalah True dalam SandboxSettings induk. Mereka tidak membatasi tool WebFetch, yang menggunakan aturan izin sebagai gantinya.

class SandboxNetworkConfig(TypedDict, total=False):
    allowedDomains: list[str]
    deniedDomains: list[str]
    allowManagedDomainsOnly: bool
    allowUnixSockets: list[str]
    allowAllUnixSockets: bool
    allowLocalBinding: bool
    allowMachLookup: list[str]
    httpProxyPort: int
    socksProxyPort: int

`SandboxIgnoreViolations`

Konfigurasi untuk mengabaikan pelanggaran sandbox tertentu.

class SandboxIgnoreViolations(TypedDict, total=False):
    file: list[str]
    network: list[str]

Fallback Izin untuk Perintah Tanpa Sandbox

Ketika allowUnsandboxedCommands diaktifkan, model dapat meminta untuk menjalankan perintah di luar sandbox dengan mengatur dangerouslyDisableSandbox: True dalam input tool. Permintaan ini kembali ke sistem izin yang ada, berarti handler can_use_tool Anda akan dipanggil, memungkinkan Anda menerapkan logika otorisasi khusus.

Entri excludedCommands Anda sebagai gantinya mengambil perintah keluar dari sandbox tanpa keterlibatan model; sandbox.excludedCommands mencakup kapan entri berlaku.

Contoh berikut mencatat setiap permintaan tanpa sandbox dan menolaknya kecuali logika otorisasi Anda sendiri mengizinkannya:

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    HookMatcher,
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


def is_command_authorized(command: str | None) -> bool:
    # Replace with your own authorization logic
    return False



async def can_use_tool(
    tool: str, input: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    # Check if the model is requesting to bypass the sandbox
    if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
        # The model is requesting to run this command outside the sandbox
        print(f"Unsandboxed command requested: {input.get('command')}")

        if is_command_authorized(input.get("command")):
            return PermissionResultAllow()
        return PermissionResultDeny(
            message="Command not authorized for unsandboxed execution"
        )
    return PermissionResultAllow()


# Required: dummy hook keeps the stream open for can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def prompt_stream():
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Deploy my application"},
    }


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            sandbox={
                "enabled": True,
                "allowUnsandboxedCommands": True,  # Model can request unsandboxed execution
            },
            permission_mode="default",
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        print(message)


asyncio.run(main())

Lihat juga

• SDK overview - Konsep SDK umum
• TypeScript SDK reference - Dokumentasi SDK TypeScript
• Custom tools - Tentukan alat MCP dalam proses untuk Claude panggil
• CLI reference - Antarmuka baris perintah
• Common workflows - Panduan langkah demi langkah