Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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.1ofgpt-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), zodatDefaultAzureCredentialkan authenticeren.
- Python 3.10 of hoger.
- .NET 10 SDK of hoger.
De pakketten installeren
Installeer het Agent Framework en het Foundry-hostingpakket:
pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv
Het agent_framework_foundry_hosting pakket biedt de hostservers voor de Foundry-protocollen:
-
ResponsesHostServervoor het openAI-compatibele/responseseindpunt. -
InvocationsHostServervoor het algemene/invocationseindpunt.
Voeg het Agent Framework- en Foundry-hostingpakketten toe aan uw project:
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
Voeg voor het Invocations-protocol ook het Invocations-serverpakket toe:
dotnet add package Azure.AI.AgentServer.Invocations
Deze pakketten bieden de hostextensies voor de Foundry-protocollen:
-
AddFoundryResponsesenMapFoundryResponsesvoor het openAI-compatibele/responseseindpunt. -
AddInvocationsServerenMapInvocationsServervoor het algemene/invocationseindpunt.
Een hostingprotocol kiezen
Gehoste agents kunnen een of meer protocollen beschikbaar maken. Begin met antwoorden voor de meeste gespreksagenten.
| Protocol | Eindpunt | Wanneer gebruiken |
|---|---|---|
| Responses | /responses |
U wilt een OpenAI-compatibele chat, streaming, antwoordgeschiedenis en conversatiethreads. |
| Aanroepen | /invocations |
U wilt een aangepaste JSON-shape, een eindpunt in webhookstijl of niet-gespreksverwerking. |
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
Maak een bestand met de naam main.py met een minimale Agent Framework-agent die gebruikmaakt van een Foundry-model.
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()
Wat dit codefragment doet: Hiermee maakt u een Agent Framework-agent die wordt ondersteund door een Foundry-model, FoundryChatClientwaarna de agent wordt doorgegeven aan ResponsesHostServer. De host start een HTTP-server en stelt de agent beschikbaar via POST /responses. De server wordt standaard verbonden met 8088poort.
Naslaginformatie: documentatie voor Microsoft Agent Framework
Voer de app lokaal uit:
python main.py
Maak een Program.cs-bestand met een minimale Agent Framework-agent die gebruikmaakt van een Foundry-model via het Responses-protocol.
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();
Wat dit codefragment doet: Hiermee maakt u een AIAgent van de Foundry-projectclient, registreert u deze als een Foundry Responses-host met AddFoundryResponsesen wijst u het POST /responses eindpunt toe aan MapFoundryResponses. De host dient standaard op poort 8088.
Verwijzing: AIProjectClient | DefaultAzureCredential
Voer de app lokaal uit:
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
Gebruik dezelfde agentinstallatie als het voorbeeld Antwoorden, maar begin InvocationsHostServer in plaats van 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
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()
Wat dit codefragment doet: Host de Agent Framework-agent via POST /invocations. De host beheert de status per sessie via de agent_session_id queryparameter en antwoordheader.
Naslaginformatie: documentatie voor Microsoft Agent Framework
Het Invocations-protocol maakt gebruik van een InvocationHandler dat u implementeert om elk verzoek te verwerken. Registreer de aanroepserver en uw handler en wijs vervolgens de eindpunten toe.
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();
Wat dit codefragment doet: Registreert de serverservices voor aanroepen en uw InvocationHandler implementatie en wijst vervolgens de /invocations eindpunten toe. U implementeert MyInvocationHandler om te definiëren hoe elke aanvraag wordt verwerkt. Zie het .NET-voorbeeld voor aanroepen voor een volledig voorbeeld van een handler.
Referentie: AddInvocationsServer
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). Initialisatie vereist een volledige sample azure.yaml, niet een geparameteriseerde AgentManifest. Kies de broncode of containerimplementatie voor de gehoste runtime.
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
azd ai agent run start uw toepassing lokaal; de implementatiecontainer wordt niet gebouwd. Docker is vereist wanneer u een containerimplementatiewerkstroom kiest die lokaal bouwt. Zie Een gehoste agent lokaal uitvoeren.
Initialiseer met een voorbeeldbestand 'azure.yaml'
Gebruik een volledig azure.yaml voorbeeld voor uw taal.
--src . gebruikt het voorbeeld in de huidige map.
Initialiseer het voorbeeld Python-antwoorden:
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
In dit voorbeeld wordt het eerder geparameteriseerde Python manifest vervangen. Het definieert een Foundry-project en een modeldeployment. Controleer de beschikbaarheid en het quotum voor het model, de SKU en de regio voordat u het inricht.
Initialiseer het voorbeeld van de Hosted ChatClient-agent op basis van een bestaand Foundry-project:
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>"
Installeer de .NET 10 SDK voordat u dit voorbeeld lokaal uitvoert. De sjabloon maakt gebruik van de dotnet_10 gehoste runtime met externe afhankelijkheidsresolutie.
Als u een bestaand project opnieuw wilt gebruiken met een van beide voorbeelden, geeft u de ARM-resource-id door met --project-id. Stel AZURE_AI_MODEL_DEPLOYMENT_NAME in op een compatibele deployment in dat project. Geef een verouderde agent.manifest.yaml wrapper niet door aan init.
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
Provisioning maakt de resources die door de sjabloon zijn gedeclareerd. Het Python broncodevoorbeeld declareert een Foundry-project en modeldeployment. Hiervoor is geen containerregister vereist. Aanvullende telemetrie-infrastructuur wordt niet automatisch gemaakt.
De agent 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
Voor deze broncodevoorbeelden uploadt de deployment een ZIP van de bron voor externe build en deploit de agent vervolgens naar de door Foundry gehoste runtime. Er wordt geen image naar een projectcontainerregister gebouwd en gepusht.
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 tijdensazd ai agent init. -
APPLICATIONINSIGHTS_CONNECTION_STRING: de verbindingsreeks wanneer Application Insights is geconfigureerd voor de agent.
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. Protocolversie 1.0.0 wordt niet meer ondersteund.