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 agen selesai, pesan hasil mencakup bidang structured_output dengan data yang divalidasi sesuai dengan skema Anda.
Contoh di bawah ini meminta agen 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.
- Inferensi tipe penuh (TypeScript) dan petunjuk tipe (Python)
- Validasi runtime dengan
safeParse()ataumodel_validate() - Pesan kesalahan yang lebih baik
- Skema yang dapat dikomposisi dan dapat digunakan kembali
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()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.
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 agen tidak dapat menghasilkan JSON yang valid sesuai dengan skema Anda. Ini biasanya terjadi ketika skema terlalu kompleks untuk tugas, tugas itu sendiri ambigu, atau agen mencapai batas percobaan ulangnya mencoba memperbaiki kesalahan validasi. Ketika kesalahan terjadi, pesan hasil memilikisubtype yang menunjukkan apa yang salah:
| Subtype | Arti |
|---|---|
success | Output dihasilkan dan divalidasi dengan berhasil |
error_max_structured_output_retries | Agen tidak dapat menghasilkan output yang valid setelah beberapa percobaan |
subtype untuk menentukan apakah output dihasilkan dengan berhasil atau jika Anda perlu menangani 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 agen 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