Externe Agenten für Beobachtbarkeit und Auswertung registrieren (Vorschau)

mit Microsoft Foundry Agent Service können Sie Agents registrieren, die außerhalb von Foundry ausgeführt werden, auf jeder Cloud, lokal oder einem anderen Host, sodass Sie die Ablaufverfolgungsansicht und Auswertungserfahrung von Foundry verwenden können. Foundry speichert nur Registrierungsmetadaten für diese Agents. Sie hostet die Runtime nicht, fungiert nicht als Proxy und ruft sie nicht auf.

Externe Agents unterscheiden sich von benutzerdefinierten Agents der Steuerungsebene, die den Datenverkehr über ein AI-Gateway weiterleiten. Mit externen Agents behält Ihr Agent seinen vorhandenen Endpunkt bei und teilt nur die OpenTelemetry-Telemetrie. Es ist kein KI-Gateway erforderlich.

In diesem Artikel erfahren Sie, wie Sie:

• Instrumentieren Sie einen externen Agent, damit er OpenTelemetry-Spans an Application Insights ausgibt.
• Registrieren Sie den Agenten in Foundry als external-Agenten.
• Überprüfen Sie die Traces im Foundry-Portal.
• Führen Sie eine auf dem Trace basierende Bewertung für die erfasste Telemetrie des Agents aus.

Das folgende Diagramm zeigt den Datenfluss: Ihr externer Agent sendet OpenTelemetry-Spans mit einem gen_ai.agent.id-Attribut an eine mit Ihrem Foundry-Projekt verbundene Application Insights-Ressource. Ein separater Registrierungsaufruf erstellt den Agentdatensatz in Foundry. Das Foundry-Portal gleicht daraufhin Traces nach Agent-ID ab und zeigt sie in der Trance-Ansicht des Agents an.

Voraussetzungen

• Ein Foundry-Projekt, das mit einer Application Insights-Ressource verbunden ist.

• Ein Agent, der außerhalb von Foundry ausgeführt wird und OpenTelemetry ausgeben kann, erstreckt sich auf diese Application Insights-Ressource.

• Python 3.11 oder höher.

• Foundry User-Rolle im Projekt.

• Leser-Rolle oder Überwachungsleser-Rolle für die verbundene Application Insights-Ressource, um Traces anzuzeigen.

  Important

  Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

• DefaultAzureCredential Konfiguriert. Melden Sie sich mit az login an, oder richten Sie eine verwaltete Identität oder einen Dienstprinzipal ein.

• (Nur zur Auswertung) Eine Azure OpenAI-Bereitstellung mit einem GPT-Modell, das den Chatabschluss unterstützt (z. B. gpt-5-mini).

Instrumentieren des externen Agents mit OpenTelemetry

Bevor Sie den Agent in Foundry registrieren, konfigurieren Sie ihn so, dass OpenTelemetry-Spans an die mit Ihrem Foundry-Projekt verbundene Application Insights-Ressource exportiert werden. Jeder Bereich muss das gen_ai.agent.id Attribut tragen, damit Foundry die Spanne der richtigen Agent-Registrierung zuordnen kann.

Installieren des Microsoft OpenTelemetry-Pakets

pip install "microsoft-opentelemetry[langchain]"

Konfigurieren des Exporters

Führen Sie diesen Code einmal beim Starten des Agents aus, bevor Sie Frameworkimporte durchführen, die instrumentiert werden sollten:

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,
        },
    },
)

Legen Sie die APPLICATIONINSIGHTS_CONNECTION_STRING Umgebungsvariable auf dem Host fest, auf dem der Agent ausgeführt wird. Verwenden Sie die Verbindungszeichenfolge aus der Application Insights-Ressource, die mit Ihrem Foundry-Projekt verknüpft ist. Um die Verbindungszeichenfolge zu finden, öffnen Sie das Foundry-Portal, navigieren Sie zu Ihrem Projekt und wählen Sie Verwalten>>. Wählen Sie die Application Insights-Ressource aus, um die Verbindungszeichenfolge anzuzeigen. Öffnen Sie alternativ die Application Insights-Ressource direkt im Azure-Portal, und kopieren Sie die Verbindungszeichenfolge von der Seite Overview.

Nach der Konfiguration werden nachfolgende OpenTelemetry-Spans aus Ihrem Agent-Framework automatisch an Application Insights weitergeleitet. Jeder Span muss das gen_ai.agent.id-Attribut auf den Wert setzen, den Sie bei der Registrierung als otel_agent_id auswählen.

Wenn Ihr Agent-Framework dieses Attribut nicht automatisch festgelegt hat, fügen Sie es manuell hinzu:

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 ...

Registrieren des externen Agents in Foundry

