Microsoft Foundry-modellprovider

Microsoft Agent Framework stöder direkt modellinferens från Microsoft Foundry-projektslutpunkter medan ditt program äger agentdefinitionen, verktygen och orkestreringen.

För tjänsthanterade prompter och värdbaserade agenter, se Microsoft Foundry Agent Service.

Getting Started

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

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

Två integreringsmönster

Microsoft Foundry-integreringen exponerar två distinkta användningsmönster:

Pattern Producerad typ Description Använd när
Svarsagent ChatClientAgent Appen tillhandahåller automatiskt en modell, instruktioner och verktyg under körning via AIProjectClient.AsAIAgent(...). Ingen agentresurs på serversidan skapas. Du äger agentdefinitionen och vill ha en enkel, flexibel konfiguration. Det här är det mönster som används i de flesta exempel.
Foundry Agent (fråga eller värdbaserad) FoundryAgent Serverhanterad – Prompt Agents namnges och versionshanteras definitioner. Värdbaserade agenter distribueras program som nås via en agentspecifik slutpunkt. Foundry äger agentdefinitionen eller värdbaserad körning. Se Microsoft Foundry Agent Service.

Svarsagent (direkt slutsatsdragning)

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

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Varning

DefaultAzureCredential är praktiskt för utveckling men kräver noggrant övervägande i produktion. I produktion bör du överväga att använda en specifik autentiseringsuppgift (t.ex. ManagedIdentityCredential) för att undvika problem med svarstid, oavsiktlig avsökning av autentiseringsuppgifter och potentiella säkerhetsrisker från reservmekanismer.

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

Använda agenten

Svarsagenten är en standard AIAgent och har stöd för sessioner, verktyg, mellanprogram och strömning.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

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

Tools

Foundry Responses-agenter som skapats från AIProjectClient.AsAIAgent(...) har stöd för Standard Agent Framework-verktygsytan. Se Översikt över verktyg för den fullständiga funktionsmatrisen.

Verktyg Notes
Funktionsverktyg Stöds.
Godkännande av verktyg Stöds. Tillhandahålls av ramverkets funktionsanropande chattklient.
Kodtolkare Stöds.
Filsökning Stöds.
Värdhanterade MCP-verktyg Stöds.
Lokala MCP-verktyg Stöds.
verktygslådan Microsoft Foundry Stöds.

Foundry-plattform i Python

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

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

Important

