Cara kerja agent loop

​

Loop sekilas

1. Terima prompt. Claude menerima prompt Anda, bersama dengan system prompt, tool definitions, dan conversation history. SDK menghasilkan SystemMessage dengan subtype "init" yang berisi session metadata.
2. Evaluasi dan respons. Claude mengevaluasi state saat ini dan menentukan cara melanjutkan. Ini dapat merespons dengan teks, meminta satu atau lebih tool calls, atau keduanya. SDK menghasilkan AssistantMessage yang berisi teks dan permintaan tool call apa pun.
3. Eksekusi tools. SDK menjalankan setiap tool yang diminta dan mengumpulkan hasilnya. Setiap set hasil tool umpan balik ke Claude untuk keputusan berikutnya. Anda dapat menggunakan hooks untuk mengintersepsi, memodifikasi, atau memblokir tool calls sebelum dijalankan.
4. Ulangi. Langkah 2 dan 3 berulang sebagai siklus. Setiap siklus penuh adalah satu turn. Claude terus memanggil tools dan memproses hasil sampai menghasilkan respons tanpa tool calls.
5. Kembalikan hasil. SDK menghasilkan AssistantMessage final dengan respons teks (tanpa tool calls), diikuti oleh ResultMessage dengan teks final, token usage, cost, dan session ID.

​

Turns dan messages

1. Turn 1: Claude memanggil Bash untuk menjalankan npm test. SDK menghasilkan AssistantMessage dengan tool call, menjalankan perintah, kemudian menghasilkan UserMessage dengan output (tiga kegagalan).
2. Turn 2: Claude memanggil Read pada auth.ts dan auth.test.ts. SDK mengembalikan konten file dan menghasilkan AssistantMessage.
3. Turn 3: Claude memanggil Edit untuk memperbaiki auth.ts, kemudian memanggil Bash untuk menjalankan kembali npm test. Ketiga tests lulus. SDK menghasilkan AssistantMessage.
4. Turn final: Claude menghasilkan respons hanya teks tanpa tool calls: “Fixed the auth bug, all three tests pass now.” SDK menghasilkan AssistantMessage final dengan teks ini, kemudian ResultMessage dengan teks yang sama ditambah cost dan usage.

​

Tipe Message

• SystemMessage: session lifecycle events. Field subtype membedakannya:
  • "init": session metadata untuk run. Ketika hook SessionStart atau Setup berjalan selama session startup, hook lifecycle messages tiba sebelum message init
  • "compact_boundary": menyala setelah compaction
  • "informational": plain-text status banners dari loop
  • "worker_shutting_down": loop akan berakhir setelah turn saat ini karena host sedang keluar atau Remote Control terputus
  Di TypeScript, setiap subtype selain "init" adalah tipenya sendiri dalam union SDKMessage daripada subtype dari SDKSystemMessage.
• AssistantMessage: dipancarkan setelah setiap respons Claude, termasuk yang hanya teks final. Berisi text content blocks dan tool call blocks dari turn itu.
• UserMessage: dipancarkan setelah setiap eksekusi tool dengan tool result content yang dikirim kembali ke Claude. Juga dipancarkan untuk input pengguna apa pun yang Anda stream mid-loop.
• StreamEvent: hanya dipancarkan ketika partial messages diaktifkan. Berisi raw API streaming events (text deltas, tool input chunks). Lihat Stream responses.
• ResultMessage: menandai akhir dari agent loop. Berisi hasil teks final, token usage, cost, dan session ID. Periksa field subtype untuk menentukan apakah tugas berhasil atau mencapai batas. Sejumlah kecil trailing system events, seperti prompt_suggestion, dapat tiba setelahnya, jadi iterasi stream hingga selesai daripada break pada hasil. Lihat Handle the result.

​

Handle messages

• Final results only: handle ResultMessage untuk mendapatkan output, cost, dan apakah tugas berhasil atau mencapai batas.
• Progress updates: handle AssistantMessage untuk melihat apa yang dilakukan Claude setiap turn, termasuk tools mana yang dipanggilnya.
• Live streaming: aktifkan partial messages (include_partial_messages di Python, includePartialMessages di TypeScript) untuk mendapatkan StreamEvent messages secara real time. Lihat Stream responses in real-time.

• Python: periksa message types dengan isinstance() terhadap classes yang diimpor dari claude_agent_sdk (misalnya, isinstance(message, ResultMessage)).
• TypeScript: periksa field string type (misalnya, message.type === "result"). AssistantMessage dan UserMessage membungkus raw API message dalam field .message, jadi content blocks berada di message.message.content, bukan message.content.

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                print(f"Turn completed: {len(message.content)} content blocks")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

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

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      console.log(`Turn completed: ${message.message.content.length} content blocks`);
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

Eksekusi tool

​

Built-in tools

• Hubungkan layanan eksternal dengan MCP servers (databases, browsers, APIs)
• Tentukan custom tools dengan custom tool handlers
• Muat project skills melalui setting sources untuk reusable workflows

​

Tool permissions

