Получение структурированного вывода от агентов

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

Для полной типобезопасности используйте Zod (TypeScript) или Pydantic (Python) для определения вашей схемы и получения строго типизированных объектов.

Зачем нужны структурированные выводы?

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

Рассмотрим приложение рецептов, где агент ищет в Интернете и возвращает рецепты. Без структурированных выводов вы получаете свободный текст, который вам нужно было бы парсить самостоятельно. Со структурированными выводами вы определяете нужную вам форму и получаете типизированные данные, которые можно использовать непосредственно в вашем приложении.

Быстрый старт

Чтобы использовать структурированные выводы, определите JSON Schema, описывающую форму данных, которые вы хотите, затем передайте его в query() через опцию outputFormat (TypeScript) или output_format (Python). Когда агент завершит работу, сообщение результата включает поле structured_output с валидированными данными, соответствующими вашей схеме.

Пример ниже просит агента исследовать Anthropic и вернуть название компании, год основания и штаб-квартиру как структурированный вывод.

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

// Определите форму данных, которые вы хотите получить
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
    }
  }
})) {
  // Сообщение результата содержит structured_output с валидированными данными
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

Типобезопасные схемы с Zod и Pydantic

Вместо написания JSON Schema вручную вы можете использовать Zod (TypeScript) или Pydantic (Python) для определения вашей схемы. Эти библиотеки генерируют JSON Schema для вас и позволяют парсить ответ в полностью типизированный объект, который вы можете использовать во всей вашей кодовой базе с автодополнением и проверкой типов.

Пример ниже определяет схему для плана реализации функции с резюме, списком шагов (каждый с уровнем сложности) и потенциальными рисками. Агент планирует функцию и возвращает типизированный объект FeaturePlan. Затем вы можете получить доступ к свойствам, таким как plan.summary, и перебирать plan.steps с полной типобезопасностью.

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

// Определите схему с 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>

// Преобразуйте в JSON Schema
const schema = z.toJSONSchema(FeaturePlan)

// Используйте в запросе
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) {
    // Валидируйте и получите полностью типизированный результат
    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}`)
      })
    }
  }
}

Преимущества:

• Полный вывод типов (TypeScript) и подсказки типов (Python)
• Валидация во время выполнения с safeParse() или model_validate()
• Лучшие сообщения об ошибках
• Составляемые, переиспользуемые схемы

Конфигурация формата вывода

Опция outputFormat (TypeScript) или output_format (Python) принимает объект с:

• type: Установите на "json_schema" для структурированных выводов
• schema: Объект JSON Schema, определяющий структуру вашего вывода. Вы можете сгенерировать это из схемы Zod с z.toJSONSchema() или модели Pydantic с .model_json_schema()

SDK поддерживает стандартные функции JSON Schema, включая все основные типы (object, array, string, number, boolean, null), enum, const, required, вложенные объекты и определения $ref. Для полного списка поддерживаемых функций и ограничений см. Ограничения JSON Schema.

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

Этот пример демонстрирует, как работают структурированные выводы с многошаговым использованием инструментов. Агент должен найти комментарии TODO в кодовой базе, а затем найти информацию git blame для каждого из них. Он автономно решает, какие инструменты использовать (Grep для поиска, Bash для запуска команд git) и объединяет результаты в один структурированный ответ.

Схема включает необязательные поля (author и date), так как информация git blame может быть недоступна для всех файлов. Агент заполняет то, что может найти, и опускает остальное.

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

// Определите структуру для извлечения 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']
}

// Агент использует Grep для поиска TODO, Bash для получения информации 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}`)
      }
    })
  }
}

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

Генерация структурированного вывода может не пройти, когда агент не может создать валидный JSON, соответствующий вашей схеме. Это обычно происходит, когда схема слишком сложна для задачи, сама задача неоднозначна или агент достигает лимита повторных попыток при попытке исправить ошибки валидации.

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

Пример ниже проверяет поле subtype, чтобы определить, был ли вывод успешно сгенерирован или вам нужно обработать сбой:

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) {
      // Используйте валидированный вывод
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Обработайте сбой - повторите с более простым запросом, вернитесь к неструктурированному и т.д.
      console.error('Could not produce valid output')
    }
  }
}

Советы по избежанию ошибок:

• Держите схемы сосредоточенными. Глубоко вложенные схемы со многими обязательными полями сложнее удовлетворить. Начните с простого и добавляйте сложность по мере необходимости.
• Соответствуйте схему задаче. Если задача может не иметь всю информацию, которую требует ваша схема, сделайте эти поля необязательными.
• Используйте четкие подсказки. Неоднозначные подсказки затрудняют для агента понимание того, какой вывод производить.

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

• Документация JSON Schema: изучите синтаксис JSON Schema для определения сложных схем с вложенными объектами, массивами, перечислениями и ограничениями валидации
• API Structured Outputs: используйте структурированные выводы с Claude API напрямую для однооборотных запросов без использования инструментов
• Пользовательские инструменты: дайте вашему агенту пользовательские инструменты для вызова во время выполнения перед возвратом структурированного вывода