Registrieren und Verwalten von benutzerdefinierten Agents

Microsoft Foundry Control Plane bietet zentrale Verwaltung und Observierbarkeit für Agenten, die auf verschiedenen Plattformen und Infrastrukturen ausgeführt werden. Sie können benutzerdefinierte Agents registrieren, die in Azure Computediensten oder anderen Cloudumgebungen ausgeführt werden, um Einblicke in ihre Vorgänge zu erhalten und ihr Verhalten zu steuern.

In diesem Artikel erfahren Sie, wie Sie einen benutzerdefinierten Agent in foundry Control Plane registrieren. Sie erfahren, wie Sie Ihren Agent für die Registrierung konfigurieren, die Datensammlung einrichten und die Verwaltungsfunktionen von Foundry Control Plane verwenden.

Voraussetzungen

  • Ein AI-Gateway, das in Ihrer Foundry-Ressource konfiguriert ist. Foundry verwendet Azure API Management, um Agents als APIs zu registrieren.

  • Ein Agent, den Sie über einen erreichbaren Endpunkt bereitstellen und verfügbar machen. Der Endpunkt kann entweder ein öffentlicher Endpunkt oder ein Endpunkt sein, der über das Netzwerk erreichbar ist, in dem Sie die Foundry-Ressource bereitstellen.

Hinweis

Diese Funktion ist nur im Foundry-Portal (neu) verfügbar. Suchen Sie nach im Portalbanner, um sicherzustellen, dass Sie Foundry (neu) verwenden.

Hinzufügen eines benutzerdefinierten Agents

Sie können einen benutzerdefinierten Agent in foundry Control Plane registrieren. Entwickeln Sie den Agenten in der Technologie Ihrer Wahl für Plattform- und Infrastrukturlösungen.

Wenn Sie einen benutzerdefinierten Agent registrieren, verwendet Foundry DIE API-Verwaltung, um als Proxy für die Kommunikation mit Ihrem Agent zu fungieren, damit er den Zugriff steuern und Aktivitäten überwachen kann.

Das folgende Diagramm zeigt die resultierende Architektur, wenn Sie einen benutzerdefinierten Agent registrieren.

Diagramm, das die resultierende Architektur zeigt, nachdem ein benutzerdefinierter Agent registriert und konfiguriert wurde.

Überprüfen Sie Ihren Agenten

Stellen Sie sicher, dass Ihr Agent die Anforderungen für die Registrierung erfüllt:

  • Ihr Agent macht einen exklusiven Endpunkt verfügbar.
  • Das Netzwerk, in dem Sie die Foundry-Ressource bereitstellen, kann den Endpunkt des Agents erreichen.
  • Der Agent kommuniziert mithilfe eines der unterstützten Protokolle: HTTP (allgemein) oder A2A (spezifischer).
  • Ihr Agent sendet Daten mithilfe der OpenTelemetry-Semantikkonventionen für generative KI-Lösungen (oder Sie benötigen diese Funktion nicht).
  • Sie können den Endpunkt konfigurieren, den Benutzer für die Kommunikation mit dem Agent verwenden. Nachdem Sie einen Agent registriert haben, generiert foundry Control Plane eine neue URL. Clients und Benutzer müssen diese URL verwenden, um mit dem Agent zu kommunizieren.

Vorbereiten des Foundry-Projekts

