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.

Tools

Agenci Foundry utworzeni przy użyciu AIProjectClient.AsAIAgent(...) (ścieżki Responses) obsługują standardowy zestaw narzędzi Agent Framework — pełną listę i macierz obsługiwanych funkcji znajdziesz w omówieniu narzędzi. W przypadku agentów Foundry załadowanych z definicji agenta z określoną wersją (FoundryAgent) narzędzia agenta należą do definicji agenta Foundry, a nie do klienta.

Tool Notatki
Narzędzia funkcji Supported.
Zatwierdzanie narzędzi Supported. Udostępnione przez klienta czatu wywołującego funkcje biblioteki.
Interpreter kodów Supported.
Wyszukiwanie plików Supported.
Hostowane narzędzia MCP Supported.
Lokalne narzędzia MCP Supported.
Przyborniki Foundry Supported.

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.

Tools

FoundryChatClient udostępnia statyczne metody fabryczne dla każdego hostowanego narzędzia Foundry. Fabryki zwracają obiekty narzędzi SDK, które przekazujesz do tools= w elemencie Agent lub bezpośrednio do client.get_response(..., tools=[...]). W przypadku FoundryAgent narzędzia agenta są zdefiniowane bezpośrednio w samej definicji agenta Foundry — zobacz Co działa, a co nie działa z FoundryAgent.

Metody fabrykujące są metodami klasy, więc nie potrzebujesz instancji, aby utworzyć narzędzie:

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

Obsługa narzędzi

W poniższej tabeli wymieniono wszystkie narzędzia, które Python FoundryChatClient uwidacznia dzisiaj. FoundryAgent działa z tymi samymi narzędziami, ale muszą być skonfigurowane w definicji agenta foundry, a nie przekazywane w kodzie.

Tool Fabryka w FoundryChatClient Status Szczegół
Narzędzia funkcji n/a — przekaż dowolny obiekt wywoływalny Pythona lub @ai_function ogólna dostępność Wywoływane lokalnie w procesie Python.
Zatwierdzanie narzędzi n/a — opakowuje istniejące narzędzia ogólna dostępność Współpracuje z hostowanymi narzędziami MCP i narzędziami funkcyjnymi.
Interpreter kodów get_code_interpreter_tool ogólna dostępność Wykonywanie kodu w izolowanym środowisku na platformie Foundry.
Wyszukiwanie plików get_file_search_tool ogólna dostępność Przeszukuj przesłane pliki w wektorowych magazynach danych Foundry.
Wyszukiwanie w Sieci Web get_web_search_tool ogólna dostępność Oparte na usłudze Bing tworzenie podstaw internetowych zarządzanych przez Microsoft. Tylko modele Azure OpenAI.
Generowanie obrazów get_image_generation_tool ogólna dostępność Generowanie obrazów hostowane w usłudze Foundry.
Hostowana umowa MCP get_mcp_tool ogólna dostępność Zdalny serwer MCP wywoływany przez usługę Foundry.
Lokalne MCP n/a — użyj MCPStreamableHTTPTool / MCPStdioTool ogólna dostępność Działa w Twoim procesie; współpracuje z dowolnym klientem.
Przyborniki Foundry MCPStreamableHTTPTool do punktu końcowego MCP zestawu narzędzi ogólna dostępność Wykorzystywane przez MCP z FoundryChatClient; podłączone po stronie serwera na FoundryAgent.
Podstawy Binga get_bing_grounding_tool Experimental Bring-your-own Grounding with Bing Search resource (Korzystanie z własnego rozwiązania Grounding za pomocą zasobu wyszukiwania Bing).
Wyszukiwanie niestandardowe Bing get_bing_custom_search_tool Preview Uziemienie Bing jest ograniczone do wyselekcjonowanych list domen.
Wyszukiwanie AI platformy Azure get_azure_ai_search_tool Experimental Przeszukaj indeks Wyszukiwanie AI platformy Azure za pośrednictwem połączenia z usługą Foundry.
SharePoint get_sharepoint_tool Preview Podstawowe odpowiedzi w zawartości SharePoint.
Microsoft Fabric get_fabric_tool Preview Wysyłaj zapytania do agenta danych Fabric.
Wyszukiwanie pamięci get_memory_search_tool Preview Wyszukaj magazyn pamięci zarządzanej przez program Foundry.
Wykorzystanie komputerów get_computer_use_tool Preview Pozwól agentowi sterować środowiskiem pulpitu lub przeglądarki.
Automatyzacja przeglądarki get_browser_automation_tool Preview Sterowanie przeglądarką przy użyciu połączenia z Azure Playwright.
Agent do agenta (A2A) get_a2a_tool Preview Wywołaj innego agenta A2A w charakterze narzędzia.

