Разработка агента с помощью интерфейса командной строки разработчика Azure

Important

Элементы, помеченные предварительным просмотром в этой статье, в настоящее время находятся в предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и Microsoft не рекомендует использовать её для рабочих нагрузок в производственной среде. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.

Azure Developer CLI (azd) и его расширение azd ai agent обеспечивают единый рабочий процесс в командной строке, позволяя пройти путь от идеи до готового к промышленному использованию агента на Microsoft Foundry. Вы можете создавать размещаемых агентов на основе кода и декларативных голосовых агентов на основе промптов. В этой статье объясняются путь разработчика, файлы, определяющие агента, и основные понятия, с которыми вы столкнётесь в процессе.

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

Путешествие разработчика

Процесс azd ai проходит один и тот же жизненный цикл независимо от того, создаёте ли вы небольшой прототип или промышленный агент. Вы один раз создаете каркас проекта, а затем комбинируете команды по мере его развития.

Этап	Что вы делаете	Где узнать больше
Install	Установите `azd` и расширения для Foundry.	Настройка среды разработчика
Каркас	Инициализировать размещенный агент из шаблона или существующего кода или создать агент голосовой связи на основе запроса.	Краткое руководство: Развертывание размещенного агента или Краткое руководство: Создание голосового агента с подсказками
Определять	Настройте агент, зависимости развертывания модели, протоколы, инструменты и среду в `azure.yaml`.	Создание файла azure.yaml для размещённых агентов
Develop	Написание логики агента, добавление инструментов с помощью панели элементов и локальное тестирование.	Обзор панели элементов
Deploy	Подготовка инфраструктуры и развертывание в Foundry.	Развертывание размещенного агента
Работать	Отслеживайте журналы, управляйте версиями и автоматизируйте запуски.	Управление размещенными агентами
Evaluate	Оцените качество агента и улучшите запрос.	Выполнение вычислений агента с помощью azd CLI

Типы агентов

Расширение azd ai agent поддерживает типы агентов на основе кода и декларативных агентов.

Тип	Description	Когда использовать
Агент на хостинге	Контейнеризованное приложение, которое вы создаете в коде, упаковываете в образ Docker и развертываете в Foundry.	Вам нужна собственная логика, интеграция с фреймворком или полный контроль над поведением.
Агент подсказок	Агент полностью определен с помощью инструкций и конфигураций инструментов без пользовательского кода.	Вам нужен быстрый управляемый конфигурацией агент без написания кода приложения.
Агент голосовой связи на основе запроса	Декларативный голосовой агент, использующий управляемую или самостоятельно развертываемую модель без пользовательского кода среды выполнения.	Вы хотите использовать голосовую связь в режиме реального времени без создания и размещения звукового конвейера.
Хостинговый голосовой агент с управляемой обёрткой	Размещённый целевой узел обрабатывает логику диалога, а отдельная голосовая служба делегирует ему через `conversationEngine`. Voice Live отвечает за аудиовозможности.	Вам нужна собственная логика агента без необходимости реализовывать распознавание и синтез речи на размещённой целевой платформе.

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

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

Чтобы сохранить логику диалога в развернутом текстовом агенте, пока Voice Live обрабатывает аудио, используйте сценарий обертки для хостируемого голосового агента. Оболочка и целевой объект являются отдельными службами в одном azure.yaml проекте. Этот поток не заменяет существующий пользовательский invocations_ws поток аудио-конвейера.

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

Файлы конфигурации

Проект размещённого агента использует один файл azure.yaml в корневом каталоге проекта для определения как самого агента, так и его модели подготовки инфраструктуры и развертывания. В файле используется модель разделения служб, где каждая именованная служба имеет значение host, например azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skill или azure.ai.routine.

File	Purpose	Кто поддерживает его
`azure.yaml`	Определяет проект Foundry, развертывания моделей, размещённую службу агента, зависимости, протоколы, инструменты, переменные среды, ресурсы контейнера и параметры развертывания. Идентификатор агента, модель, протоколы, инструменты и значения переменных среды хранятся в службе `azure.ai.agent`.	Инициализация создает ее. Вы настраиваете его по мере необходимости.

Служба azure.ai.agent определяет вашего размещённого агента непосредственно и использует uses: для обращения к другим службам, таким как проект, подключения, наборы инструментов, навыки и подпрограммы. В текущей модели проекта agent.yaml с размещённым агентом нет отдельного файла agent.manifest.yaml или azd.

