Microsoft Foundry

Erste Schritte

Fügen Sie dem Projekt die erforderlichen NuGet-Pakete hinzu.

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

Zwei Agenttypen

Die Microsoft Foundry-Integration macht zwei verschiedene Verwendungsmuster verfügbar:

Typ	Herstellungstyp	Beschreibung	Verwenden Sie, wenn
Antwort-Agent	ChatClientAgent	Ihre App stellt programmgesteuert ein Modell, Anweisungen und Tools zur Laufzeit bereit, AIProjectClient.AsAIAgent(...). Es wird keine serverseitige Agentressource erstellt.	Sie besitzen die Agentdefinition und möchten eine einfache, flexible Einrichtung. Dies ist das Muster, das in den meisten Beispielen verwendet wird.
Foundry Agent (versioniert)	FoundryAgent	Serververwaltet — Agentdefinitionen werden entweder über das Foundry-Portal oder programmgesteuert über AIProjectClient.AgentAdministrationClient erstellt und versioniert. Übergeben Sie ein ProjectsAgentVersion oder ProjectsAgentRecord oder AgentReference an AIProjectClient.AsAIAgent(...).	Sie benötigen strenge, versionsgesteuerte Agentdefinitionen, die im Foundry-Portal verwaltet werden, über Dienst-APIs

Antwort-Agent (direkte Ableitung)

Verwenden Sie AsAIAgent auf AIProjectClient direkt mit einem Modell und Anweisungen. Dies ist der empfohlene Ausgangspunkt für die meisten Szenarien.

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

Dieser Pfad ist codezentriert und erstellt keine serververwaltete Agent-Ressource.

Foundry Agent (versioniert)

Verwenden Sie die nativen AIProjectClient.AgentAdministrationClient APIs aus dem AI Projects SDK, um versionsierte Agent-Ressourcen abzurufen, und schließen Sie sie dann mit AsAIAgent. Agents können direkt im Foundry-Portal oder programmgesteuert über AIProjectClient.AgentAdministrationClient erstellt und konfiguriert werden.

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

Verwendung des Agenten

Sowohl ChatClientAgent (Antworten) als auch FoundryAgent (versioniert) sind StandardAIAgent-Instanzen und unterstützen alle Standardvorgänge, einschließlich Sitzungen, Tools, Middleware und 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));

Weitere Informationen zum Ausführen und Interagieren mit Agenten finden Sie in den Agenten-Einführungstutorials.

Tools

Foundry-Agents, die aus AIProjectClient.AsAIAgent(...) (dem Responses-Pfad) erstellt wurden, unterstützen die standardmäßige Tooloberfläche des Agent Frameworks — siehe die Toolübersicht für die vollständige Liste und die Matrix der unterstützten Features. Für Foundry-Agents, die aus einer versionierten Agentdefinition (FoundryAgent) geladen wurden, gehören die Werkzeuge des Agents zur Foundry-Agentdefinition und nicht dem Client.

Werkzeug	Hinweise
Funktionswerkzeuge	Supported.
Toolgenehmigung	Supported. Bereitgestellt vom Chatclient des Frameworks zum Funktionsaufruf.
Codedolmetscher	Supported.
Dateisuche	Supported.
Gehostete MCP-Tools	Supported.
Lokale MCP-Tools	Supported.
Foundry Toolboxes	Supported.

Werkzeugkästchen

Gießerei in Python

In Python befinden sich alle foundry-spezifischen Clients jetzt unter agent_framework.foundry.

• agent-framework-foundry stellt die Cloud Foundry Connectors bereit: FoundryChatClient, FoundryAgent, , FoundryEmbeddingClientund FoundryMemoryProvider.
• agent-framework-foundry-local ermöglicht die lokale FoundryLocalClient-Ausführung des Modells.

Foundry-Chat- und Agentenmuster in Python

Szenario	Python-Form	Verwenden Sie, wenn
Einfache Ableitung mit dem Endpunkt "Foundry Responses"	Agent(client=FoundryChatClient(...))	Ihre App besitzt die Definition des Agenten, die Werkzeuge und die Konversationsschleife, und Sie möchten ein Modell in einem Foundry-Projekt bereitstellen.
Vom Dienst verwaltete Agents im Foundry Agent Service	FoundryAgent(...)	Sie möchten eine Verbindung mit einem PromptAgent oder HostedAgent herstellen, der im Foundry-Portal oder über die Dienst-APIs erstellt und konfiguriert wird.

