Разверните размещённый агент из исходного кода

В этой статье показано, как развернуть размещённый агент в службе Foundry Agent Service из исходного кода Python или .NET без сборки и отправки образа контейнера. Вы отправляете .zip код (и при необходимости зависимости), а служба агента выполняет ее as-is или создает зависимости для вас в облаке.

Tip

В большинстве случаев используйте Azure Developer CLI (azd) или Foundry Toolkit для VS Code для развертывания. Эти средства берут на себя основную работу: они упаковывают ваш исходный код, загружают его, опрашивают active и автоматически настраивают управление доступом на основе ролей. Чтобы приступить к работе, выполните краткое руководство. Разверните первый размещенный агент и выберите код (или исходный код (ZIP-отправка)) при появлении запроса на метод развертывания.

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

  • Выберите режим разрешения зависимостей и упаковайте источник.
  • Создайте агент, подождите, пока он не достигнет active, и вызовите его.
  • Обновление, версия, скачивание и потоковая передача журналов для развернутого агента.

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

Если вы используете ИИ-ассистент для программирования, такой как GitHub Copilot, для упаковки и развертывания исходного кода, Навык Microsoft Foundry может помочь подготовить ваш проект и выполнить необходимые azdдействия для SDK или REST.

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

  • Проект Microsoft Foundry в поддерживаемом регионе.
  • Azure CLI версии 2.80 или более поздней, войдите в клиент, которому принадлежит проект.

  • pip в Python 3.13 и более поздних версиях, чтобы упаковать исходный код локально.

  • Версия azure-ai-projects 2.2.0 или более поздняя, а также пакеты azure-identity.

    pip install "azure-ai-projects>=2.2.0" azure-identity

Поддерживаемые среды выполнения

Поле code_configuration.runtime в определении агента принимает следующие значения. Выберите среду выполнения, соответствующую двоичным файлам в вашем ZIP-архиве: Linux wheel-пакетам x86_64 для Python или TargetFramework в выходных данных dotnet publish для .NET.

Язык Значения времени выполнения
Python python_3_13, python_3_14
.NET dotnet_10

Политика поддержки версий языка

Среда выполнения службы агента включает созданный платформой образ контейнера для каждого значения code_configuration.runtime. Чтобы развернутые агенты оставались полностью поддерживаемыми, Foundry приводит поддержку языков для размещенных агентов в соответствие со сроками окончания поддержки каждого языка. Поддержка заканчивается на дату окончания поддержки сообщества для языковой версии. Microsoft может прекратить поддержку значения code_configuration.runtime раньше, если этого требуют ограничения платформы (например, используемый базовый образ).

Графики окончания поддержки у первоначального поставщика см.:

Этап выхода на пенсию

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

Необходимые разрешения

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

Important

Роли RBAC в Foundry были недавно переименованы. Foundry User, Foundry Owner, Foundry Account Owner и Foundry Project Manager ранее назывались пользователь Azure AI, владелец Azure AI, владелец учетной записи Azure AI и руководитель проекта Azure AI. Пока новое название внедряется, в некоторых местах вы всё ещё можете видеть прежние названия. Идентификаторы ролей и основные разрешения не меняются из-за переименования.

Агент запускается как управляемое удостоверение, назначаемое платформой, отдельно от удостоверения пользователя. По умолчанию эта учетная запись имеет доступ к выполнению инференса модели через конечную точку проекта и к хранилищу сеансов. Для внешних ресурсов (например, вашего собственного хранилища Azure) назначьте роли RBAC вручную для Microsoft Entra ID агента. Дополнительные сведения см. в разделе "Доступ к агенту за пределами по умолчанию".

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

Каждое развертывание исходного кода выполняется по одной и той же последовательности: упаковка -> создание или обновление -> опрос до active -> вызов. В определении агента путь к исходному коду использует code_configuration. Путь на основе образа вместо этого использует container_configuration. Эти два варианта являются взаимоисключающими для одной версии.