Bevor Sie den benutzerdefinierten Agent registrieren, den Sie einem Foundry-Projekt hinzugefügt haben, stellen Sie sicher, dass Sie das Projekt ordnungsgemäß konfiguriert haben:

  1. Melden Sie sich bei Microsoft Foundry an. Stellen Sie sicher, dass die Umschaltfläche "Neue Gießerei " aktiviert ist. Diese Schritte beziehen sich auf Foundry (neu).

  2. Stellen Sie sicher, dass ein KI-Gateway in Ihrem Projekt konfiguriert ist:

    1. Wählen Sie auf der Symbolleiste "Ausführen" aus.

    2. Wählen Sie im linken Bereich "Administrator" aus.

    3. Öffnen Sie die Registerkarte "AI-Gateway ".

    4. Im Bereich werden alle KI-Gateways aufgelistet, die einer Foundry-Ressource konfiguriert und zugeordnet sind. Überprüfen Sie, ob die foundry-Ressource, die Sie verwenden möchten, über ein zugeordnetes KI-Gateway verfügt.

      Screenshot des Verwaltungsportals

    5. Wenn für die Foundry-Ressource, die Sie verwenden möchten, kein KI-Gateway konfiguriert ist (es ist nicht aufgeführt), fügen Sie eine ressource mithilfe der Option "KI-Gateway hinzufügen" hinzu .

      Ein KI-Gateway ist kostenlos einzurichten und schaltet leistungsstarke Governance-Features wie Sicherheit, Diagnosedaten und Nutzungsgrenzen für Ihre Agenten, Tools und Modelle frei. Weitere Informationen finden Sie unter Erstellen eines KI-Gateways.

  3. Stellen Sie sicher, dass die Überwachbarkeit im Projekt konfiguriert ist. Foundry Control Plane verwendet die Application Insights-Ressource, die Ihrem ausgewählten Projekt zugeordnet ist, um Daten zu senden und so die Diagnose Ihres Agenten zu unterstützen.

    1. Wählen Sie auf der Symbolleiste "Ausführen" aus.

    2. Wählen Sie im linken Bereich "Administrator" aus.

    3. Verwenden Sie unter "Alle Projekte" das Suchfeld, um nach Ihrem Projekt zu suchen.

    4. Wählen Sie das Projekt aus.

    5. Wählen Sie die Registerkarte "Verbundene Ressourcen " aus.

    6. Stellen Sie sicher, dass in der Kategorie "AppInsights " eine zugeordnete Ressource vorhanden ist.

      Screenshot des Verwaltungsportals, das Die Schritte zeigt, um zu überprüfen, ob ein Projekt über eine zugeordnete Application Insights-Ressource verfügt.

    7. Wenn keine zugeordnete Ressource vorhanden ist, fügen Sie eine hinzu, indem Sie "Verbindung hinzufügen" auswählen und > verwenden.

Ihr Projekt ist für Beobachtbarkeit und Ablaufverfolgung konfiguriert.

