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.
Foundry 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 illustra i client Python correnti per gli endpoint del progetto Microsoft Foundry, gli endpoint dei modelli e il servizio Foundry Agent. 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 | 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 Python appropriato
| Scenario | Client preferito | Note |
|---|---|---|
| Risorsa OpenAI di Azure | OpenAIChatCompletionClient / OpenAIChatClient |
Utilizzare la pagina del provider OpenAI. |
| Inferenza del progetto Microsoft Foundry | Agent(client=FoundryChatClient(...)) |
Usa l'endpoint Foundry Responses. |
| Agente gestito dal servizio Microsoft Foundry | FoundryAgent |
Consigliato per gli agenti prompt e gli agenti ospitati. |
| Incorporamenti 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 Python Foundry-first per l'inferenza diretta e supporta strumenti, output strutturato 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 Python consigliata per prompt agents e 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.
Avviso
Le aree di compatibilità di incorporamento precedenti di Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider e di intelligenza artificiale di Azure sono state rimosse dallo spazio dei nomi corrente agent_framework.azure. Per il codice Python corrente, usare FoundryChatClient quando l'app è proprietaria di istruzioni e strumenti, FoundryAgent quando la definizione dell'agente risiede in Foundry e FoundryEmbeddingClient per gli incorporamenti degli endpoint dei modelli Foundry.
Uso dell'agente
Sia FoundryChatClient che FoundryAgent si integrano con l'esperienza Python Agent standard, tra cui chiamate, sessioni e risposte di streaming. Per i runtime locali, utilizzare la pagina separata del provider locale Foundry.