Microsoft Agent Framework-Agenten als von Foundry gehostete Agenten bereitstellen

Verwenden Sie die Microsoft Agent Framework-Hostingpakete, um einen Agent Framework-Agent über die Protokolle für foundry gehostete Agents verfügbar zu machen. Mit den Hostingpaketen können Sie Ihre Agentlogik im Code beibehalten, während Foundry die gehostete Laufzeit, Sitzungen, Skalierung, Identität und Protokollendpunkte verwaltet.

In diesem Artikel erstellen Sie einen minimalen Agent Framework-Agent, machen ihn entweder über das Antwort- oder Aufrufprotokoll verfügbar, testen sie über HTTP und stellen sie mit der Azure Developer CLI in Foundry bereit.

Die Microsoft Foundry Skill kann dabei helfen, den Adapter zu implementieren, die Protokolle zu testen und bereitzustellen.azd

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto.
• Ein Foundry-Projekt.
• Ein bereitgestelltes Chatmodell, wie gpt-4.1 oder gpt-4o.
• Die Rolle Foundry Project Manager im Projekt zur Bereitstellung eines gehosteten Agenten. Ausführliche Informationen finden Sie unter Bereitstellen eines gehosteten Agents.
• Azure CLI ist angemeldet (az login), damit DefaultAzureCredential sich authentifizieren kann.

Installieren der Pakete

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

Auswählen eines Hostingprotokolls

Gehostete Agents können ein oder mehrere Protokolle verfügbar machen. Beginnen Sie für die meisten Konversationsagenten mit Responses.

Hintergrundinformationen zu Protokollverhalten und Sitzungen finden Sie unter "Gehostete Agents " und "Verwalten von gehosteten Agent-Sitzungen".

Umgebungsvariablen konfigurieren

Legen Sie den Projektendpunkt und den Modellbereitstellungsnamen für die lokale Entwicklung fest:

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"

Wenn derselbe Code in Foundry als gehosteter Agent ausgeführt wird, injiziert die Plattform zur Laufzeit FOUNDRY_PROJECT_ENDPOINT und AZURE_AI_MODEL_DEPLOYMENT_NAME.

Antwortprotokoll

Verwenden Sie das Responses-Protokoll, wenn Sie einen OpenAI-kompatiblen Chat-Endpunkt mit Streaming, Antwortverlauf und Konversations-Threads benötigen.

Erstellen eines Antworthosts

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

Testen des Endpunkts "Antworten"

Senden Sie eine Antwortanforderung ohne Streaming an den lokalen 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"

Der Server antwortet mit einem JSON-Objekt, das den Antworttext und eine Antwort-ID enthält. Setzen Sie für Streaming-Antworten stream auf true. Der Host sendet vom API-Server übermittelte Ereignisse wie z. B. response.created, response.output_text.delta und response.completed.

Mehrstufige Unterhaltungen

Um eine Unterhaltung fortzusetzen, übergeben Sie die vorherige Antwort-ID im previous_response_id Feld der nächsten Anforderung:

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

Wenn der Agent in Foundry läuft, funktioniert dasselbe Muster über den Responses-Endpunkt des gehosteten Agenten. Wenn in späteren Interaktionen ebenfalls dasselbe gehostete Sandbox-Dateisystem benötigt wird, fügen Sie agent_session_id ein oder verwenden Sie eine conversation-ID. Ausführliche Informationen finden Sie unter Verwalten gehosteter Agentsitzungen.

Aufrufeprotokoll

Verwenden Sie das Aufrufprotokoll, wenn Ihre Anrufer das Antwort-API-Anforderungs-Shape nicht verwenden können oder wenn Ihr Szenario keine Chatunterhaltung ist. Der Invocations-Host verwaltet den Sitzungszustand über einen agent_session_id-Abfrageparameter und einen Antwortheader.

Invocations-Host erstellen

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

Den Endpunkt für Aufrufe testen

Senden Sie eine Anforderung an den lokalen Server:

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

Verwenden Sie für mehrteilige Konversationen den agent_session_id-Wert aus dem Antwortheader als agent_session_id-Abfrageparameter für die nächste Anfrage:

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

Die Plattform speichert keinen Unterhaltungsverlauf für das Aufrufprotokoll. Verwenden Sie den agent_session_id Abfrageparameter, um spätere Aufrufe an dieselbe gehostete Sandbox weiterzuleiten.

Deploy

Bereitstellen mithilfe der Azure Developer CLI (azd). Der Ablauf verwendet Beispielmanifeste und Docker, um das Container-Image des Agents zu erstellen und es in der gehosteten Agent-Runtime von Foundry bereitzustellen.

