Registrare e gestire agenti personalizzati

Piano di controllo Foundry di Microsoft fornisce gestione e osservabilità centralizzate per gli agenti in esecuzione su piattaforme e infrastrutture diverse. È possibile registrare agenti personalizzati eseguiti in Azure servizi di calcolo o in altri ambienti cloud per ottenere visibilità nelle operazioni e controllarne il comportamento.

Questo articolo illustra come registrare un agente personalizzato nel piano di controllo Foundry. Si apprenderà come configurare l'agente per la registrazione, configurare la raccolta dati e usare le funzionalità di gestione di Foundry Control Plane.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Se non ne hai uno, crea un account gratuito Azure, che include una sottoscrizione di valutazione gratuita.

• Progetto Foundry. Se non ne hai uno, crea un progetto.

• Un gateway di intelligenza artificiale configurato nella risorsa Foundry. Foundry usa Gestione API di Azure per registrare gli agenti come API.

• Un agente che viene distribuito ed esposto tramite un endpoint raggiungibile. L'endpoint può essere un endpoint pubblico o un endpoint raggiungibile dalla rete in cui si distribuisce la risorsa Foundry.

Aggiungere un agente personalizzato

È possibile registrare un agente personalizzato nel piano di controllo Foundry. Sviluppare l'agente nella tecnologia preferita, sia per le soluzioni di piattaforma che per l'infrastruttura.

Quando si registra un agente personalizzato, Foundry usa Gestione API per fungere da proxy per le comunicazioni con l'agente, in modo da poter controllare l'accesso e monitorare l'attività.

Il diagramma seguente mostra l'architettura risultante quando si registra un agente personalizzato.

Verificare l'agente

Verificare che l'agente soddisfi i requisiti per la registrazione:

Preparare il progetto Foundry

Prima di registrare l'agente personalizzato aggiunto a un progetto Foundry, assicurarsi di aver configurato correttamente il progetto:

1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).

   

2. Assicurarsi che un gateway di intelligenza artificiale sia configurato nel progetto:

   1. Sulla barra degli strumenti selezionare Opera.

   2. Nel riquadro sinistro selezionare Amministratore.

   3. Aprire la scheda Gateway di intelligenza artificiale .

   4. Il riquadro elenca tutti i gateway di intelligenza artificiale configurati e mappati a una risorsa Foundry. Controllare se la risorsa Foundry che si vuole usare ha un gateway di intelligenza artificiale associato.

      

   5. Se la risorsa Foundry che si vuole usare non dispone di un gateway di intelligenza artificiale configurato (non elencato), aggiungerne uno usando l'opzione Aggiungi gateway di intelligenza artificiale .

      Un gateway di intelligenza artificiale è gratuito per configurare e sbloccare potenti funzionalità di governance, ad esempio sicurezza, dati di diagnostica e limiti di frequenza per agenti, strumenti e modelli. Per altre informazioni, vedere Creare un gateway di intelligenza artificiale.

3. Assicurarsi di avere configurato l'osservabilità nel progetto. Foundry Control Plane usa la risorsa di Application Insights associata al progetto selezionato per emettere dati che aiutano a diagnosticare il tuo agente.

   1. Sulla barra degli strumenti selezionare Opera.

   2. Nel riquadro sinistro selezionare Amministratore.

   3. In Tutti i progetti usare la casella di ricerca per cercare il progetto.

   4. Selezionare il progetto.

   5. Selezionare la scheda Risorse connesse .

   6. Assicurarsi che sia presente una risorsa associata nella categoria AppInsights .

      

   7. Se non è presente alcuna risorsa associata, aggiungerne una selezionando Aggiungi connessione>Application Insights.

Il progetto è configurato per l'osservabilità e il tracciamento.

Registrare l'agente (asset)

1. Sulla barra degli strumenti selezionare Opera.

2. Nel riquadro Panoramica selezionare Registra risorsa.

   