Выберите путь, соответствующий рабочему процессу. Если вы не уверены, начните с Azure CLI разработчика или VS Code— это рекомендуемый путь для большинства клиентов.

Путь лучше всего подходит для Упаковка
Интерфейс командной строки Azure Developer или VS Code Большинство развертываний, включая первые развертывания и самый быстрый внутренний цикл. Инструменты соберут и загрузят ZIP-архив за вас.
Пакет SDK для Python Программное развертывание из Python приложений или автоматизации. Вы создаете zip-файл; Пакет SDK отправляет его.
Пакет SDK для .NET Программное развертывание из .NET приложений или автоматизации. SDK архивирует папку за вас.
Пакет SDK JavaScript и TypeScript Программное развертывание из Node.js приложений или автоматизации. Поддерживается развертывание исходного кода Python или .NET; размещаемая среда выполнения Node.js не предусмотрена. Вы создаете zip-файл; Пакет SDK отправляет его.
REST API Специализированные инструменты, языконезависимая автоматизация и системы CD. Вы собираете ZIP-архив и отправляете multipart-запрос.

Выбор способа разрешения зависимостей

Перед началом выберите значение для code_configuration.dependency_resolution. Этот выбор влияет на то, что вы помещаете в zip-файл.

Ценность Behavior Используйте, если
remote_build Служба агента устанавливает зависимости от requirements.txt (Python) или восстанавливает файл проекта (.NET) во время подготовки. Вам нужен небольшой объём загружаемых данных и как можно более простой внутренний цикл. Рекомендуется для первых пользователей.
bundled ZIP-файл запускается как есть. Вы отправляете предварительно созданные зависимости Linux в выходные данные packages/ (Python) или dotnet publish (.NET). Вам нужны воспроизводимые сборки, ваши зависимости являются приватными или доступны только в виде wheel-пакетов, либо ваш проект не удаётся корректно восстановить на стороне сервера.

Сведения о пакетном режиме см. в разделе "Упаковка zip-файла" вручную для локальных команд сборки.

Требования к брандмауэру для частных виртуальных сетей

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

Для всех развертываний исходного кода требуется исходящий доступ:

  • mcr.microsoft.com
  • *.login.microsoft.com

Сведения о конфигурации сети см. в разделе "Развертывание размещенного агента в виртуальной сети".

Развертывание с помощью интерфейса командной строки разработчика Azure или VS Code

Интерфейс командной строки разработчика Azure (azd) и набор средств Foundry для VS Code автоматизирует полный жизненный цикл развертывания исходного кода— они упаковывают исходный код в zip-файл, вычисляют SHA-256, отправляют его, опрашивают active и настраивают для вас управление доступом на основе ролей. Эти средства — это рекомендуемый путь для большинства клиентов и самый быстрый внутренний цикл.

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

Выбор развертывания исходного кода

При интерактивном запуске azd ai agent init средство предложит выбрать режим развертывания. Выберите код для развертывания из источника в виде ZIP-отправки вместо создания образа контейнера. Развертывание кода — это режим по умолчанию для размещённых агентов Python и .NET. Инструментарий Foundry для VS Code точно так же предлагает выбрать способ развертывания.

Чтобы выбрать развертывание из исходного кода в неинтерактивном режиме, например в конвейере CI/CD, передайте --deploy-mode code. Этот режим требует --runtime и --entry-pointпринимает необязательное --dep-resolution значение remote_build (по умолчанию) или bundled:

azd ai agent init --no-prompt --project-id "<project-resource-id>" \
  --deploy-mode code --runtime python_3_13 --entry-point main.py

После инициализации azd записывает настройки развертывания исходного кода в поле codeConfiguration службы azure.ai.agent в azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint:
        - python
        - main.py
      dependencyResolution: remote_build

Запустите azd up для настройки и развертывания. Используйте --deploy-mode container только в том случае, если вы хотите создать или ссылаться на образ контейнера.

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

Развертывание из исходного кода

