Guida introduttiva: Creare un nuovo agente (anteprima)
Il servizio Agente di intelligenza artificiale di Azure consente di creare agenti di intelligenza artificiale personalizzati in base alle proprie esigenze tramite istruzioni personalizzate e aumentata da strumenti avanzati come interprete del codice e funzioni personalizzate.
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure.
Supporto per la configurazione dell'agente di base
Prima di iniziare, determinare se si vuole eseguire un'installazione di base dell'agente o una configurazione standard dell'agente. Azure AI Foundry supporta solo la configurazione dell'agente di base.
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti. È possibile creare una configurazione di base usando il portale di Azure AI Foundry o un modello bicep automatizzato.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo. L'installazione standard può essere eseguita solo usando un modello bicep automatizzato.
Importante
Il portale di Azure AI Foundry supporta attualmente solo la configurazione di base. Per eseguire una configurazione standard dell'agente, usare le altre schede nella parte superiore dell'articolo per informazioni sulla configurazione dell'agente standard.
Creare un hub e un progetto nel portale di Azure AI Foundry
Per creare un nuovo hub e un nuovo progetto, è necessario il ruolo Proprietario o Collaboratore nel gruppo di risorse o in un hub esistente. Se non è possibile creare un hub a causa delle autorizzazioni, contattare l'amministratore.
Per creare un progetto in Azure AI Foundry, seguire questa procedura:
Passare ad Azure AI Foundry. Se si usa un progetto, selezionare Azure AI Foundry nella parte superiore sinistra della pagina per passare alla home page.
Selezionare + Crea progetto.
Immettere un nome per il progetto.
Se si dispone di un hub, verrà visualizzato quello selezionato più di recente.
Se si ha accesso a più hub, è possibile selezionare un hub diverso dall'elenco a discesa.
Se si vuole crearne uno nuovo, selezionare Crea nuovo hub e specificare un nome. Per personalizzare i valori predefiniti, vedere la documentazione di Azure AI Foundry.
Selezionare Crea.
Distribuire un modello
Accedere ad Azure AI Foundry.
Passare al progetto o creare un nuovo progetto nel portale di Azure AI Foundry.
Nella panoramica del progetto selezionare Agenti, che si trova in Compila e personalizza.
Selezionare la risorsa OpenAI di Azure.
Selezionare una distribuzione del modello per l'agente da usare. Se non è disponibile, verrà aperta una schermata per distribuire un nuovo modello. In caso contrario, è possibile selezionare Distribuisci un modello.
Usare il playground dell'agente
Il playground agents consente di esplorare, creare prototipi e testare agenti senza dover eseguire codice. Da questa pagina è possibile eseguire rapidamente l'iterazione e sperimentare le funzionalità.
Nella schermata Crea ed esegui il debug degli agenti selezionare l'agente o crearne uno nuovo con Nuovo agente. Il riquadro Installazione a destra è la posizione in cui è possibile modificare i parametri e gli strumenti.
Facoltativamente, è possibile assegnare all'agente un nome diverso da quello generato e aggiungere istruzioni per migliorarne le prestazioni. Fornire all'agente indicazioni chiare su cosa fare e come farlo. Includere attività specifiche, il relativo ordine e qualsiasi istruzione speciale, ad esempio tono o stile di coinvolgimento.
Suggerimento
L'agente può accedere a più strumenti, ad esempio l'interprete di codice, che ne estendono le funzionalità, ad esempio la possibilità di eseguire ricerche nel Web con Bing, eseguire codice e altro ancora. Nel riquadro Installazione scorrere verso il basso fino alla conoscenza e all'azione e selezionare Aggiungi per visualizzare gli strumenti disponibili per l'uso.
Vedi anche
Vedere i modelli che è possibile usare con Agents.
| Documentazione di riferimento | - Pacchetto del codice | sorgente della | libreria di esempi (NuGet) |
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Versione più recente di .NET
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure al livello appropriato.
- Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning. Se l'interfaccia della riga di comando è già installata, assicurarsi che sia aggiornata alla versione più recente.
Configurare il progetto hub e agente di Intelligenza artificiale di Azure
La sezione seguente illustra come configurare le risorse necessarie per iniziare a usare il servizio Azure AI Agent:
Creazione di un hub di intelligenza artificiale di Azure per configurare l'ambiente dell'app e le risorse di Azure.
La creazione di un progetto di intelligenza artificiale di Azure nell'hub crea un endpoint per chiamare l'app e configura i servizi app per l'accesso alle risorse nel tenant.
Connessione di una risorsa OpenAI di Azure o di una risorsa di Servizi di intelligenza artificiale di Azure
Scegliere l'installazione dell'agente Basic o Standard
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo.
Nota
È possibile usare i modelli bicep automatizzati seguenti per eseguire un agente standard o basic. È anche possibile creare un agente di base usando il portale di Azure AI Foundry. Azure AI Foundry attualmente non supporta la configurazione dell'agente standard.
| Descrizione e distribuzione automatica | Diagramma (fare clic per ingrandire) |
|---|---|
| Distribuire una configurazione dell'agente di base che usa l'identità gestita per l'autenticazione. Le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'account di archiviazione e i servizi di intelligenza artificiale vengono create automaticamente. L'account dei servizi di intelligenza artificiale è connesso al progetto e all'hub e un modello gpt-4o-mini viene distribuito nell'area eastus. Un insieme di credenziali delle chiavi gestito da Microsoft viene usato per impostazione predefinita. |
|
| Distribuire una configurazione standard dell'agente che usa l'identità gestita per l'autenticazione. Vengono create automaticamente le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'insieme di credenziali delle chiavi, l'account di archiviazione, i servizi di intelligenza artificiale e la ricerca di intelligenza artificiale. I servizi di intelligenza artificiale, la ricerca di intelligenza artificiale, l'insieme di credenziali delle chiavi e l'account di archiviazione sono connessi al progetto e all'hub. Un modello gpt-4o-mini viene distribuito nell'area eastus. |
|
[Facoltativo] Selezione del modello nel modello di distribuzione automatica
È possibile personalizzare il modello usato dall'agente modificando i parametri del modello nel modello di distribuzione automatica. Per distribuire un modello diverso, è necessario aggiornare almeno i modelName parametri e modelVersion .
Per impostazione predefinita, il modello di distribuzione è configurato con i valori seguenti:
| Parametro del modello | Valore predefinito |
|---|---|
| modelName | gpt-4o-mini |
| modelFormat | OpenAI (per Azure OpenAI) |
| modelVersion | 18-07-2024 |
| modelSkuName | GlobalStandard |
| modelLocation | eastus |
Importante
Non modificare il parametro modelFormat.
I modelli supportano solo la distribuzione di modelli OpenAI di Azure. Vedere quali modelli OpenAI di Azure sono supportati nella documentazione del supporto del modello del servizio Azure AI Agent.
[Facoltativo] Usare le proprie risorse durante la configurazione dell'agente
Nota
Se si usa una risorsa di Servizi di intelligenza artificiale o OpenAI di Azure esistente, non verrà distribuito alcun modello. È possibile distribuire un modello nella risorsa al termine dell'installazione dell'agente.
Usare una risorsa di intelligenza artificiale esistente, Azure OpenAI, Ricerca di intelligenza artificiale e/o Archiviazione BLOB di Azure fornendo l'ID risorsa arm completo nel file dei parametri:
aiServiceAccountResourceIdaiSearchServiceResourceIdaiStorageAccountResourceId
Se si vuole usare una risorsa OpenAI di Azure esistente, è necessario aggiornare aiServiceAccountResourceId e i aiServiceKind parametri nel file dei parametri. Il aiServiceKind parametro deve essere impostato su AzureOpenAI.
Per altre informazioni, vedere come usare le proprie risorse.
Configurare ed eseguire un agente
| Componente | Descrizione |
|---|---|
| Agente | Intelligenza artificiale personalizzata che usa i modelli di intelligenza artificiale in combinazione con gli strumenti. |
| Strumento | Gli strumenti consentono di estendere la capacità di un agente di rispondere in modo affidabile e accurato durante la conversazione. Ad esempio la connessione alle knowledge base definite dall'utente al modello o l'abilitazione della ricerca Web per fornire informazioni correnti. |
| Thread | Sessione di conversazione tra un agente e un utente. I thread archiviano messaggi e gestiscono automaticamente il troncamento per adattare il contenuto al contesto di un modello. |
| Message | Messaggio creato da un agente o da un utente. I messaggi possono includere testo, immagini e altri file. I messaggi vengono archiviati come elenco nel thread. |
| Run | Attivazione di un agente per iniziare l'esecuzione in base al contenuto di Thread. L'agente usa la configurazione e i messaggi del thread per eseguire attività chiamando modelli e strumenti. Nell'ambito di un'operazione Run, l'agente aggiunge messaggi al thread. |
| Eseguire il passaggio | Elenco dettagliato dei passaggi eseguiti dall'agente come parte di un'esecuzione. Un agente può chiamare strumenti o creare messaggi durante l'esecuzione. L'analisi dei passaggi di esecuzione consente di comprendere in che modo l'agente ottiene i risultati. |
Installare il pacchetto .NET nel progetto. Ad esempio, se si usa l'interfaccia della riga di comando di .NET, eseguire il comando seguente.
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity
Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.
az login
Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, è necessario creare un stringa di connessione usando le informazioni del progetto. Questa stringa è nel formato:
<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>
Suggerimento
È anche possibile trovare il stringa di connessione nella panoramica del progetto nel portale di Azure AI Foundry, in Dettagli>progetto stringa di connessione.
HostName è disponibile passando all'oggetto discovery_url e rimuovendo l'oggetto iniziale https:// e finale /discovery. Per trovare discovery_url, eseguire questo comando dell'interfaccia della riga di comando:
az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
Ad esempio, il stringa di connessione potrebbe essere simile al seguente:
eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
Impostare questa stringa di connessione come variabile di ambiente denominata PROJECT_CONNECTION_STRING.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
#nullable disable
using Azure.Identity;
namespace Azure.AI.Projects.Tests;
public class Sample_Agent
{
static async Task Main()
{
var connectionString = Environment.GetEnvironmentVariable("PROJECT_CONNECTION_STRING");
AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());
// Step 1: Create an agent
Response<Agent> agentResponse = await client.CreateAgentAsync(
model: "gpt-4o-mini",
name: "My Agent",
instructions: "You are a helpful agent.",
tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
Agent agent = agentResponse.Value;
// Intermission: agent should now be listed
Response<PageableList<Agent>> agentListResponse = await client.GetAgentsAsync();
//// Step 2: Create a thread
Response<AgentThread> threadResponse = await client.CreateThreadAsync();
AgentThread thread = threadResponse.Value;
// Step 3: Add a message to a thread
Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
thread.Id,
MessageRole.User,
"I need to solve the equation `3x + 11 = 14`. Can you help me?");
ThreadMessage message = messageResponse.Value;
// Intermission: message is now correlated with thread
// Intermission: listing messages will retrieve the message just added
Response<PageableList<ThreadMessage>> messagesListResponse = await client.GetMessagesAsync(thread.Id);
//Assert.That(messagesListResponse.Value.Data[0].Id == message.Id);
// Step 4: Run the agent
Response<ThreadRun> runResponse = await client.CreateRunAsync(
thread.Id,
agent.Id,
additionalInstructions: "");
ThreadRun run = runResponse.Value;
do
{
await Task.Delay(TimeSpan.FromMilliseconds(500));
runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
}
while (runResponse.Value.Status == RunStatus.Queued
|| runResponse.Value.Status == RunStatus.InProgress);
Response<PageableList<ThreadMessage>> afterRunMessagesResponse
= await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;
// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages)
{
Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
foreach (MessageContent contentItem in threadMessage.ContentItems)
{
if (contentItem is MessageTextContent textItem)
{
Console.Write(textItem.Text);
}
else if (contentItem is MessageImageFileContent imageFileItem)
{
Console.Write($"<image from ID: {imageFileItem.FileId}");
}
Console.WriteLine();
}
}
}
}
| Documentazione di | riferimento | - Pacchetto del codice | sorgente della libreria di esempi (PyPi) |
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Python 3.8 o versioni successive
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure al livello appropriato.
- Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning. Se l'interfaccia della riga di comando è già installata, assicurarsi che sia aggiornata alla versione più recente.
Configurare il progetto hub e agente di Intelligenza artificiale di Azure
La sezione seguente illustra come configurare le risorse necessarie per iniziare a usare il servizio Azure AI Agent:
Creazione di un hub di intelligenza artificiale di Azure per configurare l'ambiente dell'app e le risorse di Azure.
La creazione di un progetto di intelligenza artificiale di Azure nell'hub crea un endpoint per chiamare l'app e configura i servizi app per l'accesso alle risorse nel tenant.
Connessione di una risorsa OpenAI di Azure o di una risorsa di Servizi di intelligenza artificiale di Azure
Scegliere l'installazione dell'agente Basic o Standard
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo.
Nota
È possibile usare i modelli bicep automatizzati seguenti per eseguire un agente standard o basic. È anche possibile creare un agente di base usando il portale di Azure AI Foundry. Azure AI Foundry attualmente non supporta la configurazione dell'agente standard.
| Descrizione e distribuzione automatica | Diagramma (fare clic per ingrandire) |
|---|---|
| Distribuire una configurazione dell'agente di base che usa l'identità gestita per l'autenticazione. Le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'account di archiviazione e i servizi di intelligenza artificiale vengono create automaticamente. L'account dei servizi di intelligenza artificiale è connesso al progetto e all'hub e un modello gpt-4o-mini viene distribuito nell'area eastus. Un insieme di credenziali delle chiavi gestito da Microsoft viene usato per impostazione predefinita. |
|
| Distribuire una configurazione standard dell'agente che usa l'identità gestita per l'autenticazione. Vengono create automaticamente le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'insieme di credenziali delle chiavi, l'account di archiviazione, i servizi di intelligenza artificiale e la ricerca di intelligenza artificiale. I servizi di intelligenza artificiale, la ricerca di intelligenza artificiale, l'insieme di credenziali delle chiavi e l'account di archiviazione sono connessi al progetto e all'hub. Un modello gpt-4o-mini viene distribuito nell'area eastus. |
|
[Facoltativo] Selezione del modello nel modello di distribuzione automatica
È possibile personalizzare il modello usato dall'agente modificando i parametri del modello nel modello di distribuzione automatica. Per distribuire un modello diverso, è necessario aggiornare almeno i modelName parametri e modelVersion .
Per impostazione predefinita, il modello di distribuzione è configurato con i valori seguenti:
| Parametro del modello | Valore predefinito |
|---|---|
| modelName | gpt-4o-mini |
| modelFormat | OpenAI (per Azure OpenAI) |
| modelVersion | 18-07-2024 |
| modelSkuName | GlobalStandard |
| modelLocation | eastus |
Importante
Non modificare il parametro modelFormat.
I modelli supportano solo la distribuzione di modelli OpenAI di Azure. Vedere quali modelli OpenAI di Azure sono supportati nella documentazione del supporto del modello del servizio Azure AI Agent.
[Facoltativo] Usare le proprie risorse durante la configurazione dell'agente
Nota
Se si usa una risorsa di Servizi di intelligenza artificiale o OpenAI di Azure esistente, non verrà distribuito alcun modello. È possibile distribuire un modello nella risorsa al termine dell'installazione dell'agente.
Usare una risorsa di intelligenza artificiale esistente, Azure OpenAI, Ricerca di intelligenza artificiale e/o Archiviazione BLOB di Azure fornendo l'ID risorsa arm completo nel file dei parametri:
aiServiceAccountResourceIdaiSearchServiceResourceIdaiStorageAccountResourceId
Se si vuole usare una risorsa OpenAI di Azure esistente, è necessario aggiornare aiServiceAccountResourceId e i aiServiceKind parametri nel file dei parametri. Il aiServiceKind parametro deve essere impostato su AzureOpenAI.
Per altre informazioni, vedere come usare le proprie risorse.
Configurare ed eseguire un agente
| Componente | Descrizione |
|---|---|
| Agente | Intelligenza artificiale personalizzata che usa i modelli di intelligenza artificiale in combinazione con gli strumenti. |
| Strumento | Gli strumenti consentono di estendere la capacità di un agente di rispondere in modo affidabile e accurato durante la conversazione. Ad esempio la connessione alle knowledge base definite dall'utente al modello o l'abilitazione della ricerca Web per fornire informazioni correnti. |
| Thread | Sessione di conversazione tra un agente e un utente. I thread archiviano messaggi e gestiscono automaticamente il troncamento per adattare il contenuto al contesto di un modello. |
| Message | Messaggio creato da un agente o da un utente. I messaggi possono includere testo, immagini e altri file. I messaggi vengono archiviati come elenco nel thread. |
| Run | Attivazione di un agente per iniziare l'esecuzione in base al contenuto di Thread. L'agente usa la configurazione e i messaggi del thread per eseguire attività chiamando modelli e strumenti. Nell'ambito di un'operazione Run, l'agente aggiunge messaggi al thread. |
| Eseguire il passaggio | Elenco dettagliato dei passaggi eseguiti dall'agente come parte di un'esecuzione. Un agente può chiamare strumenti o creare messaggi durante l'esecuzione. L'analisi dei passaggi di esecuzione consente di comprendere in che modo l'agente ottiene i risultati. |
Eseguire i comandi seguenti per installare i pacchetti Python.
pip install azure-ai-projects
pip install azure-identity
Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.
az login
Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, è necessario creare un stringa di connessione usando le informazioni del progetto. Questa stringa è nel formato:
<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>
Suggerimento
È anche possibile trovare il stringa di connessione nella panoramica del progetto nel portale di Azure AI Foundry, in Dettagli>progetto stringa di connessione.
HostName è disponibile passando all'oggetto discovery_url e rimuovendo l'oggetto iniziale https:// e finale /discovery. Per trovare discovery_url, eseguire questo comando dell'interfaccia della riga di comando:
az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
Ad esempio, il stringa di connessione potrebbe essere simile al seguente:
eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
Impostare questa stringa di connessione come variabile di ambiente denominata PROJECT_CONNECTION_STRING.
import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import CodeInterpreterTool
from azure.identity import DefaultAzureCredential
from typing import Any
from pathlib import Path
# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery"
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables
project_client = AIProjectClient.from_connection_string(
credential=DefaultAzureCredential(), conn_str=os.environ["PROJECT_CONNECTION_STRING"]
)
with project_client:
# Create an instance of the CodeInterpreterTool
code_interpreter = CodeInterpreterTool()
# The CodeInterpreterTool needs to be included in creation of the agent
agent = project_client.agents.create_agent(
model="gpt-4o-mini",
name="my-agent",
instructions="You are helpful agent",
tools=code_interpreter.definitions,
tool_resources=code_interpreter.resources,
)
print(f"Created agent, agent ID: {agent.id}")
# Create a thread
thread = project_client.agents.create_thread()
print(f"Created thread, thread ID: {thread.id}")
# Create a message
message = project_client.agents.create_message(
thread_id=thread.id,
role="user",
content="Could you please create a bar chart for the operating profit using the following data and provide the file to me? Company A: $1.2 million, Company B: $2.5 million, Company C: $3.0 million, Company D: $1.8 million",
)
print(f"Created message, message ID: {message.id}")
# Run the agent
run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Run finished with status: {run.status}")
if run.status == "failed":
# Check if you got "Rate limit is exceeded.", then you want to get more quota
print(f"Run failed: {run.last_error}")
# Get messages from the thread
messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")
# Get the last message from the sender
last_msg = messages.get_last_text_message_by_role("assistant")
if last_msg:
print(f"Last Message: {last_msg.text.value}")
# Generate an image file for the bar chart
for image_content in messages.image_contents:
print(f"Image File ID: {image_content.image_file.file_id}")
file_name = f"{image_content.image_file.file_id}_image_file.png"
project_client.agents.save_file(file_id=image_content.image_file.file_id, file_name=file_name)
print(f"Saved image file to: {Path.cwd() / file_name}")
# Print the file path(s) from the messages
for file_path_annotation in messages.file_path_annotations:
print(f"File Paths:")
print(f"Type: {file_path_annotation.type}")
print(f"Text: {file_path_annotation.text}")
print(f"File ID: {file_path_annotation.file_path.file_id}")
print(f"Start Index: {file_path_annotation.start_index}")
print(f"End Index: {file_path_annotation.end_index}")
project_client.agents.save_file(file_id=file_path_annotation.file_path.file_id, file_name=Path(file_path_annotation.text).name)
# Delete the agent once done
project_client.agents.delete_agent(agent.id)
print("Deleted agent")
| Documentazione di riferimento | Codice sorgente della libreria | Pacchetto di codice(PyPi) |
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Python 3.8 o versioni successive
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure al livello appropriato.
- È necessario il ruolo Utente OpenAI di Servizi cognitivi assegnato per usare la risorsa Servizi di intelligenza artificiale di Azure.
- Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning. Se l'interfaccia della riga di comando è già installata, assicurarsi che sia aggiornata alla versione più recente.
Configurare il progetto hub e agente di Intelligenza artificiale di Azure
La sezione seguente illustra come configurare le risorse necessarie per iniziare a usare il servizio Azure AI Agent:
Creazione di un hub di intelligenza artificiale di Azure per configurare l'ambiente dell'app e le risorse di Azure.
La creazione di un progetto di intelligenza artificiale di Azure nell'hub crea un endpoint per chiamare l'app e configura i servizi app per l'accesso alle risorse nel tenant.
Connessione di una risorsa OpenAI di Azure o di una risorsa di Servizi di intelligenza artificiale di Azure
Scegliere l'installazione dell'agente Basic o Standard
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo.
Nota
È possibile usare i modelli bicep automatizzati seguenti per eseguire un agente standard o basic. È anche possibile creare un agente di base usando il portale di Azure AI Foundry. Azure AI Foundry attualmente non supporta la configurazione dell'agente standard.
| Descrizione e distribuzione automatica | Diagramma (fare clic per ingrandire) |
|---|---|
| Distribuire una configurazione dell'agente di base che usa l'identità gestita per l'autenticazione. Le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'account di archiviazione e i servizi di intelligenza artificiale vengono create automaticamente. L'account dei servizi di intelligenza artificiale è connesso al progetto e all'hub e un modello gpt-4o-mini viene distribuito nell'area eastus. Un insieme di credenziali delle chiavi gestito da Microsoft viene usato per impostazione predefinita. |
|
| Distribuire una configurazione standard dell'agente che usa l'identità gestita per l'autenticazione. Vengono create automaticamente le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'insieme di credenziali delle chiavi, l'account di archiviazione, i servizi di intelligenza artificiale e la ricerca di intelligenza artificiale. I servizi di intelligenza artificiale, la ricerca di intelligenza artificiale, l'insieme di credenziali delle chiavi e l'account di archiviazione sono connessi al progetto e all'hub. Un modello gpt-4o-mini viene distribuito nell'area eastus. |
|
[Facoltativo] Selezione del modello nel modello di distribuzione automatica
È possibile personalizzare il modello usato dall'agente modificando i parametri del modello nel modello di distribuzione automatica. Per distribuire un modello diverso, è necessario aggiornare almeno i modelName parametri e modelVersion .
Per impostazione predefinita, il modello di distribuzione è configurato con i valori seguenti:
| Parametro del modello | Valore predefinito |
|---|---|
| modelName | gpt-4o-mini |
| modelFormat | OpenAI (per Azure OpenAI) |
| modelVersion | 18-07-2024 |
| modelSkuName | GlobalStandard |
| modelLocation | eastus |
Importante
Non modificare il parametro modelFormat.
I modelli supportano solo la distribuzione di modelli OpenAI di Azure. Vedere quali modelli OpenAI di Azure sono supportati nella documentazione del supporto del modello del servizio Azure AI Agent.
[Facoltativo] Usare le proprie risorse durante la configurazione dell'agente
Nota
Se si usa una risorsa di Servizi di intelligenza artificiale o OpenAI di Azure esistente, non verrà distribuito alcun modello. È possibile distribuire un modello nella risorsa al termine dell'installazione dell'agente.
Usare una risorsa di intelligenza artificiale esistente, Azure OpenAI, Ricerca di intelligenza artificiale e/o Archiviazione BLOB di Azure fornendo l'ID risorsa arm completo nel file dei parametri:
aiServiceAccountResourceIdaiSearchServiceResourceIdaiStorageAccountResourceId
Se si vuole usare una risorsa OpenAI di Azure esistente, è necessario aggiornare aiServiceAccountResourceId e i aiServiceKind parametri nel file dei parametri. Il aiServiceKind parametro deve essere impostato su AzureOpenAI.
Per altre informazioni, vedere come usare le proprie risorse.
Configurare ed eseguire un agente
| Componente | Descrizione |
|---|---|
| Agente | Intelligenza artificiale personalizzata che usa i modelli di intelligenza artificiale in combinazione con gli strumenti. |
| Strumento | Gli strumenti consentono di estendere la capacità di un agente di rispondere in modo affidabile e accurato durante la conversazione. Ad esempio la connessione alle knowledge base definite dall'utente al modello o l'abilitazione della ricerca Web per fornire informazioni correnti. |
| Thread | Sessione di conversazione tra un agente e un utente. I thread archiviano messaggi e gestiscono automaticamente il troncamento per adattare il contenuto al contesto di un modello. |
| Message | Messaggio creato da un agente o da un utente. I messaggi possono includere testo, immagini e altri file. I messaggi vengono archiviati come elenco nel thread. |
| Run | Attivazione di un agente per iniziare l'esecuzione in base al contenuto di Thread. L'agente usa la configurazione e i messaggi del thread per eseguire attività chiamando modelli e strumenti. Nell'ambito di un'operazione Run, l'agente aggiunge messaggi al thread. |
| Eseguire il passaggio | Elenco dettagliato dei passaggi eseguiti dall'agente come parte di un'esecuzione. Un agente può chiamare strumenti o creare messaggi durante l'esecuzione. L'analisi dei passaggi di esecuzione consente di comprendere in che modo l'agente ottiene i risultati. |
Eseguire i comandi seguenti per installare i pacchetti Python.
pip install azure-ai-projects
pip install azure-identity
pip install openai
Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.
az login
Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, è necessario creare un stringa di connessione usando le informazioni del progetto. Questa stringa è nel formato:
<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>
Suggerimento
È anche possibile trovare il stringa di connessione nella panoramica del progetto nel portale di Azure AI Foundry, in Dettagli>progetto stringa di connessione.
HostName è disponibile passando all'oggetto discovery_url e rimuovendo l'oggetto iniziale https:// e finale /discovery. Per trovare discovery_url, eseguire questo comando dell'interfaccia della riga di comando:
az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
Ad esempio, il stringa di connessione potrebbe essere simile al seguente:
eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
Impostare questa stringa di connessione come variabile di ambiente denominata PROJECT_CONNECTION_STRING.
import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from openai import AzureOpenAI
with AIProjectClient.from_connection_string(
credential=DefaultAzureCredential(),
conn_str=os.environ["PROJECT_CONNECTION_STRING"],
) as project_client:
# Explicit type hinting for IntelliSense
client: AzureOpenAI = project_client.inference.get_azure_openai_client(
# The latest API version is 2024-10-01-preview
api_version = os.environ.get("AZURE_OPENAI_API_VERSION"),
)
with client:
agent = client.beta.assistants.create(
model="gpt-4o-mini", name="my-agent", instructions="You are a helpful agent"
)
print(f"Created agent, agent ID: {agent.id}")
thread = client.beta.threads.create()
print(f"Created thread, thread ID: {thread.id}")
message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Hello, tell me a joke")
print(f"Created message, message ID: {message.id}")
run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=agent.id)
# Poll the run while run status is queued or in progress
while run.status in ["queued", "in_progress", "requires_action"]:
time.sleep(1) # Wait for a second
run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
print(f"Run status: {run.status}")
client.beta.assistants.delete(agent.id)
print("Deleted agent")
messages = client.beta.threads.messages.list(thread_id=thread.id)
print(f"Messages: {messages}")
| Documentazione di | riferimento | - Pacchetto del codice | sorgente della libreria di esempi (npm) |
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Node.js LTS
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure al livello appropriato.
- Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning. Se l'interfaccia della riga di comando è già installata, assicurarsi che sia aggiornata alla versione più recente.
Configurare il progetto hub e agente di Intelligenza artificiale di Azure
La sezione seguente illustra come configurare le risorse necessarie per iniziare a usare il servizio Azure AI Agent:
Creazione di un hub di intelligenza artificiale di Azure per configurare l'ambiente dell'app e le risorse di Azure.
La creazione di un progetto di intelligenza artificiale di Azure nell'hub crea un endpoint per chiamare l'app e configura i servizi app per l'accesso alle risorse nel tenant.
Connessione di una risorsa OpenAI di Azure o di una risorsa di Servizi di intelligenza artificiale di Azure
Scegliere l'installazione dell'agente Basic o Standard
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo.
Nota
È possibile usare i modelli bicep automatizzati seguenti per eseguire un agente standard o basic. È anche possibile creare un agente di base usando il portale di Azure AI Foundry. Azure AI Foundry attualmente non supporta la configurazione dell'agente standard.
| Descrizione e distribuzione automatica | Diagramma (fare clic per ingrandire) |
|---|---|
| Distribuire una configurazione dell'agente di base che usa l'identità gestita per l'autenticazione. Le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'account di archiviazione e i servizi di intelligenza artificiale vengono create automaticamente. L'account dei servizi di intelligenza artificiale è connesso al progetto e all'hub e un modello gpt-4o-mini viene distribuito nell'area eastus. Un insieme di credenziali delle chiavi gestito da Microsoft viene usato per impostazione predefinita. |
|
| Distribuire una configurazione standard dell'agente che usa l'identità gestita per l'autenticazione. Vengono create automaticamente le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'insieme di credenziali delle chiavi, l'account di archiviazione, i servizi di intelligenza artificiale e la ricerca di intelligenza artificiale. I servizi di intelligenza artificiale, la ricerca di intelligenza artificiale, l'insieme di credenziali delle chiavi e l'account di archiviazione sono connessi al progetto e all'hub. Un modello gpt-4o-mini viene distribuito nell'area eastus. |
|
[Facoltativo] Selezione del modello nel modello di distribuzione automatica
È possibile personalizzare il modello usato dall'agente modificando i parametri del modello nel modello di distribuzione automatica. Per distribuire un modello diverso, è necessario aggiornare almeno i modelName parametri e modelVersion .
Per impostazione predefinita, il modello di distribuzione è configurato con i valori seguenti:
| Parametro del modello | Valore predefinito |
|---|---|
| modelName | gpt-4o-mini |
| modelFormat | OpenAI (per Azure OpenAI) |
| modelVersion | 18-07-2024 |
| modelSkuName | GlobalStandard |
| modelLocation | eastus |
Importante
Non modificare il parametro modelFormat.
I modelli supportano solo la distribuzione di modelli OpenAI di Azure. Vedere quali modelli OpenAI di Azure sono supportati nella documentazione del supporto del modello del servizio Azure AI Agent.
[Facoltativo] Usare le proprie risorse durante la configurazione dell'agente
Nota
Se si usa una risorsa di Servizi di intelligenza artificiale o OpenAI di Azure esistente, non verrà distribuito alcun modello. È possibile distribuire un modello nella risorsa al termine dell'installazione dell'agente.
Usare una risorsa di intelligenza artificiale esistente, Azure OpenAI, Ricerca di intelligenza artificiale e/o Archiviazione BLOB di Azure fornendo l'ID risorsa arm completo nel file dei parametri:
aiServiceAccountResourceIdaiSearchServiceResourceIdaiStorageAccountResourceId
Se si vuole usare una risorsa OpenAI di Azure esistente, è necessario aggiornare aiServiceAccountResourceId e i aiServiceKind parametri nel file dei parametri. Il aiServiceKind parametro deve essere impostato su AzureOpenAI.
Per altre informazioni, vedere come usare le proprie risorse.
Configurare ed eseguire un agente
| Componente | Descrizione |
|---|---|
| Agente | Intelligenza artificiale personalizzata che usa i modelli di intelligenza artificiale in combinazione con gli strumenti. |
| Strumento | Gli strumenti consentono di estendere la capacità di un agente di rispondere in modo affidabile e accurato durante la conversazione. Ad esempio la connessione alle knowledge base definite dall'utente al modello o l'abilitazione della ricerca Web per fornire informazioni correnti. |
| Thread | Sessione di conversazione tra un agente e un utente. I thread archiviano messaggi e gestiscono automaticamente il troncamento per adattare il contenuto al contesto di un modello. |
| Message | Messaggio creato da un agente o da un utente. I messaggi possono includere testo, immagini e altri file. I messaggi vengono archiviati come elenco nel thread. |
| Run | Attivazione di un agente per iniziare l'esecuzione in base al contenuto di Thread. L'agente usa la configurazione e i messaggi del thread per eseguire attività chiamando modelli e strumenti. Nell'ambito di un'operazione Run, l'agente aggiunge messaggi al thread. |
| Eseguire il passaggio | Elenco dettagliato dei passaggi eseguiti dall'agente come parte di un'esecuzione. Un agente può chiamare strumenti o creare messaggi durante l'esecuzione. L'analisi dei passaggi di esecuzione consente di comprendere in che modo l'agente ottiene i risultati. |
Eseguire i comandi seguenti per installare i pacchetti npm.
npm install @azure/ai-projects
npm install @azure/identity
Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.
az login
Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, è necessario creare un stringa di connessione usando le informazioni del progetto. Questa stringa è nel formato:
<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>
Suggerimento
È anche possibile trovare il stringa di connessione nella panoramica del progetto nel portale di Azure AI Foundry, in Dettagli>progetto stringa di connessione.
HostName è disponibile passando all'oggetto discovery_url e rimuovendo l'oggetto iniziale https:// e finale /discovery. Per trovare discovery_url, eseguire questo comando dell'interfaccia della riga di comando:
az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
Ad esempio, il stringa di connessione potrebbe essere simile al seguente:
eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
Impostare questa stringa di connessione come variabile di ambiente denominata PROJECT_CONNECTION_STRING.
// index.js
import {
AIProjectsClient,
DoneEvent,
ErrorEvent,
isOutputOfType,
MessageStreamEvent,
RunStreamEvent,
ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
const connectionString =
process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";
if (!connectionString) {
throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}
export async function main() {
const client = AIProjectsClient.fromConnectionString(
connectionString || "",
new DefaultAzureCredential(),
);
// Step 1 code interpreter tool
const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();
// Step 2 an agent
const agent = await client.agents.createAgent("gpt-4o-mini", {
name: "my-agent",
instructions: "You are a helpful agent",
tools: [codeInterpreterTool.definition],
toolResources: codeInterpreterTool.resources,
});
// Step 3 a thread
const thread = await client.agents.createThread();
// Step 4 a message to thread
await client.agents.createMessage(
thread.id, {
role: "user",
content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
});
// Intermission is now correlated with thread
// Intermission messages will retrieve the message just added
// Step 5 the agent
const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();
for await (const eventMessage of streamEventMessages) {
switch (eventMessage.event) {
case RunStreamEvent.ThreadRunCreated:
break;
case MessageStreamEvent.ThreadMessageDelta:
{
const messageDelta = eventMessage.data;
messageDelta.delta.content.forEach((contentPart) => {
if (contentPart.type === "text") {
const textContent = contentPart;
const textValue = textContent.text?.value || "No text";
}
});
}
break;
case RunStreamEvent.ThreadRunCompleted:
break;
case ErrorEvent.Error:
console.log(`An error occurred. Data ${eventMessage.data}`);
break;
case DoneEvent.Done:
break;
}
}
// 6. Print the messages from the agent
const messages = await client.agents.listMessages(thread.id);
// Messages iterate from oldest to newest
// messages[0] is the most recent
for (let i = messages.data.length - 1; i >= 0; i--) {
const m = messages.data[i];
if (isOutputOfType(m.content[0], "text")) {
const textContent = m.content[0];
console.log(`${textContent.text.value}`);
console.log(`---------------------------------`);
}
}
// 7. Delete the agent once done
await client.agents.deleteAgent(agent.id);
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
L'output contiene il prompt e le risposte.
I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).
To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\).
Therefore, the value of \(x\) that satisfies the equation is 1.
Let me know if you need help with anything else!
---------------------------------
| Documentazione di | riferimento | - Pacchetto del codice | sorgente della libreria di esempi (npm) |
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Node.js LTS
- TypeScript 5.x
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure al livello appropriato.
- Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning. Se l'interfaccia della riga di comando è già installata, assicurarsi che sia aggiornata alla versione più recente.
Configurare il progetto hub e agente di Intelligenza artificiale di Azure
La sezione seguente illustra come configurare le risorse necessarie per iniziare a usare il servizio Azure AI Agent:
Creazione di un hub di intelligenza artificiale di Azure per configurare l'ambiente dell'app e le risorse di Azure.
La creazione di un progetto di intelligenza artificiale di Azure nell'hub crea un endpoint per chiamare l'app e configura i servizi app per l'accesso alle risorse nel tenant.
Connessione di una risorsa OpenAI di Azure o di una risorsa di Servizi di intelligenza artificiale di Azure
Scegliere l'installazione dell'agente Basic o Standard
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo.
Nota
È possibile usare i modelli bicep automatizzati seguenti per eseguire un agente standard o basic. È anche possibile creare un agente di base usando il portale di Azure AI Foundry. Azure AI Foundry attualmente non supporta la configurazione dell'agente standard.
| Descrizione e distribuzione automatica | Diagramma (fare clic per ingrandire) |
|---|---|
| Distribuire una configurazione dell'agente di base che usa l'identità gestita per l'autenticazione. Le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'account di archiviazione e i servizi di intelligenza artificiale vengono create automaticamente. L'account dei servizi di intelligenza artificiale è connesso al progetto e all'hub e un modello gpt-4o-mini viene distribuito nell'area eastus. Un insieme di credenziali delle chiavi gestito da Microsoft viene usato per impostazione predefinita. |
|
| Distribuire una configurazione standard dell'agente che usa l'identità gestita per l'autenticazione. Vengono create automaticamente le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'insieme di credenziali delle chiavi, l'account di archiviazione, i servizi di intelligenza artificiale e la ricerca di intelligenza artificiale. I servizi di intelligenza artificiale, la ricerca di intelligenza artificiale, l'insieme di credenziali delle chiavi e l'account di archiviazione sono connessi al progetto e all'hub. Un modello gpt-4o-mini viene distribuito nell'area eastus. |
|
[Facoltativo] Selezione del modello nel modello di distribuzione automatica
È possibile personalizzare il modello usato dall'agente modificando i parametri del modello nel modello di distribuzione automatica. Per distribuire un modello diverso, è necessario aggiornare almeno i modelName parametri e modelVersion .
Per impostazione predefinita, il modello di distribuzione è configurato con i valori seguenti:
| Parametro del modello | Valore predefinito |
|---|---|
| modelName | gpt-4o-mini |
| modelFormat | OpenAI (per Azure OpenAI) |
| modelVersion | 18-07-2024 |
| modelSkuName | GlobalStandard |
| modelLocation | eastus |
Importante
Non modificare il parametro modelFormat.
I modelli supportano solo la distribuzione di modelli OpenAI di Azure. Vedere quali modelli OpenAI di Azure sono supportati nella documentazione del supporto del modello del servizio Azure AI Agent.
[Facoltativo] Usare le proprie risorse durante la configurazione dell'agente
Nota
Se si usa una risorsa di Servizi di intelligenza artificiale o OpenAI di Azure esistente, non verrà distribuito alcun modello. È possibile distribuire un modello nella risorsa al termine dell'installazione dell'agente.
Usare una risorsa di intelligenza artificiale esistente, Azure OpenAI, Ricerca di intelligenza artificiale e/o Archiviazione BLOB di Azure fornendo l'ID risorsa arm completo nel file dei parametri:
aiServiceAccountResourceIdaiSearchServiceResourceIdaiStorageAccountResourceId
Se si vuole usare una risorsa OpenAI di Azure esistente, è necessario aggiornare aiServiceAccountResourceId e i aiServiceKind parametri nel file dei parametri. Il aiServiceKind parametro deve essere impostato su AzureOpenAI.
Per altre informazioni, vedere come usare le proprie risorse.
Configurare ed eseguire un agente
| Componente | Descrizione |
|---|---|
| Agente | Intelligenza artificiale personalizzata che usa i modelli di intelligenza artificiale in combinazione con gli strumenti. |
| Strumento | Gli strumenti consentono di estendere la capacità di un agente di rispondere in modo affidabile e accurato durante la conversazione. Ad esempio la connessione alle knowledge base definite dall'utente al modello o l'abilitazione della ricerca Web per fornire informazioni correnti. |
| Thread | Sessione di conversazione tra un agente e un utente. I thread archiviano messaggi e gestiscono automaticamente il troncamento per adattare il contenuto al contesto di un modello. |
| Message | Messaggio creato da un agente o da un utente. I messaggi possono includere testo, immagini e altri file. I messaggi vengono archiviati come elenco nel thread. |
| Run | Attivazione di un agente per iniziare l'esecuzione in base al contenuto di Thread. L'agente usa la configurazione e i messaggi del thread per eseguire attività chiamando modelli e strumenti. Nell'ambito di un'operazione Run, l'agente aggiunge messaggi al thread. |
| Eseguire il passaggio | Elenco dettagliato dei passaggi eseguiti dall'agente come parte di un'esecuzione. Un agente può chiamare strumenti o creare messaggi durante l'esecuzione. L'analisi dei passaggi di esecuzione consente di comprendere in che modo l'agente ottiene i risultati. |
Eseguire i comandi seguenti per installare i pacchetti npm.
npm install @azure/ai-projects
npm install @azure/identity
Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.
az login
Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, è necessario creare un stringa di connessione usando le informazioni del progetto. Questa stringa è nel formato:
<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>
Suggerimento
È anche possibile trovare il stringa di connessione nella panoramica del progetto nel portale di Azure AI Foundry, in Dettagli>progetto stringa di connessione.
HostName è disponibile passando all'oggetto discovery_url e rimuovendo l'oggetto iniziale https:// e finale /discovery. Per trovare discovery_url, eseguire questo comando dell'interfaccia della riga di comando:
az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
Ad esempio, il stringa di connessione potrebbe essere simile al seguente:
eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
Impostare questa stringa di connessione come variabile di ambiente denominata PROJECT_CONNECTION_STRING.
// index.ts
import type {
MessageDeltaChunk,
MessageDeltaTextContent,
MessageTextContentOutput,
} from "@azure/ai-projects";
import {
AIProjectsClient,
DoneEvent,
ErrorEvent,
isOutputOfType,
MessageStreamEvent,
RunStreamEvent,
ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
const connectionString =
process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";
if (!connectionString) {
throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}
export async function main(): Promise<void> {
const client = AIProjectsClient.fromConnectionString(
connectionString || "",
new DefaultAzureCredential(),
);
// Step 1: Create code interpreter tool
const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();
// Step 2: Create an agent
const agent = await client.agents.createAgent("gpt-4o-mini", {
name: "my-agent",
instructions: "You are a helpful agent",
tools: [codeInterpreterTool.definition],
toolResources: codeInterpreterTool.resources,
});
// Step 3: Create a thread
const thread = await client.agents.createThread();
// Step 4: Add a message to thread
await client.agents.createMessage(
thread.id, {
role: "user",
content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
});
// Intermission: message is now correlated with thread
// Intermission: listing messages will retrieve the message just added
// Step 5: Run the agent
const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();
for await (const eventMessage of streamEventMessages) {
switch (eventMessage.event) {
case RunStreamEvent.ThreadRunCreated:
break;
case MessageStreamEvent.ThreadMessageDelta:
{
const messageDelta = eventMessage.data as MessageDeltaChunk;
messageDelta.delta.content.forEach((contentPart) => {
if (contentPart.type === "text") {
const textContent = contentPart as MessageDeltaTextContent;
const textValue = textContent.text?.value || "No text";
}
});
}
break;
case RunStreamEvent.ThreadRunCompleted:
break;
case ErrorEvent.Error:
console.log(`An error occurred. Data ${eventMessage.data}`);
break;
case DoneEvent.Done:
break;
}
}
// 6. Print the messages from the agent
const messages = await client.agents.listMessages(thread.id);
// Messages iterate from oldest to newest
// messages[0] is the most recent
for (let i = messages.data.length - 1; i >= 0; i--) {
const m = messages.data[i];
if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
const textContent = m.content[0] as MessageTextContentOutput;
console.log(`${textContent.text.value}`);
console.log(`---------------------------------`);
}
}
// 7. Delete the agent once done
await client.agents.deleteAgent(agent.id);
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
L'output contiene il prompt e le risposte.
I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).
To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\).
Therefore, the value of \(x\) that satisfies the equation is 1.
Let me know if you need help with anything else!
---------------------------------
| Documentazione di riferimento |
Prerequisiti
- Una sottoscrizione di Azure: crearne una gratuitamente.
- Assicurarsi di avere assegnato il ruolo Controllo degli accessi in base al ruolo degli sviluppatoridi Intelligenza artificiale di Azure al livello appropriato.
- È necessario il ruolo Utente OpenAI di Servizi cognitivi assegnato per usare la risorsa Servizi di intelligenza artificiale di Azure.
- Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning. Se l'interfaccia della riga di comando è già installata, assicurarsi che sia aggiornata alla versione più recente.
Configurare il progetto hub e agente di Intelligenza artificiale di Azure
La sezione seguente illustra come configurare le risorse necessarie per iniziare a usare il servizio Azure AI Agent:
Creazione di un hub di intelligenza artificiale di Azure per configurare l'ambiente dell'app e le risorse di Azure.
La creazione di un progetto di intelligenza artificiale di Azure nell'hub crea un endpoint per chiamare l'app e configura i servizi app per l'accesso alle risorse nel tenant.
Connessione di una risorsa OpenAI di Azure o di una risorsa di Servizi di intelligenza artificiale di Azure
Scegliere l'installazione dell'agente Basic o Standard
Configurazione di base: gli agenti usano risorse di ricerca e archiviazione multi-tenant completamente gestite da Microsoft. Non si ha visibilità o controllo su queste risorse di Azure sottostanti.
Configurazione standard: gli agenti usano risorse di ricerca e archiviazione a tenant singolo di proprietà del cliente. Con questa configurazione, si ha il controllo completo e la visibilità su queste risorse, ma si comportano costi in base all'utilizzo.
Nota
È possibile usare i modelli bicep automatizzati seguenti per eseguire un agente standard o basic. È anche possibile creare un agente di base usando il portale di Azure AI Foundry. Azure AI Foundry attualmente non supporta la configurazione dell'agente standard.
| Descrizione e distribuzione automatica | Diagramma (fare clic per ingrandire) |
|---|---|
| Distribuire una configurazione dell'agente di base che usa l'identità gestita per l'autenticazione. Le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'account di archiviazione e i servizi di intelligenza artificiale vengono create automaticamente. L'account dei servizi di intelligenza artificiale è connesso al progetto e all'hub e un modello gpt-4o-mini viene distribuito nell'area eastus. Un insieme di credenziali delle chiavi gestito da Microsoft viene usato per impostazione predefinita. |
|
| Distribuire una configurazione standard dell'agente che usa l'identità gestita per l'autenticazione. Vengono create automaticamente le risorse per l'hub di intelligenza artificiale, il progetto di intelligenza artificiale, l'insieme di credenziali delle chiavi, l'account di archiviazione, i servizi di intelligenza artificiale e la ricerca di intelligenza artificiale. I servizi di intelligenza artificiale, la ricerca di intelligenza artificiale, l'insieme di credenziali delle chiavi e l'account di archiviazione sono connessi al progetto e all'hub. Un modello gpt-4o-mini viene distribuito nell'area eastus. |
|
[Facoltativo] Selezione del modello nel modello di distribuzione automatica
È possibile personalizzare il modello usato dall'agente modificando i parametri del modello nel modello di distribuzione automatica. Per distribuire un modello diverso, è necessario aggiornare almeno i modelName parametri e modelVersion .
Per impostazione predefinita, il modello di distribuzione è configurato con i valori seguenti:
| Parametro del modello | Valore predefinito |
|---|---|
| modelName | gpt-4o-mini |
| modelFormat | OpenAI (per Azure OpenAI) |
| modelVersion | 18-07-2024 |
| modelSkuName | GlobalStandard |
| modelLocation | eastus |
Importante
Non modificare il parametro modelFormat.
I modelli supportano solo la distribuzione di modelli OpenAI di Azure. Vedere quali modelli OpenAI di Azure sono supportati nella documentazione del supporto del modello del servizio Azure AI Agent.
[Facoltativo] Usare le proprie risorse durante la configurazione dell'agente
Nota
Se si usa una risorsa di Servizi di intelligenza artificiale o OpenAI di Azure esistente, non verrà distribuito alcun modello. È possibile distribuire un modello nella risorsa al termine dell'installazione dell'agente.
Usare una risorsa di intelligenza artificiale esistente, Azure OpenAI, Ricerca di intelligenza artificiale e/o Archiviazione BLOB di Azure fornendo l'ID risorsa arm completo nel file dei parametri:
aiServiceAccountResourceIdaiSearchServiceResourceIdaiStorageAccountResourceId
Se si vuole usare una risorsa OpenAI di Azure esistente, è necessario aggiornare aiServiceAccountResourceId e i aiServiceKind parametri nel file dei parametri. Il aiServiceKind parametro deve essere impostato su AzureOpenAI.
Per altre informazioni, vedere come usare le proprie risorse.
Configurare ed eseguire un agente
| Componente | Descrizione |
|---|---|
| Agente | Intelligenza artificiale personalizzata che usa i modelli di intelligenza artificiale in combinazione con gli strumenti. |
| Strumento | Gli strumenti consentono di estendere la capacità di un agente di rispondere in modo affidabile e accurato durante la conversazione. Ad esempio la connessione alle knowledge base definite dall'utente al modello o l'abilitazione della ricerca Web per fornire informazioni correnti. |
| Thread | Sessione di conversazione tra un agente e un utente. I thread archiviano messaggi e gestiscono automaticamente il troncamento per adattare il contenuto al contesto di un modello. |
| Message | Messaggio creato da un agente o da un utente. I messaggi possono includere testo, immagini e altri file. I messaggi vengono archiviati come elenco nel thread. |
| Run | Attivazione di un agente per iniziare l'esecuzione in base al contenuto di Thread. L'agente usa la configurazione e i messaggi del thread per eseguire attività chiamando modelli e strumenti. Nell'ambito di un'operazione Run, l'agente aggiunge messaggi al thread. |
| Eseguire il passaggio | Elenco dettagliato dei passaggi eseguiti dall'agente come parte di un'esecuzione. Un agente può chiamare strumenti o creare messaggi durante l'esecuzione. L'analisi dei passaggi di esecuzione consente di comprendere in che modo l'agente ottiene i risultati. |
Per autenticare le richieste API, usare il comando az login per accedere alla sottoscrizione di Azure.
az login
Successivamente, sarà necessario recuperare il token Entra ID per fornire come autorizzazione alle chiamate API. Recuperare il token usando il comando dell'interfaccia della riga di comando:
az account get-access-token --resource 'https://ml.azure.com/' | jq -r .accessToken | tr -d '"'
Impostare il token di accesso come variabile di ambiente denominata AZURE_AI_AGENTS_TOKEN.
Per effettuare correttamente chiamate API REST al servizio Agenti di intelligenza artificiale di Azure, è necessario usare l'endpoint come indicato di seguito:
https://<HostName>/agents/v1.0/subscriptions/<AzureSubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.MachineLearningServices/workspaces/<ProjectName>
HostName è disponibile passando all'oggetto discovery_url e rimuovendo l'oggetto iniziale https:// e finale /discovery. Per trovare discovery_url, eseguire questo comando dell'interfaccia della riga di comando:
az ml workspace show -n {project_name} --subscription {subscription_name} --resource-group {resource_group_name} --query discovery_url
Ad esempio, l'endpoint potrebbe essere simile al seguente:
https://eastus.api.azureml.ms/agents/v1.0/subscriptions/12345678-abcd-1234-abcd-123456789000/resourceGroups/my-resource-group/providers/Microsoft.MachineLearningServices/workspaces/my-project-name
Impostare questo endpoint come variabile di ambiente denominata AZURE_AI_AGENTS_ENDPOINT.
Creare un agente
Nota
Con il servizio Azure AI Agents il model parametro richiede il nome della distribuzione del modello. Se il nome della distribuzione del modello è diverso dal nome del modello sottostante, è necessario modificare il codice in "model": "{your-custom-model-deployment-name}".
curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"instructions": "You are a helpful agent.",
"name": "my-agent",
"tools": [{"type": "code_interpreter"}],
"model": "gpt-4o-mini"
}'
Creare un thread
curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
-d ''
Aggiungere una domanda utente al thread
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"role": "user",
"content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
}'
Eseguire il thread
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "asst_abc123",
}'
Recuperare lo stato dell'esecuzione
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"
Recuperare la risposta dell'agente
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"