Claude Architect · Pelajaran

Blok Binaan SDK Ejen

Komponen yang membentuk ejen berasaskan SDK

Pelajaran 1 daripada 413 langkah

Blok Binaan SDK Ejen ialah pelajaran Claude Architect percuma di CoddyKit. Ini ialah pelajaran 1 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Claude Architect, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Claude Architect merangkumi sejumlah 4 pelajaran.

Apakah Sebenarnya Ejen SDK

Ejen SDK bukan satu panggilan API. Ia ialah gelung yang dibina daripada beberapa komponen boleh guna semula yang berfungsi bersama.

Dalam pelajaran ini, anda akan mempelajari blok binaan teras: medan permintaan, alat yang boleh dipanggil oleh model, gelung ejen yang menggerakkannya dan corak penyelaras + subejen untuk kerja yang lebih besar.

Kuasai komponen ini dan anda boleh menaakul tentang hampir mana-mana ejen pengeluaran yang dikemukakan dalam peperiksaan.

Permintaan: model, mesej, alat

Setiap giliran bermula dengan satu permintaan. Medan utamanya ialah: model, max_tokens, system, messages, tools dan tool_choice.

Fakta yang paling penting: model menyimpan NO state antara giliran. Anda mesti menghantar FULL conversation history dalam messages pada setiap permintaan. Tiada ingatan tersembunyi pada bahagian pelayan.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="You are a support agent.",
    messages=conversation_history,  # FULL history every turn
    tools=tools,
    tool_choice={"type": "auto"},
)

Sebab Berhenti Memacu Segalanya

Selepas setiap respons, anda memeriksa stop_reason. Ia memberitahu anda perkara yang perlu dilakukan seterusnya:

end_turn — model telah selesai.
tool_use — jalankan alat yang diminta, tambahkan hasilnya pada sejarah, kemudian teruskan.
max_tokens — output telah dipendekkan.
stop_sequence — rentetan berhenti yang dikonfigurasikan telah dicapai.

Anda menentukan aliran kawalan dengan membaca stop_reason — tidak sekali-kali dengan mengimbas teks untuk perkataan seperti "selesai" atau "telah tamat".

Blok Binaan: Gelung Ejen

Gelung ejen menghubungkan permintaan dan sebab berhenti:

Hantar permintaan.
Periksa stop_reason.
Jika tool_use: jalankan alat, tambahkan blok tool_result pada sejarah dan ulangi gelung.
Ulang sehingga end_turn.

Penamatan adalah dipacu model melalui sebab berhenti. Had lelaran hanyalah jaring keselamatan, tidak sekali-kali cara utama anda berhenti.

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=history,
        tools=tools,
    )
    if resp.stop_reason == "end_turn":
        break  # model decided it is done
    if resp.stop_reason == "tool_use":
        results = run_tools(resp.content)
        history.append({"role": "user", "content": results})

Alat: Perihalan Menentukan Penghalaan

Alat ialah tindakan yang boleh dipanggil oleh model. Perihalan — bukan nama — ialah mekanisme utama yang digunakan oleh model untuk memilih alat yang betul.

Perihalan yang baik menyatakan tujuan, nilai pulangan, format input berserta contoh, kes tepi dan batasan kebolehgunaan. Perihalan yang bertindih atau kabur menyebabkan penghalaan yang salah.

tool = {
    "name": "lookup_order",
    "description": (
        "Fetch an order by its ID. Use ONLY after the "
        "customer identity is verified. Input: order_id like "
        "'ORD-10293'. Returns status, items, total_usd. "
        "Returns an empty result if the ID does not exist."
    ),
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}

Hadkan Alat Mengikut Peranan

Lebih banyak alat tidak semestinya lebih baik. Sekitar 4-5 alat bagi setiap ejen adalah optimum; 18+ merosotkan kebolehpercayaan pemilihan kerana perihalan mula bertindih dan model tersalah menghala.

Hadkan set alat setiap ejen kepada peranannya dan ikuti prinsip keistimewaan minimum. Ejen sokongan mungkin hanya membawa: get_customer, lookup_order, process_refund, escalate_to_human — dan tiada yang lain.

tool_choice: Memaksa Struktur

tool_choice mengawal sama ada dan alat yang mana dijalankan:

"auto" — model memilih teks atau alat.
"any" — model MUST memanggil mana-mana alat, yang menjamin output berstruktur.
{"type":"tool","name":"X"} — paksa satu alat tertentu.

Gandingan tool_use dengan Skema JSON menghapuskan ralat sintaks dan menguatkuasakan medan wajib — asas output berstruktur yang boleh dipercayai.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=history,
    tools=[extract_invoice_tool],
    tool_choice={"type": "any"},  # must emit structured output
)

Cangkuk: Pengawal Keselamatan Tentu