Den här sidan beskriver slutpunkter för Microsoft Foundry-projekt och modeller. Information om Foundry Agent Service finns i Microsoft Foundry Agent Service. Om du har en fristående Azure OpenAI-resursslutpunkt (https://<your-resource>.openai.azure.com) använder du Python-vägledningen på sidan OpenAI-provider. Om du vill köra modeller som stöds lokalt kan du se sidan Foundry Lokal leverantör.

Mönster för Foundry-chatt och agent i Python

Scenario Python-struktur Använd när
Enkel slutsatsdragning med API-slutpunkten Foundry Responses Agent(client=FoundryChatClient(...)) Din app äger agentdefinitionen, verktygen och konversationsloopen och du vill att en modell ska distribueras i ett Foundry-projekt.
Tjänsthanterade agenter i Foundry Agent-tjänsten FoundryAgent(...) Du vill ansluta till en PromptAgent eller HostedAgent som skapas och konfigureras i Foundry-portalen eller via tjänst-API:erna.

Installation

pip install agent-framework-foundry

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

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

Välj rätt Python-klient

Scenario Önskad klient Notes
Azure OpenAI-resurs OpenAIChatCompletionClient / OpenAIChatClient Använd sidan OpenAI-leverantör.
Microsoft Foundry-projektets inferens Agent(client=FoundryChatClient(...)) Använder Foundry Responses-slutpunkten.
Microsoft Foundry-tjänsthanterad agent FoundryAgent Rekommenderas för Prompt Agents och HostedAgents.
Microsoft Foundry-modeller - endpoint-embeddingar FoundryEmbeddingClient Använder FOUNDRY_MODELS_ENDPOINT plus FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Foundry Lokal körning Agent(client=FoundryLocalClient(...)) Se Foundry Local.

Skapa en agent med FoundryChatClient

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

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

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient är en Python-miljö avsedd för Foundry för direkt inferens, och den stöder verktyg, strukturerade utdata och strömning.

Tools

FoundryChatClient levererar statiska fabriksmetoder för varje värdbaserat Foundry-verktyg. Fabrikerna returnerar SDK-verktygsobjekt som du skickar till tools= på Agent eller direkt till client.get_response(..., tools=[...]). För tjänsthanterade agentverktyg, se Microsoft Foundry Agent Service.

Fabrikerna är klassmetoder, så du behöver ingen instans för att skapa ett verktyg:

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

Verktygsstöd

Tabellen nedan visar varje verktyg som Python FoundryChatClient exponerar idag.

Verktyg Fabriksläge på FoundryChatClient Status Detaljer
Funktionsverktyg n/a — skicka in vilket Python-anropbart objekt som helst eller @ai_function GA Anropas lokalt i din Python process.
Godkännande av verktyg n/a – omsluter befintliga verktyg GA Fungerar med värdbaserade MCP- och funktionsverktyg.
Kodtolkare get_code_interpreter_tool GA Körning av kod i begränsat läge på Foundry.
Filsökning get_file_search_tool GA Sök efter uppladdade filer via Foundry-vektorlager.
Webbsökning get_web_search_tool GA Bing-baserad webbförankring hanteras av Microsoft. Endast Azure OpenAI-modeller.
Bildgenerering get_image_generation_tool GA Avbildningsgenerering som finns på Foundry.
Hanterad MCP get_mcp_tool GA Fjärr-MCP-server som anropas av Foundry.
Lokal MCP n/a – använd MCPStreamableHTTPTool / MCPStdioTool GA Körs i din process; fungerar med alla klienter.
verktygslådan Microsoft Foundry MCPStreamableHTTPTool eller FoundryToolbox Beta-version Förbrukas via MCP från FoundryChatClient; ansluten serversida på FoundryAgent.
Grundläggning i Bing get_bing_grounding_tool Experimental Använd egen förankring med resursen Bing Search.
Bing anpassad sökning get_bing_custom_search_tool Preview Bing-förankring är begränsad till en utvald domänlista.
Azure AI-sökning get_azure_ai_search_tool Experimental Sök i ett Azure AI-sökning index via en Foundry-anslutning.
SharePoint get_sharepoint_tool Preview Grundsvar i SharePoint innehåll.
Microsoft Fabric get_fabric_tool Preview Fråga en Fabric-dataagent.
Minnessökning get_memory_search_tool Preview Sök i ett Foundry-hanterat minneslager.
Datoranvändning get_computer_use_tool Preview Låt agenten köra en skrivbords- eller webbläsarmiljö.
Webbläsarautomatisering get_browser_automation_tool Preview Kör en webbläsare via en Azure Playwright-anslutning.
Agent-till-agent (A2A) get_a2a_tool Preview Anropa en annan A2A-agent som ett verktyg.

Anmärkning

experimentella fabriksklasser omger GA Foundry SDK-typer, men de omgivande klasserna kan komma att ändras innan GA. Förhandsgranskningsfabriker omsluter Foundry SDK-typer vars underliggande funktion är i förhandsversion och kan ändras eller tas bort. Båda genererar en ExperimentalWarning första gång de används i en process.

Webbsökningsvarianter

Foundry erbjuder tre alternativ för förankring med stöd av Bing. Välj den som matchar ditt scenario:

  • get_web_search_tool (GA) – standardinställningen noll; Bing-resurs som hanteras av Microsoft. Endast Azure OpenAI-modeller. Begränsad till user_location och search_context_size.
  • get_bing_grounding_tool (experimentell) – ta med din egen grounding med Bing Search Azure resurs. Stöder count, freshness, market, set_langoch icke-OpenAI Foundry-modeller.
  • get_bing_custom_search_tool (förhandsversion) – använd din egen Bing Custom Search-instans för att begränsa grundningen till en utvald uppsättning domäner.

Alla tre skickar sökdata utanför Azure efterlevnadsgräns. Se översikten över webbgrundning för den fullständiga jämförelsen.

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

Bildgenerering

get_image_generation_tool konfigurerar Foundrys värdbaserade avbildningsgenereringsverktyg. Modellen genererar bildinnehåll i svaret – det finns inga extra filer att hantera.

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

Jordning i Bing

get_bing_grounding_tool omger verktyget Grounding with Bing Search Foundry. Du skapar resursen Grounding med Bing Search själv och lägger till den som en Foundry-projektanslutning och skickar sedan anslutnings-ID:t.

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

get_bing_custom_search_tool begränsar förankringen till den tillåtslista som definieras i en Bing Custom Search-resurs.

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 låter agenten köra frågor mot ett Azure AI-sökning index via en Foundry-projektanslutning.

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 baserar svar på SharePoint-innehåll som är åtkomligt via en Foundry SharePoint-anslutning.

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

Microsoft Fabric

get_fabric_tool ansluter agenten till en Microsoft Fabric dataagent via en Foundry-anslutning så att agenten kan svara på frågor om dina Fabric data.

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

get_memory_search_tool låter agenten söka i ett Foundry-hanterat minneslager, eventuellt begränsat till en användare eller klientorganisation.

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

Datoranvändning

get_computer_use_tool konfigurerar förhandsverktyget för datoranvändning – modellen kan styra en skrivbords- eller webbläsarmiljö genom att utföra mus- och tangentbordsåtgärder.

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

Webbläsarautomatisering

get_browser_automation_tool kopplar agenten till en Azure Playwright Testing-resurs via en Foundry-anslutning. Agenten kan köra en riktig webbläsare via Playwright.

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

Agent-till-agent (A2A)

get_a2a_tool gör en fjärransluten A2A-agent tillgänglig som ett verktyg så att en Foundry-agent kan anropa den. Ange antingen en base_url (och eventuellt agent_card_path) eller en project_connection_id för en lagrad A2A-anslutning.

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

Allmän A2A-identifiering, sessioner och strömningsvägledning finns i A2A-agenttjänsten.

Skapa inbäddningar med FoundryEmbeddingClient

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

from agent_framework.foundry import FoundryEmbeddingClient

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

Använda agenten

FoundryChatClientintegreras med standardupplevelsen för PythonAgent, inklusive verktygssamtal, sessioner och strömningssvar. För lokala körmiljöer använder du den separata Foundry Local-provider-sidan.

För namngivna versionspaket med värdbaserade verktygskonfigurationer, se Microsoft Foundry Toolbox.

Foundry i Go

Go SDK tillhandahåller Microsoft Foundry-agenter via github.com/microsoft/agent-framework-go/provider/foundryprovider.

Se Foundry Go-exempel för direkt slutsatsdragning, funktionsverktyg, värdbaserade verktyg, MCP och serveragentexempel.

Paketet stöder två agentmål:

Target Go-formen Använd när
Projektstödd modelldriftsättning foundryprovider.ModelDeployment("gpt-4o-mini") Din app äger instruktioner, verktyg och konversationsflöde.
Befintlig Foundry-agent på serversidan foundryprovider.ServerAgent("my-agent") Agentdefinitionen har redan konfigurerats i Foundry.

Configuration

Ange ändpunkten för ditt Foundry-projekt och modelldistributionen:

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

Projektstödd Foundry-agent

Använd ModelDeployment när du vill skapa en Agent Framework-agent i kod och skicka instruktioner, verktyg, mellanprogram och kontextproviders från ditt Go-program.

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

Befintlig Foundry-agent på serversidan

Använd ServerAgent när du vill anropa en agent som redan har konfigurerats i Foundry. Agenten på serversidan äger sina instruktioner och verktyg, så AgentConfig.Instructions ignoreras för det här målet.

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

Project-backade Foundry-agenter har stöd för Go Agent Framework-standardverktygsytan för lokala verktyg och värdbaserade verktygsdeklarationer som stöds.

Verktyg Status Notes
Funktionsverktyg Stöds Funktioner körs i din Go-process.
Godkännande av verktyg Stöds Fungerar med lokala funktionsverktyg via verktygets automatiska anropsloop.
Kodtolkare Stöds Använd &hostedtool.CodeInterpreter{}.
Webbsökning Stöds Använd &hostedtool.WebSearch{}.
Lokala MCP-verktyg Stöds Använd tool/mcptool för att ansluta till en MCP-server och exponera dess verktyg lokalt.
Värdhanterade MCP-verktyg Inte dokumenterat för Go Foundry Använd lokala MCP-verktyg när du behöver MCP-servrar med Go Foundry-agenter.
verktygslådan Microsoft Foundry Inte för närvarande tillgängliggjord via en hjälpfunktion i Go.

För lokala funktionsverktyg lägger du till tool.Tool värden via 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},
        },
    },
)