Installation

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

Das gleiche agent-framework-foundry Paket umfasst FoundryEmbeddingClient auch für Foundry Models-Endpunkt-Einbettungen.

Konfiguration

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"

Verwenden Sie FOUNDRY_AGENT_VERSION für Prompt-Agents. Gehostete Agents können sie weglassen.

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 und FoundryAgent verwenden den Projektendpunkt. FoundryEmbeddingClient verwendet den Endpunkt separater Modelle.

Wählen Sie den richtigen Python Client aus.

Szenario	Bevorzugter Client	Hinweise
Azure OpenAI-Ressource	OpenAIChatCompletionClient / OpenAIChatClient	Verwenden Sie die OpenAI-Anbieterseite.
Microsoft Gießereiprojekt-Ableitung	Agent(client=FoundryChatClient(...))	Verwendet den Endpunkt "Foundry Responses".
Microsoft Foundry-verwalteter Dienstagent	FoundryAgent	Empfohlen für Prompt Agents und HostedAgents.
Microsoft Foundry Models-Endpunkteinbettungen	FoundryEmbeddingClient	Verwendet FOUNDRY_MODELS_ENDPOINT plus FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Foundry Local Runtime	Agent(client=FoundryLocalClient(...))	Siehe Foundry Local.

Erstellen eines Agents mit FoundryChatClient

FoundryChatClient stellt eine Verbindung mit einem bereitgestellten Modell in einem Foundry-Projekt her und verwendet den Endpunkt "Antworten". Verbinden Sie Ihre App mit einem Standard Agent, wenn sie Anweisungen, Tools und Sitzungssteuerung besitzen soll.

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 ist der Foundry-first Python-Pfad für direkte Inferenzen und unterstützt Tools, strukturierte Ausgaben und Streaming.

Tools

FoundryChatClient stellt für jedes gehostete Foundry-Tool statische Factory-Methoden bereit. Die Factory-Methoden geben SDK-Toolobjekte zurück, die Sie an tools= auf Agent oder direkt an client.get_response(..., tools=[...]) übergeben. Für FoundryAgent sind die Tools des Agents direkt in der Foundry-Agentdefinition hinterlegt — siehe Was mit FoundryAgent funktioniert und was nicht.

Die Factory-Methoden sind Klassenmethoden, daher benötigen Sie keine Instanz, um ein Werkzeug zu erstellen:

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(),
    ],
)

Toolunterstützung

In der folgenden Tabelle sind alle Tools aufgeführt, die das Python FoundryChatClient heute verfügbar macht. FoundryAgent funktioniert mit den gleichen Tools, aber sie müssen in der Definition des Foundry-Agents konfiguriert werden, anstatt im Code übergeben zu werden.

Werkzeug	Werk ein FoundryChatClient	Status	Einzelheit
Funktionswerkzeuge	n/v — übergeben Sie ein beliebiges aufrufbares Python-Objekt oder @ai_function	GA	Lokal in Ihrem Python Prozess aufgerufen.
Toolgenehmigung	n/a — umschließt vorhandene Tools	GA	Funktioniert mit gehosteten MCP- und Funktionstools.
Codedolmetscher	get_code_interpreter_tool	GA	Codeausführung in einer Sandbox in Foundry.
Dateisuche	get_file_search_tool	GA	Durchsuchen sie hochgeladene Dateien über Vektorspeicher von Foundry.
Websuche	get_web_search_tool	GA	Bing-gestütztes Grounding im Web, verwaltet von Microsoft. Nur Azure OpenAI-Modelle.
Bilderzeugung	get_image_generation_tool	GA	In Foundry gehostete Bildgenerierung.
Gehosteter MCP	get_mcp_tool	GA	Remote-MCP-Server, der von Foundry aufgerufen wird.
Local MCP	n/a — verwenden MCPStreamableHTTPTool / MCPStdioTool	GA	Wird in Ihrem Prozess ausgeführt; funktioniert mit jedem Client.
Foundry Toolboxes	MCPStreamableHTTPTool zum MCP-Endpunkt der Toolbox	GA	Verbraucht über MCP von FoundryChatClient; angefügt serverseitig auf FoundryAgent.
Bing Grounding	get_bing_grounding_tool	Experimental	Eigene Grounding-Ressource mit Bing Search verwenden.
Benutzerdefinierte Bing-Suche	get_bing_custom_search_tool	Preview	Bing Grounding auf eine kuratierte Liste von Domänen beschränkt.
Azure KI-Suche	get_azure_ai_search_tool	Experimental	Suchen Sie einen Azure KI-Suche Index über eine Foundry-Verbindung.
SharePoint	get_sharepoint_tool	Preview	Grundantworten in SharePoint Inhalten.
Microsoft Fabric	get_fabric_tool	Preview	Einen Fabric-Daten-Agenten abfragen.
Speichersuche	get_memory_search_tool	Preview	Durchsuchen Sie einen von Foundry verwalteten Speicher.
Computernutzung	get_computer_use_tool	Preview	Lassen Sie den Agent eine Desktop- oder Browserumgebung steuern.
Browserautomatisierung	get_browser_automation_tool	Preview	Steuern Sie einen Browser über eine Azure Playwright-Verbindung.
Agent–zu–Agent (A2A)	get_a2a_tool	Preview	Rufen Sie einen anderen A2A-Agent als Tool auf.

