Mengapa output terstruktur?
Agen mengembalikan teks bentuk bebas secara default, yang berfungsi untuk obrolan tetapi tidak ketika Anda perlu menggunakan output secara terprogram. Output terstruktur memberi Anda data yang diketik yang dapat Anda teruskan langsung ke logika aplikasi, database, atau komponen UI Anda. Pertimbangkan aplikasi resep di mana agen mencari web dan membawa kembali resep. Tanpa output terstruktur, Anda mendapatkan teks bentuk bebas yang perlu Anda parsing sendiri. Dengan output terstruktur, Anda menentukan bentuk yang Anda inginkan dan mendapatkan data yang diketik yang dapat Anda gunakan langsung di aplikasi Anda.Tanpa output terstruktur
Tanpa output terstruktur
Dengan output terstruktur
Dengan output terstruktur
Mulai cepat
Untuk menggunakan output terstruktur, tentukan JSON Schema yang menggambarkan bentuk data yang Anda inginkan, kemudian teruskan kequery() melalui opsi outputFormat (TypeScript) atau opsi output_format (Python). Ketika agent selesai, pesan hasil mencakup bidang structured_output dengan data yang divalidasi sesuai dengan skema Anda.
Sebelum menjalankan contoh di halaman ini, instal Claude Agent SDK dengan mengikuti mulai cepat. Contoh di bawah ini meminta agent untuk meneliti Anthropic dan mengembalikan nama perusahaan, tahun didirikan, dan kantor pusat sebagai output terstruktur.
Skema yang aman tipe dengan Zod dan Pydantic
Alih-alih menulis JSON Schema dengan tangan, Anda dapat menggunakan Zod (TypeScript) atau Pydantic (Python) untuk menentukan skema Anda. Perpustakaan ini menghasilkan JSON Schema untuk Anda dan memungkinkan Anda mengurai respons menjadi objek yang sepenuhnya diketik yang dapat Anda gunakan di seluruh basis kode Anda dengan pelengkapan otomatis dan pemeriksaan tipe. Contoh di bawah ini menentukan skema untuk rencana implementasi fitur dengan ringkasan, daftar langkah (masing-masing dengan tingkat kompleksitas), dan risiko potensial. Agen merencanakan fitur dan mengembalikan objekFeaturePlan yang diketik. Anda kemudian dapat mengakses properti seperti plan.summary dan mengulangi plan.steps dengan keamanan tipe penuh.
SDK memvalidasi skema dengan JSON Schema draft-07, jadi skema yang mendeklarasikan versi yang lebih baru ditolak. Zod menargetkan draft 2020-12 secara default, jadi teruskan target: "draft-7" saat mengonversi skema Anda.
Konfigurasi format output
OpsioutputFormat (TypeScript) atau output_format (Python) menerima objek dengan:
type: Atur ke"json_schema"untuk output terstrukturschema: Objek JSON Schema yang menentukan struktur output Anda. Anda dapat menghasilkan ini dari skema Zod denganz.toJSONSchema(schema, { target: "draft-7" })atau model Pydantic dengan.model_json_schema()
enum, const, required, objek bersarang, dan definisi $ref. Untuk daftar lengkap fitur yang didukung dan batasan, lihat Batasan JSON Schema.
Skema yang bukan JSON Schema yang valid gagal dijalankan saat startup dengan kesalahan yang menyebutkan masalahnya. Sebelum v2.1.205, skema yang tidak valid secara diam-diam diabaikan dan agen mengembalikan teks yang tidak terstruktur.
Kata kunci format, seperti "format": "email", diterima sebagai anotasi dan tidak diberlakukan oleh validator SDK. Sebelum v2.1.205, skema apa pun yang berisi format dianggap tidak valid.
Contoh: agen pelacakan TODO
Contoh ini menunjukkan bagaimana output terstruktur bekerja dengan penggunaan alat multi-langkah. Agen perlu menemukan komentar TODO dalam basis kode, kemudian mencari informasi git blame untuk masing-masing. Agen secara mandiri memutuskan alat mana yang akan digunakan (Grep untuk mencari, Bash untuk menjalankan perintah git) dan menggabungkan hasil menjadi respons terstruktur tunggal. Skema mencakup bidang opsional (author dan date) karena informasi git blame mungkin tidak tersedia untuk semua file. Agen mengisi apa yang dapat ditemukannya dan menghilangkan sisanya.
Penanganan kesalahan
Pembuatan output terstruktur dapat gagal ketika agent tidak dapat menghasilkan JSON yang valid sesuai dengan skema Anda. Ini biasanya terjadi ketika skema terlalu kompleks untuk tugas, tugas itu sendiri ambigu, atau agent mencapai batas retry-nya saat mencoba memperbaiki kesalahan validasi. Ini juga dapat terjadi tanpa ada kegagalan validasi: fallback model dapat menarik kembali output yang sudah selesai di tengah aliran, dan jika tidak ada retry yang menggantinya, jalannya berakhir dengan kesalahan yang sama. Periksa daftarerrors pada pesan hasil kesalahan untuk membedakan dua penyebab tersebut sebelum men-debug skema Anda.
Ketika kesalahan terjadi, pesan hasil memiliki subtype yang menunjukkan apa yang salah:
Hasil juga dapat berakhir dengan subtype
success tetapi tanpa nilai structured_output, misalnya ketika jalannya selesai tanpa agent menghasilkan output terstruktur. Perlakukan kasus itu sebagai kegagalan juga. Entri troubleshooting structured_output is None but the result says success mencakup kasus ini. Contoh di bawah ini memperlakukan hasil sebagai berhasil hanya ketika subtype adalah success dan structured_output ada, dan menangani setiap hasil lainnya sebagai kegagalan:
- Jaga skema tetap fokus. Skema yang bersarang dalam dengan banyak bidang yang diperlukan lebih sulit untuk dipenuhi. Mulai sederhana dan tambahkan kompleksitas sesuai kebutuhan.
- Cocokkan skema dengan tugas. Jika tugas mungkin tidak memiliki semua informasi yang diperlukan skema Anda, buat bidang tersebut opsional.
- Gunakan prompt yang jelas. Prompt yang ambigu membuat lebih sulit bagi agent untuk mengetahui output apa yang harus dihasilkan.
Sumber daya terkait
- Dokumentasi JSON Schema: pelajari sintaks JSON Schema untuk menentukan skema kompleks dengan objek bersarang, array, enum, dan batasan validasi
- API Structured Outputs: gunakan output terstruktur dengan Claude API secara langsung untuk permintaan satu putaran tanpa penggunaan alat
- Custom tools: berikan agen Anda alat khusus untuk dipanggil selama eksekusi sebelum mengembalikan output terstruktur