Microsoft Foundry-modelprovider

Microsoft Agent Framework ondersteunt directe modeldeductie van Microsoft Foundry-projecteindpunten, terwijl uw toepassing eigenaar is van de agentdefinitie, hulpprogramma's en indeling.

Zie Microsoft Foundry Agent-service voor door de service beheerde prompts en gehoste agents.

Getting Started

Voeg de vereiste NuGet-pakketten toe aan uw project.

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

Twee integratiepatronen

De integratie van Microsoft Foundry toont twee verschillende gebruikspatronen:

Pattern	Geproduceerd type	Description	Wanneer gebruiken
Antwoordagent	ChatClientAgent	Uw app levert programmatisch een model, instructies en hulpprogramma's tijdens uitvoeringstijd via AIProjectClient.AsAIAgent(...). Er wordt geen agent-resource aan de serverzijde aangemaakt.	U bent de eigenaar van de agentdefinitie en wilt een eenvoudige, flexibele installatie. Dit is het patroon dat in de meeste voorbeelden wordt gebruikt.
Foundry Agent (prompt of gehost)	FoundryAgent	Door de server beheerd : promptagenten hebben een naam en versiedefinities; Gehoste agents zijn geïmplementeerde toepassingen die zijn bereikt via een agentspecifiek eindpunt.	Foundry is eigenaar van de agentdefinitie of gehoste runtime. Zie Microsoft Foundry Agent Service.

Antwoordagent (directe deductie)

Gebruik AsAIAgent op AIProjectClient rechtstreeks met een model en instructies. Dit is het aanbevolen uitgangspunt voor de meeste scenario's.

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 is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. Overweeg in productie een specifieke referentie te gebruiken (bijvoorbeeld ManagedIdentityCredential) om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

Dit pad is 'code-first' en creëert geen server-beheerde agentresource.

De agent gebruiken

De Response Agent is een standaard AIAgent en ondersteunt sessies, hulpprogramma's, middleware en streaming.

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

Voor meer informatie over hoe je agents uitvoert en ermee werkt, raadpleeg de Aan de slag met agent-tutorials.

Gereedschappen

Foundry Response Agents die zijn gemaakt op basis van de ondersteuning van AIProjectClient.AsAIAgent(...) het standaardhulpprogramma voor Agent Framework. Zie het overzicht van extra's voor de volledige functiematrix.

Tool	Aantekeningen
Functiehulpmiddelen	Supported.
Goedkeuring van hulpprogramma	Supported. Geleverd door de chatclient van het framework voor het aanroepen van functies.
Code-interpreter	Supported.
Zoeken naar bestanden	Supported.
Gehoste MCP-tools	Supported.
Lokale MCP-hulpprogramma's	Supported.
Microsoft Foundry Toolbox	Supported.

Gieterij in Python

In Python leven alle Foundry-specifieke clients nu onder agent_framework.foundry.

• agent-framework-foundry biedt de Cloud Foundry-connectors: FoundryChatClient, FoundryAgent, FoundryEmbeddingClient, en FoundryMemoryProvider.
• agent-framework-foundry-local biedt FoundryLocalClient voor de uitvoering van een lokaal model.

Important