Websuchvarianten

Foundry bietet drei Bing-gestützte Grounding-Optionen. Wählen Sie das Szenario aus, das Ihrem Szenario entspricht:

• get_web_search_tool (GA) – standardmäßig ohne Einrichtung; von Microsoft verwaltete Bing-Ressource. Nur Azure OpenAI-Modelle. Beschränkt auf user_location und search_context_size.
• get_bing_grounding_tool (experimentell) – mit Ihrer eigenen Azure-Bing-Suche-Ressource für Grounding. Unterstützt count, freshness, market, set_lang und Modelle, die nicht zu OpenAI Foundry gehören.
• get_bing_custom_search_tool (Vorschau) – Bringen Sie Ihre eigene benutzerdefinierte Bing-Suchinstanz mit, um das Grounding auf eine kuratierte Gruppe von Domänen einzuschränken.

Alle drei senden Suchdaten außerhalb der Azure-Compliance-Grenze. Eine vollständige Gegenüberstellung finden Sie in der Übersicht zur Web-Grounding.

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",
)

Bildgenerierung

get_image_generation_tool konfiguriert das Tool für die gehostete Bildgenerierung von Foundry. Das Modell erzeugt Bildinhalte in der Antwort – es gibt keine zusätzlichen Dateien, die verwaltet werden müssen.

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

Bing-Erdung

get_bing_grounding_tool ist ein Wrapper für das Bing Search Foundry-Tool Grounding. Sie erstellen die Grounding with Bing Search-Ressource selbst und fügen diese als Foundry-Projektverbindung hinzu und übergeben dann die Verbindungs-ID.

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

Benutzerdefinierte Bing-Suche

get_bing_custom_search_tool beschränkt das Grounding auf die Allowlist, die in einer Bing Custom Search-Ressource definiert ist.

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

Azure KI-Suche

mit get_azure_ai_search_tool kann der Agent einen Azure KI-Suche Index über eine Foundry-Projektverbindung abfragen.

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 basiert Antworten auf SharePoint-Inhalten, die über eine Foundry-SharePoint-Verbindung erreichbar sind.

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

Microsoft Fabric

get_fabric_tool verbindet den Agent mit einem Microsoft Fabric Daten-Agent über eine Foundry-Verbindung, damit der Agent Fragen zu Ihren Fabric Daten beantworten kann.

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

Speichersuche

get_memory_search_tool ermöglicht dem Agenten, einen von Foundry verwalteten Speicher zu durchsuchen, der optional auf einen Benutzer oder Mandanten beschränkt ist.

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

Computerverwendung

get_computer_use_tool konfiguriert die Vorschaufunktion „Computernutzung“ – das Modell kann eine Desktop- oder Browserumgebung steuern, indem es Mauszeiger- und Tastaturaktionen ausführt.

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

Browserautomatisierung

get_browser_automation_tool bindet den Agent über eine Foundry-Verbindung an eine Azure Playwright Testing-Ressource an. Der Agent kann einen echten Browser mithilfe von Playwright steuern.

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

Agent-zu-Agent (A2A)

get_a2a_tool stellt einen A2A-Remote-Agenten als Tool zur Verfügung, damit ein Foundry-Agent ihn aufrufen kann. Geben Sie entweder eine base_url (und optional agent_card_path) oder eine project_connection_id für eine gespeicherte A2A-Verbindung an.

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

