Agents Hébergés Microsoft Foundry

Créez des agents hébergés sur le backend Microsoft Foundry Agent Service actualisé. Les agents hébergés sont des applications agentiques conteneurisées qui exposent un ou plusieurs protocoles de plateforme et s'exécutent sur l'infrastructure Foundry gérée.

Note de migration : le backend initial-preview est retiré. Ne créez pas de nouveaux agents hébergés autour de ImageBasedHostedAgentDefinition, du protocole version="v1", des hôtes de capacité, de tools dans la définition de l'agent, de l'accès à l'identité gérée du projet partagé au moment de l'exécution, ou du routage d'invocation agent_reference.

Avant l'implémentation

Les agents hébergés sont en aperçu et changent rapidement. Consultez Microsoft Learn pour accéder à la documentation actuelle sur les agents hébergés avant de générer du code de production :

• Requête : « Microsoft Foundry hosted agents deploy hosted agent refreshed preview »
• Requête : « azure-ai-agentserver-responses ResponsesAgentServerHost »
• Requête : « azure-ai-agentserver-invocations InvocationAgentServerHost »
• Requête : « AIProjectClient HostedAgentDefinition protocol version 1.0.0 »

Installation

Utilisez les packages qui correspondent à votre chemin d'implémentation.

pip install azure-identity azure-ai-agentserver-responses azure-ai-agentserver-invocations
pip install agent-framework-foundry-hosting "azure-ai-projects>=2.1.0"

Variables d'environnement

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project> # Injecté automatiquement dans les conteneurs hébergés
AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name> # Déclarez ceci dans agent.manifest.yaml quand votre code en a besoin
APPLICATIONINSIGHTS_CONNECTION_STRING=<connection-string> # Injecté automatiquement dans les conteneurs hébergés
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Les variables injectées par la plateforme sont définies automatiquement au moment de l'exécution. Ne redéclarez pas FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_PROJECT_ARM_ID, FOUNDRY_AGENT_NAME, FOUNDRY_AGENT_VERSION, FOUNDRY_AGENT_SESSION_ID, ou APPLICATIONINSIGHTS_CONNECTION_STRING dans agent.yaml ou agent.manifest.yaml.

Choisir un protocole

Par défaut, préférez Responses en cas de doute. Un seul conteneur peut exposer plusieurs protocoles en listant chaque protocole dans agent.yaml ou container_protocol_versions.

Des protocoles supplémentaires existent pour des cas spécialisés : Activity pour les canaux Teams/M365 et A2A pour la délégation agent vers agent.

Choisir un chemin d'implémentation

Les agents hébergés ont actuellement des bibliothèques de protocole propriétaires pour Python et C#. Le déploiement et le contrat de conteneur sont neutres en langage.

Flux de travail principal avec azd

Utilisez azd pour le chemin le plus rapide car il gère la configuration du projet, la génération/envoi de conteneurs, la création de versions et le RBAC courant.

azd ext install azure.ai.agents

mkdir my-hosted-agent
cd my-hosted-agent

azd ai agent init
azd ai agent run
azd ai agent invoke --local "What can you do?"

azd up
azd ai agent show --output table
azd ai agent invoke "What can you do?"
azd ai agent monitor --tail 20

azd down

Pour les environnements non interactifs, utilisez azd ai agent init --no-prompt et fournissez tous les drapeaux requis.

Contrat de conteneur

• Générez des images Linux x64. Sur Apple Silicon, utilisez docker build --platform linux/amd64 ....
• Servez localement sur le port 8088. La passerelle Foundry gère le routage de production.
• Utilisez les bibliothèques de protocole pour exposer /responses, /invocations et /readiness ; ne codez pas manuellement le point de terminaison de santé.
• Utilisez l'identité Entra dédiée de l'agent au moment de l'exécution. L'identité gérée du projet est destinée aux travaux d'infrastructure de plateforme tels que les extractions ACR.
• Accordez le RBAC des ressources Azure en aval à l'identité de l'agent, pas à l'identité gérée du projet.
• Mettez uniquement la configuration personnalisée dans environment_variables ; ne mettez jamais de secrets dans les images ou variables d'environnement.

Python : Responses Agent Framework