Для голосового агента на основе промптов azure.yaml хранит декларативное определение агента, включая kind: prompt-voice, модель, тип модели и имя агента. Не включает среду выполнения контейнеров для размещаемого агента. Сведения о настройке инструкций, распознавания звука, транскрибирования, вывода голоса, инструментов и приветствий см. в статье "Настройка голосового агента".

Для размещенной голосовой оболочки conversationEngine.name ссылается на имя службы размещенного целевого объекта. Зависимость оболочки conversationEngine.version задаёт порядок развертывания, а uses по умолчанию использует версию, развернутую в текущей среде. См. справочник по голосовой службе для полей конфигурации.

Замена переменных

Используйте ${VAR_NAME} в azure.yaml для значений, которые различаются в зависимости от среды azd. Заполнитель подставляется из .azure/<env>/.env во время развертывания или выполнения, поэтому один и тот же azure.yaml работает в разных средах, например dev, стейджинг и продакшен.

Где запускается CLI

Команды azd ai работают как внутри, так и за пределами azd каталога проекта:

В проекте azd команды определяют конечный адрес проекта Foundry из активной среды azd.
Вне проекта один раз задайте активный контекст с помощью azd, или передайте azd ai project set <endpoint> в отдельной команде ресурса (--project-endpoint, connection, toolbox или skill). В качестве запасного варианта azd ai считывает переменную среды FOUNDRY_PROJECT_ENDPOINT.
Среда в проекте всегда имеет приоритет над глобальным контекстом, поэтому изменение каталогов в проект перенацеливает интерфейс командной строки в конечной точке этого проекта.

Протоколы

Протокол определяет http-контракт между Foundry и контейнером агента. Ваш агент прослушивает порт 8088 и отвечает на проверки работоспособности независимо от протокола.

Protocol	Стиль API	Когда использовать
`responses`	API ответов OpenAI (`POST /responses`)	Стандартный выбор, совместимый с экосистемой API OpenAI.
`invocations`	Настраиваемый контракт JSON (`POST /invocations`)	Когда нужен полный контроль над данными запросов и ответов.

Полное описание см. в документе контракт среды выполнения размещённого агента.

Эти параметры протокола применяются к контейнерам размещённого агента. Голосовые агенты на основе промптов не поддерживают протокол хостируемого агента.

azd ai agent invoke не поддерживает голосовые диалоги для голосовых агентов на основе промптов или размещённых голосовых обёрток. Рекомендации по поведению и тестированию интерфейса командной строки см. в разделе об ограничениях агента голосовой связи.

Сеансы и беседы

Концепция	Description
Session	Изолированная среда выполнения для взаимодействия с одним агентом. Каждый сеанс проходит в собственной песочнице с выделенными ресурсами.
Разговор	Последовательность сообщений в сеансе. Foundry управляет историей беседы и может восстанавливать её между запросами.

Сеансы идентифицируются с помощью session_id. При запуске azd ai agent invoke Foundry по умолчанию повторно использует сеанс, созданный при последнем запуске. Используйте --new-session, чтобы начать заново, или --session-id <id>, чтобы указать конкретный сеанс.

Ресурсы в проекте Foundry

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

Resource	Что это такое	Управляется с помощью
Connection	Связывает проект Foundry с внешним ресурсом, таким как сервер MCP, Поиск с использованием ИИ Azure или Grounding with Bing.	Команды `azd ai connection`.
Ящик для инструментов	Именованная коллекция инструментов, используемых агентами в процессе выполнения.	Команды `azd ai toolbox`.
Skill	Повторно используемое руководство по поведению, совместно используемое между агентами в проекте.	Команды `azd ai skill`.
Рутина	Триггер и действие, которое запускает агента.	Команды `azd ai routine`.

Эти ресурсы совместно используются разработчиками и агентами в одном проекте. Каждая группа команд поддерживает стандартные глаголы create, update, delete, show и list.

Оценка и улучшение агента

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

Оценка запускает вашего агента на наборе данных, оценивает ответы с помощью одного или нескольких оценщиков и выдает сводный показатель качества. Вы управляете этим с помощью azd ai agent eval.
Оптимизация итеративно перезаписывает запрос агента на отмену сигнала оценки. Она использует оценку в качестве целевой функции и создает запрос кандидата, который вы просматриваете и принимаете. Вы управляете этим с помощью azd ai agent optimize.

Дополнительные сведения см. в разделах Запуск оценки агента с помощью azd CLI и Оптимизация промптов агента.

Жизненный цикл развертывания

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

Сведения о сценарии с управляемым голосовым агентом см. в кратком руководстве: Создание голосового агента с подсказкой.

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-09-24