Provider di modelli Microsoft Foundry

Microsoft Agent Framework supporta l'inferenza diretta del modello dagli endpoint del progetto Foundry Microsoft mentre l'applicazione è proprietaria della definizione, degli strumenti e dell'orchestrazione dell'agente.

Per gli agenti prompt e ospitati gestiti dal servizio, vedere Servizio agenti Foundry Microsoft.

Come iniziare

Aggiungere i pacchetti NuGet necessari al progetto.

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

Due modelli di integrazione

L'integrazione di Microsoft Foundry espone due modelli di utilizzo distinti:

Modello	Tipo prodotto	Descrizione	Usa quando
Agente di Risposte	ChatClientAgent	L'app fornisce a livello di codice un modello, istruzioni e strumenti in fase di esecuzione tramite AIProjectClient.AsAIAgent(...). Non viene creata alcuna risorsa agente sul lato server.	Si è proprietari della definizione dell'agente e si vuole una configurazione semplice e flessibile. Questo è il modello usato nella maggior parte degli esempi.
Agente Foundry (prompt o ospitato)	FoundryAgent	Gestiti dal server — i Prompt Agents sono definizioni con nome e versione; gli Hosted Agents sono applicazioni distribuite raggiungibili tramite un endpoint specifico per l'agente.	Foundry è proprietario della definizione dell'agente o del runtime ospitato. Vedere Microsoft Foundry Agent Service.

Agente di Risposte (inferenza diretta)

Usare direttamente AsAIAgent su AIProjectClient con un modello e delle istruzioni. Questo è il punto di partenza consigliato per la maggior parte degli scenari.

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

Avvertimento

DefaultAzureCredential è utile per lo sviluppo, ma richiede un'attenta considerazione nell'ambiente di produzione. Nell'ambiente di produzione prendere in considerazione l'uso di credenziali specifiche ,ad esempio ManagedIdentityCredential, per evitare problemi di latenza, probe di credenziali indesiderate e potenziali rischi per la sicurezza dai meccanismi di fallback.

Questo percorso è code-first e non crea una risorsa agente gestita dal server.

Uso dell'agente

L'agente risposte è uno standard AIAgent e supporta sessioni, strumenti, middleware e 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));

Per altre informazioni su come eseguire e interagire con gli agenti, vedere le esercitazioni introduttive su Agent.

Tools

Gli agenti Foundry Responses creati a partire da AIProjectClient.AsAIAgent(...) supportano l'interfaccia degli strumenti standard di Agent Framework. Vedere la panoramica degli strumenti per la matrice di funzionalità completa.

Tool	Notes
Strumenti per le funzioni	Supportato.
Approvazione degli strumenti	Supportato. Fornito dal client di chat con invocazione di funzioni del framework.
Interprete di codice	Supportato.
Ricerca file	Supportato.
Strumenti MCP ospitati	Supportato.
Strumenti MCP locali	Supportato.
Casella degli strumenti Microsoft Foundry	Supportato.

Fonderia in Python

In Python tutti i client specifici di Foundry ora si trovano in agent_framework.foundry.

• agent-framework-foundry fornisce i connettori cloud Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingCliente FoundryMemoryProvider.
• agent-framework-foundry-local fornisce FoundryLocalClient per l'esecuzione del modello locale.

Importante