Registrieren des Agents (Objekt)

  1. Wählen Sie auf der Symbolleiste "Ausführen" aus.

  2. Wählen Sie im Bereich "Übersicht " die Option "Objekt registrieren" aus.

    Screenshot der Schaltfläche zum Registrieren eines Agents im Übersichtsbereich des Foundry-Portals.

  3. Der Registrierungs-Assistent wird angezeigt. Führen Sie zunächst die Details zu dem Agent aus, den Sie registrieren möchten. Die folgenden Eigenschaften beschreiben den Agent, wie er auf seiner Plattform ausgeführt wird:

    Eigenschaft Beschreibung Erforderlich
    Agent-URL Der Endpunkt (URL), an dem Ihr Agent ausgeführt wird und Anforderungen entgegennimmt. Im Allgemeinen geben Sie jedoch je nach Protokoll die Basis-URL an, die Ihre Clients verwenden. Wenn Ihr Agent z. B. die OpenAI Chat Completions-API verwendet, geben Sie https://<host>/v1/ an, da Clients sie im Allgemeinen ohne /chat/completions hinzufügen. Ja
    Protokoll Das Kommunikationsprotokoll, das Ihr Agent unterstützt. Verwenden Sie HTTP im Allgemeinen. Oder wenn Ihr Agent A2A genauer unterstützt, geben Sie das an. Ja
    A2A-Agentkarten-URL Der Pfad zur JSON-Spezifikation der Agentkarte. Wenn Sie sie nicht angeben, verwendet das System den Standardwert /.well-known/agent-card.json. Nein
    OpenTelemetry-Agent-ID Die Agent-ID, die Ihr Agent verwendet, um Ablaufverfolgungen gemäß OpenTelemetry-Semantikkonventionen für generative KI zu emittieren. Spuren zeigen es im gen_ai.agent.id-Attribut für Bereiche mit dem Vorgangsnamen create_agent an. Wenn Sie diesen Wert nicht angeben, verwendet das System den Agentnamen-Wert, um Ablaufverfolgungen und Logdateien zu finden, die dieser neue Agent meldet. Nein
    URL des Verwaltungsportals Die Verwaltungsportal-URL, in der Sie weitere Verwaltungsvorgänge für diesen Agent ausführen können. Foundry kann diesen Wert zur Bequemlichkeit speichern. Foundry hat keinen Zugriff, um Direktoperationen auf diesem Portal durchzuführen. Nein

  4. Konfigurieren Sie, wie der Agent im Foundry Control Plane angezeigt werden soll.

    Eigenschaft Beschreibung Erforderlich
    Project Das Projekt, in dem Sie den Agent registrieren. Foundry verwendet das in der Ressource konfigurierte KI-Gateway, das das Projekt enthält, um den Eingangsendpunkt zum Agenten zu konfigurieren. Sie können nur Projekte auswählen, für die ein KI-Gateway in ihren Ressourcen aktiviert ist. Wenn keine KI-Gateways angezeigt werden, konfigurieren Sie ein KI-Gateway in Ihrer Foundry-Ressource. Außerdem wird empfohlen, Application Insights im ausgewählten Projekt zu konfigurieren. Foundry verwendet die Application Insights-Ressource des Projekts, um Ablaufverfolgungen und Protokolle zu übermitteln. Ja
    Agentname Der Name des Agents, wie er in Foundry angezeigt werden soll. Das System kann diesen Namen auch verwenden, um relevante Ablaufverfolgungen und Protokolle in Application Insights zu finden, wenn Sie keinen anderen Wert für die OpenTelemetry-Agent-ID angeben. Ja
    Beschreibung Eine klare Beschreibung zu diesem Agent. Nein

  5. Speichern Sie die Änderungen.

  6. Foundry fügt den neuen Agent hinzu. Um die Liste der Agents zu überprüfen, wählen Sie " Objekte " im linken Bereich aus.

  7. Um nur benutzerdefinierte Agents anzuzeigen, verwenden Sie den Quellfilter , und wählen Sie "Benutzerdefiniert" aus.

    Screenshot eines registrierten benutzerdefinierten Agents.

Verbinden von Clients mit dem Agent

Wenn Sie Ihren Agent in Foundry registrieren, erhalten Sie eine neue URL für Ihre Clients zu verwenden. Da Foundry als Proxy für die Kommunikation mit Ihrem Agent fungiert, kann er den Zugriff steuern und Aktivitäten überwachen.

So verteilen Sie die neue URL so, dass Ihre Clients den Agent aufrufen können:

  1. Wählen Sie den benutzerdefinierten Agent aus.

  2. Wählen Sie im Detailbereich unter Agent-URL die Option "Kopieren" aus .

    Screenshot der Schritte zum Kopieren der neuen URL des Agents nach der Registrierung.

  3. Verwenden Sie die neue URL, um den Agent anstelle des ursprünglichen Endpunkts aufzurufen.

In diesem Beispiel stellen Sie einen LangGraph-Agent bereit. Clients verwenden das LangGraph SDK, um es zu nutzen. Der Client verwendet den neuen Agent-URL-Wert . Mit diesem Code wird ein Thread erstellt, eine Nachricht gesendet, die über das Wetter gefragt wird, und die Antwort wird zurückgestreamt.

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())

Erwartete Ausgabe: Der Agent verarbeitet die Nachricht und sendet Antworten als Blöcke zurück. Jeder Abschnitt enthält Teilergebnisse aus der Ausführung des Agenten. Zu diesen Ergebnissen gehören möglicherweise Toolaufrufe an die Wetterfunktion und die endgültige Antwort über das Wetter von Los Angeles.

