fournisseur de modèles Microsoft Foundry

Microsoft Agent Framework prend en charge l’inférence de modèle direct à partir de points de terminaison de projet Foundry Microsoft pendant que votre application possède la définition, les outils et l’orchestration de l’agent.

Pour obtenir l’invite gérée par le service et les agents hébergés, consultez Microsoft Service de l’agent Foundry.

Getting Started

Ajoutez les packages NuGet requis à votre projet.

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

Deux modèles d’intégration

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

Pattern	Type de production	Description	À utiliser quand
Agent de réponses	ChatClientAgent	Votre application fournit par programmation un modèle, des instructions et des outils au moment de l’exécution via AIProjectClient.AsAIAgent(...). Aucune ressource d’agent côté serveur n’est créée.	Vous êtes propriétaire de la définition de l’agent et souhaitez une configuration simple et flexible. Il s’agit du modèle utilisé dans la plupart des exemples.
Agent Foundry (invite ou hébergé)	FoundryAgent	Géré par le serveur : les agents d’invite sont nommés et des définitions avec version ; Les agents hébergés sont des applications déployées par le biais d’un point de terminaison spécifique à l’agent.	Foundry possède la définition de l’agent ou le runtime hébergé. Consultez Microsoft Service de l’agent Foundry.

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."));

Warning

DefaultAzureCredential est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques (par exemple ManagedIdentityCredential) pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

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

Utilisation de l’agent

L’Agent réponses est un agent standard AIAgent et prend en charge les sessions, les outils, les intergiciels et le streaming.

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.

Tools

Agents de réponses trouvées créés à partir de la prise en charge de AIProjectClient.AsAIAgent(...) l’aire d’outil Agent Framework standard. Consultez la vue d’ensemble des outils pour la matrice complète des fonctionnalités.

Tool	Notes
Outils de fonction	Soutenu.
Approbation de l’outil	Soutenu. Fourni par le client de chat avec appel de fonctions du framework.
Interpréteur de code	Soutenu.
Recherche de fichiers	Soutenu.
Outils MCP hébergés	Soutenu.
Outils MCP locaux	Soutenu.
Boîte à outils Microsoft Foundry	Soutenu.

Fonderie en Python

En 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.

Important

