Registrare e gestire agenti personalizzati

Microsoft Foundry Control Plane offre una gestione e un'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 Azure gratuito, che include una prova 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 l'emissione di dati per aiutarti 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 (la risorsa)

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 proprietà seguenti descrivono l'agente mentre viene eseguito sulla sua piattaforma:

   Proprietà	Descrizione	Obbligatorio
   URL dell'agente	L'endpoint (URL) 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 l'agente usa l'OpenAI Chat Completions API, si indica https://<host>/v1/ senza /chat/completions perché i clienti lo aggiungono in genere.	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 dell'agente A2A	Percorso della specifica JSON della carta dell'agente. Se non lo si specifica, il sistema usa il valore predefinito /.well-known/agent-card.json.	Sì, quando il protocollo è A2A
   ID agente OpenTelemetry	ID dell'agente che l'agente utilizza per emettere tracce secondo le convenzioni semantiche di 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	Il progetto dove si effettua la registrazione dell'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 acquisire 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. Nell'elenco degli agenti, selezionare il pulsante di selezione accanto al nome dell'agente personalizzato per aprire il pannello delle informazioni. Non selezionare il nome dell'agente, perché quel collegamento porta via dal riquadro Assets.

2. Nel riquadro informazioni, 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 dall'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'opzione radio accanto all'agente che si vuole bloccare. Viene visualizzato il riquadro informazioni. Non selezionare il nome dell'agente, perché il collegamento si allontana dal riquadro Asset .

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 continuano a funzionare nell'infrastruttura associata, ma non possono accettare richieste in entrata. 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:

• Eseguire
• 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 il pulsante di opzione accanto all'agente per aprire il pannello delle informazioni. Non selezionare il nome dell'agente, perché il collegamento si allontana dal riquadro Asset .

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 l'Agent Protocol di LangChain. I clienti usano il percorso /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).

Instrumentare agenti di codice personalizzati

Se si compila l'agente usando codice personalizzato, instrumentare la soluzione per generare tracce in base allo 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 dell'agente, inclusi i richiami agli strumenti e le interazioni del modello. 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]

Instrumentare quindi l'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 emettendo automaticamente tracciamenti 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 in una soluzione di piattaforma che supporta OpenTelemetry ma non supporta Application Insights, distribuire un agente di raccolta OpenTelemetry e configurare il software per inviare dati OTLP all'agente di raccolta (configurazione OpenTelemetry standard).

Configurare il collettore con l'utilità di esportazione dell'Monitoraggio di Azure per inoltrare i dati ad Application Insights utilizzando 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