Hostovat agenty Microsoft Agent Frameworku jako agenty hostované ve Foundry

Pomocí balíčků hostování Microsoft Agent Framework zpřístupňte agenta Agent Framework prostřednictvím protokolů pro agenty hostované v Foundry. Balíčky hostingu vám umožňují ponechat logiku agenta v kódu, zatímco Foundry spravuje hostovaný běhový systém, relace, škálování, identitu a koncové body protokolu.

V tomto článku vytvoříte minimálního agenta v Agent Frameworku, zpřístupníte ho prostřednictvím protokolu Responses nebo Invocations, otestujete ho přes HTTP a nasadíte ho do Foundry pomocí Azure Developer CLI.

Předpoklady

• Předplatné služby Azure. Vytvořte si ho zdarma.
• Projekt Foundry.
• Nasazený model chatu, například gpt-4.1gpt-4o.
• Role projektového manažera Foundry v projektu pro nasazení hostovaného agenta. Podrobnosti najdete v tématu Nasazení hostovaného agenta.
• Azure CLI je přihlášen (az login), takže DefaultAzureCredential se může ověřit.

Instalace balíčků

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

dotnet add package Azure.AI.AgentServer.Invocations

Volba hostitelského protokolu

Hostovaní agenti můžou vystavit jeden nebo více protokolů. Začněte odpověďmi pro většinu konverzačních agentů.

Základní informace o chování protokolu a relacích najdete v tématu Hostovaní agenti a správa relací hostovaného agenta.

Konfigurace proměnných prostředí

Nastavte název koncového bodu projektu a nasazení modelu pro místní vývoj:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

V prostředí PowerShell:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Když stejný kód běží jako hostovaný agent ve Foundry, platforma za běhu vloží FOUNDRY_PROJECT_ENDPOINT a AZURE_AI_MODEL_DEPLOYMENT_NAME.

Protokol odpovědí

Protokol Odpovědi použijte, pokud chcete koncový bod chatu kompatibilní s OpenAI se streamováním, historií odpovědí a vlákny konverzace.

Vytvoření hostitele odpovědí

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

python main.py

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";

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

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

dotnet run

Testování koncového bodu Odpovědi

Odešlete požadavek na odpovědi, které nejsou streamované, na místní server.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

Server odpoví objektem JSON, který obsahuje text odpovědi a ID odpovědi. Pro streamované odpovědi nastavte stream na hodnotu true. Hostitel generuje události odesílané serverem rozhraní API pro odpovědi, například response.created, response.output_text.deltaa response.completed.

Konverzace s více výměnami

Pokud chcete pokračovat v konverzaci, předejte předchozí ID odpovědi v previous_response_id poli dalšího požadavku:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

Když agent běží ve Foundry, stejný postup funguje prostřednictvím koncového bodu Responses pro hostovaného agenta. Pokud budou i v dalších tazích potřeba stejný hostovaný souborový systém sandboxu, zahrňte agent_session_id nebo použijte ID conversation. Podrobnosti najdete v tématu Správa relací hostovaného agenta.

Protokol vyvolání

Protokol Vyvolání použijte, když volající nemůžou použít tvar žádosti rozhraní API pro odpovědi nebo když váš scénář není chatovací konverzace. Hostitel vyvolání spravuje stav relace prostřednictvím parametru agent_session_id dotazu a hlavičky odpovědi.

Vytvořte hostitele pro Invocations

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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()


if __name__ == "__main__":
    main()

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

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

Otestování koncového bodu Vyvolání

Odešlete požadavek na místní server:

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Pro vícekolové konverzace znovu použijte hodnotu agent_session_id z hlavičky odpovědi jako parametr dotazu agent_session_id v dalším požadavku:

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

Platforma neukládá historii konverzací pro protokol Vyvolání. Pomocí parametru agent_session_id dotazu můžete směrovat pozdější volání do stejného hostovaného sandboxu.

Deploy

