Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Important
Элементы, помеченные (предварительная версия) в этой статье, в настоящее время находятся в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.
CLI Azure Developer (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. | Вам нужна собственная логика, интеграция с фреймворком или полный контроль над поведением. |
| Агент подсказок | Агент полностью определен с помощью инструкций и конфигураций инструментов без пользовательского кода. | Вам нужен быстрый управляемый конфигурацией агент без написания кода приложения. |
Размещенные агенты обеспечивают полный контроль над средой выполнения, платформой и интеграцией инструментов, а Foundry обрабатывает инфраструктуру, масштабирование и управление сеансами.
Файлы конфигурации
Проект размещённого агента использует один файл 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: для обращения к другим службам, таким как проект, подключения, наборы инструментов, навыки и подпрограммы. В текущей модели проекта azd с размещённым агентом нет отдельного файла agent.yaml или agent.manifest.yaml.
Замена переменных
Используйте ${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) |
Когда нужен полный контроль над данными запросов и ответов. |
Полное описание см. в документе контракт среды выполнения размещённого агента.
Сеансы и беседы
| Концепция | 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