poskytovatel modelu Microsoft Foundry

Microsoft Agent Framework podporuje přímé odvozování modelu z koncových bodů projektu Microsoft Foundry, zatímco vaše aplikace vlastní definici agenta, nástroje a orchestraci.

Informace o výzev spravovaných službou a hostovaných agentech najdete v tématu Microsoft Služba agenta Foundry.

Začínáme

Přidejte do projektu požadované balíčky NuGet.

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

Dva vzory integrace

Integrace Microsoft Foundry zveřejňuje dva různé vzory použití:

Pattern Typ produkovaný Description Použít, když
Agent odpovědí ChatClientAgent Aplikace programově poskytuje model, pokyny a nástroje za běhu prostřednictvím AIProjectClient.AsAIAgent(...). Není vytvořen žádný prostředek agenta na straně serveru. Vlastníte definici agenta a chcete jednoduchou flexibilní instalaci. Toto je vzor používaný ve většině ukázek.
Foundry Agent (výzva nebo hostovaný) FoundryAgent Spravované serverem – Agenti výzvy jsou pojmenované a verze definice; Hostovaní agenti jsou nasazené aplikace, které jsou dostupné prostřednictvím koncového bodu specifického pro agenta. Foundry vlastní definici agenta nebo hostovaný modul runtime. Viz Microsoft Služba agenta Foundry.

Agent odpovědí (přímé odvození)

Používejte AsAIAgent přímo na AIProjectClient spolu s modelem a pokyny. Toto je doporučený výchozí bod pro většinu scénářů.

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

Warning

DefaultAzureCredential je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Tato cesta je zaměřená na kód a nevytváří prostředek agenta spravovaného serverem.

Použití agenta

Agent odpovědi je standardní AIAgent a podporuje relace, nástroje, middleware a streamování.

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

Další informace o tom, jak spouštět agenty a pracovat s nimi, najdete v úvodních kurzech agenta.

Tools

Foundry Responses Agents vytvořená z AIProjectClient.AsAIAgent(...) podpory standardní plochy nástroje Agent Framework. Podívejte se na přehled nástrojů pro celou matici funkcí.

nástroj Poznámky
Funkční nástroje Supported.
Schválení nástroje Supported. Poskytuje chatovací klient frameworku pro volání funkcí.
Interpretér kódu Supported.
Hledání souborů Supported.
Hostované nástroje MCP Supported.
Místní nástroje MCP Supported.
Sada nástrojů Microsoft Foundry Supported.

Fondry v Pythonu

V rámci Pythonu se nyní všechny klienty specifické pro Foundry nacházejí pod agent_framework.foundry.

  • agent-framework-foundryposkytuje konektory Cloud Foundry: FoundryChatClient, FoundryAgentFoundryEmbeddingClient, a FoundryMemoryProvider.
  • agent-framework-foundry-local poskytuje FoundryLocalClient pro místní spuštění modelu.

Important

