Microsoft Foundry

Aan de slag komen

Voeg de vereiste NuGet-pakketten toe aan uw project.

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

Twee agenttypen

De integratie van Microsoft Foundry toont twee verschillende gebruikspatronen:

Antwoordagent (directe deductie)

Gebruik AsAIAgent op AIProjectClient rechtstreeks met een model en instructies. Dit is het aanbevolen uitgangspunt voor de meeste scenario's.

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

Dit pad is 'code-first' en creëert geen server-beheerde agentresource.

Foundry Agent (versie)

Gebruik de systeemeigen AIProjectClient.AgentAdministrationClient API's van de AI Projects SDK om resources van de versie van de agent op te halen en verpakken ze vervolgens met AsAIAgent. Agents kunnen rechtstreeks in de Foundry-portal of via een programma AIProjectClient.AgentAdministrationClientworden gemaakt en geconfigureerd.

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

De agent gebruiken

Zowel ChatClientAgent (Antwoorden) als FoundryAgent (versiebeheer) zijn standaardexemplaren AIAgent en ondersteunen alle standaardbewerkingen, waaronder sessies, hulpprogramma's, middleware en 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));

Voor meer informatie over hoe je agents uitvoert en ermee werkt, raadpleeg de Aan de slag met agent-tutorials.

Gereedschapskisten

Foundry in Python

In Python wonen alle Foundry-specifieke clients nu onder agent_framework.foundry.

• agent-framework-foundry biedt de Cloud Foundry-connectors: FoundryChatClient, FoundryAgent, FoundryEmbeddingClient, en FoundryMemoryProvider.
• agent-framework-foundry-local biedt FoundryLocalClient voor de uitvoering van een lokaal model.

Foundry-chat- en agentpatronen in Python

Installation

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

Hetzelfde agent-framework-foundry pakket omvat FoundryEmbeddingClient ook voor Foundry-modellen-eindpunten insluiten.

Configuratie

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"

Gebruik FOUNDRY_AGENT_VERSION voor promptagents. Gehoste agents kunnen deze weglaten.

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 en FoundryAgent gebruiken het projecteindpunt. FoundryEmbeddingClient maakt gebruik van het eindpunt voor afzonderlijke modellen.

De juiste Python-client kiezen

Een agent maken met FoundryChatClient

FoundryChatClient maakt verbinding met een geïmplementeerd model in een Foundry-project en maakt gebruik van het eindpunt Antwoorden. Koppel deze aan een standaard Agent wanneer uw app eigenaar moet zijn van instructies, hulpprogramma's en sessieafhandeling.

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 is het Foundry-first-Python-pad voor directe deductie en ondersteunt hulpprogramma's, gestructureerde uitvoer en streaming.

Insluitingen maken met FoundryEmbeddingClient

Gebruik FoundryEmbeddingClient wanneer u tekst- of afbeeldingsinbeddingen wilt insluiten vanuit een Foundry-modelendpoint.

from agent_framework.foundry import FoundryEmbeddingClient

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

Verbinding maken met een door de service beheerde agent met FoundryAgent

Gebruik FoundryAgent deze optie wanneer de agentdefinitie zich in Foundry bevindt. Dit is de aanbevolen Python-API voor promptagents en 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(),
)

Voor een HostedAgent laat u agent_version weg en gebruikt u in plaats daarvan de naam van de gehoste agent.

Verbinding maken met een geïmplementeerde (gehoste) Foundry-agent

Voor HostedAgents waarop sessies aan de servicezijde worden uitgevoerd (/agents/{name}/sessions), gebruik FoundryAgent met allow_preview=True om u aan te melden voor het preview-antwoordoppervlak en geef version="v2" het volgende door:

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

Wanneer u de onderliggende servicesessie zelf moet beheren, bijvoorbeeld om een sessie te binden aan een specifieke tenant of gebruiker, maakt u de sessie via de preview-API AIProjectClient en verpakt u deze met 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)

De agent gebruiken

Zowel FoundryChatClient als FoundryAgent integreren met de standaardervaring Python Agent, waaronder het aanroepen van hulpprogramma's, sessies en streaming-antwoorden. Voor lokale runtimes gebruikt u de afzonderlijke Foundry Local Provider pagina.

Gereedschapskisten

Een Foundry-werkset is een benoemde, versienummerde server-side bundel met gehoste configuraties van hulpprogramma's (code-interpreter, bestandszoekopdracht, beeldgeneratie, MCP, webzoekopdracht) die is geconfigureerd in een Microsoft Foundry-project. Met werksets kunt u de configuratie van hulpprogramma's eenmaal beheren in de Foundry-portal en deze opnieuw gebruiken tussen agents.

Agent Framework omvat alleen verbruik : het maken en bijwerken van werksetversies wordt uitgevoerd via de Foundry-portal of de onbewerkte azure-ai-projects SDK (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Twee verbruikspatronen

Een gereedschapskist ophalen

Gebruik FoundryChatClient.get_toolbox() om een gereedschapskist op te halen.

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)

Wanneer version wordt weggelaten, bepaalt get_toolbox de standaardversie in twee aanvragen. Maak een specifieke versie vast om de extra retour te voorkomen:

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

Impliciete vervlakking

U hoeft niet te schrijven toolbox.tools. Het framework normalize_tools herkent ToolboxVersionObject en vereffent automatisch. Al deze werkzaamheden:

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

Filterhulpmiddelen met select_toolbox_tools

Als uw gereedschapskist verschillende hulpmiddelen bundelt, maar een agent alleen een subset nodig heeft, gebruik select_toolbox_tools om de set te verfijnen na het ophalen. Dit voorkomt dat onnodige hulpprogrammadefinities naar het model worden verzonden, waardoor het tokengebruik wordt verminderd en wordt voorkomen dat het model hulpprogramma's aanroept die u niet wilt beschikbaar maken:

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

Helperfuncties get_toolbox_tool_name(tool) en get_toolbox_tool_type(tool) retourneren respectievelijk de selectienaam en het ruwe type van een invoer van een tool. FoundryHostedToolType is een TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) voor IDE-ondersteunde voltooiing op include_types / exclude_types.

MCP-verbruikspad

U kunt een werkset ook gebruiken als een MCP-server door te MCPStreamableHTTPTool verwijzen naar de MCP-eindpunt-URL van de werkset.

De MCP-eindpunt-URL wordt weergegeven in de Foundry-portal of volgt de indeling:

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

Omdat de client rechtstreeks verbinding maakt met het Foundry-werkseteindpunt, moet u zich verifiëren met een Entra ID-bearertoken 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

• MCP-hulpprogramma's in een werkset maken gebruik van verificatie aan de serverzijde. Verificatie voor de upstream MCP-server wordt verwerkt via project_connection_id (een OAuth-verbinding die is geconfigureerd in het Foundry-project). De client bevat nooit bearer-tokens voor de upstream-server.
• Voor het gebruik van een toolkit als een MCP-server is authenticatie aan de clientzijde vereist. Wanneer u MCPStreamableHTTPTool op het MCP-eindpunt van een gereedschapskist richt, moet u een Entra ID-bearer token opgeven (bijvoorbeeld via get_bearer_token_provider(credential, "https://ai.azure.com/.default")) via header_provider.
• Verwerking van toestemmingsstromen is een runtimeprobleem. Als een MCP-hulpprogramma in de gereedschapskist wordt geactiveerd CONSENT_REQUIRED tijdens agent.run() runtime, wordt het tijdens runtime verwerkt, niet bij het ophalen van de gereedschapskist.

Samples