3. Verrà visualizzata la procedura guidata di registrazione. Prima di tutto, completare i dettagli sull'agente da registrare. Le seguenti proprietà descrivono l'agente mentre è in esecuzione sulla sua piattaforma.

   Proprietà	Descrizione	Obbligatorio
   URL dell'agente	L'URL dell'endpoint in cui viene eseguito l'agente e riceve le richieste. In generale, ma a seconda del protocollo, si indica l'URL di base usato dai client. Ad esempio, se il tuo agente utilizza l'API di completamento chat di OpenAI, si indica https://<host>/v1/ senza /chat/completions perché generalmente i client lo aggiungono.	Sì
   Protocollo	Protocollo di comunicazione supportato dall'agente. Usare HTTP in generale. In alternativa, se l'agente supporta A2A in modo più specifico, indicarne uno.	Sì
   URL della scheda agente A2A	Percorso della specifica JSON della scheda dell'agente. Se non lo si specifica, il sistema usa il valore predefinito /.well-known/agent-card.json.	No
   ID agente OpenTelemetry	ID agente che il tuo agente utilizza per emettere tracce secondo le convenzioni semantiche OpenTelemetry per l'intelligenza artificiale generativa. Le tracce lo indicano nell'attributo gen_ai.agent.id per gli intervalli con il nome create_agent dell'operazione. Se non si specifica questo valore, il sistema usa il valore del nome dell'agente per trovare tracce e log segnalati da questo nuovo agente.	No
   URL del portale di amministrazione	URL del portale di amministrazione in cui è possibile eseguire altre operazioni di amministrazione per questo agente. Foundry può archiviare questo valore per praticità. Foundry non ha accesso per eseguire operazioni direttamente in questo portale.	No

4. Configurare la modalità di visualizzazione dell'agente nel piano di controllo Foundry:

   Proprietà	Descrizione	Obbligatorio
   Project	Progetto in cui si registra l'agente. Foundry usa il gateway di intelligenza artificiale configurato nella risorsa che contiene il progetto per configurare l'endpoint in ingresso per l'agente. È possibile selezionare solo i progetti con un gateway di intelligenza artificiale abilitato nelle risorse. Se non vengono visualizzati gateway di intelligenza artificiale, configurare un gateway di intelligenza artificiale nella risorsa Foundry. È anche consigliabile configurare Application Insights nel progetto selezionato. Foundry utilizza la risorsa Application Insights del progetto per confluire tracce e log.	Sì
   Nome agente	Nome dell'agente che si vuole visualizzare in Foundry. Il sistema potrebbe anche usare questo nome per trovare tracce e log pertinenti in Application Insights se non si specifica un valore diverso per l'ID agente OpenTelemetry.	Sì
   Descrizione	Descrizione chiara di questo agente.	No

5. Salvare le modifiche.

6. Foundry aggiunge il nuovo agente. Per controllare l'elenco degli agenti, selezionare Risorse nel riquadro sinistro.

7. Per visualizzare solo gli agenti personalizzati, usare il filtro Origine e selezionare Personalizzato.

   

Collegare i clienti all'agente

Quando si registra l'agente in Foundry, si ottiene un nuovo URL che i client possono usare. Poiché Foundry funge da proxy per le comunicazioni con l'agente, può controllare l'accesso e monitorare l'attività.

Per distribuire il nuovo URL in modo che i client possano chiamare l'agente:

1. Selezionare l'agente personalizzato.

2. Nel riquadro dei dettagli, in URL agente selezionare l'opzione Copia .

   

3. Usare il nuovo URL per chiamare l'agente anziché l'endpoint originale.

In questo esempio si distribuisce un agente LangGraph. I client usano LangGraph SDK per utilizzarlo. Il client usa il nuovo valore dell'URL dell'agente . Questo codice crea un thread, invia un messaggio che chiede informazioni sul meteo e trasmette la risposta.

import asyncio
from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/")

async def stream_run():
    thread = await client.threads.create()
    input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}

    async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
        print(chunk)

asyncio.run(stream_run())

Output previsto: l'agente elabora il messaggio e trasmette le risposte come blocchi. Ogni blocco contiene risultati parziali dell'esecuzione dell'agente. Questi risultati possono includere chiamate di strumenti alla funzione meteo e la risposta finale sul meteo di Los Angeles.

Bloccare e sbloccare l'agente

Per gli agenti personalizzati, Foundry non ha accesso all'infrastruttura sottostante in cui viene eseguito l'agente, quindi le operazioni di avvio e arresto non sono disponibili. Foundry può tuttavia bloccare le richieste in ingresso all'agente in modo che i client non possano utilizzarlo. Questa funzionalità consente agli amministratori di disabilitare un agente se non funziona correttamente.

Per bloccare le richieste in ingresso all'agente:

1. Sulla barra degli strumenti selezionare Opera.

2. Nel riquadro sinistro selezionare Asset.

3. Selezionare l'agente che si vuole bloccare. Viene visualizzato il riquadro informazioni.

4. Selezionare Aggiorna stato e quindi Blocca.

   