Questa pagina descrive gli endpoint dei progetti e dei modelli di Microsoft Foundry. Per informazioni su Foundry Agent Service, vedere Microsoft Foundry Agent Service. Se si dispone di un endpoint di risorsa OpenAI di Azure autonomo (https://<your-resource>.openai.azure.com), usare le linee guida per Python nella pagina del provider OpenAI. Per eseguire modelli supportati in locale, vedere la Pagina del Provider Locale di Foundry.

Modelli di chat e agenti di Foundry in Python

Scenario	Struttura di Python	Usa quando
Inferenza semplice con l'endpoint Foundry Responses	Agent(client=FoundryChatClient(...))	L'app è proprietaria della definizione dell'agente, degli strumenti e del ciclo di conversazione e si vuole distribuire un modello in un progetto Foundry.
Agenti gestiti dal Servizio agenti Foundry	FoundryAgent(...)	Si vuole connettersi a un PromptAgent o HostedAgent creato e configurato nel portale foundry o tramite le API del servizio.

Installation

pip install agent-framework-foundry

Lo stesso pacchetto agent-framework-foundry include anche FoundryEmbeddingClient per gli incorporamenti dell'endpoint dei modelli Foundry.

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 usa l'endpoint del progetto. FoundryEmbeddingClient usa l'endpoint dei modelli separato.

Scegliere il client Python appropriato

Scenario	Client preferito	Notes
Risorsa OpenAI di Azure	OpenAIChatCompletionClient / OpenAIChatClient	Utilizzare la pagina del provider OpenAI.
inferenza del progetto Foundry Microsoft	Agent(client=FoundryChatClient(...))	Usa l'endpoint Foundry Responses.
Agente gestito dal servizio Microsoft Foundry	FoundryAgent	Consigliato per gli agenti prompt e HostedAgents.
Incorporamenti dell'endpoint dei modelli Microsoft Foundry	FoundryEmbeddingClient	Usa FOUNDRY_MODELS_ENDPOINT più FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Runtime locale di Foundry	Agent(client=FoundryLocalClient(...))	Vedere Foundry Local.

Creare un agente con FoundryChatClient

FoundryChatClient si connette a un modello distribuito in un progetto Foundry e usa l'endpoint Risposte. Associarlo a uno standard Agent quando l'app deve possedere istruzioni, strumenti e gestione delle sessioni.

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 è il percorso di Python Foundry-first per l'inferenza diretta e supporta strumenti, output strutturati e streaming.

Riutilizzare il client contemporaneamente

Un'istanza FoundryChatClient può gestire chiamate asincrone concorrenti sullo stesso ciclo di eventi, incluse chiamate in streaming e non in streaming sovrapposte.

Creare un oggetto separato Agent e AgentSession per ogni esecuzione simultanea e passare messaggi e opzioni separati. Anche il middleware, gli strumenti e i callback forniti dall'utente devono supportare la concorrenza. Non condividere il client tra thread del sistema operativo o cicli di eventi o modificarne la configurazione mentre le chiamate sono attive.

Acconsentire esplicitamente al ragionamento crittografato

FoundryChatClient non richiede reasoning.encrypted_content per impostazione predefinita. Questa impostazione predefinita impedisce gli errori delle richieste nei modelli che non supportano il ragionamento crittografato.

Per una distribuzione compatibile, attiva l'opzione tramite le opzioni predefinite dell'agente:

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="<reasoning-model-deployment>",
        credential=AzureCliCredential(),
    ),
    default_options={"include": ["reasoning.encrypted_content"]},
)

Tools

FoundryChatClient fornisce metodi di fabbrica statici per ogni strumento Foundry ospitato. Le factory restituiscono oggetti strumento dell'SDK da passare a tools= in Agent o direttamente a client.get_response(..., tools=[...]). Per gli strumenti per agenti gestiti dal servizio, vedere Microsoft Foundry Agent Service.

Le factory sono metodi di classe, quindi non è necessaria un'istanza per creare uno strumento:

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

Supporto degli strumenti

La tabella seguente elenca ogni strumento esposto da Python FoundryChatClient.

Tool	Factory in FoundryChatClient	Condizione	Detail
Strumenti per le funzioni	N/D: passare qualsiasi callable Python o @ai_function	GA	Richiamato localmente nel processo di Python.
Approvazione degli strumenti	n/a — incapsula gli strumenti esistenti	GA	Funziona con MCP ospitato e strumenti funzione.
Interprete di codice	get_code_interpreter_tool	GA	Esecuzione di codice in modalità sandbox in Foundry.
Ricerca file	get_file_search_tool	GA	Cerca i file caricati nei vector store di Foundry.
Ricerca Web	get_web_search_tool	GA	Web grounding basato su Bing e gestito da Microsoft. Solo modelli Azure OpenAI.
Generazione di immagini	get_image_generation_tool	GA	Generazione di immagini ospitata in Foundry.
MCP ospitato	get_mcp_tool	GA	Server MCP remoto richiamato da Foundry.
McP locale	n/a - usare MCPStreamableHTTPTool / MCPStdioTool	GA	Viene eseguito all'interno del processo dell'applicazione; funziona con qualsiasi client.
Casella degli strumenti Microsoft Foundry	MCPStreamableHTTPTool oppure FoundryToolbox	Versione Beta	Utilizzato tramite MCP da FoundryChatClient; collegato lato server in FoundryAgent.
Grounding di Bing	get_bing_grounding_tool	Experimental	Usare una propria risorsa Grounding with Bing Search.
Ricerca personalizzata Bing	get_bing_custom_search_tool	Anteprima	Ancoraggio di Bing limitato a un elenco selezionato di domini.
Ricerca di intelligenza artificiale di Azure	get_azure_ai_search_tool	Experimental	Cercare un indice Azure AI Search tramite una connessione Foundry.
SharePoint	get_sharepoint_tool	Anteprima	Risposte di base nel contenuto SharePoint.
Microsoft Fabric	get_fabric_tool	Anteprima	Eseguire query su un agente dati di Fabric.
Ricerca memoria	get_memory_search_tool	Anteprima	Cercare un archivio di memoria gestito da Foundry.
Uso del computer	get_computer_use_tool	Anteprima	Consentire all'agente di guidare un ambiente desktop o browser.
Automazione del browser	get_browser_automation_tool	Anteprima	Controllare un browser tramite una connessione Playwright di Azure.
Da agente a agente (A2A)	get_a2a_tool	Anteprima	Chiama un altro agente A2A come strumento.

Annotazioni

Le factory sperimentali eseguono il wrapping dei tipi dell'SDK Foundry disponibili a livello generale, ma i wrapper possono cambiare prima della disponibilità generale. Le factory di anteprima incapsulano i tipi dell'SDK Foundry la cui funzionalità sottostante è in anteprima e può cambiare o essere rimossa. Entrambe generano una ExperimentalWarning prima volta che vengono usate in un processo.

Varianti di ricerca Web

Foundry offre tre opzioni di grounding basate su Bing. Selezionare quello che corrisponde allo scenario:

• get_web_search_tool (GA) — impostazione predefinita che non richiede configurazione; risorsa Bing gestita da Microsoft. Solo modelli Azure OpenAI. Limitato a user_location e search_context_size.
• get_bing_grounding_tool (sperimentale): usare una propria risorsa Azure Grounding with Bing Search. Supporta count, freshness, market, set_lang e i modelli non OpenAI Foundry.
• get_bing_custom_search_tool (anteprima): usare una propria istanza di Ricerca personalizzata Bing per limitare il grounding a un set selezionato di domini.

Tutti e tre inviano i dati di ricerca all'esterno del limite di conformità Azure. Per il confronto completo, vedere la panoramica del grounding 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",
)

Creazione di immagini

get_image_generation_tool configura lo strumento ospitato di Foundry per la generazione di immagini. Il modello produce contenuto immagine nella risposta, senza file aggiuntivi da gestire.

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

Grounding Bing

get_bing_grounding_tool esegue il wrapping dello strumento Foundry Grounding with Bing Search. Crei manualmente la risorsa Grounding with Bing Search e la aggiungi come connessione del progetto Foundry, quindi passi l'ID della connessione.

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

Ricerca personalizzata Bing

get_bing_custom_search_tool limita il grounding all'elenco consentiti definito in una risorsa Ricerca personalizzata Bing.

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

Ricerca di intelligenza artificiale di Azure

get_azure_ai_search_tool consente all'agente di eseguire una query su un indice Azure AI Search tramite una connessione di progetto 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 basa le risposte sul contenuto di SharePoint accessibile tramite una connessione SharePoint di Foundry.

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

Microsoft Fabric

get_fabric_tool connette l'agente a un agente dati Microsoft Fabric tramite una connessione Foundry in modo che l'agente possa rispondere alle domande sui dati Fabric.

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

Ricerca di memoria

get_memory_search_tool consente all'agente di cercare un archivio di memoria gestito da Foundry, con ambito facoltativo per un utente o un tenant.

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

Utilizzo del computer

get_computer_use_tool configura lo strumento Computer Use in anteprima: il modello può controllare un ambiente desktop o browser inviando azioni del puntatore e della tastiera.

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

Automazione del browser

get_browser_automation_tool collega l'agente a una risorsa di Azure Playwright Testing tramite una connessione Foundry. L'agente può guidare un browser reale tramite Playwright.

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

Agente-a-Agente (A2A)

get_a2a_tool espone un agente A2A remoto come strumento affinché un agente Foundry possa chiamarlo. Specificare un base_url (e facoltativamente un agent_card_path) oppure un project_connection_id per una connessione A2A archiviata.

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

Per indicazioni generali sul rilevamento A2A, le sessioni e lo streaming, consulta il servizio agent A2A.

