Агенты, размещенные на платформе Foundry

Hosted agents в службе агентов Microsoft Foundry позволяют развертывать агентов Agent Framework в качестве контейнерных приложений на инфраструктуре, управляемой Microsoft. Платформа обрабатывает масштабирование, сохраняемость состояния сеанса, безопасность и управление жизненным циклом, чтобы сосредоточиться на логике агента. Размещенные агенты Microsoft Foundry общедоступны.

Благодаря интеграции размещения в Agent Framework вы можете предоставить Agent, в том числе рабочий процесс, обернутый в Workflow.as_agent(), через протокол Foundry Responses или Invocations, написав минимальный объем кода.

Когда следует использовать размещенные агенты

Выберите размещенные агенты Foundry, если требуется:

  • Управляемая инфраструктура — не нужно настраивать контейнеры, веб-серверы или правила масштабирования самостоятельно.
  • Встроенное управление сеансами — платформа сохраняет и загруженные файлы между циклами взаимодействия и в периодах простоя.
  • Удостоверение выделенного агента — каждый развернутый агент получает собственное удостоверение Entra для безопасного доступа к моделям, средствам и подчиненным службам.
  • Конечные точки, совместимые с OpenAI , — клиенты могут взаимодействовать с агентом с помощью любого пакета SDK, совместимого с OpenAI, через протокол Responses.

Замечание

Интеграция Python agent-framework-foundry-hosting находится в предварительной версии. Размещённые агенты Microsoft Foundry, сервис управляемого хостинга, стали общедоступными.

Предпосылки

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

Для локального тестирования также требуется:

Установите пакет NuGet для хостинга.

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 или более поздней версии

Установите пакет предварительного размещения, клиент Foundry и пакет проверки подлинности Azure:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

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

Протокол ответов

Протокол Responses является рекомендуемой отправной точкой для большинства агентов. Она предоставляет конечную точку, совместимую /responses с OpenAI, и платформа автоматически управляет журналом бесед, потоковой передачей и жизненным циклом сеансов.

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

Создает AgentHost.CreateBuilder хост приложения, предварительно настроенный для среды размещения Foundry. AddFoundryResponses регистрирует агент с помощью обработчика протокола Responses и MapFoundryResponses сопоставляет конечную точку /responses HTTP.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

Упаковывает ResponsesHostServer агент и предоставляет его через протокол Foundry Responses. Настройка store на False в default_options предотвращает дублирование истории бесед, так как инфраструктура размещения управляет историей автоматически.

Протокол вызовов

Протокол вызовов обеспечивает полный контроль над HTTP-запросом и ответом. Используйте его, если вам нужны нестандартные полезные нагрузки, не требующие обработки разговоров, или протоколы потоковой передачи, не совместимые с OpenAI.

С помощью протокола Invocations в C#вы реализуете пользовательский InvocationHandler метод обработки входящих запросов:

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

Метод AddInvocationsServer регистрирует службы протокола Invocations. Вы реализуете InvocationHandler, чтобы определить, как ваш агент обрабатывает каждый запрос.

Для упрощенной настройки используйте InvocationsHostServer из agent_framework_foundry_hosting пакета. Он упаковывает агент так же, как ResponsesHostServer и обрабатывает управление сеансами автоматически:

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

Для полного управления обработкой запросов используйте InvocationAgentServerHost непосредственно из azure.ai.agentserver.invocations пакета и реализуйте собственный обработчик вызова:

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


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

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

Хранилище сеансов в памяти в примере пользовательского обработчика теряется при перезапуске. Используйте устойчивое хранилище (например, Cosmos DB) в рабочей среде.

Замечание

Скоро появится поддержка Go для размещенных агентов Foundry. Сведения о последнем состоянии см. в репозитории Agent Framework Go .

Подсказка

Можно ознакомиться с примерами проектов размещенного агента на языке Python или C#. Или используйте команду azd ai agent init, чтобы создать структуру проекта нового размещенного агента с нуля. В этом кратком руководстве приведены пошаговые инструкции.

Запуск на локальной машине

Интерфейс командной строки разработчика Azure (azd) предоставляет самый простой способ запуска и тестирования размещенного агента локально.

Инициализация проекта

Создайте новую папку и инициализируйте из примера манифеста:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Подсказка

Манифест может быть путем к локальному файлу YAML или URL-адресу удаленного манифеста.

Настройка переменных среды

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

Запуск хоста агента

azd ai agent run

Агентский узел запускается на http://localhost:8088.

Вызов агента

azd ai agent invoke --local "Hello!"

Или используйте curl:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Или в PowerShell:

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Развертывание в Foundry

После локальной проверки агента разверните его в Microsoft Foundry:

  1. Подготовка ресурсов (если у вас еще нет проекта Foundry):

    azd provision

    При этом создается группа ресурсов с экземпляром Foundry, проектом, развертыванием модели, Application Insights и реестром контейнеров.

  2. Разверните агент:

    azd deploy

    Это упаковывает ваш агент в виде образа контейнера, отправляет его в Реестр контейнеров Azure и развертывает в службе Foundry Agent Service.

Инфраструктура размещения Foundry автоматически внедряет следующие переменные среды в контейнер агента во время выполнения:

Переменная Description
FOUNDRY_PROJECT_ENDPOINT URL-адрес конечной точки для проекта Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Имя развертывания модели (настроено во время azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING Строка подключения Application Insights для телеметрии.

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

Дальнейшие шаги

Основные понятия облачных агентов

  • Last updated on