5. Confermare l'operazione.

Dopo aver bloccato l'agente, il valore Di stato dell'agente in Foundry è Bloccato. Gli agenti nello stato Bloccato operano nell'infrastruttura associata, ma non possono accettare richieste in ingresso. Foundry blocca qualsiasi tentativo di interfacciarsi con l'agente.

Per sbloccare l'agente:

1. Selezionare Aggiorna stato e quindi Sblocca.

2. Confermare l'operazione.

Abilitare i dati di diagnostica per l'agente

Foundry usa lo standard openTelemetry open per comprendere le operazioni eseguite dagli agenti. Se il progetto ha configurato Application Insights, Foundry registra le richieste in Application Insights per impostazione predefinita. Foundry usa anche questi dati per calcolare:

• Eseguito
• Tasso di errore
• Utilizzo (se disponibile)

Per ottenere il livello di fedeltà migliore, Foundry prevede che gli agenti personalizzati siano conformi alle convenzioni semantiche per le soluzioni di intelligenza artificiale generative nello standard OpenTelemetry.

Visualizzare tracce e log inviati a Foundry

1. Sulla barra degli strumenti selezionare Opera.

2. Nel riquadro sinistro selezionare Asset.

3. Selezionare l'agente.

4. La sezione Tracce mostra una voce per ogni chiamata HTTP effettuata all'endpoint dell'agente.

   Per visualizzare i dettagli, selezionare una voce.

   

   Suggerimento

   In questo esempio è possibile vedere in che modo i client usano l'endpoint del nuovo agente per comunicare con l'agente. L'esempio mostra un agente servito con il protocollo dell'agente da LangChain. I clienti usano la route /runs/stream.

In questo esempio la traccia non include dettagli oltre il post HTTP. Il codice dell'agente non include altre strumentazioni. Nella sezione successiva si apprenderà come instrumentare il codice e ottenere dettagli come le chiamate agli strumenti e le chiamate LLM (Large Language Model).

Configurare agenti di codice personalizzati

Se costruisci il tuo agente usando codice personalizzato, configura la soluzione per generare tracce secondo lo standard OpenTelemetry e inviarle ad Application Insights. La strumentazione consente a Foundry di accedere a informazioni dettagliate sulle operazioni dell'agente.

Inviare tracce alla risorsa di Application Insights del progetto usando la relativa chiave di strumentazione. Per ottenere la chiave di strumentazione associata al progetto, seguire le istruzioni in Connettere Application Insights al progetto Foundry.

In questo esempio viene configurato un agente sviluppato con LangGraph per generare tracce nello standard OpenTelemetry. Il tracciatore acquisisce tutte le operazioni degli agenti, incluse le chiamate agli strumenti e le interazioni con i modelli. Il tracciare invia quindi le operazioni ad Application Insights per il monitoraggio.

Questo codice usa il pacchetto langchain-azure-ai . Per indicazioni sulla strumentazione di soluzioni specifiche con OpenTelemetry, a seconda del linguaggio di programmazione e del framework usati dalla soluzione, vedere API del linguaggio e SDK.

pip install -U langchain-azure-ai[opentelemetry]

Ora, strumenta il tuo agente:

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = "InstrumentationKey=12345678-..."

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

Output previsto: l'agente viene eseguito normalmente durante l'emissione automatica di tracce OpenTelemetry in Application Insights. Le tracce includono nomi delle operazioni, durate, chiamate di modelli, chiamate agli strumenti e utilizzo dei token. È possibile visualizzare queste tracce nel portale Foundry, nella sezione Tracce .

Soluzioni della piattaforma instrumentare

Se l'agente viene eseguito su una soluzione di piattaforma che supporta OpenTelemetry ma non supporta Application Insights, distribuisci un collector OpenTelemetry e configura il software per inviare dati in formato OTLP al collector (configurazione standard di OpenTelemetry).

Configurare il collettore con l'utilità di esportazione di Monitoraggio di Azure per inoltrare i dati ad Application Insights usando la stringa di connessione. Per informazioni dettagliate su come implementarla, vedere Configurare Monitoraggio di Azure OpenTelemetry.

Risolvere i problemi relativi alle tracce

Se non vengono visualizzate tracce, controllare gli elementi seguenti:

Contenuto correlato

• Che cos'è Microsoft Piano di controllo Foundry?
• Monitorare l'integrità e le prestazioni dell'agente nella flotta
• Ottimizzare i costi e le prestazioni del modello