Allgemeine A2A-Anleitungen – Ermittlung, Sitzungen, Streaming – finden Sie auf der Seite "Agent-to-Agent-Anbieter".

Erstellen von Einbettungen mit FoundryEmbeddingClient

Verwenden Sie FoundryEmbeddingClient, wenn Sie Text- oder Bildeinbettungen von einem Foundry-Modelle-Endpunkt benötigen.

from agent_framework.foundry import FoundryEmbeddingClient

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

Verbindung zu einem vom Dienst verwalteten Agenten herstellen mit FoundryAgent

Verwenden Sie FoundryAgent, wenn sich die Agentdefinition in Foundry befindet. Dies ist die empfohlene Python-API für "Prompt Agents" und "HostedAgents".

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

Verwenden Sie bei einem HostedAgent stattdessen den Namen des gehosteten Agents und lassen Sie agent_version weg.

Was funktioniert und was nicht? FoundryAgent

FoundryAgent stellt eine Verbindung mit einem Agent her, der bereits in Foundry vorhanden ist (ein Eingabeaufforderungs-Agent oder ein gehosteter Agent). Die Definition des Agents – seine Anweisungen und seine Toolkonfiguration – befindet sich in Foundry, nicht in Ihrem Python Code. Dies bedeutet, dass sich mehrere Funktionen auf Agent-Ebene anders verhalten als bei Agent(client=FoundryChatClient(...)) oder anderen chatclientgestützten Agenten.

Tools

An den Tooltyp übergeben FoundryAgent(...)	Behavior
FunctionTool (ein lokales Python-Callable)	Unterstützt, aber nur, wenn die übereinstimmende Funktionsdefinition bereits im Foundry-Agent vorhanden ist. Die Foundry-Laufzeit entscheidet, welche Tools basierend auf der Agentdefinition für das Modell verfügbar gemacht werden sollen. Wenn das Modell eine Funktion aufruft, gibt Foundry einen Toolaufruf an den Client zurück, und das Framework ruft ihre lokale Python aufrufbar in your process (nicht in Foundry) auf, und sendet das Ergebnis zurück. Das bloße Übergeben einer clientseitigen FunctionTool stellt nur diese lokale Implementierung bereit — wenn die Funktion nicht auf dem Foundry-Agenten deklariert ist, wird das Modell sie niemals aufrufen.
Gehostete Tools (Websuche, Codedolmetscher, Dateisuche, MCP, Bildgenerierung usw.)	Ignoriert. Diese müssen in der Definition des Foundry-Agents selbst konfiguriert werden, entweder im Foundry-Portal oder über die Dienst-APIs. Ihre clientseitige Übergabe hat keine Wirkung, da die Foundry-Laufzeit nur die Tools kennt, die an die Agentdefinition angehängt sind.

Kurz gesagt: Sie können zur Bauzeit keine neuen Werkzeuge hinzufügen. Jedes Tool, das das Modell aufrufen kann – einschließlich lokaler Python Funktionen – muss bereits Teil der Agentdefinition in Foundry sein. Das Übergeben eines FunctionTool an FoundryAgent(...) stellt nur die lokale Implementierung bereit, die in Ihrem Python Prozess ausgeführt wird, wenn die Foundry-defined-Funktion aufgerufen wird; es registriert kein neues Tool beim Agent.

Kontextanbieter

context_providers=[...] wird teilweise unterstützt. Ob ein Kontextanbieter funktioniert, hängt davon ab , was der Anbieter zu tun versucht:

Verhalten des Kontextanbieters	Funktioniert mit FoundryAgent?
Fügt zusätzlichen Kontext als Nachrichten hinzu (z. B. abgerufener Speicher, RAG-Codeausschnitte, Benutzerprofilinformationen)	Ja Der eingefügte Kontext wird mit der Anforderung weitergeleitet.
Speichert oder überwacht die Konversation (z. B. indem Dialogbeiträge in einem externen Speicher abgelegt werden)	Ja Wird lokal um die Anforderung/Antwort herum ausgeführt.
Fügt Tools dynamisch hinzu (z. B. SkillsProvider oder jeder beliebige Anbieter, der Tools von invoking() zurückgibt)	Nein, es sei denn, die Tools sind bereits in der Foundry-Agent-Definition enthalten. Die Foundry-Laufzeit führt das Modell mit den Tools aus, die dem Agent in Foundry zugeordnet sind; Tools, die nur lokal vorhanden sind, werden nicht für das Modell verfügbar gemacht und nicht aufgerufen.

Wenn Sie dynamische Toolauswahl, fähigkeitsbasiertes Laden oder ein anderes Verhalten benötigen, das auf tools basiert, die zur Laufzeit hinzugefügt werden, verwenden Sie Agent(client=FoundryChatClient(...)) stattdessen – dieser Pfad besitzt die Modellschleife lokal und unterstützt den vollständigen Satz von Tooltypen und Tool-Add-Kontextanbietern.

Ausführungsoptionen (default_options- und agent.run(...)-Optionen)

Optionen, die Sie an FoundryAgent(default_options=...) oder an agent.run(..., **options) übergeben (z. B. temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata usw.), werden nicht alle unterstützt. Da die Agentdefinition in Foundry die Quelle der Wahrheit ist, werden viele Optionen im Hintergrund ignoriert.

Für Prompt Agents entfernt oder überschreibt das Framework explizit Folgendes, bevor die Anfrage an die Foundry Responses API gesendet wird:

Auswahl	Verhalten mit FoundryAgent
model	Ignoriert. Das Modell wird aus der Agentendefinition in Foundry übernommen.
tools, tool_choiceparallel_tool_calls	Aus dem Anfragetext entfernt. Tools müssen in der Definition des Foundry-Agents deklariert werden (siehe vorheriger Abschnitt). FunctionTool Aufrufbare Funktionen sind weiterhin lokal für Funktionsaufrufe eingebunden, die Liste der Tools selbst wird jedoch nicht an den Dienst gesendet.
instructions und System-/Entwicklernachrichten	Ignoriert. Die eigenen Anweisungen des Foundry-Agenten sind maßgeblich. System-/Entwicklernachrichten werden aus der Nachrichtenliste entfernt, bevor die Anforderung gesendet wird.
conversation_id	Verwendet und der Foundry-Agent-Session zugeordnet, wenn damit eine gemeint ist.
extra_body	Weitergeleitet, zusammengeführt mit der vom Framework festgelegten Payload agent_reference.
Abtastparameter (temperature, top_p, max_tokens, seed, frequency_penalty, presence_penalty, stop, …), metadata, user, store, response_format usw.	Wird an die Antwort-API weitergeleitet. Ob Foundry sie tatsächlich anwendet, hängt von der Agent- und Modellkonfiguration ab – die Agentdefinition kann sie außer Kraft setzen oder einschränken – und verlassen Sie sich daher nicht darauf, dass sie für einen Eingabeaufforderungs-Agent wirksam werden.

Für Hosted Agents gilt dieselbe clientseitige Entfernung, aber alles Weitere hängt davon ab, was der jeweilige Hosted Agent implementiert. Ein gehosteter Agent kann jede Option akzeptieren, ignorieren oder erneut interpretieren, die weitergeleitet wird. Behandeln Sie Laufzeitoptionen als Richtwerte und überprüfen Sie das tatsächliche Verhalten anhand des gehosteten Agents, den Sie aufrufen.

Herstellen einer Verbindung mit einem bereitgestellten (gehosteten) Foundry-Agent

Für HostedAgents, die serverseitige Sitzungen ausführen (/agents/{name}/sessions), verwenden Sie FoundryAgent mit allow_preview=True, um die Responses-Vorschauoberfläche zu verwenden:

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

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

Wenn Sie die zugrunde liegende Dienstsitzung selbst verwalten müssen – z. B. zum Binden einer Sitzung an einen bestimmten Mandanten oder Benutzer – erstellen Sie die Sitzung über die Vorschau-API AIProjectClient , und schließen Sie sie mit 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)

Verwendung des Agenten

Sowohl FoundryChatClient als auch FoundryAgent integrieren sich in die Standard-Python-Agent-Erfahrung, einschließlich Aufrufe von Werkzeugen, Sitzungen und Streamingantworten. Verwenden Sie für lokale Laufzeiten die separate Seite des lokalen Anbieters "Foundry Local".

Werkzeugkästchen

Eine Foundry-Toolbox ist ein benanntes serverseitiges Paket gehosteter Toolkonfigurationen (Codedolmetscher, Dateisuche, Bildgenerierung, MCP, Websuche), das in einem Microsoft Foundry-Projekt konfiguriert ist. Mit Toolboxen können Sie die Toolkonfiguration einmal im Foundry-Portal verwalten und für alle Agents wiederverwenden.