Tato stránka popisuje koncové body projektu a modelů Microsoft Foundry. Informace o službě agenta Foundry najdete v tématu Microsoft Služba agenta Foundry. Pokud máte samostatný koncový bod pro Azure OpenAI (https://<your-resource>.openai.azure.com), použijte pokyny pro Python na stránce poskytovatele OpenAI. Pokud chcete spouštět podporované modely místně, podívejte se na stránku místního poskytovatele Foundry.

Chatové a agentní vzory ve Foundry v Pythonu

Scénář tvar v Pythonu Použít, když
Jednoduché inference pomocí koncového bodu Foundry Responses Agent(client=FoundryChatClient(...)) Vaše aplikace vlastní definici agenta, nástroje a smyčku konverzací a vy chcete model nasazený v projektu Foundry.
Agenti spravovaní službou ve Foundry Agent Service FoundryAgent(...) Chcete se připojit k promptagentu nebo hostovanému agentu, který je vytvořený a nakonfigurovaný na portálu Foundry nebo prostřednictvím rozhraní API služby.

Instalace

pip install agent-framework-foundry

Stejný agent-framework-foundry balíček také zahrnuje FoundryEmbeddingClient vkládání modelů Foundry do koncových bodů.

Configuration

FoundryChatClient

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

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 používá koncový bod projektu. FoundryEmbeddingClient používá samostatný koncový bod modelů.

Výběr správného klienta Pythonu

Scénář Upřednostňovaný klient Poznámky
Azure OpenAI prostředek OpenAIChatCompletionClient / OpenAIChatClient Použijte stránku zprostředkovatele OpenAI.
Odvození projektu Microsoft Foundry Agent(client=FoundryChatClient(...)) Používá koncový bod odpovědí Foundry.
Agent spravovaný službou Microsoft Foundry FoundryAgent Doporučeno pro okamžité agenty a hostované agenty.
Vložení embeddingů modelů Microsoft Foundry - koncové body rozhraní API FoundryEmbeddingClient Používá FOUNDRY_MODELS_ENDPOINT plus FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Místní modul runtime Foundry Agent(client=FoundryLocalClient(...)) Viz Foundry Local.

Vytvoření agenta pomocí FoundryChatClient

FoundryChatClient připojí se k nasazenému modelu v projektu Foundry a použije koncový bod Odpovědi. Spárujte ji se standardem Agent , když má vaše aplikace vlastní pokyny, nástroje a zpracování relací.

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 je Python cesta typu Foundry-first pro přímé odvozování a podporuje nástroje, strukturované výstupy a streamování.

Tools

FoundryChatClient poskytuje statické tovární metody pro každý hostovaný nástroj Foundry. Továrny vracejí objekty nástrojů sady SDK, které předáte do tools= v Agent nebo přímo do client.get_response(..., tools=[...]). Nástroje agenta spravovaného službou najdete v tématu Microsoft Služba agenta Foundry.

Tovární metody jsou metody třídy, takže k vytvoření nástroje nepotřebujete instanci:

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

Podpora nástrojů

V následující tabulce jsou uvedeny všechny nástroje, které Python FoundryChatClient dnes zveřejňuje.

nástroj Továrna na FoundryChatClient Stav Detail
Funkční nástroje n/a – předejte libovolný volatelný objekt v Pythonu nebo @ai_function GA Vyvoláno místně v procesu Python.
Schválení nástroje n/a – zabalí existující nástroje. GA Funguje s hostovanými nástroji MCP a funkčními nástroji.
Interpretér kódu get_code_interpreter_tool GA Spouštění kódu v sandboxu ve Foundry
Hledání souborů get_file_search_tool GA Prohledávejte nahrané soubory prostřednictvím úložišť vektorů Foundry.
Vyhledávání na webu get_web_search_tool GA Webové ukotvení podporované Bingem, spravované společností Microsoft. Azure pouze modely OpenAI.
Generování obrazu get_image_generation_tool GA Generování imagí hostované v Foundry
Hostovaný MCP get_mcp_tool GA Vzdálený server MCP spuštěný nástrojem Foundry.
Místní MCP n/a – použijte MCPStreamableHTTPTool / MCPStdioTool GA Spouští se ve vašem procesu; funguje s libovolným klientem.
Sada nástrojů Microsoft Foundry MCPStreamableHTTPTool nebo FoundryToolbox Beta Využíváno přes MCP z FoundryChatClient; připojeno na straně serveru na FoundryAgent.
Zemnění Bingu get_bing_grounding_tool Experimental Přineste si vlastní uzemnění pomocí prostředku Vyhledávání Bingu.
Vlastní vyhledávání Bingu get_bing_custom_search_tool Náhled Uzemnění Bingu omezeno na kurátorovaný seznam domén.
Azure AI Vyhledávač get_azure_ai_search_tool Experimental Pomocí připojení Foundry vyhledejte index Azure AI Vyhledávač.
SharePoint get_sharepoint_tool Náhled Základní odpovědi v SharePoint obsahu
Microsoft Fabric get_fabric_tool Náhled Dotazovat se na datového agenta Fabric
Hledání paměti get_memory_search_tool Náhled Prohledejte úložiště paměti spravované službou Foundry.
Použití počítačů get_computer_use_tool Náhled Nechte agenta řídit desktopové nebo prohlížečové prostředí.
Automatizace prohlížeče get_browser_automation_tool Náhled Využte prohlížeč přes připojení Azure Playwright.
Agent-to-Agent (A2A) - komunikace mezi agenty get_a2a_tool Náhled Zavolejte jiného agenta A2A jako nástroj.

Note

Experimentální továrny obalují typy z GA Foundry SDK, ale samotné obalové vrstvy se před vydáním GA mohou změnit. Továrny Preview zabalují typy sady Foundry SDK, jejichž podkladová funkce je ve verzi Preview a může se změnit nebo být odebrána. Oba vygenerují ExperimentalWarning při prvním použití v procesu.

Varianty vyhledávání na webu

Foundry nabízí tři možnosti ukotvení s podporou Bingu. Vyberte ten, který odpovídá vašemu scénáři:

  • get_web_search_tool (GA) – výchozí možnost bez nutnosti nastavení; prostředek Bing spravovaný společností Microsoft. Azure pouze modely OpenAI. Omezeno na user_location a search_context_size.
  • get_bing_grounding_tool (experimentální) – použijte vlastní Grounding s prostředkem Azure Bing Search. Podporuje count, freshness, market, set_lang a modely mimo OpenAI Foundry.
  • get_bing_custom_search_tool (preview) — použijte vlastní instanci Bing Custom Search k omezení ukotvení na pečlivě vybranou sadu domén.

Všechny tři odesílají vyhledávací data mimo hranice dodržování předpisů Azure. Úplné porovnání najdete v přehledu webového uzemnění .

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

Generování obrázků

get_image_generation_tool konfiguruje hostovaný nástroj Foundry pro generování obrázků. Model v odpovědi vytváří obsah obrázku – nejsou k dispozici žádné další soubory ke správě.

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

Zemnění Bingu

get_bing_grounding_tool zapouzdřuje nástroj Grounding with Bing Search Foundry. Prostředek Grounding with Bing Search si vytvoříte sami, přidáte ho jako připojení projektu Foundry a potom předáte ID připojení.

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

get_bing_custom_search_tool omezuje ukotvení na seznam povolených položek definovaný v prostředku 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žňuje agentovi dotazovat se na index Azure AI Vyhledávač pomocí připojení 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,
)