Nachdem der Agent Spans an Application Insights ausgibt, registrieren Sie ihn in Foundry, damit diese Spans in der auf den Agent eingegrenzten Foundry-Traceansicht angezeigt werden. Durch die Registrierung wird in Foundry ein benannter Datensatz erstellt, der eingehende Traces (Abgleich über gen_ai.agent.id) mit der Foundry-Agent-Erfahrung verknüpft. Ohne diese Registrierung fließen Traces weiterhin in Application Insights, werden jedoch nicht in der Traceansicht für den Foundry-Agent angezeigt, und Sie können keine tracebasierten Auswertungen ausführen, die auf den Agent beschränkt sind.

Das SDK installieren

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

Erstellen der Registrierung

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

Überprüfen Sie die Traces im Foundry-Portal

Nachdem der Agent Datenverkehr sendet und Spans in Application Insights erfasst wurden (in der Regel nach 2 bis 5 Minuten), überprüfen Sie, ob im Foundry-Portal Traces angezeigt werden:

1. Öffnen Sie das Foundry-Portal.

2. Navigiere zu deinem Projekt.

3. Wählen Sie "Agents" im linken Bereich aus.

4. Wählen Sie den Namen des externen Agents aus (z. B. Reiseplaner-Agent).

5. Wählen Sie die Registerkarte Traces aus, um die diesem Agenten zugeordneten Spans anzuzeigen.

Traces werden über die gen_ai.agent.id = <otel_agent_id> aus der Application Insights-Ressource abgeglichen, die mit dem Projekt verbunden ist. Sie können Eingaben, Ausgaben, Toolaufrufe und Latenz für jeden Bereich anzeigen.

Eine trace-basierte Evaluierung ausführen

Nachdem Ablaufverfolgungen in Application Insights eingegangen sind, können Sie Auswertungen direkt anhand dieser Ablaufverfolgungen durchführen. Die Erstellung eines separaten Datensatzes ist nicht erforderlich. Foundry löst Traces auf, indem die (project, agent_id) innerhalb eines Rückblickfensters abgeglichen wird.

otel_agent_id des Agenten auflösen

Um die ID des Agenten für Traces abzurufen, verwenden Sie Folgendes:

# 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;

Erstellen und Ausführen der Auswertung

Verwenden Sie die otel_agent_id, um eine Auswertung der Traces anhand der vom Agent erfassten Telemetriedaten auszuführen. Eine vollständige exemplarische Vorgehensweise, die auch die Erstellung einer Bewertungsgruppe, die Konfiguration von Testkriterien und die Interpretation von Ergebnissen umfasst, finden Sie unter Trace-Bewertung (Vorschau).

Verwalten externer Agents

Verwenden Sie die gleichen SDK-Methoden zum Auflisten, Abrufen und Löschen externer Agents.

Externe Agents auflisten

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);
}

Löschen eines externen Agents

# 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 });

Referenz: AIProjectClient

Durch das Löschen der Registrierung wird der Agent aus dem Foundry-Portal entfernt, und in der Trace-Ansicht des Foundry-Agents werden keine Traces mehr angezeigt. Die Spans verbleiben in Application Insights, und der ausgeführte Agent ist davon nicht betroffen.

Problembehandlung

Problembehandlung bei fehlenden Traces

Wenn keine Spuren angezeigt werden, überprüfen Sie die folgenden Punkte:

Weitere Anleitungen zur Problembehandlung finden Sie unter Problembehandlung bei Auswertungen und Beobachtbarkeitsproblemen.

Beheben von Registrierungsfehlern

Wenn create_version() (Python) oder createVersion() (JavaScript/TypeScript) fehlschlägt, überprüfen Sie die folgenden Elemente:

Aktuelle Einschränkungen

Die folgenden Foundry-Features werden für externe Agents derzeit nicht unterstützt:

• Menschliche Auswertung – Manuelle Überprüfungsworkflows sind für extern registrierte Agents nicht verfügbar.
• Konvertieren von Agentablaufverfolgungen in Auswertungsdatensets – Die Konvertierung von Ablaufverfolgungen in Datensätze wird für externe Agents nicht unterstützt.
• KI Red Teaming — Red-Teaming-Scans können nicht auf externe Agenten abzielen.

Verwandte Inhalte

• Übersicht über die Agent-Nachverfolgung
• Ablaufverfolgung in Microsoft Foundry einrichten
• Konfiguriere die Ablaufverfolgung für KI-Agent-Frameworks
• Bewerten Sie Ihre KI-Agenten
• Benutzerdefinierte Agenten registrieren und verwalten (Control Plane)
• Integrierte Evaluatoren
• Übersicht über Azure Monitor OpenTelemetry
• Ausführen von Cloud-Auswertungen