Host Microsoft Agent Framework-agenten als in Foundry gehoste agenten

Gebruik de Microsoft Agent Framework-hostingpakketten om een Agent Framework-agent beschikbaar te maken via de protocollen voor gehoste Foundry-agents. Met de hostingpakketten kunt u uw agentlogica in code houden terwijl Foundry de gehoste runtime, sessies, schaal, identiteit en protocoleindpunten beheert.

In dit artikel maakt u een minimale Agent Framework-agent, maakt u deze beschikbaar via het protocol Antwoorden of Aanroepen, test u deze via HTTP en implementeert u deze in Foundry met de Azure Developer CLI.

De Microsoft Foundry Skill kan helpen bij het implementeren van de adapter, het testen van de protocollen en het implementeren met azd.

Prerequisites

• Een Azure-abonnement. Maak er gratis een.
• Een Gieterij-project.
• Een geïmplementeerd chatmodel, zoals gpt-4.1 of gpt-4o.
• De rol van Foundry Project Manager in het project voor het implementeren van een gehoste agent. Zie Een gehoste agent implementeren voor meer informatie.
• Azure CLI aangemeld (az login), zodat DefaultAzureCredential kan authenticeren.

De pakketten installeren

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

Een hostingprotocol kiezen

Gehoste agents kunnen een of meer protocollen beschikbaar maken. Begin met antwoorden voor de meeste gespreksagenten.

Zie Gehoste agents en gehoste agentsessies beheren voor achtergrondinformatie over protocolgedrag en - sessies.

Omgevingsvariabelen configureren

Stel de naam van het projecteindpunt en de modelimplementatie in voor lokale ontwikkeling:

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

In PowerShell:

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

Wanneer dezelfde code als een gehoste agent in Foundry wordt uitgevoerd, injecteert het platform FOUNDRY_PROJECT_ENDPOINT en AZURE_AI_MODEL_DEPLOYMENT_NAME tijdens runtime.

Protocol voor antwoorden

Gebruik het protocol Antwoorden als u een openAI-compatibel chat-eindpunt wilt met streaming, antwoordgeschiedenis en gespreksthreading.

Een antwoordhost maken

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

Het eindpunt voor antwoorden testen

Verzend een niet-streaming Responses-verzoek naar de lokale 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"

De server reageert met een JSON-object dat de antwoordtekst en een antwoord-id bevat. Voor streamingreacties stelt u stream in op true. De host stuurt serververzonden gebeurtenissen van de Responses API, zoals response.created, response.output_text.delta en response.completed.

Gesprekken met meerdere beurten

Als u een gesprek wilt voortzetten, geeft u de vorige antwoord-id door in het previous_response_id veld van de volgende aanvraag:

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}'

Wanneer de agent in Foundry draait, werkt hetzelfde patroon ook via het Responses-endpoint van de gehoste agent. Als u later ook hetzelfde gehoste sandboxbestandssysteem nodig hebt, neem dan agent_session_id op of gebruik een conversation-ID. Zie Gehoste agentsessies beheren voor meer informatie.

Protocol voor aanroepen

Gebruik het protocol Invocations wanneer uw bellers de aanvraagshape voor antwoorden-API niet kunnen gebruiken of wanneer uw scenario geen chatgesprek is. De aanroephost beheert de sessiestatus via een agent_session_id queryparameter en antwoordheader.

Een aanroephost maken

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();

Het eindpunt voor aanroepen testen

Een aanvraag verzenden naar de lokale server:

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

Voor gesprekken met meerdere beurten hergebruikt u de waarde agent_session_id uit de antwoordheader als de queryparameter agent_session_id in het volgende verzoek:

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

Het platform slaat geen gespreksgeschiedenis op voor het protocol Aanroepen. Gebruik de agent_session_id queryparameter om latere aanroepen naar dezelfde gehoste sandbox te routeren.

Implementeren

Implementeren met behulp van de Azure Developer CLI (azd). Deze workflow gebruikt voorbeeldmanifesten en Docker om de containerimage van de agent te bouwen en uit te rollen naar de door Foundry gehoste agentruntime.