Für die Bereitstellung des gehosteten Agents ist im Projekt die Rolle Foundry Project Manager erforderlich. Ausführliche Informationen finden Sie unter Bereitstellen eines gehosteten Agents.

Installieren der Azure Developer CLI-Erweiterung

Installieren Sie die AI-Agent-Erweiterung, und melden Sie sich an, bevor Sie ein Beispiel initialisieren:

azd ext install azure.ai.agents
azd auth login

Docker muss lokal laufen, da azd ai agent run das im Dockerfile des Beispiels deklarierte Container-Image erstellt. Weitere Informationen finden Sie in der Azure Developer CLI-Referenz.

Mit einem Beispielmanifest initialisieren

Erstellen Sie einen neuen Ordner, und initialisieren Sie ihn aus einem Beispielmanifest. Ersetzen Sie die Manifest-URL durch das Beispiel, das Sie verwenden möchten.

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

Folgen Sie den Anweisungen von azd ai agent init. Wenn Sie noch nicht über ein Foundry-Projekt und eine Modellbereitstellung verfügen, kann der Initialisierungsfluss Sie durch die Erstellung führen.

Bereitstellen von Azure-Ressourcen

Wenn das initialisierte Projekt ein neues Foundry-Projekt und eine Modellbereitstellung verwendet, stellen Sie zuerst die Azure Ressourcen bereit:

azd provision

Mit diesem Befehl wird eine Ressourcengruppe erstellt, die unter anderem eine Foundry-Instanz, ein Foundry-Projekt mit einer Modellbereitstellung, eine Application Insights-Instanz und eine Containerregistrierung für die gehosteten Agent-Images enthält.

Den Container lokal ausführen

Führen Sie den Agent-Host lokal über azd aus:

azd ai agent run

Der Host wird auf http://localhost:8088 bereitgestellt. Rufen Sie in einem anderen Terminal den lokalen Protokollendpunkt auf:

azd ai agent invoke --local "Hello!"

Sie können den Endpunkt auch direkt mit curl:

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

Bereitstellen in Foundry

Bereitstellen des Agents:

azd deploy

Die Bereitstellung verpackt den Agenten in ein Container-Image, überträgt es in die bereitgestellte Containerregistrierung und stellt es für die von Foundry gehostete Agent-Laufzeit bereit.

Die Foundry-Hostinginfrastruktur fügt Laufzeitumgebungsvariablen in den Agent ein, einschließlich:

• FOUNDRY_PROJECT_ENDPOINT: Die Endpunkt-URL für das Foundry-Projekt, in dem der Agent bereitgestellt wird.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: Der Name der Modellbereitstellung, der während azd ai agent init ausgewählt wurde.
• APPLICATIONINSIGHTS_CONNECTION_STRING: Die Verbindungszeichenfolge für die Application Insights-Instanz des Projekts.

Vollständige Bereitstellungskonzepte, Berechtigungen und Verwaltungsdetails finden Sie unter Bereitstellen eines gehosteten Agents und Verwalten des Lebenszyklus des gehosteten Agents.

Troubleshooting

Verwenden Sie diese Checkliste, um häufige Probleme beim Entwickeln gehosteter Agents mit Agent Framework zu diagnostizieren.

Das Modell kann im gehosteten Container nicht erreicht werden.

Vergewissern Sie sich, dass die version des gehosteten Agents enthält AZURE_AI_MODEL_DEPLOYMENT_NAMEund dass die Agentidentität über die Berechtigung zum Aufrufen des Foundry-Projekts verfügt. Die Plattform setzt FOUNDRY_PROJECT_ENDPOINT; Ihr Code sollte diese Variable auslesen, wenn er in Foundry ausgeführt wird.

Der Konversationsstatus wird nicht fortgeführt

Übergeben Sie beim Antworten-Protokoll in späteren Interaktionen previous_response_id oder eine conversation ID.

Für das Aufrufprotokoll speichert die Plattform keinen Unterhaltungsverlauf. Verwenden Sie einen agent_session_id Abfrageparameter, um spätere Aufrufe an dieselbe gehostete Sandbox weiterzuleiten.

Nichtübereinstimmung der Protokollversion

Wenn Anforderungen nach einem Upgrade fehlschlagen, vergewissern Sie sich, dass Ihr Manifest und das Hostingpaket beide Protokollversion 2.0.0 verwenden. Protokollversionen 1.0.0 und 2.0.0 sind nicht kompatibel.

Nächster Schritt

Verwandte Inhalte

• Was ist Foundry Agent Service?
• Gehostete Agenten
• Verwalten Sie gehostete Agenten-Sitzungen
• LangGraph-Agenten als in Foundry gehostete Agenten hosten