Быстрый старт: Развертывание первого размещенного агента

• Azure Developer CLI (azd) версии 1.25.3 или более поздней.

• Расширение azd microsoft.foundry . Установите и проверьте расширение после azd установки:

  azd ext install microsoft.foundry
  

• Azure CLI установлен и прошел проверку подлинности:

  az login
  

• Пакеты пакета SDK Python, используемые в этом кратком руководстве:

  pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv
  

• Существующий проект Foundry с уже развернутой моделью. Путь пакета SDK Python в этом кратком руководстве создает и направляет размещенную версию агента, но не создает шаблон нового проекта Foundry или создает для вас развертывание модели. Если вам нужен полный процесс подготовки ресурсов, используйте в этой статье вкладку Azure Developer CLI.

• Visual Studio Code.
• Инструментарий Microsoft Foundry для Visual Studio Code.

• GitHub Copilot приложение.

• Расширение Microsoft Foundry Canvas. Чтобы установить его, в приложении GitHub Copilot откройте Settings>Plugins, найдите microsoft-foundry и выберите Install. Дополнительные сведения см. в статье Что такое Microsoft Foundry Canvas?

• Azure Developer CLI (azd) версии 1.25.3 или более поздней. Холст использует azd для тестирования и развертывания агента.

• Расширение azd microsoft.foundry . Установите и проверьте расширение после azd установки:

  azd ext install microsoft.foundry
  

• Узел агента программирования с установленным навыком Microsoft Foundry Skill.

• Azure CLI и интерфейс командной строки разработчика Azure (azd) установлен и прошел проверку подлинности:

  az login
  azd auth login
  

Шаг 1: Инициализируйте пример агента

Инициализировать новый размещенный агент с помощью базового примера Agent Framework в пустом каталоге:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml" --deploy-mode code

Интерактивный сценарий запрашивает следующие данные:

• Имя агента: настройте имя или примите имя по умолчанию, agent-framework-agent-basic-responses
• Foundry Project: Выберите Создать новый проект Foundry или Использовать существующий проект Foundry
• Tenant: выберите клиент Azure
• Подписка: выберите подписку Azure.
• Location: выберите регион Azure
• Модель: выберите по умолчаниюgpt-5.4-mini или другую модель, к ней можно получить доступ.
• Версия модели. Выберите параметр по умолчанию
• SKU модели: выберите вариант с доступной квотой, отличный от Batch, обычно Standard или GlobalStandard
• Емкость развертывания: выберите значение по умолчанию, 10
• Имя развертывания: выберите по умолчанию, gpt-5.4-mini

По завершении вы увидите , что определение агента ИИ успешно добавлено в проект azd! Измените каталог в только что созданную папку агента.

cd agent-framework-agent-basic-responses

Шаг 2. Подготовка ресурсов Azure

Подготовьте ресурсы, определённые в azure.yaml:

azd provision

Шаг 3. Тестирование агента локально

azd ai agent run

Эта команда создаёт виртуальную среду, устанавливает зависимости, запускает агент, используя startupCommand, определённый в azure.yaml, и открывает инспектор агента в вашем браузере, чтобы вы могли общаться с агентом.

Шаг 4: Развертывание в Foundry Agent Service

Создайте и разверните контейнер агента:

azd deploy

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

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

Шаг 5. Вызов агента

1. Отправьте тот же промпт развернутому агенту:

   azd ai agent invoke "Write a haiku about deploying cloud applications."
   

   Через несколько секунд вы должны увидеть ответ «haiku».

2. (Необязательно) Транслировать журналы контейнера во время взаимодействия с агентом:

   azd ai agent monitor --follow
   

Шаг 1. Создание или выбор проекта Foundry

1. Откройте портал Foundry и создайте проект Foundry или выберите существующий.

2. В проекте разверните модель, поддерживающую чат, например gpt-5.4-mini.

3. Скопируйте эти значения из портала:

   • конечную точку проекта из Обзор.
   • Имя развертывания из Сборка>Развертывания.

Шаг 2: Скачайте код базового примера агента

Клонируйте репозиторий примеров Foundry.

git clone https://github.com/microsoft-foundry/foundry-samples.git

Шаг 3. Создание среды Python и настройка параметров

Создайте виртуальную среду и установите пакеты Python, необходимые для этого краткого руководства.

Для macOS или Linux:

python -m venv .venv
source .venv/bin/activate
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Для Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Создайте рабочую папку для скрипта развертывания, а затем создайте .env файл в этой папке:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=basic-agent
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/01-basic/src/agent-framework-agent-basic-responses>