Uwaga / Notatka

Eksperymentalne metody fabrykujące opakowują typy zestawu SDK GA Foundry, ale same opakowania mogą ulec zmianie przed wydaniem GA. Fabryki w wersji zapoznawczej opakowują typy zestawu Foundry SDK, których bazowa funkcjonalność ma status wersji zapoznawczej i może ulec zmianie lub zostać usunięta. Oba generują ExperimentalWarning przy pierwszym użyciu w procesie.

Warianty wyszukiwania w Sieci Web

Foundry uwidacznia trzy opcje uziemienia oparte na usłudze Bing. Wybierz ten, który jest zgodny ze scenariuszem:

  • get_web_search_tool (GA) — domyślnie, bez konfiguracji; zasób Bing zarządzany przez firmę Microsoft. Tylko modele Azure OpenAI. Ograniczone do user_location i search_context_size.
  • get_bing_grounding_tool (eksperymentalne) — użyj własnego zasobu Azure Grounding with Bing Search. Obsługuje count, freshness, market, set_lang oraz modele inne niż OpenAI Foundry.
  • get_bing_custom_search_tool (wersja zapoznawcza) — użyj własnego wystąpienia usługi Bing Custom Search, aby ograniczyć wyszukiwanie do wyselekcjonowanego zestawu domen.

Wszystkie trzy wysyłają dane wyszukiwania poza granicą zgodności Azure. Aby zapoznać się z pełnym porównaniem, zobacz omówienie uziemienia sieci Web .

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

Generowanie obrazu

get_image_generation_tool Konfiguruje narzędzie do generowania obrazów hostowanych przez firmę Foundry. Model tworzy zawartość obrazu w odpowiedzi — nie ma dodatkowych plików do zarządzania.

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

Ugruntowanie w Bing

get_bing_grounding_tool opakowuje uziemienia za pomocą narzędzia wyszukiwania Bing. Samodzielnie tworzysz zasób Grounding with Bing Search i dodajesz go jako połączenie w projekcie Foundry, a następnie przekazujesz identyfikator połączenia.

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

get_bing_custom_search_tool ogranicza odwołania do listy dozwolonych elementów zdefiniowanej w zasobie Bing Custom Search.

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

get_azure_ai_search_tool umożliwia agentowi wykonywanie zapytań o indeks Wyszukiwanie AI platformy Azure za pośrednictwem połączenia projektu Foundry.

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 opiera odpowiedzi na zawartości SharePoint dostępnej za pośrednictwem połączenia Foundry SharePoint.

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

Microsoft Fabric

get_fabric_tool łączy agenta z agentem danych Microsoft Fabric za pośrednictwem połączenia z usługą Foundry, aby agent mógł odpowiedzieć na pytania dotyczące danych Fabric.

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

get_memory_search_tool umożliwia agentowi przeszukiwanie magazynu pamięci zarządzanego przez Foundry, opcjonalnie zawężonego do użytkownika lub dzierżawcy.

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

Używanie komputera

get_computer_use_tool konfiguruje narzędzie podglądu Computer Use — model może obsługiwać środowisko pulpitu lub przeglądarki, wykonując działania myszy i klawiatury.

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

Automatyzacja przeglądarki

get_browser_automation_tool łączy agenta z zasobem Azure Playwright Testing za pomocą połączenia Foundry. Agent może sterować prawdziwą przeglądarką za pomocą Playwright.

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

Komunikacja agentów (A2A)

get_a2a_tool udostępnia zdalnego agenta A2A jako narzędzie, tak aby agent Foundry mógł go wywołać. Podaj albo base_url (i opcjonalnie agent_card_path), albo project_connection_id dla zapisanego połączenia A2A.

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

Ogólne wskazówki dotyczące A2A — wykrywanie, sesje, przesyłanie strumieniowe — znajdziesz na stronie dostawcy Agent-to-Agent.

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.

Co działa, a co nie działa w przypadku FoundryAgent

FoundryAgent łączy się z agentem, który już istnieje w Foundry (Prompt Agent lub Hosted Agent). Definicja agenta — jego instrukcje i konfiguracja narzędzia — znajduje się w rozwiązaniu Foundry, a nie w kodzie Python. Oznacza to, że kilka funkcji na poziomie Agent zachowuje się inaczej niż w przypadku Agent(client=FoundryChatClient(...)) lub innych agentów opartych na kliencie czatu.

