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. In diesem Artikel werden Verwaltungs- und Diagnosedaten für vorhandene benutzerdefinierte Agents behandelt.

Die Übergangsschritte finden Sie unter Migrieren von benutzerdefinierten Agents zu externen Agents.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Wenn Sie kein Konto haben, erstellen Sie ein free Azure Konto, das ein kostenloses Testabonnement enthält.

• Ein Foundry-Projekt. Wenn Sie kein Projekt haben, erstellen Sie ein Projekt.

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

• Das in Ihrer Foundry-Ressource konfigurierte vorhandene AI-Gateway und der erreichbare Back-End-Endpunkt des Agenten.

Hinzufügen eines benutzerdefinierten Agents

Sie können keinen neuen benutzerdefinierten Agent mehr in foundry Control Plane hinzufügen. Für eine neue Integration Registrieren Sie einen externen Agenten. Folgen Sie für einen vorhandenen benutzerdefinierten Agent dem Migrationshandbuch.

Vorhandene benutzerdefinierte Agentarchitektur

Vorhandene benutzerdefinierte Agents verwenden API Management als Proxy für die Kommunikation mit dem Agent, sodass API Management den Zugriff steuern und Aktivitäten überwachen kann.

Verbinden von Clients mit dem Agent

Eine vorhandene benutzerdefinierte Agent-Registrierung verfügt über eine Gateway-URL, die von Clients verwendet werden kann. Da das Gateway als Proxy für die Kommunikation mit Ihrem Agent fungiert, kann es den Zugriff steuern und Aktivitäten überwachen. Verwenden Sie diese URL während der Migration zur Registrierung externer Agents weiterhin.

So suchen Sie die vorhandene Gateway-URL:

1. Wählen Sie in der Agentenliste das Optionsfeld neben dem Namen des benutzerdefinierten Agenten aus, um den Informationsbereich zu öffnen. Wählen Sie nicht den Agentnamen selbst aus, da dieser Link vom Bereich "Ressourcen " weg navigiert.

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

   

3. Verwenden Sie diese Gateway-URL, um den Agent aufzurufen.

In diesem Beispiel verwenden Clients das LangGraph SDK und die vorhandene Gateway-URL, um einen LangGraph-Agent aufzurufen. 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 Chunk enthält Teilergebnisse der Ausführung des Agents. Zu diesen Ergebnissen gehören möglicherweise Toolaufrufe an die Wetterfunktion und die endgültige Antwort über das Wetter von Los Angeles.

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 Anfragen an den Agent blockieren, so dass die Clients ihn nicht konsumieren 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 das Optionsfeld neben dem Agenten aus, den Sie blockieren möchten. Der Informationsbereich wird angezeigt. Wählen Sie nicht den Agentnamen aus, da dieser Link vom Bereich "Ressourcen " weg navigiert.

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

   

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:

• Ausführungen
• 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.

Ansicht der an Foundry gesendeten Traces und Protokolle

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

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

3. Wählen Sie das Optionsfeld neben dem Agent aus, um den Informationsbereich zu öffnen. Wählen Sie nicht den Agentnamen aus, da dieser Link vom Bereich "Ressourcen " weg navigiert.

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.

   

   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.

Senden Sie Traces an die Application Insights-Ressource Ihres Projekts mithilfe des zugehörigen Instrumentierungsschlüssels. 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 Traces im Foundry-Portal im Abschnitt Traces anzeigen.

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:

Verwandte Inhalte

• Benutzerdefinierte Agenten zu externen Agenten migrieren
• Was ist die Microsoft Foundry Control Plane?
• Überwachen des Zustands und der Leistung von Agenten über Ihre Flotte hinweg