Var värd för Microsoft Agent Framework-agenter som agenter med Foundry-värdtjänst

Använd värdpaket för Microsoft Agent Framework för att göra en Agent Framework-agent tillgänglig via protokoll för Foundry-värdbaserade agenter. Med värdpaketen kan du behålla agentlogik i kod medan Foundry hanterar värdbaserade slutpunkter för körning, sessioner, skalning, identitet och protokoll.

I den här artikeln skapar du en minimal Agent Framework-agent, exponerar den via protokollet Svar eller anrop, testar den via HTTP och distribuerar den till Foundry med Azure Developer CLI.

Microsoft Foundry Skill kan hjälpa dig att implementera adaptern, testa protokollen och distribuera med azd.

Förutsättningar

• Ett Azure-abonnemang. Skapa en kostnadsfritt.
• Ett Foundry-projekt.
• En distribuerad chattmodell, till exempel gpt-4.1 eller gpt-4o.
• Rollen Foundry Project Manager i projektet för att driftsätta en hostad agent. Mer information finns i Distribuera en värdbaserad agent.
• Azure CLI inloggad (az login) så DefaultAzureCredential kan autentisera.

Installera programvarupaketen

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

Välj ett värdprotokoll

Värdagenter kan tillhandahålla ett eller flera protokoll. Börja med Svar för de flesta konversationsagenter.

Bakgrund om protokollbeteende och sessioner finns i Värdbaserade agenter och Hantera värdbaserade agentsessioner.

Konfigurera miljövariabler

Ange projektets slutpunkt och modelldistributionsnamn för lokal utveckling:

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

I PowerShell:

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

När samma kod körs som en värdagent i Foundry injicerar plattformen FOUNDRY_PROJECT_ENDPOINT och AZURE_AI_MODEL_DEPLOYMENT_NAME vid körning.

Svarsprotokoll

Använd protokollet Svar när du vill ha en OpenAI-kompatibel chattslutpunkt med direktuppspelning, svarshistorik och konversationstrådar.

Skapa en Responses-värd

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

Testa svarsslutpunkten

Skicka en begäran om icke-direktuppspelningssvar till den lokala servern.

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"

Servern svarar med ett JSON-objekt som innehåller svarstexten och ett svars-ID. För strömningssvar anger du stream till true. Värden skickar serverutskickade händelser från Responses API, till exempel response.created, response.output_text.delta och response.completed.

Konversationer med flera omgångar

Om du vill fortsätta en konversation skickar du föregående svars-ID i previous_response_id fältet för nästa begäran:

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

När agenten körs i Foundry fungerar samma mönster via den värdbaserade agentens svarsslutpunkt. Om senare interaktioner också behöver samma hostade sandbox-filsystem inkluderar du agent_session_id eller använder ett conversation-ID. Mer information finns i Hantera värdbaserade agentsessioner.

Anropsprotokoll

Använd anropsprotokollet när dina anropare inte kan använda formen För svars-API-begäran eller när ditt scenario inte är en chattkonversation. Invocations-värden hanterar sessionstillstånd via en frågeparameter, agent_session_id, och ett svarshuvud.

Skapa en värd för anrop

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

Testa slutpunkten för anrop

Skicka en begäran till den lokala servern:

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

För konversationer med flera turer återanvänder du agent_session_id värdet från svarshuvudet som agent_session_id frågeparameter i nästa begäran:

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

Plattformen lagrar inte konversationshistorik för anropsprotokollet. agent_session_id Använd frågeparametern för att dirigera senare anrop till samma värdbaserade sandbox-miljö.

Deploy

Distribuera med hjälp av Azure Developer CLI (azd). Initiering kräver ett komplett prov azure.yaml, inte ett parametriserat AgentManifest. Välj källkods- eller containerdriftsättning för den värdbaserade körmiljön.

Distribution av värdbaserad agent kräver rollen Foundry Project Manager i projektet. Mer information finns i Distribuera en värdbaserad agent.

