Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Microsoft Agent Framework supporta sia l'inferenza diretta del modello dagli endpoint del progetto Microsoft Foundry che dagli agenti gestiti dal servizio Foundry Agent.
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:
| Tipo | Tipo prodotto | Descrizione | Usare 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 (con versione) | FoundryAgent |
Gestito dal server: le definizioni degli agenti vengono create e sottoposte a controllo delle versioni tramite il portale di Foundry o a livello di codice tramite AIProjectClient.AgentAdministrationClient. Passare un ProjectsAgentVersion o un ProjectsAgentRecord o un AgentReference a AIProjectClient.AsAIAgent(...). |
Sono necessarie definizioni dell'agente con controllo delle versioni rigorose gestite nel portale di Foundry tramite le API del servizio |
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."));
Avviso
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.
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."));
Importante
Gli strumenti e le istruzioni degli agenti Foundry seguono rigorosamente quelli con cui sono stati creati; il tentativo di modificare gli strumenti o le istruzioni durante l'esecuzione non è supportato.
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.
Tools
Gli agenti Foundry creati da AIProjectClient.AsAIAgent(...) (il percorso Responses) supportano il set standard di strumenti di Agent Framework — vedere la panoramica degli strumenti per l'elenco completo e la matrice delle funzionalità supportate. Per gli agenti Foundry caricati da una definizione di agente con versione (FoundryAgent), gli strumenti dell'agente appartengono alla definizione dell'agente Foundry e non al client.
| Strumento | Note |
|---|---|
| Strumenti per le funzioni | Supported. |
| Approvazione degli strumenti | Supported. Fornito dal client di chat con invocazione di funzioni del framework. |
| Interprete di codice | Supported. |
| Ricerca file | Supported. |
| Strumenti MCP ospitati | Supported. |
| Strumenti MCP locali | Supported. |
| Strumenti di fonderia | Supported. |
Cassette degli attrezzi
Note
La documentazione di Foundry Toolbox .NET sarà presto disponibile.
Fonderia in Python
In Python tutti i client specifici di Foundry ora si trovano in agent_framework.foundry.
-
agent-framework-foundryfornisce i connettori cloud Foundry:FoundryChatClient,FoundryAgent,FoundryEmbeddingClienteFoundryMemoryProvider. -
agent-framework-foundry-localfornisceFoundryLocalClientper l'esecuzione del modello locale.
Importante
Questa pagina descrive i client Python attualmente disponibili per gli endpoint del progetto Microsoft Foundry, gli endpoint dei modelli e il servizio agente Foundry. Se si dispone di un endpoint di risorsa OpenAI autonomo Azure (https://<your-resource>.openai.azure.com), usare le linee guida 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 fonderia in Python
| Scenario | Python forma | Usare 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. |
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
| Scenario | Client preferito | Note |
|---|---|---|
| Azure risorsa OpenAI | 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 FoundryAgent, gli strumenti dell'agente si trovano nella definizione dell'agente Foundry stesso. Vedere Cosa funziona e cosa non accade con FoundryAgent.
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.
FoundryAgent funziona con gli stessi strumenti, ma devono essere configurati nella definizione dell'agente Foundry anziché passare il codice.
| Strumento | Factory su FoundryChatClient |
Condizione | Dettagli |
|---|---|---|---|
| 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. |
| Caselle degli strumenti di Foundry |
MCPStreamableHTTPTool all'endpoint MCP della casella degli strumenti |
GA | 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 |
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 | Interrogare 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. |
Note
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 di Azure OpenAI. Limitato auser_locationesearch_context_size. -
get_bing_grounding_tool(sperimentale) — usa la tua risorsa Azure Grounding with Bing Search. Supportacount,freshness,market,set_lange 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,
)
Ricerca personalizzata Bing
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",
)
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 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 linee guida generali su A2A — rilevamento, sessioni, streaming — consulta la pagina del provider Agent-to-Agent.
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.
Cosa funziona e cosa non accade con FoundryAgent
FoundryAgent si connette a un agente già presente in Foundry (un Prompt Agent o un Hosted Agent). La definizione dell'agente, ovvero le istruzioni e la configurazione dello strumento, si trova in Foundry, non nel codice Python. Ciò significa che diverse funzionalità di livello Agent si comportano in modo diverso rispetto a quanto avviene con Agent(client=FoundryChatClient(...)) o con altri agenti basati su chat client.
Tools
Tipo di strumento passato a FoundryAgent(...) |
Behavior |
|---|---|
FunctionTool (un Python locale chiamabile) |
Supportato, ma solo se la definizione di funzione corrispondente esiste già nell'agente Foundry. Il runtime Foundry decide quali strumenti esporre al modello in base alla definizione dell'agente. Quando il modello chiama una funzione, Foundry restituisce una chiamata di strumento al client e il framework invoca il callable Python locale nel tuo processo (non in Foundry), quindi rimanda il risultato al client. Passare semplicemente un FunctionTool sul lato client mette solo a disposizione quell’implementazione locale: se la funzione non è dichiarata nell’agente Foundry, il modello non la chiamerà mai. |
| Strumenti ospitati (ricerca Web, interprete del codice, ricerca di file, MCP, generazione di immagini e così via) | Ignorato. Questi devono essere configurati nella definizione dell'agente Foundry stessa, nel portale foundry o tramite le API del servizio. Il passaggio sul lato client non ha alcun effetto perché il runtime foundry conosce solo gli strumenti associati alla definizione dell'agente. |
In breve: non è possibile aggiungere nuovi strumenti in fase di costruzione. Ogni strumento che il modello può chiamare, incluse le funzioni di Python locali, deve già far parte della definizione dell'agente in Foundry. Il passaggio di un FunctionTool a FoundryAgent(...) fornisce solo l'implementazione locale eseguita nel processo di Python quando viene chiamata la funzione definita da Foundry; non registra un nuovo strumento con l'agente.
Provider di contesto
context_providers=[...] è parzialmente supportato. L'eventuale funzionamento di un provider di contesto dipende da ciò che il provider tenta di eseguire:
| Comportamento del fornitore di contesto | Funziona con FoundryAgent? |
|---|---|
| Aggiunge un contesto aggiuntivo come messaggi (ad esempio, memoria recuperata, frammenti rag, informazioni sul profilo utente) | Yes. Il contesto inserito viene inoltrato con la richiesta. |
| Salva in modo persistente o monitora la conversazione (ad esempio, scrivendo i turni in un archivio esterno) | Yes. Viene eseguito localmente intorno alla richiesta/risposta. |
Aggiunge strumenti in modo dinamico (ad esempio, SkillsProvidero qualsiasi provider che restituisce strumenti da invoking()) |
No, a meno che gli strumenti non facciano già parte della definizione dell'agente Foundry. Il runtime foundry esegue il modello sugli strumenti collegati all'agente in Foundry; gli strumenti esistenti in locale non vengono esposti al modello e non verranno richiamati. |
Se hai bisogno della selezione dinamica degli strumenti, del caricamento delle skill o di qualsiasi altro comportamento che dipenda dall’aggiunta di strumenti in fase di esecuzione, usa Agent(client=FoundryChatClient(...)) invece, poiché questo approccio gestisce localmente il loop del modello e supporta l’intera gamma di tipi di strumenti e di provider di contesto per l’aggiunta di strumenti.
Opzioni di esecuzione (default_options e agent.run(...) opzioni)
Le opzioni passate a FoundryAgent(default_options=...) o a agent.run(..., **options) (ad esempio temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata, ecc.) non sono tutte supportate. Poiché la definizione dell'agente in Foundry è l'origine della verità, molte opzioni vengono ignorate automaticamente.
Per gli Agenti di prompt, il framework rimuove esplicitamente o sovrascrive i seguenti elementi prima di inviare la richiesta all'API Foundry Responses:
| Opzione | Comportamento con FoundryAgent |
|---|---|
model |
Ignorato. Il modello è ricavato dalla definizione dell'agente Foundry. |
tools, tool_choice, parallel_tool_calls |
Rimosso dal corpo della richiesta. Gli strumenti devono essere dichiarati nella definizione dell'agente Foundry (vedere la sezione precedente).
FunctionTool Gli elementi richiamabili sono ancora configurati localmente per l'invocazione di funzioni, ma l'elenco degli strumenti in sé non viene inviato al servizio. |
instructions e messaggi di sistema e sviluppatore |
Ignorato. Le istruzioni dell'agente Foundry sono autorevoli. I messaggi di sistema/sviluppatore vengono rimossi dall'elenco di messaggi prima dell'invio della richiesta. |
conversation_id |
Utilizzato, e associato alla sessione dell'agente Foundry quando fa riferimento a una sessione. |
extra_body |
Inoltrato, fuso con il payload impostato dal framework agent_reference. |
Parametri di campionamento (temperature, top_p, max_tokensseed, frequency_penalty, presence_penalty, , stop...) , metadata, , userstore, response_format, e così via. |
Inoltrato all'API Risposte. Il fatto che Foundry li applichi effettivamente dipende dalla configurazione dell'agente e del modello — la definizione dell'agente può sovrascriverli o limitarli — quindi non dare per scontato che abbiano effetto per un Prompt Agent. |
Per gli Agenti ospitati, si applica la stessa eliminazione lato client, ma per tutto il resto dipende da ciò che è implementato nello specifico agente ospitato. Un agente ospitato può accettare, ignorare o reinterpretare qualsiasi opzione inoltrata. Considerare le opzioni di runtime come avviso e verificare il comportamento effettivo rispetto all'agente ospitato che si sta chiamando.
Tip
Se hai bisogno di un controllo preciso sui parametri di generazione, sulle istruzioni o sulla selezione degli strumenti per ogni esecuzione, configurali nella definizione dell'agente Foundry oppure passa a Agent(client=FoundryChatClient(...)), che supporta ChatOptions end-to-end.
Tip
Una buona regola generale: se una funzionalità dipende dalla modifica delle istruzioni o degli strumenti dell'agente per esecuzione, appartiene a Agent(client=FoundryChatClient(...)). Se la definizione dell'agente è fissa in Foundry ed è necessaria solo la chiamata di funzione locale più il contesto a livello di messaggio, FoundryAgent è la scelta giusta.
Connessione a un agente Foundry distribuito
Per gli HostedAgents che eseguono sessioni lato servizio (/agents/{name}/sessions), usa FoundryAgent con allow_preview=True per abilitare l'interfaccia di anteprima Responses:
from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential
agent = FoundryAgent(
agent_name="my-hosted-agent",
credential=AzureCliCredential(),
allow_preview=True,
)
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)
Tip
Vedere l'esempiousing_deployed_agent.py per un esempio completo, inclusa la risoluzione automatica della versione più recente.
Avviso
Le precedenti superfici di compatibilità di incorporamento per Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider e Azure AI sono state rimosse dallo spazio dei nomi corrente agent_framework.azure. Per il codice Python corrente, usa FoundryChatClient quando l'app possiede istruzioni e strumenti, FoundryAgent quando la definizione dell'agente si trova in Foundry e FoundryEmbeddingClient per gli incorporamenti degli endpoint dei modelli Foundry.
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
Importante
Le API della casella degli strumenti sono sperimentali. La superficie può cambiare nelle versioni future.
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
| Tipo di agente | Comportamento della casella degli strumenti |
|---|---|
| FoundryAgent (ospitato) | L'allegato della casella degli strumenti avviene sul lato server. Non è necessario il collegamento lato client. |
| FoundryChatClient (inferenza diretta) | Recupera la casella degli strumenti con get_toolbox() e passarla come tools=. |
Due modelli di consumo
| Pattern | Descrizione |
|---|---|
| Nativo (strumenti ospitati) | Le configurazioni degli strumenti vengono eseguite nel Runtime di Foundry. Passare la casella degli strumenti direttamente come tools=. |
| MCP | Usare MCPStreamableHTTPTool sull'endpoint MCP della casella degli strumenti. Funziona con qualsiasi client di chat, non solo FoundryChatClient. |
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")
Note
Ogni get_toolbox() chiamata raggiunge la rete: non esiste alcuna cache sul lato framework, perché le versioni predefinite possono modificare il lato server. La memorizzazione nella cache è di proprietà del chiamante.
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
MCPStreamableHTTPToolall'endpoint MCP di una casella degli strumenti, è necessario specificare un bearer token dell'ID Entra (ad esempio, tramiteget_bearer_token_provider(credential, "https://ai.azure.com/.default")) attraversoheader_provider. - La gestione del flusso di consenso è un problema di runtime. Se uno strumento MCP della casella degli strumenti viene attivato
CONSENT_REQUIREDduranteagent.run(), viene gestito in fase di esecuzione, non durante il recupero della casella degli strumenti.
Esempi
| Sample | Descrizione |
|---|---|
| foundry_chat_client_with_toolbox.py | Recupero della toolbox di base, blocco della versione, combinazione delle toolbox e filtraggio |
| foundry_chat_client_with_toolbox_mcp.py | Percorso di utilizzo MCP con MCPStreamableHTTPTool |
| foundry_toolbox_context_provider.py | Selezione dinamica degli strumenti per turno tramite un provider di contesto |