Voor de implementatie van gehoste agents is de rol Foundry Project Manager op het project vereist. Zie Een gehoste agent implementeren voor meer informatie.

De AZURE Developer CLI-extensie installeren

Installeer de AI-agentextensie en meld u aan voordat u een voorbeeld initialiseert:

azd ext install azure.ai.agents
azd auth login

Docker moet lokaal actief zijn omdat azd ai agent run de containerimage bouwt die is opgegeven in de Dockerfile van het voorbeeld. Zie de naslaginformatie Azure Developer CLI voor meer informatie.

Initialiseren vanuit een voorbeeldmanifest

Maak een nieuwe map en initialiseer deze vanuit een voorbeeldmanifest. Vervang de manifest-URL door het voorbeeld dat u wilt gebruiken.

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

Volg de aanwijzingen van azd ai agent init. Als u nog geen Foundry-project en modelimplementatie hebt, kan de initialisatiestroom u helpen bij het maken ervan.

Azure-resources inrichten

Als het geïnitialiseerde project gebruikmaakt van een nieuw Foundry-project en een nieuwe modelimplementatie, richt u eerst de Azure resources in:

azd provision

Met deze opdracht maakt u een resourcegroep die, onder andere resources, een Foundry-exemplaar, een Foundry-project met een modelimplementatie, een Application Insights-exemplaar en een containerregister voor de gehoste agentinstallatiekopieën bevat.

De container lokaal uitvoeren

Voer de agenthost lokaal uit via azd:

azd ai agent run

De host draait op http://localhost:8088. Roep in een andere terminal het eindpunt van het lokale protocol aan:

azd ai agent invoke --local "Hello!"

U kunt het eindpunt ook rechtstreeks aanroepen met curl:

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

Implementeren in Foundry

Rol de agent uit:

azd deploy

De implementatie verpakt de agent in een containerinstallatiekopie, pusht deze naar het ingerichte containerregister en implementeert deze naar de gehoste agentruntime van Foundry.

De Foundry-hostinginfrastructuur injecteert runtime-omgevingsvariabelen in de agent, waaronder:

• FOUNDRY_PROJECT_ENDPOINT: de eindpunt-URL voor het Foundry-project waar de agent is geïmplementeerd.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: De naam van de modelimplementatie geselecteerd tijdens azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: de verbindingsreeks voor het Application Insights-exemplaar van het project.

Zie Een gehoste agent implementeren en de levenscyclus van een gehoste agent beheren voor volledige implementatieconcepten, machtigingen en beheer.

Probleemoplossingsproces

Gebruik deze controlelijst om veelvoorkomende problemen vast te stellen bij het ontwikkelen van gehoste agents met Agent Framework.

Het model kan niet worden bereikt in de gehoste container

Controleer of de versie van de gehoste agent AZURE_AI_MODEL_DEPLOYMENT_NAME bevat en of de identiteit van de agent gemachtigd is om het Foundry-project aan te roepen. Het platform stelt FOUNDRY_PROJECT_ENDPOINT in; je code moet die variabele uitlezen wanneer die in Foundry wordt uitgevoerd.

De gespreksstatus wordt niet voortgezet

Voor het Responses-protocol geeft u previous_response_id of een conversation-ID door in latere beurten.

Voor het protocol Invocations slaat het platform de gespreksgeschiedenis niet op. Gebruik een agent_session_id queryparameter om latere aanroepen naar dezelfde gehoste sandbox te routeren.

Protocolversie komt niet overeen

Als aanvragen mislukken na een upgrade, controleert u of uw manifest en hostingpakket beide protocolversie 2.0.0 gebruiken. Protocolversies 1.0.0 en 2.0.0 zijn niet compatibel.

Volgende stap

Verwante onderwerpen

• Wat is de Foundry Agent-dienst?
• Gehoste agents
• Gehoste agentsessies beheren
• LangGraph-agents hosten als door Foundry gehoste agents