Registrare agenti esterni per l'osservabilità e la valutazione (anteprima)

Microsoft Foundry Agent Service consente di registrare agenti in esecuzione all'esterno di Foundry, in qualsiasi cloud, in locale o su un altro host, in modo da poter utilizzare la vista di traccia e le funzionalità di valutazione di Foundry. Foundry archivia solo i metadati di registrazione per questi agenti. Non ospita, proxy o richiama il runtime.

Gli agenti esterni differiscono dagli agenti personalizzati del piano di controllo, che instradano il traffico attraverso un gateway di intelligenza artificiale. Con gli agenti esterni, l'agente mantiene l'endpoint esistente e condivide solo i dati di telemetria OpenTelemetry. Non è necessario alcun gateway di intelligenza artificiale.

In questo articolo vengono illustrate le operazioni seguenti:

• Configurare un agente esterno per inviare gli span di OpenTelemetry ad Application Insights.
• Registra l'agente in Foundry come agente external.
• Verifica le tracce nel portale Foundry.
• Eseguire una valutazione basata sulle tracce della telemetria raccolta dall'agente.

Il diagramma seguente illustra il flusso di dati: l'agente esterno genera intervalli OpenTelemetry con un gen_ai.agent.id attributo a una risorsa di Application Insights connessa al progetto Foundry. Una chiamata di registrazione separata crea il record dell'agente in Foundry. Il portale Foundry abbina quindi le tracce in base all'ID dell’agente e le visualizza nella vista delle tracce dell’agente.

Prerequisiti

• Progetto Foundry con una risorsa di Application Insights connessa.

• Un agente in esecuzione al di fuori di Foundry in grado di inviare span OpenTelemetry a quella risorsa di Application Insights.

• Python 3.11 o versione successiva.

• Ruolo Foundry User nel progetto.

• Ruolo lettore o ruolo lettore di monitoraggio nella risorsa di Application Insights connessa per visualizzare le tracce.

  Importante

  I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

• DefaultAzureCredential configurato. Accedi con az login oppure configura un'identità gestita o un entità di servizio.

• (solo per la valutazione) Una distribuzione OpenAI Azure con un modello GPT che supporta il completamento della chat (ad esempio, gpt-5-mini).

Instrumentare l'agente esterno con OpenTelemetry

Prima di registrare l'agente in Foundry, configuralo per esportare gli span OpenTelemetry nella risorsa Application Insights collegata al tuo progetto Foundry. Ogni intervallo deve contenere l'attributo gen_ai.agent.id in modo che Foundry possa attribuire l'intervallo alla registrazione corretta dell'agente.

Installare il pacchetto OpenTelemetry Microsoft

pip install "microsoft-opentelemetry[langchain]"

Configurare l'esportatore

Eseguire questo codice una volta durante l'avvio dell'agente, prima di qualsiasi importazione del framework che deve essere instrumentata:

import os

os.environ.setdefault("AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING", "true")
os.environ.setdefault("OTEL_SEMCONV_STABILITY_OPT_IN", "gen_ai_latest_experimental")
os.environ.setdefault("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "SPAN_AND_EVENT")

from microsoft.opentelemetry import use_microsoft_opentelemetry

# Human-readable name for the agent
AGENT_NAME = os.environ.get("AGENT_NAME", "weather-agent")
# Unique ID emitted as gen_ai.agent.id on every span.
# Foundry matches traces to registrations by this value.
OTEL_AGENT_ID = os.environ.get("OTEL_AGENT_ID", f"{AGENT_NAME}-v1")

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    azure_monitor_connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"],
    sampling_ratio=1.0,
    instrumentation_options={
        "fastapi": {"enabled": False},
        "langchain": {
            "enabled": True,
            "agent_id": OTEL_AGENT_ID,
            "agent_name": AGENT_NAME,
        },
    },
)

