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:

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.

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

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.

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.

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.

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

Verwenden Sie für HostedAgents, die dienstseitige Sitzungen ausführen (/agents/{name}/sessions), FoundryAgent mit allow_preview=True, um sich für die Vorschau der Oberflächen für Antworten zu entscheiden, und übergeben Sie folgendes: 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",
)

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

Zwei Verbrauchsmuster

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