Cette page couvre Microsoft points de terminaison de projet et de modèles Foundry. Pour le service De l’agent Foundry, consultez Microsoft Service de l’agent Foundry. Si vous disposez d’un point de terminaison de ressource Azure OpenAI autonome (https://<your-resource>.openai.azure.com), utilisez les instructions Python sur la page du fournisseur OpenAI. Si vous souhaitez exécuter des modèles pris en charge localement, consultez la page fournisseur local Foundry.

Modèles de chat Foundry et d’agents en Python

Scénario	Forme Python	À utiliser quand
Inférence simple avec le point de terminaison Foundry Responses	Agent(client=FoundryChatClient(...))	Votre application possède la définition, les outils et la boucle de conversation de l’agent, et vous souhaitez déployer un modèle dans un projet Foundry.
Agents gérés par le service dans le service d'agents Foundry	FoundryAgent(...)	Vous souhaitez vous connecter à un PromptAgent ou HostedAgent créé et configuré dans le portail Foundry ou via les API de service.

Installation

pip install agent-framework-foundry

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

Configuration

FoundryChatClient

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

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 utilise le point de terminaison du projet. FoundryEmbeddingClient utilise le point de terminaison des modèles distincts.

Choisir le client Python approprié

Scénario	Client préféré	Notes
Azure OpenAI ressource	OpenAIChatCompletionClient / OpenAIChatClient	Utilisez la page du fournisseur OpenAI.
Inférence du projet Microsoft Foundry	Agent(client=FoundryChatClient(...))	Utilise l'endpoint Foundry Responses.
Agent géré par le service Microsoft Foundry	FoundryAgent	Recommandé pour les agents de ligne de commande et HostedAgents.
Incorporations des modèles d'interface de point de terminaison de Microsoft Foundry	FoundryEmbeddingClient	Utilise FOUNDRY_MODELS_ENDPOINT plus FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Environnement d'exécution local de Foundry	Agent(client=FoundryLocalClient(...))	Voir Foundry Local.

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.

Tools

FoundryChatClient propose des méthodes de fabrique statiques pour chaque outil Foundry hébergé. Les fabriques de classes retournent des objets outils du SDK que vous passez soit à tools= sur Agent, soit directement à client.get_response(..., tools=[...]). Pour plus d’informations sur les outils d’agent gérés par le service, consultez Microsoft Service de l’agent Foundry.

Les méthodes de fabrique sont des méthodes de classe, vous n’avez donc pas besoin d’une instance pour créer un outil :

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

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Support technique des outils

Le tableau ci-dessous répertorie tous les outils que Python FoundryChatClient expose aujourd’hui.

Tool	Réglage d'usine activé FoundryChatClient	Status	Détails
Outils de fonction	n/a — passez n’importe quel callable Python ou @ai_function	GA	Appelé localement dans votre processus de Python.
Approbation de l’outil	n/a : encapsule les outils existants	GA	Fonctionne avec les MCP hébergés et les outils de fonction.
Interpréteur de code	get_code_interpreter_tool	GA	Exécution de code en bac à sable sur Foundry.
Recherche de fichiers	get_file_search_tool	GA	Recherchez des fichiers téléversés via les bases de données vectorielles de Foundry.
Recherche web	get_web_search_tool	GA	Ancrage web adossé à Bing, géré par Microsoft. Modèles Azure OpenAI uniquement.
Génération d’images	get_image_generation_tool	GA	Génération d’images hébergée sur Foundry.
MCP hébergé	get_mcp_tool	GA	Serveur MCP distant appelé par Foundry.
Local MCP	n/a — utilisez MCPStreamableHTTPTool / MCPStdioTool	GA	S’exécute dans votre processus ; fonctionne avec n’importe quel client.
Boîte à outils Microsoft Foundry	MCPStreamableHTTPTool ou FoundryToolbox	Bêta	Utilisé via MCP depuis FoundryChatClient ; attaché côté serveur sur FoundryAgent.
Fondation Bing	get_bing_grounding_tool	Experimental	Apportez votre propre ancrage à l’aide de la ressource Recherche Bing.
Recherche personnalisée Bing	get_bing_custom_search_tool	Aperçu	Ancrage Bing limité à une liste sélectionnée de domaines.
Recherche Azure AI	get_azure_ai_search_tool	Experimental	Recherchez un index Recherche Azure AI via une connexion Foundry.
SharePoint	get_sharepoint_tool	Aperçu	Basez les réponses sur le contenu SharePoint.
Microsoft Fabric	get_fabric_tool	Aperçu	Interrogez un agent de données Fabric.
Recherche de mémoire	get_memory_search_tool	Aperçu	Recherchez un magasin de mémoire géré par Foundry.
Utilisation de l’ordinateur	get_computer_use_tool	Aperçu	Laissez l’agent piloter un environnement de bureau ou de navigateur.
Automatisation des navigateurs	get_browser_automation_tool	Aperçu	Contrôler un navigateur via une connexion Azure Playwright.
Agent à agent (A2A)	get_a2a_tool	Aperçu	Appelez un autre agent A2A en tant qu’outil.

Note

Les fabriques expérimentales encapsulent les types de SDK Foundry en disponibilité générale, mais les wrappers eux-mêmes peuvent changer avant la disponibilité générale. Les fabriques en préversion encapsulent les types de SDK Foundry dont la fonctionnalité sous-jacente est en préversion et peuvent changer ou être supprimées. Les deux émettent ExperimentalWarning une première fois qu’elles sont utilisées dans un processus.

Variantes de recherche web

Foundry propose trois options d’ancrage basées sur Bing. Choisissez celui qui correspond à votre scénario :

• get_web_search_tool (GA) : valeur par défaut de configuration zéro ; Ressource Bing gérée par Microsoft. Modèles Azure OpenAI uniquement. Limité à user_location et search_context_size.
• get_bing_grounding_tool (expérimental) — utilisez votre propre ressource Azure Grounding with Bing Search. Prend en charge count, freshness, market, set_lang et les modèles non-OpenAI Foundry.
• get_bing_custom_search_tool (version préliminaire) — utilisez votre propre instance de Recherche personnalisée Bing pour limiter l’ancrage à un ensemble sélectionné de domaines.

Tous les trois envoient des données de recherche en dehors du périmètre de conformité Azure. Consultez la vue d’ensemble de l’ancrage Web pour une comparaison complète.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Génération d'image

get_image_generation_tool configure l’outil de génération d’images hébergé de Foundry. Le modèle produit du contenu d’image dans la réponse : il n’existe aucun fichier supplémentaire à gérer.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Ancrage Bing

get_bing_grounding_tool encapsule l’outil Grounding with Bing Search Foundry. Vous créez vous-même la ressource Grounding avec Recherche Bing et l’ajoutez en tant que connexion de projet Foundry, puis fournissez l’ID de connexion.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Recherche personnalisée Bing

get_bing_custom_search_tool limite l’ancrage à la liste d’autorisation définie dans une ressource Recherche personnalisée Bing.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Recherche d’IA Azure

get_azure_ai_search_tool permet à l’agent d’interroger un index Recherche Azure AI via une connexion de projet Foundry.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

SharePoint

get_sharepoint_tool fonde les réponses sur le contenu SharePoint accessible via une connexion Foundry à SharePoint.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool connecte l’agent à un agent de données Microsoft Fabric via une connexion Foundry afin que l’agent puisse répondre à des questions sur vos données Fabric.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

Recherche en mémoire

get_memory_search_tool permet à l’agent de rechercher dans un magasin de mémoire géré par Foundry, éventuellement délimité à un utilisateur ou un locataire.

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Utilisation de l’ordinateur

get_computer_use_tool configure l’outil d’aperçu de l’utilisation de l’ordinateur : le modèle peut piloter un environnement de bureau ou de navigateur en émettant des actions de pointeur et de clavier.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Automatisation du navigateur

get_browser_automation_tool relie l’agent à une ressource Azure Playwright Testing via une connexion Foundry. L’agent peut conduire un navigateur réel via Playwright.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Agent-à-Agent (A2A)

get_a2a_tool expose un agent A2A distant comme outil pour qu’un agent Foundry puisse l’invoquer. Fournissez soit un base_url (et éventuellement un agent_card_path), soit un project_connection_id pour une connexion A2A enregistrée.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Pour obtenir des conseils généraux sur la découverte, les sessions et la diffusion en continu A2A, consultez le service d’agent A2A.

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)

