Microsoft Foundry

Come iniziare

Aggiungere i pacchetti NuGet necessari al progetto.

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

Due tipi di agente

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

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

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

Agente Foundry (con versione)

Usare le API native AIProjectClient.AgentAdministrationClient di AI Projects SDK per recuperare le risorse dell'agente con versione e quindi eseguirne il wrapping con AsAIAgent. Gli agenti possono essere creati e configurati direttamente nel portale di Foundry o a livello di codice tramite AIProjectClient.AgentAdministrationClient.

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

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

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

Uso dell'agente

Sia ChatClientAgent (risposte) che FoundryAgent (versionato) sono istanze standard di AIAgent e supportano tutte le operazioni standard, comprese 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.

Cassette degli attrezzi

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.

Modelli di chat e agenti di fonderia in Python

Installazione

pip install agent-framework-foundry
pip install azure-identity

Lo stesso agent-framework-foundry pacchetto include anche gli incorporamenti degli endpoint dei modelli Foundry.

Configurazione

FoundryChatClient

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

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Usare FOUNDRY_AGENT_VERSION per gli agenti di prompt. Gli agenti ospitati possono ometterlo.

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 e FoundryAgent utilizzano l'endpoint del progetto. FoundryEmbeddingClient usa l'endpoint dei modelli separati.

Scegliere il client di Python corretto

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.

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)

connettersi all'agente gestito dal servizio con FoundryAgent

Usare FoundryAgent quando la definizione dell'agente risiede in Foundry. Si tratta dell'API consigliata di Python per gli agenti prompt e gli HostedAgents.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

Per HostedAgent, omettere agent_version e usare invece il nome dell'agente ospitato.

Connessione a un agente Foundry distribuito

Per HostedAgents che eseguono sessioni sul lato servizio (/agents/{name}/sessions), usare FoundryAgent con allow_preview=True per abilitare l'area di visualizzazione delle risposte in anteprima e passare version="v2":

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
    version="v2",
)

Quando è necessario gestire manualmente la sessione del servizio sottostante, ad esempio per associare una sessione a un tenant o a un utente specifico, creare la sessione tramite l'API di anteprima AIProjectClient ed eseguire il wrapping con agent.get_session(...):

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Uso dell'agente

Sia FoundryChatClient che FoundryAgent si integrano con l'esperienza standard Python Agent, incluse le chiamate degli strumenti, le sessioni e le risposte di streaming. Per i runtime locali, utilizzare la pagina separata del provider locale Foundry.

Cassette degli attrezzi

Una casella degli strumenti Foundry è un pacchetto lato server, con nome e versione, di configurazioni di strumenti ospitati (interprete di codice, ricerca file, generazione immagini, MCP, ricerca web) configurato in un progetto Microsoft Foundry. Le caselle degli strumenti consentono di gestire la configurazione degli strumenti una sola volta nel portale foundry e di riutilizzarla tra gli agenti.

Agent Framework copre solo il consumo: la creazione e l'aggiornamento delle versioni della toolbox vengono eseguite tramite il portale Foundry o l'SDK non elaborato azure-ai-projects (azure-ai-projects>=2.1.0).

FoundryAgent vs FoundryChatClient

Due modelli di consumo

Prendere una cassetta degli attrezzi

Utilizzare FoundryChatClient.get_toolbox() per recuperare una cassetta degli attrezzi:

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

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

Quando version viene omesso, get_toolbox risolve la versione predefinita in due richieste. Aggiungere una versione specifica per evitare il round trip aggiuntivo:

toolbox = await client.get_toolbox("research_toolbox", version="v3")

Appiattimento implicito

Non è necessario scrivere toolbox.tools. Il framework normalize_tools riconosce ToolboxVersionObject e si appiattisce automaticamente. Tutte queste operazioni:

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

Strumenti di filtro con select_toolbox_tools

Se la casella degli strumenti aggrega diversi strumenti, ma un agente richiede solo un subset, usare select_toolbox_tools per restringere il set dopo il recupero. In questo modo si evita di inviare definizioni di strumenti non necessarie al modello, riducendo l'utilizzo dei token e impedendo al modello di richiamare gli strumenti che non si intende esporre:

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

Le funzioni di supporto get_toolbox_tool_name(tool) e get_toolbox_tool_type(tool) restituiscono rispettivamente il nome della selezione e il tipo grezzo di una voce dello strumento. FoundryHostedToolType è un TypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str) per il completamento guidato dall'IDE su include_types / exclude_types.

Percorso di utilizzo MCP

È anche possibile utilizzare una casella degli strumenti come server MCP puntando MCPStreamableHTTPTool all'URL dell'endpoint MCP della casella degli strumenti.

L'URL dell'endpoint MCP viene visualizzato nel portale di Foundry o segue il formato:

https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1

Poiché il client si connette direttamente all'endpoint del Foundry toolbox, è necessario eseguire l'autenticazione con un token portatore dell'ID Entra tramite header_provider:

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Limitazioni

• Gli strumenti MCP all'interno di una casella degli strumenti usano l'autenticazione lato server. L'autenticazione al server MCP upstream viene gestita tramite project_connection_id (una connessione OAuth configurata nel progetto Foundry). Il client non contiene mai token di accesso per il server upstream.
• L'utilizzo di una casella degli strumenti come server MCP richiede l'autenticazione lato client. Quando si punta MCPStreamableHTTPTool all'endpoint MCP di una casella degli strumenti, è necessario specificare un bearer token dell'ID Entra (ad esempio, tramite get_bearer_token_provider(credential, "https://ai.azure.com/.default")) attraverso header_provider.
• La gestione del flusso di consenso è un problema di runtime. Se uno strumento MCP della casella degli strumenti viene attivato CONSENT_REQUIRED durante agent.run(), viene gestito in fase di esecuzione, non durante il recupero della casella degli strumenti.

Esempi