Registrieren und Verwalten von benutzerdefinierten Agents

Microsoft Foundry Control Plane bietet zentrale Verwaltung und Observierbarkeit für Agents, 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 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 keinen haben, create a project.

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

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 API Management, um als Proxy für die Kommunikation mit Ihrem Agent zu fungieren, damit er access steuern und Aktivitäten überwachen kann.

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

Überprüfen Sie Ihren Agenten

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

Bereiten Sie Ihr Foundry-Projekt vor

Bevor Sie den benutzerdefinierten Agent registrieren, den Sie einem Foundry-project hinzugefügt haben, stellen Sie sicher, dass Sie die project 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 Ihrer project 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.

      

   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 entsperrt leistungsstarke Governance-Features wie Sicherheit, Diagnosedaten und Ratenbegrenzungen für Ihre Agents, Tools und Modelle. Weitere Informationen finden Sie unter Erstellen eines KI-Gateways.

3. Stellen Sie sicher, dass die Beobachtbarkeit im Projekt konfiguriert ist. Foundry Control Plane verwendet die Application Insights-Ressource, die Ihrem ausgewählten Projekt zugeordnet ist, um Daten auszusenden, um Ihren Agenten zu diagnostizieren.

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

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

   3. Verwenden Sie unter All projects das Suchfeld, um nach Ihrem project 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.

      

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

Ihr Projekt ist für Beobachtbarkeit und Nachverfolgung konfiguriert.

Registrieren des Agents

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

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

   

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:

   Eigentum	Description	Erforderlich
   Agent-URL	Der Endpunkt (URL), an dem Ihr Agent ausgeführt wird und Anfragen empfängt. Im Allgemeinen geben Sie jedoch je nach Protokoll die Basis-URL an, die Ihre Clients verwenden. Wenn Ihr Agent beispielsweise die OpenAI Chat Completions-API verwendet, geben Sie https://<host>/v1/ an, ohne /chat/completions, da die Clients sie in der Regel hinzufügen.	Ja
   Protokoll	Das Kommunikationsprotokoll, das Ihr Agent unterstützt. Verwenden Sie HTTP im Allgemeinen. Oder wenn Ihr Agent A2A spezifischer 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 Traces gemäß den semantischen Konventionen von OpenTelemetry für generative KI zu emittieren. Traces geben sie im Attribut gen_ai.agents.id für Spans mit dem Operation-Namen create_agent an. Wenn Sie diesen Wert nicht angeben, verwendet das System den Wert Agentnamen, um Ablaufverfolgungen und Protokolle 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 verfügt nicht über die Berechtigung, Vorgänge direkt in diesem Portal auszuführen.	Nein

4. Konfigurieren Sie, wie der Agent in der Gießereisteuerungsebene dargestellt werden soll:

   Eigentum	Description	Erforderlich
   Project	Das Projekt, in dem Sie den Agenten registrieren. Foundry verwendet das in der Ressource konfigurierte KI-Gateway, das das Projekt enthält, um den eingehenden Endpunkt 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. Wir empfehlen außerdem, Application Insights im ausgewählten Projekt zu konfigurieren. Foundry verwendet die Application Insights-Ressource des Projekts, um Ablaufverfolgungen und Protokolle zu speichern.	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.

   

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 Agenten fungiert, kann es 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 .

   

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.

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)

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 Entblockieren des Agents

Für benutzerdefinierte Agents hat Foundry keinen Zugriff auf die zugrunde liegende Infrastruktur, auf der der Agent läuft, 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 den Agent aus, den Sie blockieren möchten. Der Informationsbereich wird angezeigt.

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 Status Blockiert werden in ihrer zugewiesenen Infrastruktur ausgeführt, können aber keine eingehenden Anforderungen entgegennehmen. 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 Ihre project Application Insights konfiguriert hat, protokolliert Foundry standardmäßig Anforderungen in Application Insights. Foundry verwendet diese Daten auch zum Berechnen:

• Läufe
• 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 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.

   

   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.

Instrumentenspezifische Code-Agenten

Wenn Sie Ihren Agent mithilfe von benutzerdefiniertem Code erstellen, versehen Sie Ihre Lösung mit Instrumentierung, um Traces gemäß dem OpenTelemetry-Standard auszugeben und sie an Application Insights zu senden. Instrumentation gibt Foundry Zugang zu detaillierten Informationen darüber, was Ihr Agent macht.

Senden Sie Traces mithilfe des Instrumentierungsschlüssels an die Application Insights-Ressource Ihres Projekts. Befolgen Sie die Anweisungen unter Ablaufverfolgung aktivieren in Ihrem Projekt, um den Instrumentierungsschlüssel abzurufen, der Ihrem Projekt zugeordnet ist.

In diesem Beispiel konfigurieren Sie einen mit LangGraph entwickelten Agent, um Ablaufverfolgungen 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 paket langchain-azure-ai. 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-Ablaufverfolgungen automatisch an Application Insights gesendet werden. Ablaufverfolgungen umfassen Vorgangsnamen, Dauer, Modellaufrufe, Toolaufrufe und Tokenverbrauch. 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 connection string an Application Insights weiterzuleiten. Ausführliche Informationen zur Implementierung finden Sie unter Configure Azure Monitor OpenTelemetry.

Problembehandlung bei Ablaufverfolgungen

Wenn Sie keine Ablaufverfolgungen sehen, überprüfen Sie die folgenden Elemente:

Verwandte Inhalte

• Was ist microsoft Foundry Control Plane?
• Überwachen Sie die Gesundheit und Leistung von Agenten in Ihrer Flotte
• Optimieren von Modellkosten und Leistung