Microsoft Foundry

program Microsoft Agent Framework obsługuje zarówno bezpośrednie wnioskowanie modelu z punktów końcowych projektów Microsoft Foundry, jak i agentów zarządzanych serwisowo w usłudze Foundry Agent Service.

Wprowadzenie

Dodaj wymagane pakiety NuGet do projektu.

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

Dwa typy agentów

Integracja Microsoft Foundry uwidacznia dwa odrębne wzorce użycia:

Typ	Typ wygenerowany	Opis	Użyj, gdy
Agent odpowiedzi	ChatClientAgent	Aplikacja programowo udostępnia model, instrukcje i narzędzia w czasie wykonywania za pomocą polecenia AIProjectClient.AsAIAgent(...). Nie utworzono zasobu agenta po stronie serwera.	Masz definicję agenta i potrzebujesz prostej, elastycznej konfiguracji. Jest to wzorzec używany w większości przykładów.
Agent Foundry (wersjonowany)	FoundryAgent	Zarządzane przez serwer — definicje agentów są tworzone i wersjonowane za pośrednictwem portalu Foundry lub programowo za pośrednictwem programu AIProjectClient.AgentAdministrationClient. Przekaż element ProjectsAgentVersion lub ProjectsAgentRecord lub AgentReference do AIProjectClient.AsAIAgent(...).	Potrzebujesz precyzyjnych, wersjonowanych definicji agentów zarządzanych poprzez portal Foundry przy użyciu interfejsów API serwisu.

Agent odpowiedzi (bezpośrednie wnioskowanie)

Użyj AsAIAgent bezpośrednio z AIProjectClient modelem i instrukcjami. Jest to zalecany punkt wyjścia dla większości scenariuszy.

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

Ostrzeżenie

DefaultAzureCredential jest wygodne do programowania, ale wymaga starannego rozważenia w środowisku produkcyjnym. W środowisku produkcyjnym rozważ użycie określonego poświadczenia (np. ManagedIdentityCredential), aby uniknąć problemów z opóźnieniami, niezamierzonego sondowania poświadczeń i potencjalnych zagrożeń bezpieczeństwa wynikających z mechanizmów awaryjnych.

Ta ścieżka jest primarnie oparta na kodzie i nie tworzy zasobu agenta zarządzanego przez serwer.

Agent Foundry (wersjonowany)

Użyj natywnych interfejsów API AIProjectClient.AgentAdministrationClient z zestawu SDK AI Projects, aby pobrać wersjonowane zasoby agenta, a następnie opakuj je przy użyciu AsAIAgent. Agentów można tworzyć i konfigurować bezpośrednio w portalu Foundry lub programowo za pośrednictwem programu 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."));

Ważna

Narzędzia i instrukcje agentów Foundry są powiązane z narzędziami i instrukcjami, z którymi zostały stworzone, próba zmodyfikowania narzędzi lub instrukcji w trakcie działania nie jest wspierana.

Korzystanie z agenta

Oba ChatClientAgent (odpowiedzi) i FoundryAgent (wersjonowane) są wystąpieniami standardowymi AIAgent i obsługują wszystkie standardowe operacje, w tym sesje, narzędzia, oprogramowanie pośredniczące i przesyłanie strumieniowe.

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

Aby uzyskać więcej informacji na temat uruchamiania agentów i interakcji z nimi, zobacz samouczki wprowadzające do agenta.

Skrzynki narzędziowe

Uwaga / Notatka

Dokumentacja programu Foundry Toolbox platformy .NET będzie dostępna wkrótce.

Odlewnia w Python

W Python wszyscy klienci specyficzni dla rozwiązania Foundry będą teraz aktywni w agent_framework.foundry.

• agent-framework-foundry Udostępnia łączniki usługi Cloud Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClienti FoundryMemoryProvider.
• agent-framework-foundry-local zapewnia FoundryLocalClient dla lokalnego wykonywania modelu.

Ważna

