Microsoft Foundry-modellprovider

Getting Started

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

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

Två integreringsmönster

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

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

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.

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.

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

Installation

pip install agent-framework-foundry

Samma agent-framework-foundry paket innehåller FoundryEmbeddingClient även för textinbäddningar via ett Foundry-projekt eller text- och bildinbäddningar via en Foundry Models-slutpunkt.

Configuration

FoundryChatClient

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

FoundryEmbeddingClient med en projektslutpunkt

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

Projektstödda embeddingar använder en OpenAI-distribution av embeddingar i Foundry-projektet. Autentisera med en asynkron tokenautentiseringsuppgift, till exempel AzureCliCredential.

FoundryEmbeddingClient med en modellslutpunkt

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

Använd Foundry Models-slutpunkten för bildinbäddningar eller för textmodeller som har driftsatts på den slutpunkten. Om båda miljövariablerna för slutpunkterna är angivna och du inte anger en explicit slutpunkt eller projektklient, har FOUNDRY_MODELS_ENDPOINT företräde.

FoundryChatClient använder projektslutpunkten. FoundryEmbeddingClient stöder projektbaserade textinbäddningar samt text- eller bildinbäddningar från modellslutpunkter.

Välj rätt Python-klient

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

Återanvänd klienten samtidigt

En FoundryChatClient instans kan hantera samtidiga asynkrona anrop i samma händelseloop, inklusive överlappande strömnings- och icke-strömmande anrop.

Skapa en separat Agent och AgentSession för varje parallell körning, samt skicka separata meddelanden och alternativ. Mellanprogram, verktyg och återanrop från användare måste också ha stöd för samtidighet. Dela inte klienten mellan OS-trådar eller händelseloopar, eller ändra dess konfiguration när anrop är aktiva.

Anmäl dig till krypterat resonemang

FoundryChatClient begär reasoning.encrypted_content inte som standard. Den här standardinställningen förhindrar begärandefel på modeller som inte stöder krypterade resonemang.

För en kompatibel distribution väljer du agentens standardalternativ:

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 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.

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

Anpassad Bing-sökning

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

Azure AI-sökning

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

Minnessökning

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_tool konfigurerar intern datoranvändning via svars-API:et. Foundry SDK-verktyget är inte i förhandsversion, men de gemensamma konstruktorerna för Agent Framework ComputerSafetyCheck och dator Content är experimentella. Ditt program kör de ordnade åtgärderna, granskar säkerhetskontroller och returnerar en skärmbild. Fullständig begäran och resultatflöde finns i Intern datoranvändning.

computer = FoundryChatClient.get_computer_tool()

Den här fabriken kräver azure-ai-projects 2.3.0 eller senare. Äldre SDK-versioner som fortfarande stöds kan fortfarande importera FoundryChatClient, men ett anrop till get_computer_tool() utlöser ett ImportError med vägledning om uppgradering.

get_computer_use_tool förblir tillgängligt för det separata API:et för förhandsgranskning av datoranvändning:

preview_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 med en projektslutpunkt när du vill ha textinbäddningar från en OpenAI-distribution i foundry-projektet.

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)

För bildinbäddningar konfigurerar du FOUNDRY_MODELS_ENDPOINT, FOUNDRY_MODELS_API_KEY och FOUNDRY_IMAGE_EMBEDDING_MODEL i stället. Kombinera inte projektslutpunktskonfiguration med modellslutpunktsargument eller klienter i samma FoundryEmbeddingClient.

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:

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.

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.

Nuvarande brister i Go

Go-supporten omfattar för närvarande inte Foundry-hanterade API:er för distribution, livscykelhantering och administration, klienter för inbäddningar eller Go-specifika hjälpfunktioner för Microsoft Foundry Toolbox. Använd Foundry-portalen eller tjänst-SDK:er för dessa åtgärder.