Использование azd ai с агентами программирования и скриптами

Important

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

Используйте azd ai из агентов для программирования и скриптов с тем же поведением, которое доступно человеку в терминале. Вы задаете автономный контекст, отключаете запросы, анализируете выходные данные JSON и вызываете конечные точки прямого агента для надежной автоматизации.

Необходимые условия

Начните с навыка Microsoft Foundry

Агенты программирования лучше всего работают, когда они уже знают azd ai соглашения. Навык Microsoft Foundry дает агенту программирования эти знания: он генерирует правильные команды azd ai и связи Foundry, а также применяет описанные в этой статье методы — задает контекст проекта, передает --no-prompt и запрашивает --output json для получения структурированных результатов. Сначала направьте своего ИИ-агента для программирования на навык, а затем используйте приёмы из остальной части этой статьи, чтобы проверить и усилить защиту того, что он создаёт.

Задайте контекст проекта один раз

Для каждой команды для ресурсов, например connection, toolbox, skill или routine, необходимо указать конечную точку проекта Foundry. При автоматизации настройте этот эндпоинт один раз для каждого сеанса, задания CI или запуска coding-агента, а затем используйте его до конца выполнения.

Существует два шаблона.

Закрепите одним нажатием с помощью azd ai project set

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

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> полностью неактивен, если вы уже знаете URL-адрес. azd ai project show подтверждает, какой источник определил активный конечный узел. Используйте его в начале сеанса, если вы не уверены, в каком состоянии находится хост.

Установка переменной среды

Задайте FOUNDRY_PROJECT_ENDPOINT в среде, в которой выполняется скрипт или агент программирования. Каждая azd ai команда автоматически выбирает ее после среды azd в проекте и глобальной конфигурации.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

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

Полное описание того, как CLI определяет конечную точку, включая порядок приоритета, см. в разделе Настройка контекста проекта azd.

Отключить подсказки

Каждая azd ai команда принимает --no-prompt. Если задать этот параметр, команда сразу завершается с ошибкой вместо ожидания интерактивного ввода. Отсутствующий обязательный аргумент или запрос delete подтверждения, который в противном случае ожидал бы нажатия клавиши, сразу приводит к ошибке при использовании структурированного вывода.

Всегда задается --no-prompt в CI и в вызовах агента кодирования.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Tip

--no-prompt также подразумевает "пропустить delete запрос подтверждения", поэтому вам не нужно --force просто подавлять этот запрос.

Получение выходных данных JSON

Большинство команд azd ai поддерживают --output json, включая команды ресурсов connection, toolbox, skill и routine, а также azd ai agent show. Используйте это, чтобы надежно разбирать результат с помощью jq, ConvertFrom-Json или JSON-парсера вашего языка, вместо того чтобы извлекать данные из человекочитаемого текстового вывода. Команда azd ai agent invoke используется --output raw для неизмененных ответов сервера.

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

Текстовый вывод предназначен для людей и может меняться от версии к версии. Структура JSON — это неизменный контракт.

Создавайте ресурсы с поддержкой идемпотентности

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

Для автоматизации, которая должна быть успешно выполнена независимо от предыдущего состояния, connection команды принимают --force для замены существующего ресурса.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Предупреждение

--force ЗАМЕНЯЕТ соединение (ARM PUT), оно не объединяется. Используйте это с осторожностью при работе с общими ресурсами, поскольку изменения, внесённые другим вызывающим процессом в тот же ресурс, могут быть потеряны.

Если вам нужно изменить только несколько полей и сохранить все остальное, используйте update. Или используйте специальные подкоманды для коллекций, например tool, tag, metadata и key.

Создать набор инструментов из файла

Для многоэлементного набора инструментов, который включает встроенные инструменты, подключения и навыки, поместите полное определение в YAML-файл и передайте --from-file в azd ai toolbox create. Файл использует соответствующую фигуру AgentSchema .

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file считывает входные данные однократно в момент вызова. Интерфейс командной строки не отслеживает или повторно считывает файл, поэтому будущие изменения в YAML не влияют до повторного запуска команды. Создайте подключения с явными флагами (--kind, --target, --auth-type и соответствующими флагами учетных данных), а затем указывайте их по имени в файле набора инструментов.

Вызов развернутого агента без проекта azd

Если агенту для написания кода или скрипту нужно вызвать развернутого агента, который находится вне его рабочего каталога, используйте --agent-endpoint, чтобы обратиться к нему напрямую. Этот подход обходит как azure.yaml, так и активное окружение azd env. Одного URL-адреса достаточно.

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

Используйте эту фигуру, когда CI в одном репозитории должен вызывать агента, принадлежащего другому репозиторию, или когда сервер MCP служит интерфейсом для нескольких агентов и знает только URL конечных точек. Полный invoke набор параметров см. в разделе "Вызов размещенного агента".

Передайте секреты при локальном запуске

Чтобы локально запустить агент с секретами, задайте их как переменные среды azd и сошлитесь на них из карты env для вашей службы azure.ai.agent в azure.yaml. Значения живут в .azure/<env>/.env, в котором по умолчанию gitignored.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

Для секретов, которые не следует хранить в локальном файле .env, сохраните их в подключении проекта в Foundry и ссылайтесь на них с помощью заполнителя ${{connections.<name>.credentials.<field>}}. См. статью "Запуск размещенного агента локально" для полной локальной среды выполнения.

Скрипт краткой настройки

Этот скрипт bash объединяет приведенные выше шаблоны. Он фиксирует контекст проекта, идемпотентно создает подключение и набор инструментов, добавляет инструмент в набор инструментов и проверяет результат, разбирая JSON.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail гарантирует, что скрипт немедленно завершит выполнение при ошибке на любом шаге. В сочетании с --no-prompt это дает предсказуемый код завершения, подходящий для проверок CI.

Просмотр разрешения конечных точек

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

  1. --project-endpoint (или -p) флаг (всегда выигрывает).
  2. В проекте azd: значение активной среды azd.
  3. Глобальная конфигурация (задаётся через azd ai project set).
  4. Переменная среды FOUNDRY_PROJECT_ENDPOINT.
  5. Ошибка со структурированной рекомендацией запустить azd ai project set или передать --project-endpoint.

Полное объяснение, включая взаимодействие автономного контекста с работой в проекте, см. в разделе "Задать контекст проекта azd".

Примените советы по использованию агента для программирования

  • Всегда передавайте --no-prompt и добавляйте --output json в командах, которые его поддерживают. Вместе они обеспечивают предсказуемый код выхода и результат, пригодный для разбора.
  • Проверьте определённый контекст с помощью azd ai project show в начале сеанса, если вы не уверены, в каком состоянии находится хост. Это дешевый, доступный только для чтения звонок.
  • При сбое для определения дальнейших шагов предпочтительно разбирать структурированную рекомендацию в сообщении об ошибке. Например, ошибка "No Foundry project endpoint resolved" означает, что перед повторной попыткой необходимо выполнить azd ai project set, или задать FOUNDRY_PROJECT_ENDPOINT.
  • Используйте --debug только при диагностике проблемы. Он выдает многословный многострочный вывод, который трудно разбирать и который изначально не предназначался для программного доступа.
  • Считать сбои create с сообщением "уже существует" устранимыми. Повторно запустите команду с --force, если хотите заменить ресурс целиком, или переключитесь на update и подкоманды коллекции, если вам нужно изменить только его часть.

Связанный контент

  • Последнее обновление: