Microsoft Foundry

Komma igång

Lägg till nödvändiga NuGet-paket i projektet.

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

Två agenttyper

Integreringen Microsoft Foundry visar två distinkta användningsmönster:

Svarsagent (direkt slutsatsdragning)

Använd AsAIAgent på AIProjectClient direkt tillsammans med en modell och instruktioner. Detta är den rekommenderade startpunkten för de flesta scenarier.

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

Den här vägen är code-first och skapar inte en agentresurs hanterad av servern.

Foundry Agent (versionerad)

Använd de interna AIProjectClient.AgentAdministrationClient API:erna från AI Projects SDK för att hämta versionshanterade agentresurser och sedan omsluta dem med AsAIAgent. Agenter kan skapas och konfigureras direkt i Foundry-portalen eller programmatiskt 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."));

Använda agenten

Både ChatClientAgent (svar) och FoundryAgent (versionerade) är standardinstanser AIAgent och stöder alla standardåtgärder, inklusive sessioner, verktyg, mellanprogram och direktuppspelning.

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

Mer information om hur du kör och interagerar med agenter finns i självstudierna om att komma igång med agenten.

Verktygskassar

Foundry i Python

I Python finns nu alla Foundry-specifika klienter under agent_framework.foundry.

• agent-framework-foundry tillhandahåller Cloud Foundry-kontakter: FoundryChatClient, FoundryAgent, FoundryEmbeddingClient och FoundryMemoryProvider.
• agent-framework-foundry-local tillhandahåller FoundryLocalClient för lokal modellkörning.

Mönster för chatt och agent i foundry i Python

Installation

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

Samma agent-framework-foundry paket innehåller även FoundryEmbeddingClient för Foundry models-endpoint embeddings.

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"

Använd FOUNDRY_AGENT_VERSION för promptagenter. Värdbaserade agenter kan utelämna det.

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 och FoundryAgent använd projektslutpunkten. FoundryEmbeddingClient använder slutpunkten för separata modeller.

Välj rätt Python klient

Skapa en agent med FoundryChatClient

FoundryChatClient ansluter till en distribuerad modell i ett Foundry-projekt och använder svarsslutpunkten. Kombinera den med en standard Agent när din app ska äga instruktioner, verktyg och sessionshantering.

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 är en Python-miljö avsedd för Foundry för direkt inferens, och den stöder verktyg, strukturerade utdata och strömning.

Skapa inbäddningar med FoundryEmbeddingClient

Använd FoundryEmbeddingClient när du vill ha text- eller bildinbäddningar från en slutpunkt för Foundry-modeller.

from agent_framework.foundry import FoundryEmbeddingClient

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

Anslut till en tjänsthanterad agent med FoundryAgent

Använd FoundryAgent när agentdefinitionen finns i Foundry. Detta är den rekommenderade Python-API:n för PromptAgents och 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(),
)

För en HostedAgent utelämnar du agent_version och använder namnet på den värdbaserade agenten i stället.

Ansluta till en distribuerad (värdbaserad) Foundry-agent

För HostedAgents som kör sessioner på tjänstsidan (/agents/{name}/sessions), använd FoundryAgent tillsammans med allow_preview=True för att aktivera förhandsgranskningsfunktionen för svarshantering och vidarebefordra 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",
)

När du behöver hantera den underliggande tjänstsessionen själv – till exempel för att binda en session till en specifik klientorganisation eller användare – skapar du sessionen via förhandsversions-API AIProjectClient :et och omsluter den med 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)

Använda agenten

Både FoundryChatClient och FoundryAgent integreras med standard-Pythonmiljö Agent, inklusive verktygsanrop, sessioner och strömningssvar. För lokala körmiljöer använder du den separata Foundry Local-provider-sidan.

Verktygskassar

En Foundry-verktygslåda är en namngiven version av serversidans paket med värdbaserade verktygskonfigurationer (kodtolk, filsökning, bildgenerering, MCP, webbsökning) som konfigurerats i ett Microsoft Foundry-projekt. Med verktygslådor kan du hantera verktygskonfigurationen en gång i Foundry-portalen och återanvända den mellan agenter.

Agent Framework omfattar endast förbrukning – att skapa och uppdatera verktygslådeversioner görs via Foundry-portalen eller rå-SDK azure-ai-projects (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Två förbrukningsmönster

Hämta en verktygslåda

Använd FoundryChatClient.get_toolbox() för att hämta en verktygslåda:

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)

När version utelämnas löser get_toolbox standardversionen i två begäranden. Fäst en specifik version för att undvika extra tur och retur:

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

Implicit utjämning

Du behöver inte skriva toolbox.tools. Ramverkets normalize_tools identifierar ToolboxVersionObject och plattas ut automatiskt. Alla dessa arbeten:

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

Filtreringsverktyg med select_toolbox_tools

Om verktygslådan paketerar flera verktyg men en agent bara behöver en delmängd använder du select_toolbox_tools för att begränsa uppsättningen efter hämtningen. Detta förhindrar att onödiga verktygsdefinitioner skickas till modellen, vilket minskar tokenanvändningen och förhindrar att modellen anropar verktyg som du inte tänker exponera:

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

Hjälpfunktioner get_toolbox_tool_name(tool) och get_toolbox_tool_type(tool) returnerar urvalsnamnet respektive råtypen för en verktygspost. FoundryHostedToolType är en TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) för IDE-guidat slutförande på include_types / exclude_types.

MCP-förbrukningssökväg

Du kan också använda en verktygslåda som en MCP-server genom att peka MCPStreamableHTTPTool på verktygslådans MCP-slutpunkts-URL.

URL:en för MCP-slutpunkten visas på Foundry Portal eller följer formatet:

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

Eftersom klienten ansluter direkt till slutpunkten för Foundry-verktygslådan måste du autentisera med en Entra ID-ägartoken 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-verktyg i en verktygslåda använder autentisering på serversidan. Autentisering till den överordnade MCP-servern hanteras via project_connection_id (en OAuth-anslutning som konfigurerats i Foundry-projektet). Klienten innehåller aldrig ägartoken för den överordnade servern.
• Användning av en verktygslåda som en MCP-server kräver klientautentisering. När du pekar MCPStreamableHTTPTool på en verktygslådas MCP-slutpunkt måste du ange en Entra ID-bärartoken (till exempel via get_bearer_token_provider(credential, "https://ai.azure.com/.default")) genom header_provider.
• Hantering av samtyckesflöde är en körningsfråga. Om ett MCP-verktyg i verktygslådan CONSENT_REQUIRED utlöses under agent.run() hanteras det vid körtid, inte under hämtning av verktygslådan.

Samples