Шаг 4. Развертывание размещенного агента с помощью Python

Создайте файл с именем deploy_hosted_agent.py в той же рабочей папке, что и .env со следующим содержимым:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  AgentEndpointConfig,
  CodeConfiguration,
  CodeDependencyResolution,
  FixedRatioVersionSelectionRule,
  HostedAgentDefinition,
  ProtocolConfiguration,
  ProtocolVersionRecord,
  ResponsesProtocolConfiguration,
  VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "basic-agent")
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
  zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
  excluded = {".git", ".venv", "__pycache__", ".env", "deploy_hosted_agent.py"}

  with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
    for path in source_dir.rglob("*"):
      if not path.is_file():
        continue
      if any(part in excluded for part in path.parts):
        continue
      zip_file.write(path, path.relative_to(source_dir))

  return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
  for attempt in range(60):
    time.sleep(10)
    details = project_client.agents.get_version(
      agent_name=agent_name,
      agent_version=version,
    )
    status = details["status"]
    print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

    if status == "active":
      return

    if status == "failed":
      raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

  raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
  code_zip_path.open("rb") as code_stream,
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  original_agent_endpoint = None
  created = None

  try:
    created = project_client.agents.create_version_from_code(
      agent_name=agent_name,
      description="Basic hosted agent deployed from local Python source.",
      definition=HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        code_configuration=CodeConfiguration(
          runtime="python_3_14",
          entry_point=["python", "main.py"],
          dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
        ),
        environment_variables={
          "FOUNDRY_PROJECT_ENDPOINT": endpoint,
          "FOUNDRY_MODEL_NAME": model_name,
        },
        protocol_versions=[
          ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
      ),
      code=code_stream,
    )

    print(f"Created hosted agent version {created.version}")

    wait_for_active_version(project_client, created.version)

    original_agent_endpoint = project_client.agents.get(
      agent_name=agent_name
    ).agent_endpoint
    project_client.agents.update_details(
      agent_name=agent_name,
      agent_endpoint=AgentEndpointConfig(
        version_selector=VersionSelector(
          version_selection_rules=[
            FixedRatioVersionSelectionRule(
              agent_version=created.version,
              traffic_percentage=100,
            ),
          ]
        ),
        protocol_configuration=ProtocolConfiguration(
          responses=ResponsesProtocolConfiguration()
        ),
      ),
    )

    print(f"Agent endpoint configured for version {created.version}")

    with project_client.get_openai_client(agent_name=agent_name) as openai_client:
      response = openai_client.responses.create(
        input="Write a haiku about deploying cloud applications.",
      )

    print(f"Agent response: {response.output_text}")
  finally:
    if original_agent_endpoint is not None:
      project_client.agents.update_details(
        agent_name=agent_name,
        agent_endpoint=original_agent_endpoint,
      )
      print("Agent endpoint restored")

    if created is not None:
      project_client.agents.delete_version(
        agent_name=agent_name,
        agent_version=created.version,
        force=True,
      )
      print(f"Deleted hosted agent version {created.version}")

Запустите скрипт:

python deploy_hosted_agent.py

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

Шаг 5. Вызов агента

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

1. Измените deploy_hosted_agent.py и измените переданное input значение openai_client.responses.create(...), а затем снова запустите скрипт.
2. Если вам нужен постоянный маршрутизируемый вариант вместо временного развертывания для проверки, измените скрипт так, чтобы пропустить шаги восстановления и delete_version(...) после анализа последствий маршрутизации трафика.

Шаг 1. Создание проекта Foundry

1. Откройте палитру команд (Ctrl+SHIFT+P) и выберите Foundry Toolkit: Create Project.
2. Выберите подписку Azure.
3. Создайте новую группу ресурсов или выберите существующую.
4. Введите имя проекта Foundry.

Шаг 2. Развертывание модели

1. Откройте палитру команд и выберите Foundry Toolkit: Открыть каталог моделей.
2. Найдите gpt-4.1 и выберите Развернуть.
3. На странице развертывания модели выберите Развернуть в Microsoft Foundry.

Шаг 3: Создание проекта размещённого агента

1. Откройте палитру команд и выберите Набор средств Foundry: создайте новый размещенный агент.
2. Выберите Python в качестве языка.
3. Для Framework выберите Agent Framework.
4. Выберите API ответов в качестве типа протокола.
5. Выберите "Базовый" в качестве примера кода.
6. Нажмите кнопку Далее.
7. Выберите папку для файлов проекта и введите имя агента.
8. Для установки среды выберите "Настройка" с помощью Microsoft Foundry. Содержимое автоматически заполняется проектом и моделью, созданной на шагах 1 и 2.
9. Выберите кнопку Создать.