Creare incorporamenti con FoundryEmbeddingClient

Usare FoundryEmbeddingClient quando si vogliono incorporare testo o immagini da un endpoint dei modelli 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)

Uso dell'agente

FoundryChatClient si integra con l'esperienza Python Agent standard, incluse le chiamate agli strumenti, le sessioni e le risposte in streaming. Per i runtime locali, utilizzare la pagina separata del provider locale Foundry.

Per i pacchetti con nome e versionati delle configurazioni degli strumenti ospitati, vedere Microsoft Foundry Toolbox.

Foundry in Go

L'SDK Go fornisce gli agenti Microsoft Foundry tramite github.com/microsoft/agent-framework-go/provider/foundryprovider.

Vedi gli esempi di Foundry Go per l'inferenza diretta, gli strumenti funzionali, gli strumenti ospitati, MCP e gli esempi di server-agent.

Il pacchetto supporta due target dell'agente:

Target	Struttura Go	Usa quando
distribuzione del modello supportata da Project	foundryprovider.ModelDeployment("gpt-4o-mini")	L'app è proprietaria di istruzioni, strumenti e flusso di conversazione.
Agente Foundry lato server esistente	foundryprovider.ServerAgent("my-agent")	La definizione dell'agente è già configurata in Foundry.

Configuration

Impostare l'endpoint del progetto Foundry e la distribuzione del modello:

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

Agente Foundry supportato da un progetto

Usare ModelDeployment quando si vuole creare un agente di Agent Framework nel codice e passare istruzioni, strumenti, middleware e provider di contesto dall'applicazione 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()

Agente Foundry lato server esistente

Usare ServerAgent quando si vuole richiamare un agente già configurato in Foundry. L'agente lato server è proprietario delle istruzioni e degli strumenti, quindi AgentConfig.Instructions viene ignorato per questa destinazione.

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

Gli agenti Foundry supportati dal progetto supportano l'interfaccia standard degli strumenti del Go Agent Framework per gli strumenti locali e per le dichiarazioni supportate degli strumenti ospitati.

Tool	Condizione	Notes
Strumenti per le funzioni	Supportato	Le funzioni vengono eseguite all'interno del processo Go.
Approvazione degli strumenti	Supportato	Funziona con strumenti per funzioni locali tramite il ciclo di chiamata automatica degli strumenti.
Interprete di codice	Supportato	Utilizzare il &hostedtool.CodeInterpreter{}.
Ricerca Web	Supportato	Utilizzare il &hostedtool.WebSearch{}.
Strumenti MCP locali	Supportato	Usare tool/mcptool per connettersi a un server MCP ed esporre i relativi strumenti in locale.
Strumenti MCP ospitati	Non attualmente documentato per Go Foundry	Usare gli strumenti MCP locali quando sono necessari server MCP con agenti Go Foundry.
Casella degli strumenti Microsoft Foundry	Attualmente non esposto tramite un helper Go.

Per gli strumenti funzione locali, aggiungere valori tool.Tool tramite 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},
        },
    },
)

Per l'esecuzione del codice ospitato, passare la dichiarazione dello strumento ospitato:

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

Header del client e modello fornito

Foundry accetta x-client-* intestazioni per esecuzione. Aggiungerli con foundryprovider.WithClientHeader o foundryprovider.WithClientHeaders:

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

Quando Foundry restituisce l'intestazione di risposta x-ms-served-model, il provider Go la aggiunge alle proprietà aggiuntive della risposta/dell'aggiornamento come ServedModel.

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

Fornitore di memoria Foundry

Usare foundryprovider.NewMemoryProvider quando si vuole che un agente di Agent Framework recuperi e aggiorni un archivio di memoria gestito da Foundry in ogni esecuzione.

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

L'endpoint deve essere un endpoint Microsoft Foundry con ambito di progetto e l'archivio di memoria deve già esistere in quel progetto. Il callback dell'ambito deve restituire una chiave di partizione stabile per l'utente, il tenant o la conversazione.

Tip

Vedere l'esempio di Foundry memory Go per un esempio eseguibile completo.

Lacune attuali di Go

Il supporto di Go non include attualmente le API di distribuzione, ciclo di vita e amministrazione ospitate da Foundry, i client per embeddings o helper specifici di Go per Microsoft Foundry Toolbox. Usare il portale di Foundry o gli SDK del servizio per tali operazioni.

Passaggi successivi

Foundry Local