• allowed_tools / allowedTools auto-approves tools yang terdaftar. Agent read-only dengan ["Read", "Glob", "Grep"] dalam daftar allowed tools-nya menjalankan tools tersebut tanpa prompting. Tools yang tidak terdaftar masih tersedia tetapi memerlukan permission.
• disallowed_tools / disallowedTools memblokir tools yang terdaftar, terlepas dari pengaturan lainnya. Lihat Permissions untuk urutan aturan yang diperiksa sebelum tool berjalan.
• permission_mode / permissionMode mengontrol apa yang terjadi pada tools yang tidak tercakup oleh allow atau deny rules. Lihat Permission mode untuk mode yang tersedia.

​

Parallel tool execution

​

Kontrol cara loop berjalan

​

Turns dan budget

​

Effort level

​

Permission mode

​

Model

​

Jendela konteks

​

Apa yang mengkonsumsi konteks

​

Automatic compaction

• Summarization instructions dalam CLAUDE.md: Compactor membaca CLAUDE.md Anda seperti context lainnya, jadi Anda dapat menyertakan section yang memberi tahu apa yang dipertahankan saat merangkum. Section header adalah free-form (bukan magic string); compactor matches pada intent.
• PreCompact hook: Jalankan custom logic sebelum compaction terjadi, misalnya untuk archive full transcript. Hook menerima field trigger (manual atau auto). Lihat hooks.
• Manual compaction: Kirim /compact sebagai prompt string untuk trigger compaction on demand. Commands yang dikirim dengan cara ini adalah SDK inputs, bukan CLI-only shortcuts. Lihat commands dalam SDK.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

​

Jaga konteks tetap efisien

• Gunakan subagents untuk subtasks. Setiap subagent dimulai dengan fresh conversation (tidak ada prior message history, meskipun dimuat system prompt dan project-level context seperti CLAUDE.md sendiri). Ini tidak melihat parent’s turns, dan hanya final responsenya kembali ke parent sebagai tool result. Main agent’s context tumbuh oleh summary itu, bukan oleh full subtask transcript. Lihat What subagents inherit untuk details.
• Jadilah selective dengan tools. Setiap tool definition mengambil context space. Gunakan field tools pada AgentDefinition untuk scope subagents ke minimum set yang mereka butuhkan.
• Perhatikan MCP server costs. MCP tool search menunda MCP tool schemas secara default dan memuat mereka on demand. Ketika tool search dimatikan, pada Google Cloud’s Agent Platform, atau di belakang non-first-party ANTHROPIC_BASE_URL, setiap MCP server menambahkan semua tool schemas-nya ke setiap request, jadi beberapa servers dengan banyak tools dapat mengkonsumsi significant context sebelum agent melakukan pekerjaan apa pun.
• Gunakan lower effort untuk routine tasks. Set effort ke "low" untuk agents yang hanya perlu membaca files atau list directories. Ini mengurangi token usage dan cost.

​

Sessions dan continuity

​

Handle the result

​

Hooks

​

Satukan semuanya

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    try:
        async for message in query(
            prompt="Find and fix the bug causing test failures in the auth module",
            options=ClaudeAgentOptions(
                allowed_tools=[
                    "Read",
                    "Edit",
                    "Bash",
                    "Glob",
                    "Grep",
                ],  # Listing tools here auto-approves them (no prompting)
                setting_sources=[
                    "project"
                ],  # Load CLAUDE.md, skills, hooks from current directory
                max_turns=30,  # Prevent runaway sessions
                effort="high",  # Thorough reasoning for complex debugging
            ),
        ):
            # Handle the final result
            if isinstance(message, ResultMessage):
                session_id = message.session_id  # Save for potential resumption

                if message.subtype == "success":
                    print(f"Done: {message.result}")
                elif message.subtype == "error_max_turns":
                    # Agent ran out of turns. Resume with a higher limit.
                    print(f"Hit turn limit. Resume session {session_id} to continue.")
                elif message.subtype == "error_max_budget_usd":
                    print("Hit budget limit.")
                else:
                    print(f"Stopped: {message.subtype}")
                if message.total_cost_usd is not None:
                    print(f"Cost: ${message.total_cost_usd:.4f}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

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

let sessionId: string | undefined;

try {
  for await (const message of query({
    prompt: "Find and fix the bug causing test failures in the auth module",
    options: {
      allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
      settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
      maxTurns: 30, // Prevent runaway sessions
      effort: "high" // Thorough reasoning for complex debugging
    }
  })) {
    // Save the session ID to resume later if needed
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }

    // Handle the final result
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`Done: ${message.result}`);
      } else if (message.subtype === "error_max_turns") {
        // Agent ran out of turns. Resume with a higher limit.
        console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
      } else if (message.subtype === "error_max_budget_usd") {
        console.log("Hit budget limit.");
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
      console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

Langkah selanjutnya

• Belum menjalankan agent? Mulai dengan quickstart untuk mendapatkan SDK terinstal dan lihat contoh lengkap berjalan end to end.
• Siap untuk hook ke proyek Anda? Load CLAUDE.md, skills, dan filesystem hooks sehingga agent mengikuti project conventions Anda secara otomatis.
• Membangun interactive UI? Aktifkan streaming untuk menampilkan live text dan tool calls saat loop berjalan.
• Butuh tighter control atas apa yang dapat dilakukan agent? Lock down tool access dengan permissions, dan gunakan hooks untuk audit, block, atau transform tool calls sebelum dieksekusi.
• Menjalankan long atau expensive tasks? Offload isolated work ke subagents untuk keep main context Anda lean.