Impostare la APPLICATIONINSIGHTS_CONNECTION_STRING variabile di ambiente nell'host in cui viene eseguito l'agente. Usa la stringa di connessione della risorsa Application Insights associata al progetto Foundry. Per trovare la stringa di connessione, apri il portale Foundry, passa al tuo progetto e seleziona Gestisci>Dettagli del progetto>Risorse connesse. Selezionare la risorsa di Application Insights per visualizzarne il stringa di connessione. In alternativa, aprire la risorsa di Application Insights direttamente nel portale di Azure e copiare il stringa di connessione dalla pagina Overview.

Dopo la configurazione, i successivi span di OpenTelemetry dal framework dell'agente vengono inviati automaticamente ad Application Insights. Ogni span deve impostare l'attributo gen_ai.agent.id sul valore che hai scelto come otel_agent_id durante la registrazione.

Se il framework agente non imposta automaticamente questo attributo, aggiungerlo manualmente:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("agent-run") as span:
    span.set_attribute("gen_ai.agent.id", "travel-planner-agent-v1")
    # ... your agent logic ...

Registrare l'agente esterno in Foundry

Dopo che l'agente ha inviato gli span ad Application Insights, registralo in Foundry in modo che tali span vengano visualizzati nella vista delle tracce di Foundry relativa all'agente. La registrazione crea in Foundry un record con nome che collega le tracce in arrivo (associate tramite gen_ai.agent.id) all'interfaccia dell'agente di Foundry. Senza questa registrazione, le tracce continuano a fluire in Application Insights, ma non vengono visualizzate nella vista delle tracce dell'agente in Foundry e non è possibile eseguire valutazioni basate sulle tracce circoscritte all'agente.

Installare l'SDK

pip install azure-ai-projects>=2.3.0 azure-identity>=1.17.0

Creare la registrazione

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ExternalAgentDefinition
from azure.identity import DefaultAzureCredential

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

# Create the project client with preview features enabled.
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

# Register the externally hosted agent.
agent = project.agents.create_version(
    agent_name="travel-planner-agent",
    description="Travel planning agent hosted externally.",
    definition=ExternalAgentDefinition(
        # Set explicitly when the running agent emits a gen_ai.agent.id
        # value that differs from the Foundry agent name.
        otel_agent_id="travel-planner-agent-v1",
    ),
)

print(f"Registered external agent: {agent.name}")
print(f"Resolved otel_agent_id: {agent.versions.latest.definition.otel_agent_id}")

Registered external agent: travel-planner-agent
Resolved otel_agent_id: travel-planner-agent-v1

npm install @azure/ai-projects @azure/identity

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

const agentName = "travel-planner-agent";
// Set explicitly when the running agent emits a gen_ai.agent.id value
// that differs from the Foundry agent name.
const otelAgentId = "travel-planner-agent-v1";

// Register the externally hosted agent. External agents are a preview
// feature, so the `ExternalAgents=V1Preview` opt-in is required.
const agent = await project.agents.createVersion(
  agentName,
  {
    kind: "external",
    otel_agent_id: otelAgentId,
  },
  {
    foundryFeatures: "ExternalAgents=V1Preview",
    description: "Travel planning agent hosted externally.",
  },
);

console.log(`Registered external agent: ${agent.name}`);
console.log(`Resolved otel_agent_id: ${otelAgentId}`);

Registered external agent: travel-planner-agent
Resolved otel_agent_id: travel-planner-agent-v1

Verificare le tracce nel portale di Foundry

Dopo che l'agente ha inviato il traffico e i dati di acquisizione ad Application Insights (in genere 2–5 minuti), verificare che le tracce siano visibili nel portale Foundry:

1. Aprire il portale Foundry.

2. Vai al tuo progetto.

3. Selezionare Agenti nel riquadro sinistro.

4. Selezionare il nome dell'agente esterno, ad esempio travel-planner-agent.

5. Selezionare la scheda Tracce per visualizzare gli intervalli attribuiti a questo agente.