Utilisation de l’agent

FoundryChatClients’intègre à l’expérience de Python Agent standard, notamment les appels d’outils, les sessions et les réponses de diffusion en continu. Pour les runtimes locaux, utilisez la page distincte du fournisseur local Foundry.

Pour obtenir des offres groupées avec version des configurations d’outils hébergés, consultez Microsoft Boîte à outils Foundry.

Foundry dans Go

Le SDK Go fournit les agents Microsoft Foundry via github.com/microsoft/agent-framework-go/provider/foundryprovider.

Consultez les exemples Foundry Go pour obtenir des exemples d’inférence directe, d’outils de fonction, d’outils hébergés, de MCP et d’agents serveur.

Le package prend en charge deux cibles d’agent :

Cible	Forme Go	À utiliser quand
déploiement de modèle adossé à un projet	foundryprovider.ModelDeployment("gpt-4o-mini")	Votre application possède des instructions, des outils et un flux de conversation.
Agent Foundry côté serveur existant	foundryprovider.ServerAgent("my-agent")	La définition de l’agent est déjà configurée dans Foundry.

Configuration

Définissez votre point de terminaison de projet Foundry et votre déploiement de modèle :

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

agent foundry soutenu par Project

Utilisez ModelDeployment quand vous souhaitez créer un agent Agent Framework dans le code et transmettre des instructions, des outils, des intergiciels et des fournisseurs de contexte à partir de votre application Go.

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

Agent Foundry côté serveur existant

Utilisez ServerAgent quand vous souhaitez appeler un agent déjà configuré dans Foundry. L’agent côté serveur gère ses propres instructions et outils, donc AgentConfig.Instructions est ignoré pour cette cible.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

Les agents Foundry adossés au projet prennent en charge l’interface d’outils standard du framework Go Agent Framework pour les outils locaux et les déclarations prises en charge d’outils hébergés.

Tool	Status	Notes
Outils de fonction	Supported	Les fonctions s’exécutent dans votre processus Go.
Approbation de l’outil	Supported	Fonctionne avec les outils de fonctions locales via la boucle d’appel automatique des outils.
Interpréteur de code	Supported	Utilisez &hostedtool.CodeInterpreter{}.
Recherche web	Supported	Utilisez &hostedtool.WebSearch{}.
Outils MCP locaux	Supported	Permet tool/mcptool de se connecter à un serveur MCP et d’exposer ses outils localement.
Outils MCP hébergés	Actuellement non documenté pour Go Foundry	Utilisez les outils MCP locaux lorsque vous avez besoin de serveurs MCP avec des agents Go Foundry.
Boîte à outils Microsoft Foundry	Actuellement non exposé via une fonction utilitaire Go.

Pour les outils de fonctions locales, ajoutez des valeurs de tool.Tool à agent.Config.Tools :

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

Pour l’exécution du code hébergé, transmettez la déclaration de l’outil hébergé :

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

En-têtes du client et modèle servi

Foundry accepte les en-têtes x-client-* pour chaque exécution. Ajoutez-les avec foundryprovider.WithClientHeader ou foundryprovider.WithClientHeaders:

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

Lorsque Foundry retourne l’en-tête de réponse x-ms-served-model, le fournisseur Go l’ajoute aux propriétés supplémentaires de la réponse/de mise à jour sous la forme de ServedModel.

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Fournisseur de mémoire Foundry

Utilisez foundryprovider.NewMemoryProvider quand vous souhaitez qu’un agent Agent Framework récupère et met à jour un magasin de mémoire géré par Foundry autour de chaque exécution.

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

Le point de terminaison doit être un point de terminaison Microsoft Foundry limité à ce projet, et le magasin de données en mémoire doit déjà exister dans ce projet. La fonction de rappel de portée doit renvoyer une clé de partition stable pour l’utilisateur, le locataire ou la conversation.

Tip

Consultez l’exemple Go de mémoire Foundry pour voir un exemple complet exécutable.

Écarts actuels en Go

La prise en charge de Go n’inclut pas actuellement les API de déploiement/cycle de vie/administrateur hébergés par Foundry, les clients incorporés ou les helpers spécifiques à Go pour Microsoft Boîte à outils Foundry. Utilisez le portail Foundry ou les kits SDK de service pour ces opérations.

Étapes suivantes

Foundry Local