Benutzerdefinierte Agenten zu externen Agenten migrieren

Registrieren Sie Ihren vorhandenen benutzerdefinierten Agent als externer Agent in Microsoft Foundry mithilfe derselben OpenTelemetry-Agent-ID. Halten Sie ihre Laufzeit, Azure API Management Gateway, Aufruf-URL, Authentifizierung und Richtlinien unverändert.

Die Registrierung externer Agenten verknüpft die Telemetrie Ihres Agenten mit Foundry. Es stellt keine Laufzeit bereit, ändert die API-Verwaltung oder ersetzt Ihre vorhandenen Gatewaysteuerelemente.

Prerequisites

• Ein vorhandener benutzerdefinierter Agent, der in Foundry Control Plane registriert ist.

• Dasselbe Foundry-Projekt und die verbundene Application Insights-Ressource wie für die Ablaufverfolgungen des benutzerdefinierten Agenten.

• Agentinstrumentation, die das gen_ai.agent.id Attribut ausgibt.

• Python 3.11 oder höher.

• PowerShell und die Azure CLI. Führen Sie die Befehle in diesem Artikel in derselben PowerShell-Sitzung aus.

• Verwenden Sie die Rolle Foundry User im Projekt, um den externen Agenten zu registrieren.

• Die Rolle Leser oder Überwachungsleser für die verbundene Application Insights-Ressource, um Ablaufverfolgungen 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.

Melden Sie sich im Verzeichnis an, das Ihr Foundry-Projekt enthält:

az login

Abrufen der vorhandenen OpenTelemetry-Agent-ID

Behalten Sie die vorhandene gen_ai.agent.id exakt bei. Generieren Sie keine neue ID und ersetzen Sie weder den Namen, den Anzeigenamen noch die Ressourcen-ID der API-Verwaltungs-API.

1. Öffnen Sie die Ablaufverfolgungsansicht Ihres vorhandenen benutzerdefinierten Agents in Foundry, und wählen Sie eine aktuelle Ablaufverfolgung aus.

2. Wählen Sie den agent span aus, und kopieren Sie sein gen_ai.agent.id Attribut.

3. Legen Sie den kopierten Wert in Ihrer PowerShell-Sitzung fest:

   $env:OTEL_AGENT_ID = "<gen_ai.agent.id-from-the-trace>"
   

Wenn das Attribut fehlt, überprüfen Sie die Instrumentierung des laufenden Agenten, bevor Sie fortfahren. Informationen zum Einrichten der Ablaufverfolgung finden Sie unter Einrichten der Ablaufverfolgung in Foundry.

Externen Agenten registrieren

Installieren Sie das SDK, und legen Sie den Foundry-Projektendpunkt fest, nicht die Gateway- oder Back-End-URL. Lassen Sie OTEL_AGENT_ID unverändert.

python -m pip install "azure-ai-projects>=2.3.0" azure-identity

$env:FOUNDRY_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"

Speichern Sie den folgenden Code als register_external_agent.py. Ersetzen Sie travel-planner durch den Namen eines nicht verwendeten Foundry-Agenten. Das SDK verwendet Ihre Azure CLI-Anmeldung und aktiviert mit allow_preview=True die Vorschau des externen Agenten.

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ExternalAgentDefinition
from azure.identity import AzureCliCredential

with AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=AzureCliCredential(),
    allow_preview=True,
) as project_client:
    registered = project_client.agents.create_version(
        agent_name="travel-planner",
        description="Travel planner hosted outside Foundry.",
        definition=ExternalAgentDefinition(
            otel_agent_id=os.environ["OTEL_AGENT_ID"],
        ),
    )
    saved = project_client.agents.get_version(
        agent_name=registered.name,
        agent_version=registered.version,
    )
    print(f"Registered agent: {saved.name}")
    print(f"OpenTelemetry agent ID: {saved.definition.otel_agent_id}")

Referenz: AIProjectClient, ExternalAgentDefinition, AgentsOperations und AzureCliCredential.

Führen Sie das Skript aus:

python register_external_agent.py

Die Ausgabe gibt die beibehaltene Telemetrie-ID an, z. B.:

Registered agent: travel-planner
OpenTelemetry agent ID: com.contoso.travel-planner

Wenn der Name bereits vorhanden ist, erstellt create_version eine weitere Registrierungsversion anstelle eines separaten Agenten.

Diese Beispiele zielen auf die öffentliche Azure-Cloud ab. Verwenden Sie für eine andere Cloud die von dieser Cloud unterstützten Foundry-Endpunkt- und SDK-Authentifizierungseinstellungen.

Aufrufe und Ablaufverfolgungen überprüfen

Senden Sie eine normale Anforderung über dieselbe Gateway-URL und Authentifizierung wie zuvor. Bestätigen Sie Folgendes:

• Der Agent antwortet weiterhin wie zuvor.
• Das SDK-Readback zeigt die vorhandene Telemetrie-ID an.
• Neue Ablaufverfolgungen werden unter dem externen Agent in Foundry angezeigt.

Behalten Sie die ursprüngliche benutzerdefinierte Agent-Registrierung und API-Verwaltungs-API bei. Die Registrierung externer Agenten leitet keinen Datenverkehr über einen Proxy weiter und bietet keine gatewaybasierte Blockierung; Ihr vorhandenes Gateway verarbeitet weiterhin Aufrufe.

Problembehandlung bei fehlenden Traces

Überprüfen Sie das Projekt, die verbundene Application Insights-Ressource, die genaue Telemetrie-ID, den Zeitraum, das Sampling und die Erfassungsverzögerung. Die Registrierung erstellt keine Spuren und kopiert keine historische Telemetrie.

Ersetzen Sie in Application Insights Logs die Beispiel-ID durch den Wert, den Sie aus der Ablaufverfolgung kopiert haben:

union requests, dependencies
| where ['timestamp'] > ago(30m)
| where tostring(['customDimensions']['gen_ai.agent.id'])
    == "com.contoso.travel-planner"
| project ['timestamp'], ['name'], ['operation_Id'],
    ['otelAgentId'] = tostring(['customDimensions']['gen_ai.agent.id'])
| order by ['timestamp'] desc
| take 20

Agentenspannen können in requests oder dependencies sein. Eine übereinstimmende Zeile bestätigt Erfassung und Identität. Vergewissern Sie sich außerdem, dass der Trace unter dem externen Agent in Foundry sichtbar ist.

Verwandte Inhalte

• Registrieren Sie externe Agenten für Observability und Bewertung.
• Verwalten vorhandener benutzerdefinierter Agents.
• Einrichten der Ablaufverfolgung in Foundry.