Tools

Typ narzędzia przekazany do FoundryAgent(...) Behavior
FunctionTool (lokalny obiekt wywoływalny Pythona) Obsługiwane, ale tylko wtedy, gdy pasująca definicja funkcji już istnieje w agencie foundry. Środowisko uruchomieniowe Foundry decyduje o tym, które narzędzia mają być uwidaczniane w modelu na podstawie definicji agenta. Gdy model wywołuje funkcję, Foundry zwraca do klienta wywołanie narzędzia, a framework wywołuje lokalny obiekt wywoływalny Pythona w Twoim procesie (nie w Foundry), a następnie odsyła wynik z powrotem. Przekazanie FunctionTool po stronie klienta jedynie zapewnia tę lokalną implementację — jeśli funkcja nie zostanie zadeklarowana w agencie Foundry, model nigdy jej nie wywoła.
Hostowane narzędzia (wyszukiwanie w internecie, interpreter kodu, wyszukiwanie plików, MCP, generowanie obrazów itp.) Ignorowane. Należy je skonfigurować w samej definicji agenta usługi Foundry w portalu Foundry lub za pośrednictwem interfejsów API usługi. Przekazywanie ich po stronie klienta nie ma wpływu, ponieważ środowisko uruchomieniowe Foundry wie tylko o narzędziach dołączonych do definicji agenta.

Krótko mówiąc: nie można dodać nowych narzędzi w czasie budowy. Każde narzędzie, które może wywołać model — w tym lokalne funkcje Python — musi już być częścią definicji agenta w narzędziu Foundry. Przekazanie elementu FunctionTool do FoundryAgent(...) udostępnia jedynie lokalną implementację uruchamianą w ramach procesu Pythona, gdy wywoływana jest funkcja zdefiniowana w Foundry; nie rejestruje jednak nowego narzędzia w agencie.

Dostawcy kontekstu

context_providers=[...] jest częściowo obsługiwane. To, czy dostawca kontekstu działa, zależy od tego, co dostawca próbuje wykonać:

Zachowanie dostawcy kontekstu Działa z FoundryAgent?
Dodaje dodatkowy kontekst jako komunikaty (na przykład pobraną pamięć, fragmenty kodu RAG, informacje o profilu użytkownika) Tak. Wstrzykiwany kontekst jest przekazywany wraz z żądaniem.
Zapisuje lub obserwuje rozmowę (na przykład zapisując wypowiedzi w zewnętrznym magazynie danych) Tak. Uruchamia się lokalnie wokół żądania/odpowiedzi.
Dodaje narzędzia dynamicznie (na przykład SkillsProvider lub dowolnego dostawcę, który zwraca narzędzia z invoking()) Nie, chyba że narzędzia są już częścią definicji agenta usługi Foundry. Środowisko uruchomieniowe Foundry wykonuje model względem narzędzi dołączonych do agenta w narzędziu Foundry; narzędzia, które istnieją tylko lokalnie, nie są widoczne dla modelu i nie będą wywoływane.

Jeśli potrzebujesz dynamicznego wyboru narzędzi, ładowania umiejętności lub innego zachowania, które opiera się na narzędziach dodawanych w czasie wykonywania, zamiast tego użyj Agent(client=FoundryChatClient(...)) — to podejście lokalnie kontroluje pętlę modelu i obsługuje pełny zestaw typów narzędzi oraz dostawców kontekstu dodawania narzędzi.

Opcje uruchamiania (opcje default_options i agent.run(...))

Opcje przekazywane do FoundryAgent(default_options=...) lub do agent.run(..., **options) (takie jak temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata itd.) nie wszystkie są uwzględniane. Ponieważ definicja agenta w narzędziu Foundry jest źródłem prawdy, wiele opcji jest ignorowanych w trybie dyskretnym.

W przypadku Prompt Agents framework jawnie usuwa lub zastępuje następujące elementy przed wysłaniem żądania do interfejsu API Foundry Responses:

Option Zachowanie za pomocą polecenia FoundryAgent
model Ignorowane. Model jest pobierany z definicji agenta Foundry.
tools, tool_choice, parallel_tool_calls Usunięte z treści żądania. Narzędzia muszą być zadeklarowane w definicji agenta Foundry (zobacz poprzednią sekcję). FunctionTool obiekty wywołujące są nadal połączone lokalnie w celu wywołania funkcji, ale sama lista narzędzi nie jest wysyłana do usługi.
instructions i komunikaty systemowe i deweloperskie Ignorowane. Własne instrukcje agenta Foundry są wiążące. Komunikaty systemowe/deweloperskie są usuwane z listy komunikatów przed wysłaniem żądania.
conversation_id Używana i przypisywana do sesji agenta Foundry, jeśli się do niej odnosi.
extra_body Przekazana dalej, scalona z ładunkiem danych ustawionym przez platformę agent_reference.
Parametry próbkowania (temperature, top_p, max_tokens, seed, frequency_penalty, presence_penalty, stop, …), metadata, user, store, response_format itd. Przekazano do interfejsu Responses API. To, czy Foundry faktycznie je stosuje, zależy od konfiguracji agenta i modelu — definicja agenta może je nadpisać lub ograniczyć — więc nie zakładaj, że będą miały zastosowanie w przypadku agenta Prompt.

W przypadku agentów hostowanych ma zastosowanie to samo usuwanie po stronie klienta, ale wszystko poza tym zależy od implementacji określonego hostowanego agenta. Hostowany agent może zaakceptować, zignorować lub ponownie zinterpretować dowolną opcję, która jest przekazywana dalej. Traktuj opcje uruchomieniowe wyłącznie jako wskazówki i zweryfikuj rzeczywiste działanie względem hostowanego agenta, którego wywołujesz.

Tip

Jeśli potrzebujesz precyzyjnej kontroli nad parametrami generowania, instrukcjami lub wyborem narzędzi dla każdego uruchomienia, skonfiguruj je w definicji agenta Foundry albo przełącz się na Agent(client=FoundryChatClient(...)), które kompleksowo obsługuje ChatOptions.

Tip

Dobra praktyczna zasada: jeśli funkcja zależy od zmiany instrukcji lub narzędzi agenta przy każdym uruchomieniu, powinna znaleźć się w Agent(client=FoundryChatClient(...)). Jeśli definicja agenta jest ustalona w Foundry i potrzebujesz tylko lokalnego wywoływania funkcji oraz kontekstu na poziomie wiadomości, FoundryAgent jest właściwym wyborem.

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, aby włączyć korzystanie z interfejsu Responses w wersji zapoznawczej:

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

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

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.

Ustawianie niestandardowego limitu czasu HTTP

Domyślnie FoundryAgent (i RawFoundryAgent) dziedziczy wbudowane ustawienia limitu czasu pakietu SDK OpenAI (5 s na nawiązanie połączenia / 600 s łącznie). W przypadku wieloturowych rozmów lub wolnych połączeń sieciowych może to objawiać się jako ConnectTimeout. Przekaż timeout= (w sekundach) podczas tworzenia, aby nadpisać tę wartość:

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",
    credential=AzureCliCredential(),
    timeout=120.0,  # seconds; set to None to use the SDK default
)

Wartość jest stosowana za pośrednictwem with_options(timeout=...) na kopii klienta HTTP przypisanej do danego agenta, więc nie wpływa na innych agentów ani klientów, którzy współdzielą ten sam AIProjectClient.

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) Użyj MCPStreamableHTTPTool względem punktu końcowego MCP przybornika.

Dwa wzorce zużycia

Pattern Opis
Załącznik agenta hostowanego Konfiguracje narzędzi są wykonywane w środowisku uruchomieniowym Foundry. Dołącz zestaw narzędzi do hostowanego agenta Foundry.
MCP Użyj MCPStreamableHTTPTool względem punktu końcowego MCP przybornika. Współpracuje z dowolnym klientem czatu, a nie tylko FoundryChatClient.

Bezpośrednie wnioskowanie przy użyciu punktu końcowego MCP zestawu narzędzi

Do FoundryChatClient inferencji bezpośredniej wskaż MCPStreamableHTTPTool na punkt końcowy MCP zestawu narzędzi. Użyj allowed_tools w MCPStreamableHTTPTool, gdy przybornik udostępnia narzędzia, których dany agent nie powinien wywoływać.

