Claude SDK Essentials

> "Claude SDK" sebenarnya mencakup dua hal yang saling terkait: Anthropic Messages API (untuk memanggil model secara langsung) dan Claude Agent SDK (untuk membangun agent custom yang loop terhadap tool). Notebook ini membahas keduanya — untuk apa masing-masing, dan bedanya dengan sekadar memanggil API endpoint.

Apa itu Claude SDK?

Anthropic menyediakan dua layer untuk membangun dengan Claude, dan penting untuk jelas layer mana yang dibutuhkan sebuah task:

1. Messages API — cara langsung dan low-level untuk mengirim percakapan ke Claude dan mendapat response. Ini adalah primitive-nya: satu call masuk, satu response keluar, dengan dukungan tool use, vision, dan system prompt terstruktur.

2. Claude Agent SDK — SDK level lebih tinggi (Python/TypeScript) yang membungkus Messages API dengan agentic loop: menjalankan tool, mengumpankan hasilnya kembali ke model, dan mengulang sampai model menghasilkan jawaban final — tanpa kita perlu menulis sendiri loop tersebut. Ini loop yang sama yang menggerakkan Claude Code, disediakan sebagai building block untuk agent custom.

Pakai Messages API kalau kita ingin kontrol langsung atas satu call atau loop custom milik sendiri. Pakai Agent SDK kalau sedang membangun agent yang perlu merencanakan, memanggil tool berulang kali, dan mengelola state loop tersebut — dan tidak mau mengimplementasikannya ulang dari nol.

Messages API

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a concise technical writing assistant.",
    messages=[
        {"role": "user", "content": "Summarize what a message queue does, in two sentences."}
    ],
)

print(response.content[0].text)

Parameter kunci yang perlu diketahui:

Tool Use dengan Messages API

Claude bisa meminta aplikasi kita menjalankan tool tertentu, mirip dengan function calling di OpenAI — kita definisikan tool schema, Claude memutuskan kapan memanggilnya, dan kode kita mengeksekusi lalu mengembalikan hasilnya.

tools = [{
    "name": "get_order_status",
    "description": "Look up the status of a customer order by ID",
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}]

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Where's my order #A1042?"}],
)

if response.stop_reason == "tool_use":
    tool_call = next(b for b in response.content if b.type == "tool_use")
    result = get_order_status(tool_call.input["order_id"])

    # kirim hasil tool kembali supaya Claude bisa menghasilkan jawaban final
    follow_up = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "Where's my order #A1042?"},
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": [{
                "type": "tool_result",
                "tool_use_id": tool_call.id,
                "content": str(result),
            }]},
        ],
    )

Agent SDK: Loop yang Sama, Sudah Jadi

Menulis sendiri loop tool call → eksekusi → umpankan kembali itu jadi berulang-ulang begitu sebuah agent perlu memanggil beberapa tool lintas beberapa giliran. Agent SDK menyediakan loop tersebut siap pakai, plus permission handling, akses tool file/bash, dan hook untuk custom behavior — arsitektur yang sama yang ada di balik Claude Code, diekspos sebagai library.

from claude_agent_sdk import query

async for message in query(
    prompt="Find and fix the failing test in this repo",
    options={"allowed_tools": ["Read", "Edit", "Bash"]},
):
    print(message)

Ini layer yang tepat kalau kita membangun sesuatu yang bentuknya agent — coding assistant, research agent, ops bot — bukan sekadar satu call klasifikasi atau ekstraksi.

Use Case Umum

Best Practices

Key Takeaways

Resources