Le tracce vengono abbinate tramite gen_ai.agent.id = <otel_agent_id> dalla risorsa Application Insights collegata al progetto. È possibile visualizzare input, output, chiamate agli strumenti e latenza per ogni intervallo.

Eseguire una valutazione basata su traccia

Dopo il flusso delle tracce in Application Insights, è possibile eseguire valutazioni direttamente su tali tracce. Non è necessaria alcuna costruzione di set di dati separata. Foundry risolve le tracce abbinando i tag (project, agent_id) in una finestra di lookback.

Risolvere l'otel_agent_id dell'agente

Per ottenere l'ID dell'agente per le tracce, usare quanto segue:

# Retrieve the registered agent and its resolved otel_agent_id.
agent = project.agents.get(agent_name="travel-planner-agent")
otel_agent_id = agent.versions.latest.definition.otel_agent_id

// Retrieve the registered agent and its resolved otel_agent_id.
const agent = await project.agents.get("travel-planner-agent");
const definition = agent.versions.latest.definition;
if (definition.kind !== "external") {
  throw new Error(
    `Expected an external agent definition, got "${definition.kind}".`,
  );
}
const otelAgentId = definition.otel_agent_id;

Creare ed eseguire la valutazione

Utilizza il tag otel_agent_id per eseguire una valutazione della traccia sui dati telemetrici raccolti dall'agente. Per la guida dettagliata completa, incluse le istruzioni per creare un gruppo di valutazione, configurare i criteri di test e interpretare i risultati, vedere Valutazione della traccia (anteprima).

Gestire agenti esterni

Usare gli stessi metodi SDK per elencare, recuperare ed eliminare agenti esterni.

Elencare gli agenti esterni

agents = project.agents.list(kind="external")
for a in agents:
    print(a.name)

const agents = project.agents.list({ kind: "external" });
for await (const agent of agents) {
  console.log(agent.name);
}

Eliminare un agente esterno

# Delete the registration. This does not affect the running agent.
# force=True removes all internal revisions of the agent atomically.
project.agents.delete(agent_name="travel-planner-agent", force=True)

// Delete the registration. This does not affect the running agent.
// force: true removes all internal revisions of the agent atomically.
await project.agents.delete("travel-planner-agent", { force: true });

Riferimento: AIProjectClient

L'eliminazione della registrazione rimuove l'agente dal portale Foundry e fa sì che le tracce non vengano più visualizzate nella vista tracce dell'agente di Foundry. Gli intervalli rimangono in Application Insights e l'agente in esecuzione non ne risente.

Risoluzione dei problemi

Risolvere i problemi relativi alle tracce mancanti

Se non vengono visualizzate tracce, controllare gli elementi seguenti:

Per altre indicazioni sulla risoluzione dei problemi, vedere Risolvere i problemi di valutazione e osservabilità.

Risolvere gli errori di registrazione

Se create_version() (Python) o createVersion() (JavaScript/TypeScript) ha esito negativo, controllare gli elementi seguenti:

Limitazioni correnti

Le funzionalità foundry seguenti non sono attualmente supportate per gli agenti esterni:

• Valutazione umana : i flussi di lavoro di revisione manuale non sono disponibili per gli agenti registrati esternamente.
• Convertire le tracce dell'agente in set di dati di valutazione : la conversione da traccia a set di dati non è supportata per gli agenti esterni.
• Red teaming dell'IA: le analisi di red teaming non possono avere come oggetto agenti esterni.

Contenuti correlati

• Panoramica del tracciamento degli agenti
• Configurare il tracciamento in Microsoft Foundry
• Configurare il tracciamento per i framework di agenti di intelligenza artificiale
• Valutare gli agenti di intelligenza artificiale
• Registrare e gestire agenti personalizzati (piano di controllo)
• Analizzatori predefiniti
• Panoramica di OpenTelemetry per Monitoraggio di Azure
• Avviare valutazioni cloud