Руководство по пониманию, созданию и оптимизации агентов, вызывающих API API списка дел version: 1.0.0 paths: /tasks: post: summary: Добавить новое задание requestBody: required: true

Роль искусственного интеллекта в технологических компаниях быстро эволюционирует; случаи использования ИИ эволюционировали от пассивной обработки информации до активных агентов, способных выполнять задачи. Согласно опросу о глобальном внедрении ИИ, проведенному в марте 2025 года Georgian и NewtonX, 91% технических руководителей компаний на этапе роста и крупных предприятий, как сообщается, используют или планируют использовать агентный ИИ.

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

Например, переводя естественные языковые команды в точные вызовы API, агенты могут получать данные в режиме реального времени, автоматизировать рутинные задачи или даже управлять другими программными системами. Эта возможность превращает агентов ИИ в полезных посредников между человеческими намерениями и программной функциональностью.

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

• Приложения для потребителей: Помощники, такие как Siri от Apple или Alexa от Amazon, были разработаны для упрощения повседневных задач, таких как управление устройствами умного дома и бронирование.
• Потоки работы предприятий: Предприятия развернули агенты API для автоматизации повторяющихся задач, таких как получение данных из CRM, генерация отчетов или консолидация информации из внутренних систем.
• Получение и анализ данных: Предприятия используют агенты API для упрощения доступа к проприетарным наборам данных, ресурсам по подписке и общедоступным API для генерации информационных сообщений.

В этой статье я буду использовать инженерный подход к пониманию, созданию и оптимизации агентов, вызывающих API. Материал в этой статье основан частично на практических исследованиях и разработках, проведенных лабораторией ИИ Georgian. Основной вопрос, который движет многими исследованиями лаборатории ИИ в области агентов, вызывающих API, был: “Если у организации есть API, какой наиболее эффективный способ построить агент, который может взаимодействовать с этим API, используя естественный язык?”

Я объясню, как работают агенты, вызывающие API, и как успешно архитектурно и инженерно проектировать эти агенты для производительности. Наконец, я предоставлю системный рабочий процесс, который команды инженеров могут использовать для реализации агентов, вызывающих API.

I. Ключевые определения:

• API или интерфейс программирования приложений: Набор правил и протоколов, позволяющих различным программным приложениям общаться и обмениваться информацией.
• Агент: Система ИИ, предназначенная для восприятия своей среды, принятия решений и выполнения действий для достижения конкретных целей.
• Агент, вызывающий API: Специализированный агент ИИ, переводящий естественные языковые инструкции в точные вызовы API.
• Агент, генерирующий код: Система ИИ, помогающая в разработке программного обеспечения, записывая, изменяя и отлаживая код. Хотя связано, моя основная направленность здесь в основном на агентах, которые вызывают API, хотя ИИ также может помочь создать этих агентов.
• MCP (Протокол контекста модели): Протокол, разработанный, например, Anthropic, определяющий, как LLM могут подключаться к внешним инструментам и источникам данных.

II. Основная задача: перевод естественного языка в действия API

Фундаментальной функцией агента, вызывающего API, является интерпретация запроса пользователя на естественном языке и преобразование его в один или несколько точных вызовов API. Этот процесс обычно включает:

1. Распознавание намерения: Понимание цели пользователя, даже если она выражена неоднозначно.
2. Выбор инструмента: Определение соответствующей конечной точки API (или “инструмента”) из набора доступных вариантов, которые могут выполнить намерение.
3. Извлечение параметров: Определение и извлечение необходимых параметров для вызовов API из запроса пользователя.
4. Выполнение и генерация ответа: Вызов API, получение ответа и затем синтез этой информации в связный ответ или выполнение последующего действия.

Рассмотрим запрос, такой как “Привет, Siri, какая погода сегодня?” Агент должен определить необходимость вызова API погоды, определить местоположение пользователя (или разрешить указание местоположения) и затем сформулировать вызов API для получения информации о погоде.

Для запроса “Привет, Siri, какая погода сегодня?” образец вызова API может выглядеть так:

GET /v1/weather?location=New%20York&units=metric

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

Например, агент должен часто “помнить” предыдущие части разговора или предыдущие результаты вызовов API, чтобы информировать текущие действия.

Потеря контекста является распространенным режимом сбоя, если не управлять им явно.

III. Архитектура решения: ключевые компоненты и протоколы

Построение эффективных агентов, вызывающих API, требует структурированного архитектурного подхода.

1. Определение “инструментов” для агента

Для того чтобы LLM могла использовать API, возможности этого API должны быть описаны в понятной для нее форме. Каждая конечная точка API или функция часто представлена как “инструмент”. Надежное определение инструмента включает:

• Ясное, естественное описание цели и функциональности инструмента.
• Точное описание его входных параметров (имя, тип, является ли он обязательным или необязательным, и описание).
• Описание выходных данных или информации, возвращаемой инструментом.

2. Роль протокола контекста модели (MCP)

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

Стандартизация MCP полезна, поскольку она позволяет легче интегрировать различные инструменты, способствует повторному использованию определений инструментов в разных агентах или моделях. Кроме того, это лучшая практика для команд инженеров, начиная с хорошо определенных спецификаций API, таких как спецификация OpenAPI. Инструменты, такие как Stainless.ai, предназначены для помощи в преобразовании этих спецификаций OpenAPI в конфигурации MCP, упрощая процесс того, чтобы сделать API “готовыми к агенту”.

