Output terstruktur dalam SDK

Dapatkan JSON terstruktur dan tervalidasi dari alur kerja agen. Agent SDK mendukung output terstruktur melalui JSON Schemas, memastikan agen Anda mengembalikan data dalam format yang tepat sesuai kebutuhan Anda.

Mengapa menggunakan output terstruktur

Output terstruktur menyediakan integrasi yang andal dan type-safe dengan aplikasi Anda:

• Struktur yang divalidasi: Selalu terima JSON yang valid sesuai dengan skema Anda
• Integrasi yang disederhanakan: Tidak perlu kode parsing atau validasi
• Keamanan tipe: Gunakan dengan petunjuk tipe TypeScript atau Python untuk keamanan end-to-end
• Pemisahan yang bersih: Tentukan persyaratan output secara terpisah dari instruksi tugas
• Otonomi tool: Agen memilih tool mana yang akan digunakan sambil menjamin format output

Cara kerja output terstruktur

Fitur JSON Schema yang didukung

Agent SDK mendukung fitur dan batasan JSON Schema yang sama seperti API Structured Outputs.

Fitur utama yang didukung:

• Semua tipe dasar: object, array, string, integer, number, boolean, null
• enum, const, required, additionalProperties (harus false)
• Format string: date-time, date, email, uri, uuid, dll.
• $ref, $def, dan definitions

Untuk detail lengkap tentang fitur yang didukung, batasan, dan dukungan pola regex, lihat JSON Schema limitations dalam dokumentasi API.

Contoh: Agen pelacakan TODO

Berikut adalah contoh lengkap yang menunjukkan agen yang mencari TODO dalam kode dan mengekstrak informasi git blame:

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

// Define structure for TODO extraction
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']
}

// Agent uses Grep to find TODOs, Bash to get git blame info
for await (const message of query({
  prompt: 'Find all TODO comments in src/ 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}`)
      }
    })
  }
}

Agen secara otonomi menggunakan tool yang tepat (Grep, Bash) untuk mengumpulkan informasi dan mengembalikan data yang divalidasi.

Penanganan kesalahan

Jika agen tidak dapat menghasilkan output yang valid sesuai dengan skema Anda, Anda akan menerima hasil kesalahan:

for await (const msg of query({
  prompt: 'Analyze the data',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: mySchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      console.error('Could not produce valid output')
    }
  }
}

Sumber daya terkait

• JSON Schema documentation
• API Structured Outputs - Untuk panggilan API tunggal
• Custom tools - Tentukan tool untuk agen Anda
• TypeScript SDK reference - Referensi API TypeScript lengkap
• Python SDK reference - Referensi API Python lengkap