Руководства

Структурированные выходные данные в SDK

Получайте проверенные результаты JSON из рабочих процессов агентов

Получайте структурированные, проверенные JSON из рабочих процессов агентов. Agent SDK поддерживает структурированные выходные данные через JSON Schemas, гарантируя, что ваши агенты возвращают данные в точном формате, который вам нужен.

Когда использовать структурированные выходные данные

Используйте структурированные выходные данные, когда вам нужен проверенный JSON после того, как агент завершит многоходовый рабочий процесс с инструментами (поиск файлов, выполнение команд, веб-исследование и т. д.).

Для одиночных вызовов API без использования инструментов см. API Structured Outputs.

Почему использовать структурированные выходные данные

Структурированные выходные данные обеспечивают надежную интеграцию, безопасную по типам, с вашими приложениями:

Проверенная структура: Всегда получайте корректный JSON, соответствующий вашей схеме
Упрощенная интеграция: Не требуется код для парсинга или валидации
Безопасность типов: Используйте с подсказками типов TypeScript или Python для полной безопасности
Чистое разделение: Определяйте требования к выходным данным отдельно от инструкций задачи
Автономия инструментов: Агент выбирает, какие инструменты использовать, гарантируя формат выходных данных

Как работают структурированные выходные данные

Определите вашу JSON схему
Создайте JSON Schema, которая описывает структуру, которую должен вернуть агент. Схема использует стандартный формат JSON Schema.
Добавьте параметр outputFormat
Включите параметр outputFormat в параметры запроса с type: "json_schema" и определением вашей схемы.
Запустите ваш запрос
Агент использует любые инструменты, необходимые для выполнения задачи (операции с файлами, команды, веб-поиск и т. д.).
Получите доступ к проверенному выходу
Окончательный результат агента будет корректным JSON, соответствующим вашей схеме, доступным в message.structured_output.

Поддерживаемые функции JSON Schema

Agent SDK поддерживает те же функции и ограничения JSON Schema, что и API Structured Outputs.

Ключевые поддерживаемые функции:

Все базовые типы: object, array, string, integer, number, boolean, null
enum, const, required, additionalProperties (должно быть false)
Форматы строк: date-time, date, email, uri, uuid и т. д.
$ref, $def и definitions

Для полной информации о поддерживаемых функциях, ограничениях и поддержке регулярных выражений см. JSON Schema limitations в документации API.

Пример: агент отслеживания TODO

Вот полный пример, показывающий агента, который ищет TODO в коде и извлекает информацию о 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}`)
      }
    })
  }
}

Агент автономно использует правильные инструменты (Grep, Bash) для сбора информации и возвращает проверенные данные.

Обработка ошибок

Если агент не может создать корректный выход, соответствующий вашей схеме, вы получите результат ошибки:

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')
    }
  }
}

Связанные ресурсы

JSON Schema documentation
API Structured Outputs - Для одиночных вызовов API
Custom tools - Определите инструменты для ваших агентов
TypeScript SDK reference - Полный API TypeScript
Python SDK reference - Полный API Python