3. Фреймворки агентов и варианты реализации

Несколько фреймворков могут помочь в построении самого агента. Это включает:

• Pydantic: Хотя это не исключительно фреймворк агента, Pydantic полезен для определения структур данных и обеспечения безопасности типов для входных и выходных данных инструментов, что важно для надежности. Многие пользовательские реализации агентов используют Pydantic для этой структурной целостности.
• mcp_agent от LastMile: Этот фреймворк специально разработан для работы с MCP, предлагая более мнительный структуру, соответствующую практикам построения эффективных агентов, описанным в исследованиях из таких мест, как Anthropic.
• Внутренний фреймворк: Также становится все более распространенным использовать агенты ИИ, генерирующие код (с помощью инструментов, таких как Cursor или Cline), чтобы помочь написать код для агента, его инструментов и окружающей логики. Опыт лаборатории ИИ Georgian, работающей с компаниями над реализациями агентов, показывает, что это может быть отлично для создания очень минимальных, пользовательских фреймворков.

IV. Инженерия для надежности и производительности

Обеспечение того, чтобы агент делал вызовы API надежно и работал хорошо, требует сосредоточенных инженерных усилий. Два способа сделать это – это создание набора данных и проверка, а также проектирование и оптимизация подсказок.

1. Создание и проверка набора данных

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

• Ручное создание: Ручная курирование набора данных обеспечивает высокую точность и актуальность, но может быть трудоемким.
• Синтетическая генерация: Генерация данных программно или с помощью LLM может масштабировать создание набора данных, но этот подход представляет значительные проблемы. Исследования лаборатории ИИ Georgian показали, что обеспечение правильности и реалистичной сложности синтетически сгенерированных вызовов API и запросов очень сложно. Часто генерируемые вопросы были либо слишком тривиальными, либо невозможными, что делало трудным измерение тонкой производительности агента. Тщательная проверка синтетических данных абсолютно критична.

Для критической оценки меньший, высококачественный, ручной набор данных часто обеспечивает более надежные выводы, чем большой, шумный синтетический.

2. Проектирование и оптимизация подсказок

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

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

V. Рекомендуемый путь к эффективным агентам API

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

1. Начните с четких определений API: Начните с хорошо структурированных спецификаций OpenAPI для API, с которыми будет взаимодействовать ваш агент.
2. Стандартизируйте доступ к инструментам: Преобразуйте свои спецификации OpenAPI в MCP. Инструменты, такие как Stainless.ai, могут облегчить это, создавая стандартизированный способ для вашего агента понять и использовать ваши API.
3. Реализуйте агент: Выберите подходящий фреймворк или подход. Это может включать использование Pydantic для моделирования данных в пользовательской структуре агента или использование фреймворка, такого как mcp_agent от LastMile, который предназначен для работы с MCP.
   • Прежде чем делать это, рассмотрите возможность подключения MCP к инструменту, такому как Claude Desktop или Cline, и ручное использование этого интерфейса, чтобы получить представление о том, насколько хорошо общий агент может использовать его, сколько итераций обычно требуется для использования MCP правильно, и любые другие детали, которые могут сэкономить время во время реализации.
4. Создайте качественный набор данных для оценки: Ручное создание или тщательная проверка набора данных запросов и ожидаемых взаимодействий API. Это критически важно для надежного тестирования и оптимизации.
5. Оптимизируйте подсказки и логику агента: Используйте фреймворки, такие как DSPy, чтобы усовершенствовать подсказки и внутреннюю логику вашего агента, используя ваш набор данных для улучшения точности и надежности.

VI. Иллюстративный пример рабочего процесса

Вот упрощенный пример, иллюстрирующий рекомендуемый рабочий процесс для построения агента, вызывающего API:

Шаг 1: Начните с четких определений API

Представьте API для управления простым списком дел, определенным в OpenAPI:

openapi: 3.0.0

info:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: Задание создано успешно

get:

summary: Получить все задания

responses:

‘200’:

description: Список заданий

Шаг 2: Стандартизируйте доступ к инструментам

Преобразуйте спецификацию OpenAPI в конфигурации протокола контекста модели (MCP). Используя инструмент, такой как Stainless.ai, это может дать:

Шаг 3: Реализуйте агент

Используя Pydantic для моделирования данных, создайте функции, соответствующие конфигурациям MCP. Затем используйте LLM для интерпретации естественных языковых запросов и выбора соответствующего инструмента и параметров.

Шаг 4: Создайте качественный набор данных для оценки

Создайте набор данных:

Шаг 5: Оптимизируйте подсказки и логику агента

Используйте DSPy для усовершенствования подсказок, сосредоточившись на ясных инструкциях, выборе инструментов и извлечении параметров, используя курируемый набор данных для оценки и улучшения.

Интегрируя эти строительные блоки – от структурированных определений API и стандартизированных протоколов инструментов до строгих практик данных и систематической оптимизации – команды инженеров могут построить более способных, надежных и поддерживаемых агентов ИИ, вызывающих API.