Das Agent Framework deckt nur den Verbrauch ab – das Erstellen und Aktualisieren von Toolboxversionen erfolgt über das Foundry-Portal oder das raw azure-ai-projects SDK (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Agent-Typ	Toolboxverhalten
FoundryAgent (gehostet)	Toolboxanlage erfolgt serverseitig. Es ist keine clientseitige Verkabelung erforderlich.
FoundryChatClient (direkte Ableitung)	Rufen Sie die Toolbox mit get_toolbox() und übergeben Sie sie als tools=.

Zwei Verbrauchsmuster

Pattern	Beschreibung
Systemeigene (gehostete Tools)	Toolkonfigurationen werden auf der Foundry-Laufzeit ausgeführt. Übergeben Sie die Toolbox direkt als tools=.
MCP	Verwenden Sie MCPStreamableHTTPTool für den MCP-Endpunkt der Toolbox. Funktioniert mit jedem Chatclient, nicht nur FoundryChatClient.

Abrufen einer Toolbox

Verwenden Sie FoundryChatClient.get_toolbox(), um eine Toolbox abzurufen.

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)

Wenn version weggelassen wird, löst get_toolbox die Standardversion in zwei Anfragen auf. Legen Sie eine bestimmte Version fest, um den zusätzlichen Roundtrip zu vermeiden.

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

Implizite Abflachung

Sie müssen nicht schreiben toolbox.tools. Das Framework normalize_tools erkennt ToolboxVersionObject und vereinfacht automatisch. Alle diese funktionieren:

# 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])

Filterwerkzeuge mit select_toolbox_tools

Wenn Ihre Toolbox mehrere Tools bündelt, aber ein Agent nur eine Teilmenge benötigt, verwenden Sie select_toolbox_tools, um die Menge nach dem Abruf einzuschränken. Dadurch wird vermieden, unnötige Tooldefinitionen an das Modell zu senden, wodurch die Tokenverwendung reduziert wird und verhindert, dass das Modell Tools aufruft, die Sie nicht verfügbar machen möchten:

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

Hilfsfunktionen get_toolbox_tool_name(tool) und get_toolbox_tool_type(tool) geben jeweils den Auswahlnamen und den rohen Typ eines Werkzeugeintrags zurück. FoundryHostedToolType ist ein TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) für die IDE-geführte Codevervollständigung in include_types / exclude_types.

MCP-Verbrauchspfad

Sie können eine Toolbox auch als MCP-Server verwenden, indem Sie MCPStreamableHTTPTool auf die MCP-Endpunkt-URL der Toolbox verweisen.

Die MCP-Endpunkt-URL wird im Foundry Portal angezeigt oder folgt dem Format:

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

Da der Client direkt eine Verbindung mit dem Foundry Toolbox-Endpunkt herstellt, müssen Sie sich mit einem Entra ID-Bearertoken über header_providerfolgendes authentifizieren:

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)

Einschränkungen

• MCP-Tools in einer Toolbox verwenden die serverseitige Authentifizierung. Die Authentifizierung am upstream-MCP-Server wird über project_connection_id den (im Foundry-Projekt konfigurierte OAuth-Verbindung) verarbeitet. Der Client enthält niemals Bearertoken für den Upstreamserver.
• Die Verwendung einer Toolbox als MCP-Server erfordert clientseitige Authentifizierung. Wenn Sie MCPStreamableHTTPTool auf den MCP-Endpunkt einer Toolbox verweisen, müssen Sie ein Entra ID-Bearertoken (z. B. über get_bearer_token_provider(credential, "https://ai.azure.com/.default")) über header_provider bereitstellen.
• Die Verarbeitung des Zustimmungsflusses ist ein Laufzeitproblem. Wenn ein Toolbox-MCP-Tool CONSENT_REQUIRED während der Laufzeit ausgelöst wird, wird es zur Laufzeit behandelt, nicht während des Toolbox-Abrufs agent.run().

Beispiele

Beispiel	Beschreibung
foundry_chat_client_with_toolbox.py	Grundlegendes Abrufen der Toolbox, Versionsanheftung, Kombinieren von Toolboxen und Filtern
foundry_chat_client_with_toolbox_mcp.py	Pfad für MCP-Verbrauch mit MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	Dynamische werkzeugspezifische Auswahl pro Zug über einen Kontextprovider