Op deze pagina worden Microsoft Foundry-project- en modeleindpunten beschreven. Zie Microsoft Foundry Agent Service voor de Foundry-agent voor de foundry-service. Als u een zelfstandig Azure OpenAI-resource-eindpunt (https://<your-resource>.openai.azure.com) hebt, gebruikt u de Python-richtlijnen op de pagina van de OpenAI-provider. Als u ondersteunde modellen lokaal wilt uitvoeren, raadpleegt u de pagina Foundry Local Provider.

Foundry-chat- en agentpatronen in Python

Scenario	Pythonvorm	Wanneer gebruiken
Eenvoudige inferentie met het eindpunt van Foundry-antwoorden	Agent(client=FoundryChatClient(...))	Uw app is eigenaar van de agentdefinitie, hulpprogramma's en gesprekslus en u wilt een model dat is geïmplementeerd in een Foundry-project.
Agents beheerd door de service in de Foundry Agent-service	FoundryAgent(...)	U wilt verbinding maken met een PromptAgent of HostedAgent die is gemaakt en geconfigureerd in de Foundry-portal of via de service-API's.

Installatie

pip install agent-framework-foundry

Hetzelfde agent-framework-foundry pakket omvat FoundryEmbeddingClient ook voor Foundry-modellen-eindpunten insluiten.

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 maakt gebruik van het projecteindpunt. FoundryEmbeddingClient maakt gebruik van het eindpunt voor afzonderlijke modellen.

De juiste Python-client kiezen

Scenario	Voorkeursklant	Aantekeningen
Azure OpenAI-resource	OpenAIChatCompletionClient / OpenAIChatClient	Gebruik de openAI-providerpagina.
Microsoft Foundry-projectinferentie	Agent(client=FoundryChatClient(...))	Maakt gebruik van het API-eindpunt voor Foundry-antwoorden.
Microsoft Foundry-servicebeheerde agent	FoundryAgent	Aanbevolen voor Prompt Agents en HostedAgents.
Microsoft Foundry-modellen-eindpuntembeddings	FoundryEmbeddingClient	Gebruikt FOUNDRY_MODELS_ENDPOINT plus FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Foundry Local Runtime	Agent(client=FoundryLocalClient(...))	Zie Foundry Local.

Een agent maken met FoundryChatClient

FoundryChatClient maakt verbinding met een geïmplementeerd model in een Foundry-project en maakt gebruik van het eindpunt Antwoorden. Koppel deze aan een standaard Agent wanneer uw app eigenaar moet zijn van instructies, hulpprogramma's en sessieafhandeling.

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 is het Foundry-first-Python-pad voor directe deductie en ondersteunt hulpprogramma's, gestructureerde uitvoer en streaming.

Gereedschappen

FoundryChatClient bevat statische fabrieksmethoden voor elke gehoste Foundry-tool. De factories retourneren SDK-toolobjecten die u doorgeeft aan tools= op Agent of rechtstreeks aan client.get_response(..., tools=[...]). Zie Microsoft Foundry Agent Service voor servicebeheer.

De factory's zijn klassemethoden, dus u hebt geen exemplaar nodig om een hulpprogramma te maken:

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

Ondersteuning voor hulpmiddelen

In de onderstaande tabel ziet u elk hulpprogramma dat de Python FoundryChatClient vandaag beschikbaar maakt.

Tool	Fabriek op FoundryChatClient	Status	Detail
Functiehulpmiddelen	n/a — geef alle Python aanroepbare of @ai_function door	GA	Lokaal aangeroepen in uw Python proces.
Goedkeuring van hulpprogramma	n/a — verpakt bestaande hulpprogramma's	GA	Werkt met gehoste MCP- en functiehulpprogramma's.
Code-interpreter	get_code_interpreter_tool	GA	Uitvoering van code in sandbox op Foundry.
Zoeken naar bestanden	get_file_search_tool	GA	Zoek geüploade bestanden via Foundry vector stores.
Zoeken op internet	get_web_search_tool	GA	Webverankering met Bing-ondersteuning, beheerd door Microsoft. Alleen Azure OpenAI-modellen.
Beeldgeneratie	get_image_generation_tool	GA	Afbeeldingen genereren gehost op Foundry.
Gehoste MCP	get_mcp_tool	GA	Externe MCP-server die wordt aangeroepen door Foundry.
Lokaal MCP	n/a — gebruik MCPStreamableHTTPTool / MCPStdioTool	GA	Wordt uitgevoerd in uw proces; werkt met elke client.
Microsoft Foundry Toolbox	MCPStreamableHTTPTool of FoundryToolbox	Bèta	Verbruikt via MCP van FoundryChatClient; gekoppelde serverzijde aan FoundryAgent.
Bing Aarding	get_bing_grounding_tool	Experimental	Bring-your-own Grounding met Bing Search-resource.
Bing Aangepaste Zoekopdracht	get_bing_custom_search_tool	Voorbeeld	Bing grounding beperkt tot een gecureerde domeinlijst.
Azure AI Zoeken	get_azure_ai_search_tool	Experimental	Een Azure AI Zoeken-index doorzoeken via een Foundry-verbinding.
SharePoint	get_sharepoint_tool	Voorbeeld	Basisantwoorden in SharePoint inhoud.
Microsoft Fabric	get_fabric_tool	Voorbeeld	Een query uitvoeren op een Fabric gegevensagent.
Geheugen zoeken	get_memory_search_tool	Voorbeeld	Zoek in een door Foundry beheerde geheugenopslag.
Computergebruik	get_computer_use_tool	Voorbeeld	Laat de agent een bureaublad- of browseromgeving aandrijven.
Browserautomatisering	get_browser_automation_tool	Voorbeeld	Bestuur een browser via een Azure Playwright-verbinding.
Agent-naar-agent (A2A)	get_a2a_tool	Voorbeeld	Gebruik een andere A2A-agent als tool.

Opmerking

Experimentele fabrieken omhullen GA Foundry SDK-typen, maar de wrappers zelf kunnen nog veranderen vóór GA. Preview-factory’s omvatten Foundry SDK-typen waarvan de onderliggende functionaliteit nog in preview is en kan worden gewijzigd of verwijderd. Beide verzenden een ExperimentalWarning eerste keer dat ze in een proces worden gebruikt.

Webzoekvarianten

Foundry biedt drie door Bing ondersteunde grounding-opties. Kies het scenario dat overeenkomt met uw scenario:

• get_web_search_tool (GA) — standaard zonder configuratie; door Microsoft beheerde Bing-resource. Alleen Azure OpenAI-modellen. Beperkt tot user_location en search_context_size.
• get_bing_grounding_tool (experimenteel) — gebruik uw eigen Grounding with Bing Search Azure-resource. Ondersteuntcount, freshness, , marketset_langen niet-OpenAI Foundry-modellen.
• get_bing_custom_search_tool (preview) — gebruik uw eigen Bing Custom Search-exemplaar om grounding te beperken tot een zorgvuldig samengestelde set domeinen.

Alle drie verzenden zoekgegevens buiten de Azure nalevingsgrens. Zie het web grounding-overzicht voor de volledige vergelijking.

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

Afbeeldingen genereren

get_image_generation_tool configureert de gehoste tool van Foundry voor het genereren van afbeeldingen. Het model produceert afbeeldingsinhoud in het antwoord. Er zijn geen extra bestanden om te beheren.

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

Bing-gronding

get_bing_grounding_tool omsluit de Grounding met de Bing Search Foundry-tool. U maakt zelf de Grounding-resource met Bing Search en voegt deze toe als een Foundry-projectverbinding en geeft vervolgens de verbindings-id door.

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

Bing Aangepaste zoekopdrachten

get_bing_custom_search_tool beperkt de aarding tot de acceptatielijst die is gedefinieerd in een Bing Custom Search-resource.

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

Azure AI Zoeken

get_azure_ai_search_tool kan de agent een query uitvoeren op een Azure AI Zoeken-index via een Foundry-projectverbinding.

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 baseert antwoorden op SharePoint-inhoud die toegankelijk is via een Foundry SharePoint-verbinding.

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

Microsoft Fabric

get_fabric_tool verbindt de agent met een Microsoft Fabric gegevensagent via een Foundry-verbinding, zodat de agent vragen over uw Fabric gegevens kan beantwoorden.

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

Geheugen zoeken

get_memory_search_tool hiermee kan de agent zoeken in een door Foundry beheerd geheugenarchief, optioneel beperkt tot een gebruiker of tenant.

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

Computergebruik

get_computer_use_tool configureert het hulpprogramma Computer use preview: het model kan een bureaublad- of browseromgeving aandrijven door aanwijzers en toetsenbordacties uit te geven.

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

Browserautomatisering

get_browser_automation_tool verbindt de agent met een Azure Playwright Testing-resource via een Foundry-verbinding. Een agent kan een echte browser aansturen via Playwright.

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

Agent-tot-Agent (A2A)

get_a2a_tool maakt een externe A2A-agent beschikbaar als een hulpprogramma, zodat een Foundry-agent deze kan aanroepen. Geef een base_url (en optioneel agent_card_path) of een project_connection_id voor een opgeslagen A2A-verbinding op.

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

Zie de A2A-agentservice voor algemene A2A-detectie, sessies en streamingrichtlijnen.

Insluitingen maken met FoundryEmbeddingClient

Gebruik FoundryEmbeddingClient wanneer u tekst- of afbeeldingsinbeddingen wilt insluiten vanuit een Foundry-modelendpoint.

from agent_framework.foundry import FoundryEmbeddingClient

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

De agent gebruiken

FoundryChatClientkan worden geïntegreerd met de standaardervaring voor PythonAgent, waaronder het aanroepen van hulpprogramma's, sessies en streamingreacties. Voor lokale runtimes gebruikt u de afzonderlijke Foundry Local Provider pagina.

Zie Microsoft Foundry Toolbox voor benoemde, geversiede bundels met gehoste hulpprogrammaconfiguraties.

Gieterij in Go

De Go SDK biedt Microsoft Foundry-agents viagithub.com/microsoft/agent-framework-go/provider/foundryprovider.

Zie de Foundry Go-voorbeelden voor directe deductie, functiehulpprogramma's, gehoste hulpprogramma's, MCP- en serveragentvoorbeelden.

Het pakket ondersteunt twee agentdoelen:

Target	Ga naar vorm	Wanneer gebruiken
Project-ondersteunde modelimplementatie	foundryprovider.ModelDeployment("gpt-4o-mini")	Uw app is eigenaar van instructies, hulpprogramma's en gespreksstroom.
Bestaande Foundry-agent aan de serverzijde	foundryprovider.ServerAgent("my-agent")	De agentdefinitie is al geconfigureerd in Foundry.

Configuration

Stel uw Foundry-projecteindpunt en -modelimplementatie in:

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

Projectondersteunde Foundry-agent

Gebruik ModelDeployment deze optie als u een Agent Framework-agent wilt maken in code en instructies, hulpprogramma's, middleware en contextproviders wilt doorgeven vanuit uw Go-toepassing.

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

Bestaande Foundry-agent aan de serverzijde

Gebruik ServerAgent deze optie als u een agent wilt aanroepen die al is geconfigureerd in Foundry. De agent aan de serverzijde is eigenaar van de instructies en hulpprogramma's, dus AgentConfig.Instructions wordt genegeerd voor dit doel.

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

Gereedschappen

Door projecten ondersteunde Foundry-agents ondersteunen de standaardtoolinterface van het Go Agent Framework voor lokale tools en ondersteunde declaraties van gehoste tools.

Tool	Status	Aantekeningen
Functiehulpmiddelen	Supported	Functies worden uitgevoerd in uw Go-proces.
Goedkeuring van hulpprogramma	Supported	Werkt met lokale functietools via de lus voor het automatisch aanroepen van tools.
Code-interpreter	Supported	Gebruik &hostedtool.CodeInterpreter{}.
Zoeken op internet	Supported	Gebruik &hostedtool.WebSearch{}.
Lokale MCP-hulpprogramma's	Supported	Gebruik tool/mcptool dit om verbinding te maken met een MCP-server en de bijbehorende hulpprogramma's lokaal beschikbaar te maken.
Gehoste MCP-tools	Momenteel niet gedocumenteerd voor Go Foundry	Gebruik lokale MCP-hulpprogramma's wanneer u MCP-servers nodig hebt met Go Foundry-agents.
Microsoft Foundry Toolbox	Momenteel niet weergegeven via een Go-helper.

Voor hulpprogramma's voor lokale functies voegt u waarden toe tool.Tool 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},
        },
    },
)