Выберите язык или интерфейс. Каждая вкладка проходит один и тот же жизненный цикл: создание агента, опрос его состояния, пока он не достигнет active, его вызов и загрузка развернутого кода.

Используйте пакет SDK Python для развертывания агентов исходного кода из собственных приложений или автоматизации. Вы создаете zip-файл самостоятельно и передаете свои байты и SHA-256 в пакет SDK, который отправляет его и предоставляет те же операции создания, опроса, вызова и скачивания, что и REST API. Для развертывания кода требуется azure-ai-projects версия 2.2.0 или более поздняя.

Создание ZIP-файла

Пакет SDK Python отправляет zip-файл, который вы создаете. Используйте те же правила макета и разрешения зависимостей, которые описаны в разделе "Упаковка zip-файла вручную". Минимальный пакет remote_build представляет собой ZIP-архив без вложенных папок, в корне которого находятся main.py и requirements.txt.

Создать агента

import hashlib
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")

code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

created = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="1.0.0")
        ],
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini"},
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hello-world code agent",
)
print(f"Created version: {created.version}")

Для протокола Invocations задайте для записи protocol_versions значение ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Для протокола Invocations (WebSocket) используйте ProtocolVersionRecord(protocol="invocations_ws", version="1.0.0"). Для bundled режима установите dependency_resolution="bundled" и отправьте предварительно созданные зависимости в zip-файле. Дополнительные сведения см. в разделе Локальная сборка зависимостей Linux.

Опрос активных

import time

while True:
    version = project.agents.get_version(
        agent_name=AGENT_NAME, agent_version=created.version
    )
    status = version["status"]
    print(f"Status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Provisioning failed: {version.get('error')}")
    time.sleep(5)

См. Poll for active, чтобы узнать полный список значений состояния и как интерпретировать объект error при сбое.

Вызов агента

После того как версия достигнет active, привяжите клиент OpenAI к конечной точке агента и вызовите его. В этом примере используется протокол Responses:

openai_client = project.get_openai_client(agent_name=AGENT_NAME)

response = openai_client.responses.create(input="Hello! What can you do?")
print(response.output_text)

Для протокола вызовов вызовите конечную точку вызова непосредственно с маркером носителя, как показано в разделе "Вызов агента".

Скачать развернутый ZIP-архив

Убедитесь, что развернута именно та версия, скачав ZIP-архив и сравнив его SHA-256 со значением, которое вы загрузили:

import hashlib
from pathlib import Path

out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
    for chunk in project.agents.download_code(
        agent_name=AGENT_NAME, agent_version=created.version
    ):
        f.write(chunk)
        sha.update(chunk)

print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")

Полностью работоспособный пример см. в примерах размещённых агентов на Python.

Упаковка ZIP-файла вручную

Если вы используете azd, пропустите этот раздел — azd соберёт ZIP-архив за вас. Прочитайте его, если вы используете REST API, если вы перейдете на пакетное разрешение зависимостей или если вам нужен полный контроль над содержимым отправки.

ZIP-архив должен быть с файлами прямо в корне — без папки-обёртки верхнего уровня.

Выберите вкладку для языка агента.

макет Python (режим удаленной сборки)

Служба устанавливает зависимости в облаке из requirements.txt.

agent-code.zip
+-- main.py
+-- requirements.txt

Структура Python (в комплекте)

Вы отправляете предварительно созданные зависимости Linux в packages/.

agent-code.zip
+-- main.py                    # entry point
+-- requirements.txt
+-- packages/                  # extracted modules (not raw .whl files)
    +-- azure/identity/__init__.py
    +-- requests/__init__.py

Сборка зависимостей Linux локально (пакетная, Python)

Используйте тег платформы manylinux2014_x86_64, чтобы pip скачивает колеса Linux даже из Windows или macOS.

Bash

pip install -r requirements.txt \
    --target packages/ \
    --platform manylinux2014_x86_64 \
    --python-version 3.13 \
    --implementation cp \
    --only-binary=:all:

zip -r agent-code.zip main.py requirements.txt packages/

PowerShell / Windows cmd

pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:

tar -a -c -f agent-code.zip main.py requirements.txt packages

--only-binary=:all: силы колес (без исходных сборок). Значение --python-version должно соответствовать значению runtime в определении агента.

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

Распространенные ошибки упаковки, которые вызывают session_creation_failed или ModuleNotFoundError:

  • Помещение источника в папку (my-agent/main.py вместо main.py в корне).
  • Включение необработанных файлов .whl в packages/ вместо извлечённых модулей.
  • Объединение двоичных файлов Windows (.pyd, .dll) для среды выполнения Linux.

Limits

Ограничение Ценность
Максимальный размер ZIP-файла (отправка с несколькими частями) 250 МБ

Сведения о поддерживаемых cpu и memory сочетаниях см. в разделе Размеры песочниц.

Troubleshooting

Симптом Вероятно, причина Исправление
401 Unauthorized Отсутствующий токен или токен с неверной областью действия Получите токен с помощью --resource https://ai.azure.com.
403 Forbidden У вызывающего нет прав управления доступом на основе ролей для проекта Предоставьте роль Foundry Agent Consumer (только для вызова) или Foundry User (также для разработки) на уровне проекта.
409 conflict при создании (Agent '<name>' already exists) Имя агента уже существует Используйте обновление (POST /agents/{name}) или выберите новое имя.
400 bad_request (CPU and Memory must be specified as a valid resource tier) при создании или обновлении cpu / memory не является одним из поддерживаемых уровней Установите cpu и memory на допустимую пару из размеров песочницы.
400 bad_request (Agent version is still being provisioned) при вызове Новая версия находится в процессе развертывания, и выполняется переключение активной версии Проверяйте версию status, пока не произойдёт active, затем повторите попытку.
424 session_not_ready при вызове Контейнер запущен, но /readiness не вернул HTTP 200 в течение времени ожидания Передавайте журналы с помощью :logstream, исправьте проверку готовности или ошибку запуска, затем повторно разверните.
409 conflict в агенте DELETE (Agent has active sessions) Открытые сеансы блокируют удаление Дождитесь, пока сеансы перейдут в состояние простоя, или добавьте &force=true, чтобы каскадно удалить сеансы.
Версия зависла на creating (>10 минут, удаленная сборка) Сбой сборки сервера или не удалось устранить requirements.txt Переключитесь на dependency_resolution: bundled и выполните предварительную сборку локально.
Сбой развертывания в частной виртуальной сети Необходимые исходящие конечные точки блокируются брандмауэром Разрешите конечные точки, указанные в разделе Требования к брандмауэру для частных виртуальных сетей, а затем выполните повторное развертывание.
Версия переходит на failed Неправильный zip-макет, синтаксическая ошибка или (remote_build) сбой восстановления и компиляции Сначала прочитайте объект версии error — error.code классифицирует сбой, а error.message содержит исходную строку ошибки восстановления или компиляции (pip для Python, NuGet для .NET), а также ссылку на инструкции по устранению неполадок. Проверьте структуру папок. Используйте :logstream только после запуска контейнера.
ModuleNotFoundError во время выполнения packages/ отсутствует, содержит необработанные файлы .whl или содержит двоичные файлы Windows Пересобрать с помощью pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased при загрузке Агент основан на изображениях Используйте документ развертывания на основе контейнера.

Очистите ресурсы

Если вы создали проект по шаблону из раздела Quickstart с помощью azd, запустите azd down из корневого каталога проекта, чтобы удалить всё подготовленное окружение.

Чтобы удалить агент, развернутый с помощью пакета SDK или REST API, используйте приведенный ниже путь.

# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)

# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)

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

При удалении агента удаляются все его версии и завершаются активные сеансы. Это действие не может быть отменено.

Дальнейшие действия

Управление жизненным циклом размещаемых агентов

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

  • Last updated on