Hinweis

Obwohl Foundry als Proxy für eingehende Anforderungen für Ihren Agent fungiert, gilt weiterhin das ursprüngliche Autorisierungs- und Authentifizierungsschema im ursprünglichen Endpunkt. Wenn Sie den neuen Endpunkt nutzen, stellen Sie den gleichen Authentifizierungsmechanismus bereit, wie wenn Sie den ursprünglichen Endpunkt verwenden.

Blockieren und den Agenten entsperren

Für benutzerdefinierte Agents verfügt Foundry nicht über Zugriff auf die zugrunde liegende Infrastruktur, in der der Agent ausgeführt wird, sodass Start- und Stoppvorgänge nicht verfügbar sind. Foundry kann jedoch eingehende Anforderungen an den Agent blockieren, sodass Clients sie nicht nutzen können. Mit dieser Funktion können Administratoren einen Agent deaktivieren, wenn er falsch funktioniert.

So blockieren Sie eingehende Anforderungen an Ihren Agent:

  1. Wählen Sie auf der Symbolleiste "Ausführen" aus.

  2. Wählen Sie im linken Bereich "Objekte" aus.

  3. Wählen Sie den Agent aus, den Sie blockieren möchten. Der Informationsbereich wird angezeigt.

  4. Wählen Sie "Updatestatus" und dann " Blockieren" aus.

    Screenshot der Schritte zum Blockieren eingehender Anforderungen an einen Agent.

  5. Bestätigen Sie den Vorgang.

Nachdem Sie den Agent blockiert haben, wird der Statuswert des Agents in Foundry blockiert. Agents im blockierten Zustand laufen in der ihnen zugeordneten Infrastruktur, können jedoch keine eingehenden Anforderungen annehmen. Foundry blockiert jeden Versuch, eine Schnittstelle mit dem Agent zu erstellen.

So heben Sie die Blockierung des Agents auf:

  1. Wählen Sie "Updatestatus" und dann " Blockierung aufheben" aus.

  2. Bestätigen Sie den Vorgang.

Aktivieren von Diagnosedaten für den Agent

Foundry verwendet den offenen OpenTelemetry-Standard, um zu verstehen, was Agents tun. Wenn Ihr Projekt Application Insights konfiguriert hat, protokolliert Foundry standardmäßig Anforderungen in Application Insights. Foundry verwendet diese Daten auch zum Berechnen:

  • Läuft
  • Fehlerrate
  • Verwendung (sofern verfügbar)

Um die beste Genauigkeit zu erzielen, erwartet Foundry, dass benutzerdefinierte Agents die semantischen Konventionen für generative KI-Lösungen im OpenTelemetry-Standard einhalten.

Anzeigen von an Foundry gesendeten Ablaufverfolgungen und Protokollen

  1. Wählen Sie auf der Symbolleiste "Ausführen" aus.

  2. Wählen Sie im linken Bereich "Objekte" aus.

  3. Wählen Sie den Agent aus.

  4. Im Abschnitt "Ablaufverfolgungen " wird ein Eintrag für jeden HTTP-Aufruf angezeigt, der an den Endpunkt des Agents gesendet wurde.

    Um die Details anzuzeigen, wählen Sie einen Eintrag aus.

    Screenshot eines Anrufs an den Endpunkt des Agents unter der Route für Ausführung und Datenströme.

    Tipp

    In diesem Beispiel können Sie sehen, wie Clients den Endpunkt des neuen Agents für die Kommunikation mit dem Agent verwenden. Das Beispiel zeigt einen Agent, der mit dem Agent-Protokoll von LangChain bedient wird. Clients verwenden die Route /runs/stream.

In diesem Beispiel enthält die Ablaufverfolgung keine Details über den HTTP-Beitrag hinaus. Der Code des Agents enthält keine weitere Instrumentierung. Im nächsten Abschnitt erfahren Sie, wie Sie Ihren Code instrumentieren und Details wie Toolaufrufe und LLM-Aufrufe (Large Language Model) abrufen.