För körning av värdbaserad kod skickar du den värdbaserade verktygsdeklarationen:

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

Klientrubriker och serverad modell

Foundry godtar x-client-* rubriker i varje körning. Lägg till dem med foundryprovider.WithClientHeader eller foundryprovider.WithClientHeaders:

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

När Foundry returnerar svarshuvudet x-ms-served-model lägger Go-providern till det i ytterligare egenskaper för svar/uppdatering som ServedModel.

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

Foundry-minnesleverantör

Använd foundryprovider.NewMemoryProvider när du vill att en Agent Framework-agent ska hämta från och uppdatera ett Foundry-hanterat minneslager runt varje körning.

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

Slutpunkten måste vara en projektspecifik Microsoft Foundry-slutpunkt, och minneslagret måste redan finnas i det projektet. Omfångsåteranropet ska returnera en stabil användare, klientorganisation eller konversationspartitionsnyckel.

Tips/Råd

Ett fullständigt körbart exempel finns i Foundry Memory Go-exemplet .

Nuvarande brister i Go

Go-supporten inkluderar för närvarande inte Foundry-värdbaserad distribution/livscykel/administratörs-API:er, inbäddningsklienter eller Go-specifika hjälpverktyg för Microsoft Foundry Toolbox. Använd Foundry-portalen eller tjänst-SDK:er för dessa åtgärder.

Nästa steg

Foundry Local

  • Last updated on