Dapatkan output terstruktur dari agen

Output terstruktur memungkinkan Anda menentukan bentuk data yang tepat yang ingin Anda dapatkan kembali dari agen. Agen dapat menggunakan alat apa pun yang diperlukan untuk menyelesaikan tugas, dan Anda tetap mendapatkan JSON yang divalidasi sesuai dengan skema Anda di akhir. Tentukan JSON Schema untuk struktur yang Anda butuhkan, dan SDK menjamin output cocok dengannya.

Untuk keamanan tipe penuh, gunakan Zod (TypeScript) atau Pydantic (Python) untuk menentukan skema Anda dan dapatkan objek yang sangat diketik kembali.

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.

Mulai cepat

Untuk menggunakan output terstruktur, tentukan JSON Schema yang menggambarkan bentuk data yang Anda inginkan, kemudian teruskan ke query() 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.

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

// Tentukan bentuk data yang ingin Anda dapatkan kembali
const schema = {
  type: 'object',
  properties: {
    company_name: { type: 'string' },
    founded_year: { type: 'number' },
    headquarters: { type: 'string' }
  },
  required: ['company_name']
}

for await (const message of query({
  prompt: 'Research Anthropic and provide key company information',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  // Pesan hasil berisi structured_output dengan data yang divalidasi
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

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 objek FeaturePlan yang diketik. Anda kemudian dapat mengakses properti seperti plan.summary dan mengulangi plan.steps dengan keamanan tipe penuh.

import { z } from 'zod'
import { query } from '@anthropic-ai/claude-agent-sdk'

// Tentukan skema dengan Zod
const FeaturePlan = z.object({
  feature_name: z.string(),
  summary: z.string(),
  steps: z.array(z.object({
    step_number: z.number(),
    description: z.string(),
    estimated_complexity: z.enum(['low', 'medium', 'high'])
  })),
  risks: z.array(z.string())
})

type FeaturePlan = z.infer<typeof FeaturePlan>

// Konversi ke JSON Schema
const schema = z.toJSONSchema(FeaturePlan)

// Gunakan dalam query
for await (const message of query({
  prompt: 'Plan how to add dark mode support to a React app. Break it into implementation steps.',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    // Validasi dan dapatkan hasil yang sepenuhnya diketik
    const parsed = FeaturePlan.safeParse(message.structured_output)
    if (parsed.success) {
      const plan: FeaturePlan = parsed.data
      console.log(`Feature: ${plan.feature_name}`)
      console.log(`Summary: ${plan.summary}`)
      plan.steps.forEach(step => {
        console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`)
      })
    }
  }
}

Manfaat:

• Inferensi tipe penuh (TypeScript) dan petunjuk tipe (Python)
• Validasi runtime dengan safeParse() atau model_validate()
• Pesan kesalahan yang lebih baik
• Skema yang dapat dikomposisi dan dapat digunakan kembali

Konfigurasi format output

Opsi outputFormat (TypeScript) atau output_format (Python) menerima objek dengan:

• type: Atur ke "json_schema" untuk output terstruktur
• schema: Objek JSON Schema yang menentukan struktur output Anda. Anda dapat menghasilkan ini dari skema Zod dengan z.toJSONSchema() atau model Pydantic dengan .model_json_schema()

SDK mendukung fitur JSON Schema standar termasuk semua tipe dasar (object, array, string, number, boolean, null), 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 otonom 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.

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

// Tentukan struktur untuk ekstraksi TODO
const todoSchema = {
  type: 'object',
  properties: {
    todos: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          text: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          author: { type: 'string' },
          date: { type: 'string' }
        },
        required: ['text', 'file', 'line']
      }
    },
    total_count: { type: 'number' }
  },
  required: ['todos', 'total_count']
}

// Agen menggunakan Grep untuk menemukan TODO, Bash untuk mendapatkan informasi git blame
for await (const message of query({
  prompt: 'Find all TODO comments in this codebase and identify who added them',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: todoSchema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    const data = message.structured_output
    console.log(`Found ${data.total_count} TODOs`)
    data.todos.forEach(todo => {
      console.log(`${todo.file}:${todo.line} - ${todo.text}`)
      if (todo.author) {
        console.log(`  Added by ${todo.author} on ${todo.date}`)
      }
    })
  }
}

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 memiliki subtype yang menunjukkan apa yang salah:

Contoh di bawah ini memeriksa bidang subtype untuk menentukan apakah output dihasilkan dengan berhasil atau jika Anda perlu menangani kegagalan:

for await (const msg of query({
  prompt: 'Extract contact info from the document',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: contactSchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      // Gunakan output yang divalidasi
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Tangani kegagalan - coba lagi dengan prompt yang lebih sederhana, kembali ke yang tidak terstruktur, dll.
      console.error('Could not produce valid output')
    }
  }
}

Tips untuk menghindari kesalahan:

• 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 diproduksi.

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
• Alat kustom: berikan agen Anda alat kustom untuk dipanggil selama eksekusi sebelum mengembalikan output terstruktur