Microsoft Foundry

Getting Started

Ajoutez les packages NuGet requis à votre projet.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Deux types d’agent

L’intégration Microsoft Foundry expose deux modèles d’utilisation distincts :

Agent de réponses (inférence directe)

Utilisez AsAIAgent sur AIProjectClient directement avec un modèle et des instructions. Il s’agit du point de départ recommandé pour la plupart des scénarios.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Ce chemin d’accès est code-first et ne crée pas de ressource d’agent managé par le serveur.

Agent de Fonderie (versionné)

Utilisez les API natives AIProjectClient.AgentAdministrationClient du Kit de développement logiciel (SDK) AI Projects pour récupérer les ressources de l’agent avec version, puis encapsulez-les avec AsAIAgent. Les agents peuvent être créés et configurés directement dans le portail Foundry ou par programmation via AIProjectClient.AgentAdministrationClient.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Utilisation de l’agent

Les deux ChatClientAgent (réponses) et FoundryAgent (versioned) sont des instances standard AIAgent et prennent en charge toutes les opérations standard, notamment les sessions, les outils, les intergiciels et la diffusion en continu.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

Pour plus d’informations sur l’exécution et l’interaction avec les agents, consultez les didacticiels de prise en main de l’agent.

Boîtes à outils

Foundry dans Python

Dans Python, tous les clients spécifiques à Foundry vivent désormais sous agent_framework.foundry.

• agent-framework-foundry fournit les connecteurs Cloud Foundry : FoundryChatClient, FoundryAgent, FoundryEmbeddingClientet FoundryMemoryProvider.
• agent-framework-foundry-local fournit l’exécution FoundryLocalClient du modèle local.

Modèles de discussion et d'agents dans le cadre de la fonderie en Python

Installation

pip install agent-framework-foundry
pip install azure-identity

Le même agent-framework-foundry package inclut également FoundryEmbeddingClient pour les encodages des modèles et des points de terminaison Foundry.

Paramétrage

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Utiliser FOUNDRY_AGENT_VERSION pour les agents d’invite. Les agents hébergés peuvent l’omettre.

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient et FoundryAgent utilisent le point de terminaison du projet. FoundryEmbeddingClient utilise le point de terminaison des modèles distincts.

Choisir le bon client Python

Créer un agent avec FoundryChatClient

FoundryChatClient se connecte à un modèle déployé dans un projet Foundry et utilise le point de terminaison Réponses. Associez-le à une norme Agent lorsque votre application doit posséder des instructions, des outils et une gestion de session.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient est le chemin de Python Foundry-first pour l’inférence directe et prend en charge les outils, les sorties structurées et la diffusion en continu.

Créer des incorporations avec FoundryEmbeddingClient

Utilisez FoundryEmbeddingClient quand vous souhaitez incorporer du texte ou des images à partir d’un point de terminaison de modèles Foundry.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Se connecter à un agent géré par le service avec FoundryAgent

Utilisez FoundryAgent quand la définition de l’agent réside dans Foundry. Il s’agit de l’API Python recommandée pour les Agents d’invite et les Agents hébergés.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

Pour un HostedAgent, omettez agent_version et utilisez plutôt le nom de l’agent hébergé.

Connexion à un agent Foundry déployé (hébergé)

Pour les HostedAgents qui exécutent des sessions côté service (/agents/{name}/sessions), utilisez FoundryAgent avec allow_preview=True pour activer la surface d'aperçu des réponses et passer version="v2" :

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
    version="v2",
)

Lorsque vous devez gérer vous-même la session de service sous-jacente ( par exemple pour lier une session à un locataire ou un utilisateur spécifique), créez la session via l’API en préversion AIProjectClient et encapsulez-la avec agent.get_session(...):

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Utilisation de l’agent

Les deux FoundryChatClient et FoundryAgent s’intègrent à l’expérience standard Python Agent, notamment l’appel d’outils, les sessions et les réponses de streaming. Pour les runtimes locaux, utilisez la page distincte du fournisseur local Foundry.

Boîtes à outils

Une boîte à outils Foundry est un ensemble nommé côté serveur avec version des configurations d’outils hébergés (interpréteur de code, recherche de fichiers, génération d’images, MCP, recherche web) configuré dans un projet Microsoft Foundry. Les boîtes à outils vous permettent de gérer la configuration des outils une fois dans le portail Foundry et de les réutiliser entre les agents.

Agent Framework couvre uniquement la consommation : la création et la mise à jour des versions de boîte à outils sont effectuées via le portail Foundry ou le SDK brut azure-ai-projects (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Deux modèles de consommation

Extraction d’une boîte à outils

Utilisez FoundryChatClient.get_toolbox() pour récupérer une boîte à outils :

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

Lorsqu’il version est omis, get_toolbox résout la version par défaut dans deux requêtes. Épinglez une version spécifique pour éviter l’aller-retour supplémentaire :

toolbox = await client.get_toolbox("research_toolbox", version="v3")

Aplatissement implicite

Vous n’avez pas besoin d’écrire toolbox.tools. Le framework normalize_tools reconnaît ToolboxVersionObject et aplatit automatiquement. Tous ces travaux sont les suivants :

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

Outils de filtrage avec select_toolbox_tools

Si votre boîte à outils regroupe plusieurs outils, mais qu’un agent a uniquement besoin d’un sous-ensemble, utilisez select_toolbox_tools pour affiner l’ensemble après l’extraction. Cela évite d’envoyer des définitions d’outils inutiles au modèle, ce qui réduit l’utilisation des jetons et empêche le modèle d’appeler des outils que vous n’envisagez pas d’exposer :

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

Les fonctions d’assistance get_toolbox_tool_name(tool) et get_toolbox_tool_type(tool) renvoient respectivement le nom de la sélection et le type brut d’une entrée d’outil. FoundryHostedToolType est un TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) pour l’achèvement guidé par l’IDE sur include_types / exclude_types.

Chemin de consommation MCP

Vous pouvez également utiliser une boîte à outils en tant que serveur MCP en pointant MCPStreamableHTTPTool sur l’URL du point de terminaison MCP de la boîte à outils.

L’URL du point de terminaison MCP s’affiche sur le portail Foundry ou suit le format suivant :

https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1

Étant donné que le client se connecte directement au point de terminaison de la boîte à outils Foundry, vous devez vous authentifier à l'aide d'un jeton de porteur Entra ID via header_provider:

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Limitations

• Les outils MCP à l’intérieur d’une boîte à outils utilisent l’authentification côté serveur. L’authentification auprès du serveur MCP en amont est gérée via project_connection_id (une connexion OAuth configurée dans le projet Foundry). Le client ne détient jamais de jetons porteurs pour le serveur en amont.
• L’utilisation d’une boîte à outils en tant que serveur MCP nécessite une authentification côté client. Lorsque vous dirigez MCPStreamableHTTPTool vers le point de terminaison MCP d’une boîte à outils, vous devez fournir un jeton porteur Entra ID (par exemple, via get_bearer_token_provider(credential, "https://ai.azure.com/.default")) par l'intermédiaire de header_provider.
• La gestion des flux de consentement est un problème d’exécution. Si un outil MCP de boîte à outils se déclenche CONSENT_REQUIRED pendant agent.run(), il est géré au moment de l’exécution, et non lors de la récupération de la boîte à outils.

Samples