Откроется новое окно VS Code с проектом в качестве активной рабочей области.

Шаг 4. Установка зависимостей

Создайте виртуальную среду и установите требования.

Для macOS или Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Для Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Шаг 5. Тестирование агента локально

Нажмите клавишу F5 , чтобы запустить локальный HTTP-сервер с включенной отладкой. Инспектор агента Foundry Toolkit открывается для интерактивного тестирования, и вы можете задать точки останова в коде.

Чтобы запустить сервер без отладки, выполните следующие действия:

python main.py

Агент прослушивает http://localhost:8088/. Отправьте тестовый запрос с помощью curl (или любого HTTP-клиента):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

Шаг 6. Развертывание в службе агента Foundry

1. Откройте палитру команд и выберите Foundry Toolkit: Развернуть размещённый агент. Откроется веб-представление развертывания.
2. Для метода развертывания выберите "Код".
3. Выберите "Удаленный" в качестве режима пакета.
4. Agent Name заполняется автоматически.
5. Нажмите кнопку Далее.
6. Страница "Проверка и развертывание " заполняется автоматически.
7. Нажмите кнопку "Развернуть ".

После завершения развертывания агент появится в разделе Размещенные агенты в обозревателе Foundry Toolkit.

Шаг 7. Вызов агента

1. В обозревателе Foundry Toolkit разверните Размещенные агенты и выберите своего агента. На странице сведений отображается состояние в разделе "Сведения о развертывании".
2. Выберите вкладку "Детская площадка " и отправьте тестовый запрос, например Write a haiku about deploying cloud applications..

Microsoft Foundry Canvas помогает пошагово создать и развернуть размещённый агент с помощью боковой панели в приложении GitHub Copilot. По мере того как вы делаете выбор на холсте, система передает Copilot каждый шаг вместе с соответствующим контекстом из вашего проекта Foundry.

Шаг 1. Открытие холста

1. В приложении GitHub Copilot попросите Copilot создать агент, размещенный в Foundry. Рассмотрим пример.

   Create a Foundry hosted agent using Microsoft Foundry Canvas
   

2. Холст открывается на правой панели. Если он не открывается автоматически, откройте его с правой панели.

На холсте показано три этапа, которые соответствуют следующим шагам:

• Создайте размещаемый агент. Выберите проект Foundry и сообщите Copilot, что вы хотите создать. Вы можете начать с предварительно созданного запроса, чтобы ускорить работу.
• Создайте размещаемый агент. Выберите модель, наборы инструментов, навыки и ограничения для своего агента из ресурсов вашего проекта Foundry.
• Развертывание и тестирование. Протестируйте агента локально и, когда результат вас устроит, разверните его в Foundry Agent Service.

Шаг 2. Подключение проекта Foundry

1. Откройте меню проекта холста и войдите в Azure, если появится запрос.
2. Выберите подписку.
3. Выберите проект Foundry. Холст сохраняет этот выбор при повторном открытии.

Шаг 3: Создайте структуру агента

Выберите, как начать:

• Выберите Inspire me, чтобы создать хостируемого агента на основе сгенерированной идеи.
• Выберите пример запроса Hello world, чтобы начать с базового агента.

Copilot создает каркас кода агента в вашей рабочей области на основе вашего выбора.

Шаг 4. Настройка агента

На этом этапе агент подключается к ресурсам в проекте Foundry. Каждый выбор отправляет запрос на Copilot, который обновляет код агента и конфигурацию для вас:

1. Выберите развернутую модель для рассуждений агента.
2. Подключите наборы инструментов Foundry и их инструменты, чтобы предоставить агенту такие возможности, как вызов API или выполнение кода.
3. Подключите навыки, которые содержат многократно используемую логику, которую может использовать агент.
4. Назначьте ограждения для применения элементов управления безопасностью и содержимым.

Шаг 5. Тестирование агента локально

1. Выберите "Проверить локально". Холст запускается azd ai agent run во встроенном терминале Copilot, ожидает подключения агента на порту 8088 и встраивает Agent Inspector.

2. Отправьте тестовый запрос, например:

   Write a haiku about deploying cloud applications.
   

3. Если инспектор сообщает об ошибке, скопируйте сообщение об ошибке в область запроса холста и попросите Copilot устранить проблему.

Шаг 6. Развертывание в службе агента Foundry