Ś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 _kwargs: {"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 Korzystanie z Toolbox MCP przy użyciu MCPStreamableHTTPTool
foundry_chat_client_with_toolbox_skills.py Konfiguracja umiejętności oparta na zestawie narzędzi
invoke_foundry_toolbox_mcp Ścieżka konsumpcji MCP z MCPStreamableHTTPTool

Foundry w języku Go

Zestaw SDK języka Go udostępnia agentów Microsoft Foundry za pośrednictwem usługi github.com/microsoft/agent-framework-go/provider/foundryprovider.

Pakiet obsługuje dwa obiekty docelowe agenta:

Obiekt docelowy Kształt języka Go Użyj, gdy
wdrażanie modelu wspieranego przez projekt foundryprovider.ModelDeployment("gpt-4o-mini") Twoja aplikacja kontroluje instrukcje, narzędzia i przebieg rozmowy.
Istniejący agent usługi Foundry po stronie serwera foundryprovider.ServerAgent("my-agent") Definicja agenta jest już skonfigurowana w narzędziu Foundry.

Konfiguracja

Ustaw punkt końcowy projektu Foundry i wdrożenie modelu:

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
FOUNDRY_MODEL="gpt-4o-mini"

Agent Foundry wspierany przez projekt

Użyj ModelDeployment, jeśli chcesz utworzyć w kodzie agenta Agent Framework i przekazać instrukcje, narzędzia, middleware oraz dostawców kontekstu z aplikacji napisanej w Go.

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

Istniejący agent usługi Foundry po stronie serwera

Użyj ServerAgent polecenia , jeśli chcesz wywołać agenta już skonfigurowanego w narzędziu Foundry. Agent po stronie serwera jest właścicielem swoich instrukcji i narzędzi, dlatego AgentConfig.Instructions jest ignorowany dla tego obiektu docelowego.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

Agenci Foundry obsługiwani przez projekty obsługują standardowy interfejs narzędziowy platformy Go Agent Framework dla narzędzi lokalnych i obsługiwanych deklaracji narzędzi hostowanych.

Tool Status Notatki
Narzędzia funkcji Supported Funkcje są uruchamiane w procesie języka Go.
Zatwierdzanie narzędzi Supported Współpracuje z lokalnymi narzędziami funkcji za pośrednictwem pętli automatycznego wywoływania narzędzi.
Interpreter kodów Supported Użyj &hostedtool.CodeInterpreter{}.
Wyszukiwanie w Sieci Web Supported Użyj &hostedtool.WebSearch{}.
Lokalne narzędzia MCP Supported Użyj tool/mcptool polecenia , aby nawiązać połączenie z serwerem MCP i uwidocznić jego narzędzia lokalnie.
Hostowane narzędzia MCP Obecnie brak dokumentacji dla Go Foundry Użyj lokalnych narzędzi MCP, jeśli potrzebujesz serwerów MCP z agentami Go Foundry.
Przyborniki Foundry Obecnie nie jest udostępnione przez funkcję pomocniczą Go.

W przypadku lokalnych narzędzi funkcji dodaj wartości tool.Tool za pośrednictwem agent.Config.Tools:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

W przypadku wykonywania hostowanego kodu przekaż deklarację hostowanego narzędzia:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

Nagłówki klienta i serwowany model

Narzędzie Foundry akceptuje x-client-* nagłówki na przebieg. Dodaj je za pomocą polecenia foundryprovider.WithClientHeader lub foundryprovider.WithClientHeaders:

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

Gdy Foundry zwraca nagłówek odpowiedzi x-ms-served-model, dostawca Go dodaje go jako ServedModel do dodatkowych właściwości odpowiedzi/aktualizacji.

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Dostawca pamięci Foundry

Użyj foundryprovider.NewMemoryProvider, jeśli chcesz, aby agent Agent Framework przy każdym uruchomieniu pobierał dane z magazynu pamięci zarządzanego przez Foundry i go aktualizował.

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

Punkt końcowy musi być punktem końcowym w zakresie projektu Microsoft Foundry, a magazyn pamięci musi już istnieć w tym projekcie. Funkcja zwrotna zakresu powinna zwracać stabilny klucz użytkownika, dzierżawcy lub partycji konwersacji.

Tip

Zobacz przykład pamięci Foundry w języku Go, aby poznać kompletny działający przykład.

Bieżące luki języka Go

Wsparcie dla języka Go nie obejmuje obecnie hostowanych interfejsów API wdrażania, cyklu życia i administracji Foundry, klientów osadzeń ani pomocników specyficznych dla języka Go dla zestawów narzędziowych Foundry. Użyj portalu Foundry lub zestawów SDK usługi do wykonywania tych operacji.

Następne kroki

Znaleziono lokalnie

  • Last updated on