Gesaan hanya memandu tingkah laku secara kebarangkalian (~90%). Apabila kegagalan membawa akibat kewangan, undang-undang atau keselamatan, anda memerlukan penguatkuasaan tentu (100%) — itulah yang disediakan oleh cangkuk.

Cangkuk PostToolUse memintas hasil alat sebelum model melihatnya. Cangkuk panggilan keluar boleh menyekat tindakan yang melanggar dasar, contohnya bayaran balik melebihi $500. Simpan kod tegar untuk jaminan; biarkan model membuat keputusan yang fleksibel.

def post_tool_use_hook(tool_name, tool_input, tool_result):
    if tool_name == "process_refund" and tool_input["amount"] > 500:
        # Deterministic block - the model never gets to override this
        return {"deny": True, "reason": "Refund > $500 needs a human."}
    return {"allow": True}

Berbilang Ejen: Penyelaras + Subejen

Untuk kerja yang lebih besar, blok binaan bergabung menjadi sistem hab-dan-jejari. Seorang penyelaras menguraikan tugas, mewakilkan kepada subejen, mengagregatkan hasil, menghala dan mengendalikan ralat.

Fakta peperiksaan yang kritikal: subejen NOT mewarisi sejarah perbualan penyelaras. Semua konteks mesti dihantar secara jelas dalam setiap gesaan subejen. allowedTools penyelaras mesti menyertakan "Task", dan berbilang panggilan Task dalam satu respons dijalankan secara selari.

Menentukan Subejen

Setiap ejen kecil diterangkan oleh AgentDefinition: name, description, system_prompt dan allowed_tools (keistimewaan minimum).

Oleh sebab tiada memori dikongsi, penyelaras membenamkan setiap fakta yang diperlukan oleh ejen kecil terus dalam gesaannya — soalan, kekangan dan sebarang data yang perlu digunakan.

research_agent = {
    "name": "source_finder",
    "description": "Finds and quotes primary sources for one claim.",
    "system_prompt": (
        "You research ONE claim. Return source URL, exact "
        "quote, and publication date. Context is given in full "
        "because you do not see prior conversation."
    ),
    "allowed_tools": ["WebSearch", "Read"],  # least privilege
}

Ralat Berstruktur Antara Blok

Komponen ini hanya kekal boleh dipercayai jika kegagalan dapat difahami. "Operation failed" yang umum menghalang pemulihan; ralat berstruktur membolehkan penghalaan yang bijak.

Konteks ralat yang baik merangkumi: isError:true, errorCategory (sementara / pengesahan / perniagaan / kebenaran), isRetryable, message, attempted_query dan sebarang partial_results. Pulihkan kegagalan sementara secara setempat dalam ejen kecil; tingkatkan ralat yang tidak boleh dipulihkan bersama hasil separa dan bukannya menghentikan keseluruhan aliran kerja.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Order service timed out",
  "attempted_query": "lookup_order(ORD-10293)",
  "partial_results": null
}

Semakan Pantas: Mereka Bentuk Gelung

Anda sedang membina ejen sokongan pelanggan menggunakan SDK ejen. Ejen ini mesti memanggil alat, terus berjalan merentasi beberapa giliran dan berhenti dengan pasti. Reka bentuk manakah yang paling menepati amalan terbaik SDK ejen?

Jawab dalam pelajaran interaktif

Imbas Kembali: Komponen Asas

Komponen ejen SDK:

Permintaan: model, max_tokens, system, messages, tools, tool_choice. Hantar keseluruhan sejarah setiap giliran — model tidak menyimpan keadaan.
Sebab berhenti: end_turn, tool_use, max_tokens, stop_sequence mengawal aliran kawalan — jangan sekali-kali menghuraikan teks.
Gelung berasaskan ejen: penamatan dipacu model; had lelaran hanyalah perlindungan.
Alat: perihalan menentukan penghalaan; 4–5 alat bagi setiap ejen, dengan keistimewaan minimum. tool_choice "any" menjamin output berstruktur.
Cangkuk: penguatkuasaan 100% berketentuan untuk peraturan kewangan/undang-undang/keselamatan.
Penyelaras + ejen kecil: corak hab-dan-jejarian, tiada sejarah diwarisi, hantarkan konteks secara jelas, gunakan ralat berstruktur untuk pemulihan.

Percuma untuk bermula

Pelajari Python dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 26
Pelajaran: 104

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Blok Binaan SDK Ejen” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran Claude Architect, termasuk “Blok Binaan SDK Ejen”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus Claude Architect merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Blok Binaan SDK Ejen”?

Komponen yang membentuk ejen berasaskan SDK Anda berlatih Claude Architect menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Claude Architect?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Claude Architect di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 1 daripada 4.

Berapa lamakah pelajaran “Blok Binaan SDK Ejen” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Claude Architect ini?

Ya. Setiap pelajaran Claude Architect menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

← Kembali ke Claude Architect