Utilisez ce chemin pour les nouveaux agents Python qui souhaitent l'intégration Foundry avec Agent Framework.

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


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 helpful assistant.",
    default_options={"store": False},
)

ResponsesHostServer(agent).run()

Pourquoi store=False : le protocole Responses des agents hébergés stocke l'historique des conversations dans la plateforme. Évitez de dupliquer l'historique dans le service d'agent à moins que vous ne le gériez intentionnellement vous-même.

Pour les outils MCP Agent Framework, utilisez les clients MCP au moment de l'exécution tels que client.get_mcp_tool(...). Ne mettez pas tools=[...] dans la définition de version de l'agent hébergé.

Python : Protocole Responses personnalisé

Utilisez la bibliothèque de protocole directement quand vous avez déjà LangGraph, CrewAI, Pydantic AI ou une orchestration personnalisée.

import asyncio

from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handle_response(
    request: CreateResponse,
    context: ResponseContext,
    cancellation_signal: asyncio.Event,
):
    user_text = await context.get_input_text()
    return TextResponse(context, request, text=f"Echo: {user_text}")


app.run()

Pour le streaming, passez un itérable asynchrone à TextResponse. Utilisez ResponseEventStream quand vous avez besoin d'éléments de sortie fins, d'événements d'appels de fonction, ou d'événements de raisonnement.

Python : Protocole Invocations personnalisé

Utilisez Invocations pour du JSON arbitraire, des webhooks, du SSE personnalisé, ou des flux de travail longue durée qui ne s'adaptent pas à Responses OpenAI.

from azure.ai.agentserver.invocations import InvocationAgentServerHost
from starlette.requests import Request
from starlette.responses import JSONResponse, Response

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invocation(request: Request) -> Response:
    payload = await request.json()
    message = payload.get("message", "")
    return JSONResponse({"response": f"Echo: {message}"})


app.run()

Pour les Invocations longue durée, ajoutez @app.get_invocation_handler et @app.cancel_invocation_handler afin que les appelants puissent interroger et annuler explicitement.

Python : Hôte multi-protocole

Exposez Responses et Invocations en composant les hôtes et en déclarant les deux protocoles dans la configuration de déploiement.

from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.ai.agentserver.responses import ResponsesAgentServerHost


class HostedAgentHost(InvocationAgentServerHost, ResponsesAgentServerHost):
    pass


app = HostedAgentHost()

Enregistrez les deux gestionnaires sur le même app.

Modèles C

Pour les agents hébergés C#, utilisez les packages de protocole .NET :

• Responses : Azure.AI.AgentServer.Responses
• Invocations : Azure.AI.AgentServer.Invocations
• Support d'hébergement principal : Azure.AI.AgentServer.Core
• Authentification : Azure.Identity

Pour les agents Agent Framework .NET, utilisez les extensions d'hébergement Foundry Agent Framework. Le modèle actualisé utilise des méthodes d'extension ASP.NET telles que AddFoundryResponses et MapFoundryResponses plutôt que l'ancien adaptateur Azure.AI.AgentServer.AgentFramework. Vérifiez les surcharges exactes par rapport à la version du package installé avant de coder.

agent.manifest.yaml

Utilisez agent.manifest.yaml pour l'échafaudage d'exemple avec azd ai agent init -m.

name: basic-responses-agent
description: >
  A hosted agent using the Responses protocol.
template:
  name: basic-responses-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
resources:
  - kind: model
    id: gpt-4.1-mini
    name: AZURE_AI_MODEL_DEPLOYMENT_NAME

agent.yaml

La définition de conteneur déployée utilise la version de protocole 1.0.0, pas v1.

kind: hosted
name: basic-responses-agent
protocols:
  - protocol: responses
    version: 1.0.0
resources:
  cpu: "0.25"
  memory: "0.5Gi"

Pour exposer les deux protocoles :

protocols:
  - protocol: responses
    version: 1.0.0
  - protocol: invocations
    version: 1.0.0

Déploiement direct avec Python SDK

Utilisez le déploiement SDK quand vous gérez les versions d'agent à partir de l'automatisation. Préférez azd ou VS Code pour le premier déploiement.

import os
import time

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentProtocol,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential


project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

agent = project.agents.create_version(
    agent_name="my-hosted-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(
                protocol=AgentProtocol.RESPONSES,
                version="1.0.0",
            ),
            ProtocolVersionRecord(
                protocol=AgentProtocol.INVOCATIONS,
                version="1.0.0",
            ),
        ],
        image="myregistry.azurecr.io/my-agent:v1",
        cpu="1",
        memory="2Gi",
        environment_variables={
            "AZURE_AI_MODEL_DEPLOYMENT_NAME": os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        },
    ),
)

while True:
    version = project.agents.get_version(
        agent_name="my-hosted-agent",
        agent_version=agent.version,
    )
    status = version["status"]
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Hosted agent provisioning failed: {version['error']}")
    time.sleep(5)

openai_client = project.get_openai_client(agent_name="my-hosted-agent")
response = openai_client.responses.create(input="Hello!")
print(response.output_text)

Pour Invocations sur REST, appelez le point de terminaison dédié :

import os
import requests
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://ai.azure.com/.default").token
project_endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

response = requests.post(
    f"{project_endpoint}/agents/my-hosted-agent/endpoint/protocols/invocations",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "Foundry-Features": "HostedAgents=V1Preview",
    },
    params={"api-version": "v1"},
    json={"message": "Process this task"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Déploiement direct avec REST

BASE_URL="https://<account>.services.ai.azure.com/api/projects/<project>"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-hosted-agent",
    "definition": {
      "kind": "hosted",
      "image": "myregistry.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"},
        {"protocol": "invocations", "version": "1.0.0"}
      ],
      "environment_variables": {
        "AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Les appels REST aux points de terminaison des agents hébergés nécessitent Foundry-Features: HostedAgents=V1Preview pendant l'aperçu. Les clients SDK définissent automatiquement les en-têtes d'aperçu.

Liste de contrôle de migration

1. Remplacez azure-ai-agentserver-agentframework et azure-ai-agentserver-langgraph par des bibliothèques de protocole.
2. Pour Agent Framework Python, remplacez AzureAIAgentClient par FoundryChatClient, ChatAgent par Agent, @ai_function par @tool, et from_agent_framework(agent).run() par ResponsesHostServer(agent).run().
3. Pour LangGraph, remplacez from_langgraph(graph).run() par ResponsesAgentServerHost plus un @app.response_handler.
4. Pour le code personnalisé/apporter le vôtre, implémentez ResponsesAgentServerHost ou InvocationAgentServerHost.
5. Mettez à jour les versions de protocole de "v1" à "1.0.0".
6. Supprimez la création d'hôte de capacité et les commandes de démarrage/arrêt/réplica manuelles.
7. Supprimez tools des définitions de version d'agent hébergé ; utilisez l'intégration MCP/Foundry Toolbox au moment de l'exécution.
8. Remplacez l'invocation de point de terminaison de projet partagé par le routage de point de terminaison dédié ou project.get_openai_client(agent_name="...").
9. Accordez le RBAC des ressources en aval à l'identité Entra d'agent dédiée.
10. Redéployez avec azd up ou create_version, puis attendez le statut de version active.

Erreurs courantes

Bonnes pratiques

1. Commencez par Responses sauf si l'appelant nécessite du JSON arbitraire, du SSE personnalisé, ou une sémantique de protocole non-OpenAI.
2. Utilisez Agent Framework pour les nouveaux agents Python/C# ; utilisez les bibliothèques de protocole pour les cadres existants ou le code personnalisé.
3. Testez localement sur http://localhost:8088/responses ou http://localhost:8088/invocations avant le déploiement.
4. Utilisez des tags d'image immuables, pas latest, pour les versions de production.
5. Gardez les secrets hors des images et variables d'environnement ; préférez l'identité gérée et les connexions gérées.
6. Traitez chaque version d'agent comme immuable. Créez une nouvelle version pour les modifications d'exécution.
7. Utilisez Application Insights et OpenTelemetry à partir des bibliothèques de protocole pour les journaux, traces et métriques.
8. Nettoyez avec azd down, project.agents.delete_version(...), ou les appels de suppression REST quand vous avez terminé.

Liens de référence