provider di modelli foundry Microsoft

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 i prompt gestiti dal servizio e gli agenti ospitati, vedere Microsoft servizio agente Foundry.

Getting Started

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:

Pattern Tipo prodotto Description 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 Gestito dal server: gli agenti prompt sono definizioni denominate e con controllo delle versioni; Gli agenti ospitati vengono distribuite applicazioni raggiunte tramite un endpoint specifico dell'agente. Foundry è proprietario della definizione dell'agente o del runtime ospitato. Vedere Microsoft servizio agente Foundry.

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

Agenti risposte foundry creati da AIProjectClient.AsAIAgent(...) supportano la superficie degli strumenti standard di Agent Framework. Vedere la panoramica degli strumenti per la matrice di funzionalità completa.

Strumento Note
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 illustra Microsoft endpoint del progetto Foundry e dei modelli. Per il servizio agente Foundry, vedere Microsoft servizio agente Foundry. 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
Semplice inferenza con l'endpoint delle risposte Foundry 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 Foundry Agent 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 agent-framework-foundry pacchetto include anche gli incorporamenti degli 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 separati.

Scegliere il client Python appropriato

Scenario Client preferito Note
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 gli agenti ospitati.
Embedding degli endpoint dei modelli di 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.

Tools

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

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.

Strumento Factory su FoundryChatClient Condizione Detail
Strumenti per le funzioni n/a — passare un qualsiasi oggetto richiamabile Python o @ai_function GA Richiamato localmente nel processo di Python.
Approvazione degli strumenti n/a — incapsula gli strumenti esistenti GA Funziona con mcp ospitati e strumenti per le funzioni.
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 gestito 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 o FoundryToolbox Versione Beta Utilizzato tramite MCP da FoundryChatClient; collegato lato server su FoundryAgent.
Fondamenti di Bing get_bing_grounding_tool Experimental Bring Your Own Grounding con la risorsa Ricerca Bing.
Ricerca personalizzata Bing get_bing_custom_search_tool Preview 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 Preview Risposte di base nel contenuto SharePoint.
Microsoft Fabric get_fabric_tool Preview Interrogare un agente dati di Fabric.
Ricerca memoria get_memory_search_tool Preview Cercare un archivio di memoria gestito da Foundry.
Uso del computer get_computer_use_tool Preview Consentire all'agente di guidare un ambiente desktop o browser.
Automazione del browser get_browser_automation_tool Preview Controllare un browser tramite una connessione Playwright di Azure.
Da agente a agente (A2A) get_a2a_tool Preview Chiama un altro agente A2A come strumento.

Annotazioni

Le factory sperimentali fungono da wrapper per i tipi dell'SDK di GA Foundry, ma i wrapper stessi potrebbero cambiare prima della disponibilità generale (GA). 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) — usa la tua risorsa Azure Grounding with Bing Search. Supporta count, freshness, market, set_lang e i modelli non OpenAI Foundry.
  • get_bing_custom_search_tool (anteprima) — usa una tua istanza di Bing Custom Search per limitare il grounding a un insieme 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 web grounding .

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

Ancoraggio con Bing

get_bing_grounding_tool funge da wrapper per lo strumento Grounding con Bing Search di Foundry. 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,
)

get_bing_custom_search_tool limita la base all'elenco elementi 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",
)

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

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 di anteprima Uso del computer: il modello può interagire con un ambiente desktop o browser tramite 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 in modo che 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 sull'individuazione, le sessioni e lo streaming A2A, vedere il servizio agente 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

FoundryChatClientsi integra con l'esperienza di Python Agent standard, tra cui chiamate, sessioni e risposte di streaming degli strumenti. Per i runtime locali, utilizzare la pagina separata del provider locale Foundry.

Per i bundle denominati e con controllo delle versioni delle configurazioni degli strumenti ospitati, vedere Microsoft Casella degli strumenti Foundry.

Foundry in Go

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

Vedere gli esempi di Foundry Go per inferenza diretta, strumenti di funzione, strumenti ospitati, MCP ed esempi di agente server.

Il pacchetto supporta due target dell'agente:

Target Vai alla forma 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 sul 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 Project

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

Strumento Condizione Note
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 Non attualmente esposto tramite un helper Go.

Per gli strumenti di funzione locali, aggiungere tool.Tool valori 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 di ambito deve restituire una chiave di partizione stabile dell'utente, del tenant o della conversazione.

Suggerimento

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

Lacune attuali di Go

Il supporto di Go non include attualmente api di distribuzione/ciclo di vita/amministrazione ospitate in Foundry, client di incorporamenti o helper specifici di Go per Microsoft Casella degli strumenti Foundry. Usare il portale di Foundry o gli SDK del servizio per tali operazioni.

Passaggi successivi

Foundry Local

  • Last updated on