Краткое руководство: Развертывание собственного кода как размещенного агента

В разделе Развертывание первого размещённого агента вы развернули пример. В этом кратком руководстве вы развернете собственный код агента на Python или .NET (C#) в Foundry Agent Service. Код может использовать любую платформу агента, например платформу агента Microsoft, LangGraph, пакет SDK для GitHub Copilot или пакет SDK для агентов OpenAI или обычный код, вызывающий модель напрямую.

Каждый шаг кода содержит вкладки для языка и протокола. Выберите то же сочетание, например C# (ответы) на каждом шаге.

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

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

Прежде чем начать, вам понадобится следующее:

• Подписка Azure — Создайте ее бесплатно.

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

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

• Расширение azd microsoft.foundry :

  azd ext install microsoft.foundry
  

• Сеанс, прошедший проверку подлинности azd :

  azd auth login
  

• Существующий код агента в локальном каталоге.

• Для пути Python Python 3.13 или более поздней версии.

• Для варианта с C# — .NET 10 SDK или более поздняя версия.

• (Необязательно) Чтобы начать с примера в Visual Studio Code, установите Visual Studio Code и набор средств Microsoft Foundry для Visual Studio Code.

Каталог проекта должен содержать как минимум следующее для Python:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Или, для C#, веб-проект на .NET:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Выбор платформы

Библиотека хостинга, которую вы добавляете на шаге 1, обрабатывает протокол — HTTP-сервер, проверки работоспособности и схемы запросов и ответов. Он не зависит от конкретной платформы агента, поэтому логика агента может использовать любые пакеты, которые вы предпочитаете, в Python или C#.

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

Framework	Пакеты для добавления в requirements.txt	Sample
Обычный Python (вызов модели напрямую)	azure-ai-projects	hello-world
LangGraph	langgraph, langchain-azure-ai	langgraph-chat
пакет SDK GitHub Copilot	github-copilot-sdk	github-copilot
Пакет SDK для агентов OpenAI	openai-agents	openai-agent-sdk

Каждый пример requirements.txt содержит точные версии пакета. Полный набор примеров с использованием собственных данных см. в папке с примерами Python.

Для C# добавьте пакеты фреймворка в файл проекта рядом с пакетом хостинга, а затем вызовите фреймворк из обработчика в Program.cs. Полный набор примеров для C# см. в папке с примерами bring-your-own для C#.

Note

Microsoft Agent Framework имеет встроенную интеграцию для хостинга, использующую собственный пакет. Сведения о развертывании агента Microsoft Agent Framework см. в статье "Развертывание первого размещенного агента".

Начните с примера в Visual Studio Code

Чтобы начать с шаблона рабочей платформы вместо собственного кода, используйте коллекцию примеров в Microsoft Foundry Toolkit для Visual Studio Code:

1. На панели действий Visual Studio Code выберите значок Foundry Toolkit.
2. В разделе Средства разработчика>Инструменты разработки агента выберите Создать агент.
3. В разделе "Создание в коде с полным контролем" выберите "Использовать пример".
4. На странице Создание размещенного агента из примера используйте фильтры, чтобы сузить галерею:
   • Для среды выберите Agent Framework, Bring Your Own, LangGraph или Copilot SDK.
   • Для типа протокола выберите API ответов или API вызовов.
5. Выберите пример и нажмите кнопку "Далее".
6. Введите имя агента, выберите проект Foundry и нажмите кнопку "Создать".

Инструментарий создаёт пример в новой рабочей области и настраивает отладку по F5 в один щелчок. Чтобы установить зависимости, протестировать приложение локально и выполнить развертывание из Visual Studio Code, выполните действия для Visual Studio Code, описанные в разделе «Развертывание первого размещенного агента».

Выбор протокола

Каждый шаг кода имеет вкладку для каждого сочетания языка и протокола. Ответы управляют журналом бесед и совместимы с OpenAI. Вызовы предоставляют полный контроль над схемами запросов и ответов. Выберите один и тот же язык и комбинацию протоколов на каждом шаге.

Tip

Не знаете, какой протокол следует использовать? Начните с Ответы.

Шаг 1: Добавьте библиотеку размещения

Добавьте в проект библиотеку протоколов. Библиотека обрабатывает HTTP-сервер, проверки работоспособности и соответствие протоколам независимо от используемой платформы агента. Если вы используете фреймворк, добавьте его пакеты вместе с библиотекой размещения — см. раздел Выберите свой фреймворк.

Python (ответы)

Добавьте библиотеку протоколов в вашу requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (вызовы)

Добавьте библиотеку протоколов в вашу requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (ответы)

Создайте веб-проект .NET и добавьте пакет протокола:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C# (вызовы)

Создайте веб-проект .NET и добавьте пакет протокола:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

Шаг 2. Добавление оболочки размещения

Создайте или обновите точку входа агента с использованием оболочки хостинга. В следующих примерах показан минимальный шаблон. Замените помеченный блок существующей логикой агента.

Python (ответы)

Создание или обновление main.py:

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Python (вызовы)

Создание или обновление main.py:

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

C# (ответы)

Замените Program.cs:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C# (вызовы)

Замените Program.cs:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Note

Эти примеры выводят введённые пользователем данные, чтобы продемонстрировать оболочку хостинга. Замените помеченный блок собственной логикой агента — вызовами модели, RAG или фреймворком, например, LangGraph или GitHub Copilot SDK. Полные примеры см. в Python примерах и примерах C#.

Шаг 3. Инициализация проекта

Запустите azd ai agent init из исходного каталога агента. Интерфейс командной строки разработчика Azure обнаруживает язык из файлов проекта:

Python (ответы)

azd ai agent init --protocol responses --deploy-mode code

Python (вызовы)

azd ai agent init --protocol invocations --deploy-mode code

C# (ответы)

azd ai agent init --protocol responses --deploy-mode code

C# (вызовы)

azd ai agent init --protocol invocations --deploy-mode code

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

• Имя агента: настройте имя или примите значение по умолчанию.
• Foundry Project: Выберите Использовать существующий проект Foundry или Создать новый проект Foundry.
• Подписка. Выберите подписку Azure.
• Расположение. Выберите регион Azure.

По завершении вы увидите: Определение агента ИИ успешно добавлено в ваш проект azd!

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

azd provision

При этом создаются необходимые Azure ресурсы, такие как Application Insights.

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

azd ai agent run

Эта команда создает виртуальную среду (Python) или восстанавливает и создает проект (C#), устанавливает зависимости и запускает агент. Также открывается инспектор агента в вашем браузере, чтобы вы могли общаться с агентом.

Можно также вызвать из интерфейса командной строки в отдельном терминале:

azd ai agent invoke --local "Hello from my hosted agent"

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

azd deploy

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

Deploying services (azd deploy)

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

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

azd ai agent invoke "Hello from my hosted agent"

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

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

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

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

azd down

Troubleshooting

Issue	Solution
ModuleNotFoundError: azure.ai.agentserver	Убедитесь, что библиотека протоколов находится в requirements.txt, и переустановите: pip install -r requirements.txt
C#: The type or namespace name 'AgentServer' could not be found	Убедитесь, что на пакет протокола есть ссылка (dotnet add package Azure.AI.AgentServer.Responses --prerelease или Azure.AI.AgentServer.Invocations), а также что проект использует веб SDK (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider в dotnet run	Профиль запуска ASPNETCORE_ENVIRONMENT=Development по умолчанию задаёт dotnet new web, что включает строгую проверку областей видимости. Используйте azd ai agent run для тестирования (он запускается в размещенном режиме) или задайте ASPNETCORE_ENVIRONMENT=Production перед dotnet run.
FOUNDRY_PROJECT_ENDPOINT not set	Используйте azd ai agent run (задает его автоматически) вместо запуска приложения напрямую. Или добавьте его в .env файл.
Connection refused при локальном запуске	Убедитесь, что другой процесс не использует порт 8088.
AuthorizationFailed во время развертывания	Вам потребуется Foundry Project Manager на уровне проекта.
Агент застрял в provisioning	Выполните azd ai agent show, чтобы проверить состояние. Первые развертывания могут занимать 2–3 минуты, пока устанавливаются зависимости.
azd ai agent init не удался	Запустите azd version, чтобы проверить, что используется версия 1.27.1 или более поздняя. Запустите azd ext show azure.ai.agents, чтобы проверить версию 1.0.0-beta.4 или более позднюю. Обновите с помощью azd ext upgrade azure.ai.agents.

Полную матрицу разрешений и назначений ролей см. в справочнике по разрешениям размещенного агента.

Что вы узнали

В этом кратком руководстве вы:

• Добавьте одну библиотеку хостинга в существующий код вашего агента.
• Инициализирован проект azd из каталога с исходным кодом.
• Протестировано локально с помощью azd ai agent run и azd ai agent invoke --local.
• Развернуто в службе Foundry Agent Service с помощью azd deploy.

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

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

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

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

• Что такое хост-агенты?
• Разверните размещённого агента из исходного кода
• Развертывание размещенного агента из контейнера
• Жизненный цикл разработки агента
• Образцы агентов Python на хостинге
• Примеры собственных платформ (LangGraph, пакет SDK для GitHub Copilot и многое другое)
• Примеры для размещённого агента C#