Na tej stronie omówiono obecne klienty Python dla punktów końcowych projektu Microsoft Foundry, punktów końcowych modeli i usługi agenta Foundry. Jeśli masz autonomiczny punkt końcowy zasobów Azure OpenAI (https://<your-resource>.openai.azure.com), skorzystaj z instrukcji dotyczących Pythona na stronie dostawcy OpenAI. Jeśli chcesz uruchamiać obsługiwane modele lokalnie, zobacz stronę Dostawcy lokalnego usługi Foundry.

Wzorce czatów i agentów programu Foundry w Python

Scenario	kształt Python	Użyj, gdy
Podstawowe wnioskowanie na punkcie końcowym odpowiedzi Foundry	Agent(client=FoundryChatClient(...))	Twoja aplikacja jest właścicielem definicji agenta, narzędzi i pętli konwersacji, a chcesz model wdrożony w projekcie Foundry.
Agenci zarządzani przez usługę w Foundry Agent Service	FoundryAgent(...)	Chcesz nawiązać połączenie z elementem PromptAgent lub HostedAgent utworzonym i skonfigurowanym w portalu Foundry lub za pośrednictwem interfejsów API usługi.

Installation

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

Ten sam agent-framework-foundry pakiet zawiera również FoundryEmbeddingClient do osadzeń dla końcówek modeli Foundry.

Konfiguracja

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"

Użyj polecenia FOUNDRY_AGENT_VERSION dla agentów monitów. Hostowani agenci mogą go pominąć.

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 i FoundryAgent używają punktu końcowego projektu. FoundryEmbeddingClient używa oddzielnego punktu końcowego dla modeli.

Wybieranie odpowiedniego klienta Python

Scenario	Preferowany klient	Notatki
Zasób Azure OpenAI	OpenAIChatCompletionClient / OpenAIChatClient	Użyj strony dostawcy OpenAI.
wnioskowanie projektu Microsoft Foundry	Agent(client=FoundryChatClient(...))	Używa punktu końcowego Reakcje Foundry.
Microsoft Agent zarządzany przez usługę Foundry	FoundryAgent	Zalecane dla szybkich agentów i hostowanych agentów.
Osadzenia punktów końcowych modeli Microsoft Foundry	FoundryEmbeddingClient	Używa znaku FOUNDRY_MODELS_ENDPOINT plus FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Lokalne środowisko uruchomieniowe usługi Foundry	Agent(client=FoundryLocalClient(...))	Zobacz Foundry Local.

Tworzenie agenta za pomocą polecenia FoundryChatClient

FoundryChatClient nawiązuje połączenie z wdrożonym modelem w projekcie Foundry i używa punktu końcowego Responses. Połącz ją ze standardem Agent , gdy aplikacja powinna posiadać instrukcje, narzędzia i obsługę sesji.

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 to ścieżka Python "Foundry-first" przeznaczona do bezpośredniego wnioskowania, która obsługuje narzędzia, strukturalne dane wyjściowe oraz strumieniowanie.

Tworzenie osadzania za pomocą polecenia FoundryEmbeddingClient

Użyj FoundryEmbeddingClient, jeśli chcesz osadzić tekst lub obraz z punktu końcowego modeli 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)

Nawiązywanie połączenia z agentem zarządzanym przez usługę za pomocą polecenia FoundryAgent

Użyj FoundryAgent , gdy definicja agenta znajduje się w narzędziu Foundry. Jest to zalecany interfejs API języka Python dla agentów komunikatów i agentów hostowanych.

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

W przypadku agenta hostedAgent pomiń agent_version i użyj nazwy hostowanego agenta.

Nawiązywanie połączenia z wdrożonym (hostowanym) agentem Foundry

W przypadku HostedAgents, które uruchamiają sesje po stronie usługi (/agents/{name}/sessions), użyj FoundryAgent z allow_preview=True do włączenia wersji zapoznawczej obszaru odpowiedzi i przekaż 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",
)

Jeśli musisz samodzielnie zarządzać podstawową sesją usługi — na przykład powiązać sesję z określoną dzierżawą lub użytkownikiem — utwórz sesję za pomocą interfejsu API w wersji zapoznawczej AIProjectClient i owiń ją za pomocą 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)

Tip

Zobacz using_deployed_agent.py przykładowy kod, aby zapoznać się z kompletnym przykładem, obejmujący automatyczne rozpoznawanie najnowszej wersji.

Ostrzeżenie

Starsze powierzchnie zgodności osadzania AI dla Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider oraz Azure zostały usunięte z bieżącej przestrzeni nazw agent_framework.azure. W przypadku bieżącego kodu Python użyj FoundryChatClient, gdy aplikacja jest właścicielem instrukcji i narzędzi, FoundryAgent, gdy definicja agenta znajduje się w Foundry, a FoundryEmbeddingClient dla osadzania modelów Foundry —endpointów.

Korzystanie z agenta

Zarówno FoundryChatClient, jak i FoundryAgent integrują się ze standardowym środowiskiem Agent Python, obejmującym wywoływanie narzędzi, sesje i odpowiedzi przesyłane strumieniowo. W przypadku lokalnych środowisk uruchomieniowych użyj oddzielnej strony dostawcy lokalnego programu Foundry.

Skrzynki narzędziowe

Ważna

Interfejsy API narzędziowe są eksperymentalne. Powierzchnia może ulec zmianie w przyszłych wersjach.

Foundry Toolbox to nazwany i wersjonowany pakiet konfiguracji narzędzi po stronie serwera (interpreter kodu, wyszukiwanie plików, generowanie obrazów, MCP, wyszukiwanie w internecie) hostowany w projekcie Microsoft Foundry. Przybornike umożliwiają zarządzanie konfiguracją narzędzi raz w portalu Foundry i ponowne używanie ich między agentami.

