dostawca modelu Microsoft Foundry

Wprowadzenie

Dodaj wymagany pakiet NuGet do projektu.

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

Dwa wzorce integracji

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

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

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

Korzystanie z agenta

Agent odpowiedzi jest standardem AIAgent i obsługuje 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 odpowiedzi Foundry utworzeni z AIProjectClient.AsAIAgent(...) obsługują standardowy interfejs narzędzi platformy Agent Framework. Zobacz Omówienie narzędzi , aby zapoznać się z pełną macierzą funkcji.

Odlewnia w Python

W języku Python wszystkie klienty specyficzne dla platformy Foundry znajdują się teraz w obszarze 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.

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

Installation

pip install agent-framework-foundry

Ten sam pakiet agent-framework-foundry zawiera również FoundryEmbeddingClient do osadzania tekstu za pośrednictwem projektu Foundry lub osadzania tekstu i obrazów za pośrednictwem punktu końcowego Foundry Models.

Configuration

FoundryChatClient

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

FoundryEmbeddingClient z endpointem projektu

FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"

Osadzenia obsługiwane przez projekt używają wdrożenia modelu osadzania OpenAI w projekcie Foundry. Uwierzytelnij się za pomocą asynchronicznego poświadczenia tokenu, takiego jak AzureCliCredential.

FoundryEmbeddingClient z punktem końcowym modeli

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

Użyj punktu końcowego Foundry Models do osadzania obrazów lub modeli tekstowych wdrożonych w tym punkcie końcowym. Jeśli obie zmienne środowiskowe punktu końcowego są ustawione i nie przekazujesz jawnego punktu końcowego ani klienta projektu, FOUNDRY_MODELS_ENDPOINT ma pierwszeństwo.

FoundryChatClient używa punktu końcowego projektu. FoundryEmbeddingClient obsługuje osadzenia tekstu oparte na projekcie oraz osadzenia tekstu lub obrazów w punktach końcowych modeli.

Wybieranie odpowiedniego klienta języka Python

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-account.services.ai.azure.com/api/projects/your-project",
        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.

Ustaw timeout limit czasu HTTP w sekundach, gdy żądanie wymaga innego limitu czasu niż domyślne ustawienia pakietu OpenAI SDK. Ten sam parametr jest dostępny w RawFoundryChatClient. Po pominięciu zestaw SDK używa pięciosekundowego limitu czasu połączenia i 600-sekundowego łącznego limitu czasu.

Współbieżne używanie klienta

Jedna instancja FoundryChatClient może obsługiwać współbieżne wywołania asynchroniczne na tej samej pętli zdarzeń, w tym równocześnie wykonywane wywołania strumieniowe i niestrumieniowe.

Utwórz osobne Agent i AgentSession dla każdego współbieżnego uruchomienia oraz przekaż osobne komunikaty i opcje. Oprogramowanie pośredniczące, narzędzia i funkcje zwrotne dostarczane przez użytkownika również muszą obsługiwać pracę współbieżną. Nie współużytkuj klienta między wątkami systemu operacyjnego ani między pętlami zdarzeń i nie zmieniaj jego konfiguracji, gdy trwa wykonywanie wywołań.

Wyrażanie zgody na zaszyfrowane rozumowanie

FoundryChatClient domyślnie nie żąda reasoning.encrypted_content. Ta wartość domyślna uniemożliwia błędy żądań w modelach, które nie obsługują szyfrowanego rozumowania.

Aby włączyć tę funkcję we wdrożeniu, które ją obsługuje, skorzystaj z domyślnych opcji agenta:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
        model="<reasoning-model-deployment>",
        credential=AzureCliCredential(),
    ),
    default_options={"include": ["reasoning.encrypted_content"]},
)

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=[...]). Informacje o narzędziach agentów zarządzanych przez usługę można znaleźć w Microsoft Foundry Agent Service.

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.

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

Wyszukiwanie niestandardowe Bing

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

Wyszukiwanie AI platformy Azure

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