Benutzerdefinierte Code-Agents für Instrumente

Wenn Sie Ihren Agenten mithilfe von benutzerdefiniertem Code erstellen, instrumentieren Sie Ihre Lösung gemäß dem OpenTelemetry-Standard, um Traces auszugeben und sie an Application Insights zu senden. Instrumentation bietet Foundry Zugriff auf detaillierte Informationen darüber, was Ihr Agent tut.

Verwenden Sie den Instrumentierungsschlüssel, um Ablaufverfolgungen an die Application Insights-Ressource Ihres Projekts zu senden. Befolgen Sie die Anweisungen unter Connect Application Insights zu Ihrem Foundry-Projekt, um den Instrumentierungsschlüssel zu erhalten, der Ihrem Projekt zugeordnet ist.

In diesem Beispiel konfigurieren Sie einen mit LangGraph entwickelten Agent, um Traces im OpenTelemetry-Standard auszugeben. Der Tracer erfasst alle Agentvorgänge, einschließlich Toolaufrufe und Modellinteraktionen. Der Tracer sendet dann die Vorgänge zur Überwachung an Application Insights.

Dieser Code verwendet das Langchain-azure-ai-Paket . Anleitungen zum Instrumentieren bestimmter Lösungen mit OpenTelemetry, je nach der von Ihrer Lösung verwendeten Programmiersprache und dem Framework, finden Sie unter Sprach-APIs & SDKs.

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

Instrumentieren Sie dann Ihren Agenten:

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

Erwartete Ausgabe: Der Agent läuft normal, während OpenTelemetry-Traces automatisch an Application Insights gesendet werden. Spuren umfassen Vorgangsnamen, Dauern, Modellaufrufe, Toolaufrufe und Tokennutzung. Sie können diese Ablaufverfolgungen im Gießereiportal im Abschnitt "Ablaufverfolgungen " anzeigen.

Tipp

Sie können die Verbindungszeichenfolge mithilfe der Umgebungsvariablen APPLICATIONINSIGHTS_CONNECTION_STRING an Application Insights übergeben.

Instrumentplattformlösungen

Wenn Ihr Agent auf einer Plattformlösung ausgeführt wird, die OpenTelemetry unterstützt, application Insights jedoch nicht unterstützt, stellen Sie einen OpenTelemetry-Sammler bereit und konfigurieren Sie Ihre Software, um OTLP-Daten an den Sammelsammler zu senden (Standardkonfiguration von OpenTelemetry).

Konfigurieren Sie den Sammler mit dem Azure Monitor Exporter, um Daten mithilfe Ihrer Verbindungszeichenfolge an Application Insights weiterzuleiten. Ausführliche Informationen zur Implementierung finden Sie unter Configure Azure Monitor OpenTelemetry.

Problembehandlung bei Ablaufverfolgungen

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

  • Das Projekt, in dem Sie Ihren Agent registrieren, hat Application Insights konfiguriert. Wenn Sie Application Insights konfiguriert haben, nachdem Sie den benutzerdefinierten Agent registriert haben, müssen Sie die Registrierung des Agents aufheben und erneut registrieren. Die Application Insights-Konfiguration wird nach der Registrierung nicht automatisch aktualisiert, wenn Sie sie geändert haben.
  • Sie haben den Agenten (in seiner Infrastruktur ausgeführt) so eingerichtet, dass er Traces an Application Insights sendet, und verwenden dieselbe Application Insights-Ressource, die auch Ihr Projekt nutzt.
  • Instrumentation entspricht den OpenTelemetry-Semantikkonventionen für generative KI.
  • Ablaufverfolgungen enthalten Bereiche mit den Attributen gen_ai.operation.name="create_agent" und gen_ai.agent.id="<agent-id>" (oder gen_ai.agent.name="<agent-id>"). Im letzten Attribut ist der Wert der "<agent-id>" angegeben, den Sie während der Registrierung konfiguriert haben.

Verwandte Inhalte

  • Last updated on