Struktura agenta obejmuje tylko konsumpcję — tworzenie i aktualizowanie wersji pakietu narzędziowego odbywa się za pośrednictwem portalu Foundry lub nieprzetworzonego zestawu azure-ai-projects SDK (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Typ agenta	Zachowanie przybornika
FoundryAgent (hostowany )	Dodawanie przybornika odbywa się po stronie serwera. Nie jest wymagane żadne okablowanie po stronie klienta.
FoundryChatClient (wnioskowanie bezpośrednie)	Pobierz skrzynkę z narzędziami get_toolbox() i przekaż ją jako tools=.

Dwa wzorce zużycia

Pattern	Opis
Natywne (narzędzia hostowane)	Konfiguracje narzędzi są wykonywane w środowisku uruchomieniowym Foundry. Przekaż przybornik bezpośrednio jako tools=.
MCP	Użyj MCPStreamableHTTPTool względem punktu końcowego MCP przybornika. Współpracuje z dowolnym klientem czatu, a nie tylko FoundryChatClient.

Pobieranie narzędziownika

Użyj FoundryChatClient.get_toolbox(), aby uzyskać dostęp do przybornika.

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)

Gdy version jest pominięty, get_toolbox rozpoznaje domyślną wersję w dwóch żądaniach. Przypnij określoną wersję, aby uniknąć dodatkowej rundy:

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

Uwaga / Notatka

Każde wywołanie get_toolbox() nawiązuje połączenie z siecią — nie ma pamięci podręcznej po stronie frameworku, ponieważ domyślne wersje mogą zmieniać się po stronie serwera. Buforowanie jest własnością obiektu wywołującego.

Niejawne spłaszczanie

Nie trzeba pisać toolbox.tools. normalize_tools Framework automatycznie rozpoznaje ToolboxVersionObject i spłaszcza. Wszystkie te prace:

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

Narzędzia filtrowania za pomocą polecenia select_toolbox_tools

Jeśli przybornik zawiera kilka narzędzi, ale agent potrzebuje tylko podzestawu, użyj narzędzia select_toolbox_tools, aby ograniczyć zestaw po pobraniu. Pozwala to uniknąć wysyłania niepotrzebnych definicji narzędzi do modelu, co zmniejsza użycie tokenu i uniemożliwia wywoływanie narzędzi, których nie zamierzasz ujawniać:

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

Funkcje pomocnicze get_toolbox_tool_name(tool) i get_toolbox_tool_type(tool) zwracają odpowiednio nazwę wyboru i surowy typ wpisu narzędzia. FoundryHostedToolType to TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) dla uzupełniania z przewodnikiem IDE na include_types / exclude_types.

Ścieżka zużycia MCP

Przybornik można również używać jako serwer MCP, kierując MCPStreamableHTTPTool na adres URL punktu końcowego MCP przybornika.

Adres URL punktu końcowego MCP jest wyświetlany w portalu Foundry lub ma następujący format:

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

Ponieważ klient łączy się bezpośrednio z punktem końcowym narzędzi Foundry, należy się uwierzytelnić za pomocą tokenu dostępu Entra ID poprzez 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)

Ograniczenia

• Narzędzia MCP w przyborniku używają uwierzytelniania po stronie serwera. Uwierzytelnianie na nadrzędnym serwerze MCP jest obsługiwane za pośrednictwem project_connection_id (połączenie OAuth skonfigurowane w projekcie Foundry). Klient nigdy nie przechowuje tokenów nosiciela dla serwera źródłowego.
• Korzystanie z zestawu narzędzi jako serwera MCP wymaga uwierzytelniania po stronie klienta. Po wskazaniu MCPStreamableHTTPTool punktu końcowego MCP przybornika należy podać token nosiciela Entra ID (na przykład za pośrednictwem get_bearer_token_provider(credential, "https://ai.azure.com/.default")) przez header_provider.
• Obsługa przepływu zgody jest problemem środowiska uruchomieniowego. Jeśli narzędzie MCP z przybornika uruchomi się CONSENT_REQUIRED podczas agent.run(), jest obsługiwane podczas działania, a nie podczas pobierania przybornika.

Samples

Sample	Opis
foundry_chat_client_with_toolbox.py	Pobieranie podstawowego zestawu narzędzi, przypinanie wersji, łączenie zestawów narzędzi i filtrowanie
foundry_chat_client_with_toolbox_mcp.py	Ścieżka konsumpcji MCP z MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	Dynamiczny wybór narzędzia dla każdej operacji za pośrednictwem dostawcy kontekstu

Następne kroki

Znaleziono lokalnie