Voor het uitvoeren van gehoste code geeft u de declaratie van het gehoste hulpprogramma door:

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

Clientheaders en geleverd model

Foundry accepteert x-client-* headers per uitvoering. Voeg ze toe met foundryprovider.WithClientHeader of foundryprovider.WithClientHeaders:

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

Wanneer Foundry de responseheader x-ms-served-model retourneert, voegt de Go-provider deze als ServedModel toe aan de aanvullende eigenschappen voor response/update.

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

Foundry-geheugenprovider

Gebruik foundryprovider.NewMemoryProvider deze optie wanneer u wilt dat een Agent Framework-agent een door Foundry beheerd geheugenarchief ophaalt en bijwerkt rond elke uitvoering.

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

Het eindpunt moet een Microsoft Foundry-eindpunt met projectbereik zijn en de geheugenopslag moet al in dat project aanwezig zijn. De scope-callback moet een stabiele partitiesleutel voor een gebruiker, tenant of gesprek retourneren.

Tip

Zie het Go-voorbeeld van Foundry-geheugen voor een volledig voorbeeld dat kan worden uitgevoerd.

Huidige hiaten in Go

Go-ondersteuning bevat momenteel geen Foundry-gehoste implementatie-/levenscyclus-/beheerders-API's, insluitingen van clients of Go-specifieke helpers voor Microsoft Foundry Toolbox. Gebruik de Foundry-portal of service-SDK's voor deze bewerkingen.

Volgende stappen 

Foundry Local