Nasazení pomocí rozhraní příkazového řádku pro vývojáře Azure (azd). Postup používá ukázkové manifesty a Docker k sestavení bitové kopie kontejneru agenta a jejímu nasazení do hostovaného běhového prostředí agenta ve Foundry.

Nasazení hostovaného agenta vyžaduje v projektu roli Foundry Project Manager. Podrobnosti najdete v tématu Nasazení hostovaného agenta.

Instalace rozšíření Azure Developer CLI

Před inicializací ukázky nainstalujte rozšíření agenta AI a přihlaste se:

azd ext install azure.ai.agents
azd auth login

Docker musí být spuštěn místně, protože azd ai agent run sestaví image kontejneru deklarovanou v souboru Dockerfile ukázky. Podrobnosti o příkazu najdete v referenčních informacích k rozhraní příkazového řádku pro vývojáře Azure.

Inicializace z ukázkového manifestu

Vytvořte novou složku a inicializujete ji z ukázkového manifestu. Nahraďte adresu URL manifestu ukázkou, kterou chcete použít.

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.manifest.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml

Postupujte podle pokynů z azd ai agent init. Pokud ještě nemáte projekt Foundry a nasazení modelu, průvodce inicializací vás může provést jejich vytvořením.

Zřízení prostředků Azure

Pokud inicializovaný projekt využívá nový projekt Foundry a nasazení modelu, nejprve zřiďte prostředky Azure:

azd provision

Tento příkaz vytvoří skupinu prostředků, která obsahuje mimo jiné i instanci Foundry, projekt Foundry s nasazením modelu, instanci Application Insights a registr kontejneru pro image hostovaného agenta.

Místní spuštění kontejneru

Spusťte hostitelského agenta lokálně pomocí azd:

azd ai agent run

Hostitel slouží na http://localhost:8088. V jiném terminálu vyvolejte koncový bod místního protokolu:

azd ai agent invoke --local "Hello!"

Koncový bod můžete také volat přímo pomocí curl:

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

Nasazení do Foundry

Nasazení agenta:

azd deploy

Nasazení zabalí agenta do image kontejneru, odešle ho do zřízeného registru kontejneru a nasadí ho do modulu runtime agenta hostovaného v Foundry.

Hostingová infrastruktura Foundry vkládá do agenta proměnné prostředí za běhu, včetně:

• FOUNDRY_PROJECT_ENDPOINT: Adresa URL koncového bodu projektu Foundry, kde je agent nasazen.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: Název nasazení modelu vybraný během azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: Připojovací řetězec pro instanci služby Application Insights daného projektu.

Úplné koncepty nasazení, oprávnění a podrobnosti správy najdete v tématu Nasazení hostovaného agenta a správa životního cyklu hostovaného agenta.

Troubleshooting

Pomocí tohoto kontrolního seznamu můžete diagnostikovat běžné problémy při vývoji hostovaných agentů pomocí rozhraní Agent Framework.

Model není dostupný v hostovaném kontejneru.

Ověřte, že hostovaná verze agenta zahrnuje AZURE_AI_MODEL_DEPLOYMENT_NAMEa že identita agenta má oprávnění volat projekt Foundry. Platforma nastaví FOUNDRY_PROJECT_ENDPOINT; váš kód by měl tuto proměnnou načíst při běhu ve Foundry.

Stav konverzace nepokračuje

U protokolu Responses v dalších kolech předejte previous_response_id nebo ID conversation.

Pro protokol Vyvolání platforma neukládá historii konverzací. Pomocí parametru agent_session_id dotazu můžete směrovat pozdější volání do stejného hostovaného sandboxu.

Neshoda verzí protokolu

Pokud požadavky po upgradu selžou, ověřte, že váš manifest i hostitelský balíček používají protokol verze 2.0.0. Verze protokolu 1.0.0 a 2.0.0 nejsou kompatibilní.

Další krok

Související obsah

• Co je služba Foundry Agent Service?
• Hostovaní agenti
• Správa relací hostovaného agenta
• Hostujte agenty LangGraph jako agenty hostované ve Foundry