Installera CLI-tillägget Azure Developer

Installera AI-agenttillägget och logga in innan du initierar ett exempel:

azd ext install azure.ai.agents
azd auth login

azd ai agent run startar applikationen lokalt. Den skapar inte distributionscontainern. Docker krävs när du väljer ett arbetsflöde för containerdistribution som byggs lokalt. Se Kör en värdbaserad agent lokalt.

Initiera med hjälp av ett exempel på azure.yaml

Använd ett fullständigt azure.yaml exempel för ditt språk. --src . antar exemplet i den aktuella katalogen.

mkdir my-agent-framework-agent
cd my-agent-framework-agent
azd ai agent init --src . --template https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent
azd ai agent init --src . --template https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/azure.yaml --project-id "<foundry-project-resource-id>"
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "<existing-model-deployment-name>"

Om du vill återanvända ett befintligt projekt med något av exempelerna skickar du dess ARM-resurs-ID med --project-id. Ange AZURE_AI_MODEL_DEPLOYMENT_NAME till en kompatibel driftsättning i det projektet. Skicka inte med en äldre agent.manifest.yaml wrapper till init.

Etablera Azure-resurser

Om det initierade projektet använder ett nytt Foundry-projekt och en ny modelldistribution etablerar du först Azure-resurserna:

azd provision

Provisionering skapar de resurser som deklareras av mallen. Python-källkodsexemplet deklarerar ett Foundry-projekt och en modelldistribution. Det kräver inte något containerregister. Ytterligare telemetriinfrastruktur skapas inte automatiskt.

Kör agenten lokalt

Kör värden för agenten lokalt via azd:

azd ai agent run

Värden fungerar på http://localhost:8088. I en annan terminal anropar du slutpunkten för det lokala protokollet:

azd ai agent invoke --local "Hello!"

Du kan också anropa slutpunkten direkt med curl:

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

Distribuera till Foundry

Distribuera agenten:

azd deploy

För dessa källkodsexempel laddar driftsättningen upp en ZIP av källan för fjärrbygge och distribuerar sedan agenten till den Foundry-värdbaserade körmiljön. Den skapar och pushar inte en image till ett projekts containerregister.

Foundrys värdinfrastruktur injicerar miljövariabler för körningsmiljön i agenten, inklusive:

• FOUNDRY_PROJECT_ENDPOINT: Slutpunkts-URL:en för Foundry-projektet där agenten distribueras.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: Namnet på modelldistributionen som valdes under azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: Connection string när Application Insights har konfigurerats för agenten.

Fullständiga distributionsbegrepp, behörigheter och hanteringsinformation finns i Distribuera en värdbaserad agent och Hantera värdbaserad agentlivscykel.

Felsökning

Använd den här checklistan för att diagnostisera vanliga problem när du utvecklar värdbaserade agenter med Agent Framework.

Det går inte att nå modellen i den värdbaserade containern

Bekräfta att den värdbaserade agentversionen innehåller AZURE_AI_MODEL_DEPLOYMENT_NAMEoch att agentidentiteten har behörighet att anropa Foundry-projektet. Plattformen anger FOUNDRY_PROJECT_ENDPOINT; din kod ska läsa den variabeln när den körs i Foundry.

Konversationstillståndet fortsätter inte

För Responses-protokollet ska du skicka med previous_response_id eller ett conversation-ID i senare omgångar.

För protokollet Anrop lagrar plattformen inte konversationshistorik. Använd en agent_session_id frågeparameter för att dirigera senare anrop till samma värdbaserade sandbox-miljö.

Felmatchning av protokollversion

Om begäranden misslyckas efter en uppgradering kontrollerar du att både manifestet och värdpaketet använder protokollversion 2.0.0. Protokollversion 1.0.0 stöds inte längre.

Nästa steg

Relaterat innehåll

• Vad är Foundry Agent Service?
• Värdagenter
• Hantera värdbaserade agentsessioner
• Distribuera LangGraph-agenter som Foundry-värdhanterade agenter