Руководство по пониманию, созданию и оптимизации агентов, вызывающих 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 или функция часто представлена как “инструмент”. Надежное определение инструмента включает:

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

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

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

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

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

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

• Pydantic: Хотя это не исключительно фреймворк агента, Pydantic полезен для определения структур данных и обеспечения безопасности типов для входных и выходных данных инструментов, что важно для надежности. Многие пользовательские реализации агентов используют Pydantic для этой структурной целостности.
• мcp_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 для моделирования данных в пользовательской структуре агента или использование фреймворка, такого как мcp_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.