Wyszukiwanie pamięci

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_tool umożliwia konfigurowanie natywnego korzystania z komputera za pomocą Responses API. Narzędzie Foundry SDK nie jest w wersji zapoznawczej, ale współdzielone konstruktory platformy Agent Framework ComputerSafetyCheck i komputerów Content są eksperymentalne. Aplikacja wykonuje uporządkowane akcje, przegląda kontrole bezpieczeństwa i zwraca zrzut ekranu. Aby uzyskać pełny przepływ żądań i wyników, zobacz Użycie komputera natywnego.

computer = FoundryChatClient.get_computer_tool()

Ta fabryka wymaga azure-ai-projects wersji 2.3.0 lub nowszej. Starsze obsługiwane wersje SDK mogą nadal importować FoundryChatClient, ale wywołanie get_computer_tool() powoduje zgłoszenie wyjątku ImportError z instrukcjami dotyczącymi aktualizacji.

get_computer_use_tool pozostaje dostępny dla osobnego interfejsu API Computer Use w wersji zapoznawczej:

preview_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 wykrywania A2A, sesji i przesyłania strumieniowego znajdziesz w usłudze agenta A2A.

Tworzenie osadzania za pomocą polecenia FoundryEmbeddingClient

Użyj elementu FoundryEmbeddingClient z punktem końcowym projektu, jeśli chcesz uzyskać osadzenia tekstu z wdrożenia OpenAI w projekcie Foundry.

import os

from agent_framework.foundry import FoundryEmbeddingClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    async with FoundryEmbeddingClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_EMBEDDING_MODEL"],
        credential=credential,
    ) as client:
        result = await client.get_embeddings(["hello from Agent Framework"])
        print(result[0].dimensions)

W przypadku osadzania obrazów skonfiguruj zamiast tego wartości FOUNDRY_MODELS_ENDPOINT, FOUNDRY_MODELS_API_KEYi FOUNDRY_IMAGE_EMBEDDING_MODEL . Nie należy łączyć konfiguracji punktu końcowego projektu z argumentami models-endpoint ani z klientami w obrębie tego samego FoundryEmbeddingClient.

Korzystanie z agenta

FoundryChatClientintegruje się ze standardowym środowiskiem PythonAgent, w tym wywoływaniem narzędzi, sesjami i odpowiedziami przesyłanymi strumieniowo. W przypadku lokalnych środowisk uruchomieniowych użyj oddzielnej strony dostawcy lokalnego programu Foundry.

Informacje o nazwanych i wersjonowanych pakietach hostowanych konfiguracji narzędzi można znaleźć w Microsoft Foundry Toolbox.

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.

Zobacz przykłady języka Foundry Go , aby zapoznać się z bezpośrednim wnioskowaniem, narzędziami funkcji, narzędziami hostowanymi, mcp i przykładami agenta serwera.

Pakiet obsługuje dwa obiekty docelowe agenta:

Configuration

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

Ponownie użyj jawnego agent.Session między przebiegami w celu zachowania stanu dostawcy. W przypadku przylepności sesji hostowanego agenta foundryprovider.HostedAgentSessionID(session) zwraca identyfikator przylepnej sesji hostowanej przechwycony przez dostawcę. SetHostedAgentSessionID przechowuje znany identyfikator, a WithHostedAgentSessionID przypina jeden identyfikator na potrzeby uruchomienia.

Identyfikator hostowanej sesji jest serializowany z sesją. Identyfikator przebiegu, który jest w konflikcie z przechowywanym identyfikatorem, powoduje błąd zamiast przełączania hostowanych sesji.

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.

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.

Embeddings

Go udostępnia osadzenia za pośrednictwem elementu foundryprovider.NewEmbeddingGenerator(endpoint, credential, foundryprovider.EmbeddingGeneratorConfig{...}). Generator uzyskuje punkt końcowy osadzania na poziomie zasobów z punktu końcowego rozwiązania Foundry i implementuje niezależny od dostawcy interfejs embedding.Generator. Zobacz Go vector stores oraz chat-history memory sample, aby zapoznać się ze sposobem użycia.

Bieżące luki języka Go

Obsługa języka Go nie obejmuje obecnie hostowanych interfejsów API wdrażania/cyklu życia/administracyjnych interfejsów API rozwiązania Foundry ani pomocników specyficznych dla języka Go dla Microsoft Foundry Toolbox. Użyj portalu Foundry lub zestawów SDK usługi do wykonywania tych operacji.