Služba SharePoint

get_sharepoint_tool zakládá odpovědi na obsahu SharePointu dostupném prostřednictvím připojení Foundry k SharePointu.

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

Microsoft Fabric

get_fabric_tool připojí agenta k datovému agentu Microsoft Fabric prostřednictvím připojení Foundry, aby agent mohl odpovídat na otázky týkající se vašich Fabric dat.

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

get_memory_search_tool umožňuje agentovi prohledávat úložiště paměti spravované foundry, volitelně omezené na uživatele nebo tenanta.

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

Použití počítače

get_computer_use_tool konfiguruje nástroj Computer Use Preview — model může ovládat prostředí plochy nebo prohlížeče prováděním akcí ukazatele a klávesnice.

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

Automatizace prohlížeče

get_browser_automation_tool propojí agenta s prostředkem Azure Playwright Testing pomocí připojení Foundry. Agent může řídit skutečný prohlížeč přes Playwright.

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

Komunikace mezi Agenty (Agent-to-Agent, A2A)

get_a2a_tool zveřejňuje vzdáleného agenta A2A jako nástroj, aby ho agent Foundry mohl volat. Zadejte buď base_url (a volitelně i agent_card_path), nebo project_connection_id pro uložené připojení A2A.

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

Obecné pokyny ke zjišťování A2A, relacím a streamování najdete ve službě agenta A2A.

Vytvořte embeddingy pomocí FoundryEmbeddingClient

Použijte FoundryEmbeddingClient , když chcete vložit text nebo obrázek z koncového bodu modelů 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)

Použití agenta

FoundryChatClientintegruje se se standardním prostředím PythonAgent, včetně volání nástrojů, relací a odpovědí streamování. Pro lokální moduly runtime použijte samostatnou stránku lokálního poskytovatele Foundry.