1. Выберите "Развернуть в Foundry". На холсте используется azd и Copilot для развертывания размещенного агента.
2. После завершения развертывания используйте ссылки в выходных данных, чтобы открыть игровую площадку агента на портале Foundry.

1. Если вы использовали пример скрипта в том виде, в котором он приведён, он уже восстанавливает конфигурацию конечной точки и удаляет временную версию размещённого агента после проверки.
2. Если вы создали выделенную группу ресурсов для этого краткого руководства, вы можете удалить группу ресурсов на портале Azure после того, как вам больше не потребуется развертывание проекта или модели.

Шаг 1: Откройте рабочую область с помощью навыка Foundry

Откройте пустую папку в узле агента программирования, например GitHub Copilot в Visual Studio Code, Copilot CLI или Claude Code. Убедитесь, что навык microsoft-foundry доступен, прежде чем просить агента по написанию кода создать ресурсы Azure.

Если навык недоступен, следуйте инструкциям в статье Использование навыка Microsoft Foundry в агентах для программирования.

Шаг 2. Попросите навык создать размещенный агент

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

Use the Microsoft Foundry Skill hosted-agent quick-start workflow to create my
first hosted agent end to end. Verify my environment first, and stop if I need
to sign in myself. Use Python 3.13, Agent Framework, the Responses API, the
Basic sample, and code deployment. Create a new Foundry project unless I provide
an existing project. Use the model deployment from the Basic sample unless I
provide an existing deployment. Test the agent locally, deploy it to Foundry
Agent Service, and invoke it with: "Write a haiku about deploying cloud
applications."

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

Шаг 3. Проверка и утверждение плана

1. Просмотрите план, файлы, команды, Azure ресурсы и назначения ролей, которые предлагает агент программирования.
2. Чтобы следовать этому краткому руководству, выберите Python 3.13, Agent Framework, Responses API, пример кода Basic и развертывание Code.
3. Утверждайте создание ресурсов, влекущих затраты, только после того, как вы проверите подписку, регион, группу ресурсов, развертывание модели и квоту.
4. Если агент для программирования просит вас пройти аутентификацию, самостоятельно выполните az login и azd auth login, а затем попросите агента для программирования продолжить работу.

Шаг 4: Позвольте шаблону навыка создать и протестировать агента

Позвольте агенту для программирования создать проект хостируемого агента, выделить ресурсы, когда вы выбираете новый проект Foundry, записать значения переменных локальной среды, подготовить локальную среду и выполнить локальную проверку работоспособности. Для агентов Python рабочий процесс навыка использует azd ai agent run для установки зависимостей при первом локальном запуске.

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

Если хост агента для программирования не может поддерживать работу локального сервера для smoke-теста, используйте вкладку Azure Developer CLI в этой статье, чтобы получить команды для локального тестирования. Вы сможете перейти к развертыванию только после того, как решите вместо этого выполнить удаленную проверку агента.

Шаг 5. Развертывание и вызов размещенного агента

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

Continue with the Microsoft Foundry Skill workflow. Deploy the hosted agent to
Foundry Agent Service, show the deployment status and playground link, and invoke
it remotely with: "Write a haiku about deploying cloud applications." If the
skill workflow requires evaluation suite generation before the final summary,
submit the generation job and show me the follow-up eval command.

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

azd down

azd выводит список ресурсов, которые он удаляет и запрашивает подтверждение. Очистка занимает около 2–5 минут.

1. Откройте портал Azure и перейдите в группу ресурсов, содержащую агент.
2. Выберите "Удалить группу ресурсов", введите имя группы ресурсов, чтобы подтвердить, и нажмите кнопку "Удалить".

Холст создает рабочую область на базе azd, поэтому очистка выполняется с помощью azd down из папки рабочей области.

azd down

azd выводит список ресурсов, которые он удаляет и запрашивает подтверждение. Очистка занимает около 2–5 минут.

Навык Microsoft Foundry не удаляет ресурсы самостоятельно. Это поможет агенту программирования определить ресурсы, созданные этим кратким руководством, и выбрать правильный метод очистки. Вы или ваш агент для написания кода по-прежнему запускаете команду очистки после того, как проверите и одобрите её.

1. В папке проекта размещенного агента попросите агента кодирования проверить очистку:

   Use the Microsoft Foundry Skill to identify the Azure resources created for
   this quickstart. Confirm whether azd down is the right cleanup method for
   this project, and show me the resources before any deletion command runs.
   

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

   azd down
   

3. Подтверждайте удаление только после того, как проверите группу ресурсов и ресурсы, перечисленные в команде.

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