Pojmenované sady verzí hostovaných nástrojů najdete v tématu Microsoft Foundry Toolbox.

Foundry v jazyce Go

Sada Go SDK poskytuje agenty Microsoft Foundry prostřednictvím github.com/microsoft/agent-framework-go/provider/foundryprovider.

Příklady přímého odvozování, nástrojů funkcí, hostovaných nástrojů, MCP a serverových agentů najdete v ukázkách Foundry Go .

Balíček podporuje dva cíle agenta:

Target Obrazec Přejít Použít, když
nasazení modelu podporovaného projektem Project foundryprovider.ModelDeployment("gpt-4o-mini") Vaše aplikace vlastní pokyny, nástroje a tok konverzací.
Existující agent Foundry na straně serveru foundryprovider.ServerAgent("my-agent") Definice agenta je už v Foundry nakonfigurovaná.

Configuration

Nastavte koncový bod projektu Foundry a nasazení modelu:

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

Agent Foundry podporovaný projektem

Použijte ModelDeployment , když chcete vytvořit agenta Agent Framework v kódu a předat pokyny, nástroje, middleware a zprostředkovatele kontextu z vaší aplikace 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()

Existující agent Foundry na straně serveru

Použijte ServerAgent , když chcete vyvolat agenta, který už je v Foundry nakonfigurovaný. Agent na straně serveru vlastní pokyny a nástroje, takže AgentConfig.Instructions je pro tento cíl ignorován.

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

Agenti Foundry podporovaní projektem podporují standardní rozhraní nástrojů Go Agent Framework pro místní nástroje a podporované deklarace hostovaných nástrojů.

nástroj Stav Poznámky
Funkční nástroje Podporováno Funkce běží v procesu Go.
Schválení nástroje Podporováno Funguje s nástroji pro lokální funkce prostřednictvím cyklu automatického volání nástrojů.
Interpretér kódu Podporováno Použijte &hostedtool.CodeInterpreter{}.
Vyhledávání na webu Podporováno Použijte &hostedtool.WebSearch{}.
Místní nástroje MCP Podporováno Pomocí tool/mcptool se připojte k serveru MCP a zpřístupněte jeho nástroje lokálně.
Hostované nástroje MCP Momentálně není dokumentováno pro Go Foundry Místní nástroje MCP použijte, když potřebujete servery MCP s agenty Go Foundry.
Sada nástrojů Microsoft Foundry V současné době není k dispozici prostřednictvím pomocné funkce v Go.

Pro místní nástroje funkcí přidejte tool.Tool hodnoty prostřednictvím 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},
        },
    },
)

Pro spuštění hostovaného kódu předejte deklaraci hostovaného nástroje:

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

Hlavičky klienta a obsluhovaný model

Foundry přijímá maximálně x-client-* hlaviček na jeden běh. Přidejte je pomocí foundryprovider.WithClientHeader nebo foundryprovider.WithClientHeaders:

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

Když Foundry vrátí hlavičku odpovědi x-ms-served-model, poskytovatel Go ji přidá do dalších vlastností response/update jako ServedModel.

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

Poskytovatel paměti Foundry

Použijte foundryprovider.NewMemoryProvider, když chcete, aby agent frameworku Agent Framework při každém spuštění načítal data z úložiště paměti spravovaného službou Foundry a aktualizoval je.

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

Koncový bod musí být koncovým bodem Microsoft Foundry s rozsahem projektu a úložiště paměti už musí v daném projektu existovat. Zpětné volání pro rozsah by mělo vracet stabilní klíč oddílu pro uživatele, tenanta nebo konverzaci.

Tip

Kompletní spustitelný příklad najdete v ukázce Foundry Memory v jazyce Go.

Současné nedostatky v Go

Podpora Go v současné době nezahrnuje rozhraní API pro nasazení, životní cyklus nebo správce Foundry, klienty vkládání nebo pomocné rutiny specifické pro Go pro Microsoft Foundry Toolbox. Pro tyto operace použijte portál Foundry nebo sady SDK služby.

Další kroky

Místní prostředí Foundry

  • Last updated on