KI-Agents

Multi-Agent-Systeme und Supervisor-Muster

Ein Multi-Agent-System ist ein AI-Anwendungsdesign, bei dem eine Benutzeranforderung von mehreren kooperierenden Agents statt von einem großen Allzweck-Agent bearbeitet wird.

Jeder Agent hat seine eigene Rolle, Anweisungen, Modellkonfiguration, Speicher-Policy und zugelassene Tools. Der Ablauf definiert, wie die Anforderung zwischen diesen Agents verschoben wird und wie die endgültige Antwort erstellt wird.

Dieses Design ist nützlich, wenn sich ein Workflow natürlich in fachliche Zuständigkeiten trennt. Beispiel: Ein Agent kann Daten abrufen, ein anderer eine API aufrufen, ein anderer kann Ergebnisse zusammenfassen, und ein Supervisor kann entscheiden, welcher Spezialist die Ergebnisse verwenden und zu einer einzigen Antwort kombinieren.

Hinweis:

Als Designprinzip ist es am besten, mit dem kleinsten Agent-Design zu beginnen, das den Anforderungen entspricht. Fügen Sie mehrere Agents hinzu, wenn die Trennung von Bedenken die Zuverlässigkeit, Sicherheit, Wartbarkeit oder Beobachtbarkeit verbessert, anstatt die Kosten und Komplexität zu erhöhen.

Vorteile von Multi-Agent-Systemen

Multi-Agent-Systeme eignen sich am besten für:

Spezialisierung: Geben Sie jedem Agent einen fokussierten Job, eine Eingabeaufforderung und ein Toolset anstelle eines überfüllten Anweisungsblocks.
Weiterleitung und Zerlegung: Ein Vorgesetzter kann die Anforderung interpretieren, in Unteraufgaben aufteilen und den richtigen Spezialisten für jede Unteraufgabe auswählen.
Tool und Datenisolierung: Stellen Sie sensible oder wirkungsvolle Tools nur den Agents zur Verfügung, die für deren Verwendung verantwortlich sind.
Governance und Fehlerbehebung: Machen Sie Übergaben, Werkzeugeigentum, Speichereinstellungen und Fehlerpunkte einfacher zu prüfen.

Wann werden Multi-Agent- oder Single-Agent-Designs ausgewählt?

Ein einziger Agent mit mehr Tools ist oft das richtige erste Design. Es ist einfacher zu testen, billiger zu laufen und einfacher darüber nachzudenken, wann die Aufgabe ein klares Ziel und ein Berechtigungsmodell hat. Verwenden Sie ein Multi-Agent-Design, wenn der Workflow von expliziten Rollen, gebundenem Toolzugriff oder einem Supervisor profitiert, der mehrere spezialisierte Ausgaben koordinieren kann.

Designfrage	Verwenden Sie einzelne Agenten, wenn...	Verwenden Sie Multi-Agents, wenn...
Aufgabenausprägung	Die Anforderung hat ein Hauptziel und ein Reaktionsstile.	Die Anforderung muss über Fachgebiete hinweg zerlegt, weitergeleitet, verifiziert oder synthetisiert werden.
Tools und Daten	Der gleiche Befehlssatz und das gleiche Berechtigungsmodell können alle Werkzeuge sicher steuern	Verschiedene Agents benötigen unterschiedliche Tools, Datenquellen oder Zugriffsgrenzen.
Anweisungen	Der Prompt bleibt auch bei allen Geschäftsregeln und Tool-Guidance an einem Ort klar.	Anweisungen können einfacher als kleinere, rollenspezifische Prompts verwaltet werden.
Kosten und Latenz	Sie möchten den kürzesten Pfad von der Benutzernachricht zur Antwort angeben.	Die Vorteile von Zuverlässigkeit, Governance oder Wartbarkeit rechtfertigen eine zusätzliche Orchestrierung.
Problembehandlung	Fehler lassen sich einfach in einem Trace debuggen.	Sie benötigen explizite Übergaben, Zustandsisolierung und klarere Eigentümerschaft für jeden Schritt.

Unterstütztes Muster: Orchestrator/Supervisor

Die aktuelle Leinwanderfahrung unterstützt das Orchestrator-/Supervisor-Muster. In diesem Muster empfängt der Chat-Trigger die Benutzernachricht, optionale Guardrails werten die Eingabe aus, und ein Supervisor-Agent fungiert als Orchestrator für den Rest des Ablaufs.

Der Supervisor sollte sich auf Planung, Routing, Delegation und abschließende Antwortsynthese konzentrieren. Es entscheidet, welcher Executor-Agent eine Aufgabe bearbeiten soll, sendet diesem Executor eine begriffsbezogene Anweisung, prüft das Ergebnis und delegiert dann entweder einen anderen Schritt oder gibt die endgültige Antwort zurück. Executor-Agents sollten engere Spezialisten sein: Sie erledigen die zugewiesene Arbeit, verwenden ihre beigefügten Tools und geben dem Supervisor nützliche Ergebnisse zurück.

Informationen zur Visual Flow Canvas

Ein Agent wird zusammengestellt, indem Knoten und Toolvorlagen aus der linken Palette auf die Leinwand gezogen und dann die Knoten in der Reihenfolge verbunden werden, in der die Anforderung weitergeleitet werden soll.

Wenn Sie einen Knoten auswählen, wird am unteren Bildschirmrand ein Konfigurationsbereich geöffnet.

Leinwand für visuellen Agent-Builder. Palette, Modusauswahl und Zoomsteuerelement werden beschriftet und hervorgehoben.

Leinwandelement	Zweck
Chattrigger	Einstiegspunkt für eine Benutzernachricht. Im Screenshot ist dieser Knoten mit dem Label "Message" gekennzeichnet und befindet sich in der Regel oben im Ablauf. Ein Chattriggerknoten kann mit einem Agent, einem Supervisor-Agent oder einem Guardrails-Knoten verbunden werden. Pro Leinwand ist nur ein Chattrigger zulässig.
Limits	Optionale Policy- und Sicherheitsschicht vor oder nach der Modellarbeit. Zu den Richtlinien für Leitplanken gehören personenbezogene Daten, Inhaltsmoderation und sofortige Injection-Erkennung. Ein Guardrails-Knoten kann den Datenverkehr zwischen einem Chat-Trigger und einem Agent-Knoten, zwischen einem Supervisor und Executor-Agents oder zwischen Agent- und Toolknoten filtern. Wir empfehlen einen einzelnen Guardrails-Knoten zwischen dem Chattrigger und dem Agent-Knoten.
Supervisor-Agent	Der Orchestrator. Sie empfängt die Benutzeranforderung, entscheidet, welcher Executor-Agent oder welches Executor-Tool jede Aufgabe bearbeiten soll, und koordiniert die endgültige Antwort. Auf einer Leinwand ist nur ein Supervisor-Agent zulässig.
Agent	Ein Executor-Agent. Jeder Executor sollte über ein klares Fachgebiet verfügen, z. B. Datenabruf, API-Lookup, Zusammenfassung oder Beantwortung von Dokumentfragen. Verwenden Sie einen Agent / Executor-Agent für ein einzelnes Agent-System.
Werkzeugvorlagen	Wiederverwendbare Funktionen, die an einzelne Executor- oder Supervisor-Agents angehängt werden können. Zu den Toolvorlagen gehören SQL, RAG, Prompt, HTTP, Remote-MCP-Server und Custom Tool.
Entwicklung / Spielplatz	Modusselektor über der Leinwand. Die Entwicklung wird beim Bearbeiten des Agent-Systems verwendet. Der Playground wird verwendet, um Testsitzungen zu initiieren und das Agent-Verhalten zu prüfen. Playground erfordert, dass ein AI-Compute an Ihren Agent angeschlossen ist.
Zoomsteuerung	Selektor für Leinwandzoom. Die Screenshots zeigen 60 Prozent und 90 Prozent Zoom.

Agent erstellen

Sie können einen Agent in einem Workspace mit der Berechtigung "Verwalten" erstellen.

Navigieren Sie auf der Homepage zu Ihrem Workspace.
Klicken Sie im linken Navigationsbereich auf Agent-Abläufe.
Klicken Sie auf Agent erstellen, oder klicken Sie oben rechts auf Erstellen.
Geben Sie einen Namen und die Beschreibung für den Agent an.
Wählen Sie unter Agent-Flow-Authoring-Modus die Option Visueller Builder aus.
Optional: Wählen Sie im Dropdown-Menü AI Compute eine Compute-Instanz aus, die für den Agent verwendet werden soll.
Klicken Sie auf Create. Erstellen Sie den Agent, indem Sie einen Knoten aus der Palette auf die Leinwand ziehen.

Hinweis:
Starten Sie Ihre erste Agent-Erstellung einfach: ein Chat-Trigger, ein Executor-Agent. Fügen Sie Komplexität nach einer erfolgreichen Ausführung Ihres ersten Builds hinzu, wie Schutzschienen, zusätzliche Werkzeuge oder sogar Multi-Agent-Systemdesign.

Chattrigger und -Agent zur Visual Builder-Leinwand hinzufügen

Ihr erster Schritt nach dem Erstellen eines Agent mit Visual Builder sollte darin bestehen, einen Chattrigger und einen Supervisor-Agent hinzuzufügen.

Der Trigger erhält die Benutzernachricht. Der Supervisor interpretiert die Anforderung, plant die Arbeit und delegiert sie an Executor-Agents oder -Tools. Sie können Knoten in die Leinwand ziehen, konfigurieren und später verbinden.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace.
Klicken Sie auf einen Chattrigger, und ziehen Sie ihn von der Palette auf die Leinwand. Der Knoten wird auf der Leinwand als Nachricht angezeigt.
Klicken und ziehen Sie einen Supervisor-Agent auf die Leinwand.
Klicken und ziehen Sie den Connector-Handle auf dem Chattrigger-Knoten, um ihn mit dem Agent-Knoten zu verbinden.

Das Abzeichen "Supervisor-Agent" zeigt an, wie viele Agents und Tools verbunden sind. In einem neuen Build zeigt der Supervisor-Agent: Agents (0) Tools (0).

Chattrigger und Supervisor-Agent auf der Visual Builder-Leinwand. Das Badge unter dem Supervisor-Agent gibt "Agents (0) Tools (0)" an.

Supervisor-Agent konfigurieren

Sie müssen einen Supervisor-Agent konfigurieren, der Ihrer Visual Builder-Leinwand hinzugefügt wurde, mit Anweisungen zur Beschreibung der Supervisor-Rolle.

Sie konfigurieren einen Supervisor-Agent mit den folgenden Feldern.

Visual Builder-Leinwand wird angezeigt. Der Supervisor-Agent wird ausgewählt und zeigt die Registerkarte "Konfiguration" an.

Feld	Konfiguration
Agentname	Geben Sie einen aussagekräftigen Namen für den Supervisor-Agent an. Ein guter, beschreibender Name ist von Vorteil, wenn das Systemverhalten über Traces und Logs debuggt wird.
Agent-Beschreibung	Geben Sie eine Beschreibung des Zwecks, der Rolle und des allgemeinen Verhaltens des Agents an. Nützlich für Dokumentationszwecke.
Bereich	Wählen Sie die Region aus, in der das vom Supervisor-Agent verwendete OCI Generative AI-Modell gehostet wird. Siehe Generative KI-Modelle nach Region.
Modell	Wählen Sie das vom Supervisor verwendete OCI Generative AI-Servicemodell aus. In der Dropdown-Liste werden die Modelle aufgeführt, die in der ausgewählten Region verfügbar sind.
Agent-Anweisungen	Beschreiben Sie die Vorgesetztenrolle, Weiterleitungsregeln, Delegierungs-Policy, die Maßnahmen zur Toolverwendung und das endgültige Antwortformat.

Navigieren Sie zum Agent in Ihrem Workspace.
Klicken Sie auf der Leinwand auf den Knoten Supervisor-Agent.
Geben Sie einen sinnvollen Namen und eine Beschreibung für Ihren Supervisor-Agent an.
Geben Sie die Region und das Modell für das OCI Generative AI-Servicemodell ein, das vom Supervisor verwendet wird.
Geben Sie die Anweisungen des Agents für Ihren Supervisor-Agent an.

Vorgeschlagene Anweisungen des Vorgesetzten

Verwenden Sie das Feld "Anweisungen" für einen Supervisor-Agent, um den Supervisor für die Orchestrierung verantwortlich zu machen, nicht für jede Aufgabe selbst.

Halten Sie die Anweisungen konkret, damit Routingentscheidungen vorhersehbar sind. Im Folgenden finden Sie ein Beispiel für eine Gruppe von Supervisor-Anweisungen:

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

Supervisor-Agent-Speicher und Statusisolierung konfigurieren

Die Registerkarte "Speicher" für einen Supervisor-Agent steuert, wie viel Konversation und Tool-Ausgabehistorie für den Supervisor verfügbar sind und wie viel Kontext mit Executor-Agents geteilt wird.

Sie konfigurieren den Speicher- und Isolationsstatus für Ihren Supervisor-Agent mit den folgenden Feldern.

Visual Builder-Leinwand wird angezeigt. Ein Supervisor-Agent wird ausgewählt, und die Registerkarte "Speicher" wird angezeigt.

Feld	Konfiguration
Agent-Speicher aktivieren	Aktivieren, wenn Benutzer Kontinuität mit mehreren Turns benötigen. Für isolierte Aufgaben mit nur einer Verwendung deaktivieren. Dieses Feld kann für Supervisor-Agents nicht deaktiviert werden.
Unterhaltungshistorie begrenzen	Aktivieren Sie diese Option, um das LLM-Kontextfenster abzuschneiden, nachdem das angegebene Limit erreicht wurde. Deaktivieren, um die vollständige Versionsgeschichte anzuzeigen.
Abschneidungskonfiguration	Wenn Unterhaltungshistorie begrenzen aktiviert ist, können Sie in diesem Feld die Bedingungen für das Abschneiden des Kontextfensters festlegen. Optionen: Letzte N Nachrichten beibehalten Tokenbudget Beides
Maximale Nachrichtenlimits und Tokenbudget	Je nach Ihrer Auswahl für Abschneidenkonfiguration wird eine oder beide Optionen angezeigt. Standardwerte sind 20 Nachrichten und 5000 Token. Wir empfehlen, mit moderaten Werten zu beginnen und nach Bedarf anzupassen.
Zustandsisolierung für Executor-Agents	Wählen Sie Zustandslos, Privat oder Gemeinsam aus. Zustandslos: Jeder Executor-Agent sieht nur die Aufgabe, die vom Supervisor zugewiesen wurde. Zwischen den Anrufen wird keine Historie übertragen. Wählen Sie diese Option aus, wenn Sie die stärkste Isolation und den geringsten Cross-Agent-Kontext wünschen. Privat: Jeder Executor-Agent sieht nur seine eigenen vergangenen Interaktionen. Andere Executor-Agents der ursprünglichen Benutzerunterhaltung werden nicht angezeigt. Wählen Sie diese Option aus, wenn Ihr Executor Kontinuität über seine eigenen Aufgaben hinweg benötigt, aber keinen Kontext mit anderen Agents teilen soll. Gemeinsam verwendet: Executor-Agents können eine vollständige Unterhaltungshistorie für alle Agents und Benutzer anzeigen. Alle Agents arbeiten aus einem gemeinsamen Kontext. Wählen Sie diese Option aus, wenn Sie einen breiten Kontextaustausch benötigen und Datenschutz- und Prompt-Injection-Risiken geprüft haben.

Navigieren Sie zum Agent in Ihrem Workspace.
Klicken Sie auf der Leinwand auf den Knoten Supervisor-Agent.
Klicken Sie auf die Registerkarte Speicher.
Wählen Sie aus, ob die Unterhaltungshistorie begrenzen aktiviert werden soll. Wählen Sie eine Abschneidungskonfiguration aus, und legen Sie Limits fest, sofern aktiviert.
Wählen Sie eine Option für Statusisolierung für Executor-Agents aus.

Registerkarte "Parameter" für Modelle

Auf der Registerkarte "Modellparameter" können Sie modellspezifische Parameter konfigurieren, die für das ausgewählte Modell verfügbar sind.

Modellparameter können separat für Supervisor- und Executor-Agents konfiguriert werden. Parameter, die Sie verwenden können, sind Temperatur, oberes K, oberes P und Frequenzstrafe.

Hinweis:

Nur eine Teilmenge von Modellen zeigt konfigurierbare Parameter an. Darüber hinaus variieren die Parameter je nach Modellfamilie.

Visual Builder-Leinwand wird angezeigt. Ein Supervisor-Agent wird ausgewählt, und die Registerkarte "Modellparameter" wird angezeigt.

Guardrails zu einem Agent hinzufügen

Sie können Ihren Agents zusätzliche Schutzschichten hinzufügen, indem Sie einen oder mehrere Schutzschienenknoten zu Ihrer Leinwand hinzufügen.

Standardmäßig werden keine Leitplanken auf Ihre Agent-Systeme angewendet, die über das hinausgehen, was der ausgewählte Modellanbieter Out-of-the-box für seine Modelle anbietet. Guardrails können zwischen dem Chattrigger und dem Supervisor-Agent platziert werden, sodass Policys angewendet werden, bevor eine Anforderung den Supervisor-Agent erreicht und bevor der Supervisor-Agent eine Antwort an den Anrufer zurückgibt.

Limit	Optionen	Wann verwendet
Personenbezogene Daten (PII)	Register "Eingabe und Ausgabe" Kontrollkästchen für Person, Adresse, Telefonnummer, E-Mail	Verwendung, wenn der Ablauf sensible personenbezogene Daten vor oder nach der Modellverarbeitung blockieren oder maskieren muss.
Prävention der Inhaltsmoderation	Ein- und Ausgabezeilen mit den Optionen Block, Inform und Allow.	Verwendung, um zu definieren, wie der Fluss mit Hass, sexuellem, gewalttätigem, giftigem, abwertendem oder belästigendem Inhalt umgeht.
Prompt-Injection-Erkennung	Eingabezeile mit Block- und Zulassungsoptionen.	Verwenden Sie diese Option, um die Wahrscheinlichkeit zu verringern, dass böswillige Anweisungen das System oder die Agent-Anweisungen außer Kraft setzen.

Weitere Informationen zu Guardrail-Einstellungen finden Sie unter Guardrails.

Navigieren Sie zum Agent in Ihrem Workspace.
Ziehen Sie einen Knoten Schutzschienen von der Palette auf die Leinwand. Platzieren Sie sie zwischen dem Chattrigger-Knoten und dem Supervisor-Agent-Knoten.
Löschen Sie die Verbindung zwischen Chat-Trigger und Supervisor-Agent, indem Sie den Mauszeiger über die Verbindung bewegen und auf das rote X klicken.
Klicken und ziehen Sie den Connector-Handle am Chattrigger auf den Guardrail-Knoten. Klicken Sie anschließend auf den Connector-Handle, und ziehen Sie ihn vom Guardrail-Knoten auf den Supervisor-Agent.
Klicken Sie auf den Guardrail-Knoten, um die Seite "Konfiguration" zu öffnen.
Konfigurieren Sie die Leitschienen, um die gewünschte Aktion für Ein- und Ausgabeprüfungen auszuwählen.

Executor-Agents und -Tools zu einem Agent hinzufügen

Sie können Executor-Agents zu Tools hinzufügen, um spezielle Aufgaben für den Supervisor-Agent auszuführen.

Im folgenden Beispiel delegiert der Supervisor-Agent AGENT_1 und AGENT_2. AGENT_1 ist mit SQL_1- und HTTP_1-Tools verbunden.

Visual Builder-Leinwand wird angezeigt. Ein Chat-Triggerknoten ist mit einem Guardrail-Knoten verbunden, der mit einem Supervisor-Knoten verbunden ist. Der Supervisor-Knoten ist mit den beiden Agent-Knoten AGENT_1 und AGENT_2 verbunden. AGENT_1 ist mit den beiden Toolknoten SQL_1 und HTTP_1 verbunden.

Navigieren Sie zum Agent in Ihrem Workspace.
Ziehen Sie einen Agent-Knoten aus der Palette auf die Leinwand. Agent-Knoten müssen unter einem Supervior-Agent platziert werden.
Ziehen Sie Werkzeuge von der Palette auf Ihre Leinwand.
Klicken Sie auf den Connector-Handle auf Ihrem Supervisor-Agent, und ziehen Sie ihn, um eine Verbindung zu den Agent-Knoten herzustellen.
Klicken und ziehen Sie den Connector-Handle auf Ihren Agents, um eine Verbindung zu den Toolknoten herzustellen.

Executor-Agent-Konfiguration

Agent-Knoten können konfiguriert werden, indem Einstellungen auf den Registerkarten "Konfiguration", "Arbeitsspeicher" und "Modell" geändert werden, um den Zweck der einzelnen Agents zu definieren.

Agents sollten aufgrund einer bestimmten Funktion und eines bestimmten Ziels eng konfiguriert werden, damit der Supervisor-Agent die Arbeit zuverlässig weiterleiten kann.
Visual Build Canvas. Ein Chat-Triggerknoten ist mit einem Supervisor-Agent verbunden, der mit zwei Agent-Knoten, AGENT_1 und AGENT_2, verbunden ist. AGENT_1 ist mit den beiden Toolknoten SQL_1 und HTTP_1 verbunden.

Tabelle 22-1: Registerkarte "Agent-Konfiguration"

Feld	Konfiguration
Agentname	Best Practice ist es, jeden Executor-Agent nach seinem Fachgebiet zu benennen, z. B. SQL_AGENT, DOCUMENT_AGENT, API_AGENT oder SUMMARY_AGENT. Der Name jedes Executor-Agents ist für den Supervisor-Agent sichtbar. Verwenden Sie daher beschreibende Namen.
Agent-Beschreibung	Geben Sie eine detaillierte Beschreibung der einzelnen Executor-Agents an. Die Beschreibung jedes Executor-Agents ist für den Supervisor-Agent sichtbar.
Bereich	Wählen Sie die Region aus, in der das vom Agent verwendete OCI Generative AI-Modell gehostet wird. Siehe Generative KI-Modelle nach Region.
Modell	Wählen Sie das vom Agent verwendete OCI Generative AI-Servicemodell aus. Im Dropdown-Menü werden die Modelle aufgeführt, die in der ausgewählten Region verfügbar sind. Wählen Sie ein Modell aus, das zur Executor-Aufgabe passt. Executor-Agents müssen nicht dasselbe Modell wie der Supervisor-Agent verwenden.
Agent-Anweisungen	Beschreiben Sie genau, was der Executor tun soll, welche Tools er verwenden kann und welche Ausgabestruktur er zurückgeben soll.

Registerkarte "Speicher" des Executor-Agent

Bei Executor-Agents, die mit einem Supervisor-Agent verbunden sind, wird der Speicher für Executors im Supervisor-Knoten konfiguriert und auf alle Executor-Agents angewendet.

Feld	Konfiguration
Agent-Speicher aktivieren	Aktivieren, wenn Benutzer Kontinuität mit mehreren Turns benötigen. Für isolierte Aufgaben mit nur einer Verwendung deaktivieren.
Unterhaltungshistorie begrenzen	Aktivieren Sie diese Option, um das LLM-Kontextfenster abzuschneiden, nachdem das angegebene Limit erreicht wurde. Deaktivieren, um die vollständige Versionsgeschichte anzuzeigen.
Abschneidungskonfiguration	Wenn Unterhaltungshistorie begrenzen aktiviert ist, können Sie in diesem Feld die Bedingungen für das Abschneiden des Kontextfensters festlegen. Optionen: Letzte N Nachrichten beibehalten Tokenbudget Beides
Maximale Nachrichtenlimits und Tokenbudget	Je nach Ihrer Auswahl für Abschneidenkonfiguration wird eine oder beide Optionen angezeigt. Standardwerte sind 20 Nachrichten und 5000 Token. Wir empfehlen, mit moderaten Werten zu beginnen und nach Bedarf anzupassen.
Zustandsisolierung für Executor-Agents	Wählen Sie Zustandslos, Privat oder Gemeinsam aus. Zustandslos: Jeder Executor-Agent sieht nur die Aufgabe, die vom Supervisor zugewiesen wurde. Zwischen den Anrufen wird keine Historie übertragen. Wählen Sie diese Option aus, wenn Sie die stärkste Isolation und den geringsten Cross-Agent-Kontext wünschen. Privat: Jeder Executor-Agent sieht nur seine eigenen vergangenen Interaktionen. Andere Executor-Agents der ursprünglichen Benutzerunterhaltung werden nicht angezeigt. Wählen Sie diese Option aus, wenn Ihr Executor Kontinuität über seine eigenen Aufgaben hinweg benötigt, aber keinen Kontext mit anderen Agents teilen soll. Gemeinsam verwendet: Executor-Agents können eine vollständige Unterhaltungshistorie für alle Agents und Benutzer anzeigen. Alle Agents arbeiten aus einem gemeinsamen Kontext. Wählen Sie diese Option aus, wenn Sie einen breiten Kontextaustausch benötigen und Datenschutz- und Prompt-Injection-Risiken geprüft haben.

Executor-Agent - Registerkarte "Modellparameter"

Auf der Registerkarte "Modellparameter" können Sie modellspezifische Parameter konfigurieren, die für das ausgewählte Modell verfügbar sind.

Hinweis:

Nur eine Teilmenge von Modellen zeigt konfigurierbare Parameter an. Die Parameter variieren auch je nach Modellfamilie.

Beispiele für Parameter sind Temperatur, Top K, Top P und Frequenzstraffung. Modellparameter können separat für Supervisor- und Executor-Agents konfiguriert werden.

Vorgeschlagene Executor-Anweisungen

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

Checkliste für Agents über Visual Builder

Verwenden Sie diese Liste als Richtlinie, um sicherzustellen, dass Sie alle erforderlichen Komponenten für einen Agent, der mit Visual Builder erstellt wurde, aufgenommen und konfiguriert haben.

Checkliste erstellen

Der Agent hat genau einen erwarteten Einstiegspunkt: Chat-Trigger / Nachricht.
Leitschienen sind in der vorgesehenen Position verbunden und bei Bedarf aktiviert. Es wird empfohlen, Schutzschienen zwischen der Trigger-Nachricht und dem Agent einzufügen.
Der Supervisor-Agent hat eine ausgewählte Region, ein ausgewähltes Modell und Orchestrierungsanweisungen. Gleiches gilt für Executor-Agents.
Konfigurieren Sie den Speicher des Multi-Agent-Systems auf der Registerkarte "Speicher" des Supervisor-Agents. Wählen Sie die Isolation des Executor-Status, die den Datenschutz- und Kontinuitätsanforderungen entspricht.
Jeder Executor Agent hat eine klare Spezialität und enge Anweisungen.
Jedes Tool wird nur an den Agent angehängt, der es verwenden soll.
Kein Knoten ist getrennt.
Ein AI-Compute wird an das Agent-System angeschlossen, um einzelne Tools zu testen und das Playground-Erlebnis auszuführen.

Tabelle 22-2 Allgemeine Probleme

Vorgang	Wahrscheinliche Ursachen	Empfohlene Maßnahme
Supervisor ruft keinen Executor auf	Supervisor-Anweisungen sind zu vage oder kein Executor ist verbunden.	Fügen Sie explizite Routingregeln hinzu, und bestätigen Sie, dass der Executor-Knoten mit dem Supervisor verbunden ist.
Executor gibt allgemeine oder nicht thematische Antworten zurück	Executor-Anweisungen sind zu allgemein.	Machen Sie die Executor-Rolle enger und definieren Sie die erforderliche Ausgabestruktur.
Tool wird nicht verwendet	Tool ist getrennt oder an den falschen Agent angehängt.	Prüfen Sie die Toolverbindung und das Abzeichen für die Anzahl der Agent-Tools.
Leitplanke brennt nicht	Guardrail-Abschnitt ist konfiguriert, aber nicht aktiviert.	Öffnen Sie den Guadrails-Knoten, und bestätigen Sie, dass der Abschnittsschalter aktiviert ist.
Kontextlecks über Agents hinweg	Die Zustandsisolierung wird auf "Freigegeben" gesetzt, oder der Speicher ist breiter als beabsichtigt.	Verwenden Sie stateless oder Private Isolation für eine strengere Trennung.
Nachfassfragen verlieren den Kontext	Speicher ist deaktiviert, oder das Abschneiden ist zu aggressiv.	Aktivieren Sie den Speicher, und passen Sie den maximalen Nachrichtengrenzwert an.

Agent-Durchlaufcode

Sie können Ihre eigene LangGraph-Codebasis in Oracle AI Data Platform Workbench für KI-Agents verwenden oder über die Agent-Codierungserfahrung direkt auf der Plattform einen brandneuen LangGraph-Agent erstellen.

Mit der Python-Library aidputils des AI Data Platform Workbench-Utilitys können Sie das Basismodell konfigurieren und Systemtools in Ihren Agent importieren. Die Aidputils-API-Referenz finden Sie unter Aidp-utils-API für Oracle AI Data Platform Workbench.

Agent SkillsTest auf der Registerkarte "Entwicklung" geöffnet.

Sie erstellen einen Agent über Code, indem Sie entweder eine vorhandene Codedatei hochladen oder Codedateien direkt in Ihrem Agent über den Inline Editor erstellen.

Der Inlinecodeeditor in Agents unterstützt die folgenden Codedateitypen:

Python (.py)
JSON
TXT
CSV
PSV
KAUF
Ordner

Sie können die verfügbaren Codedateien anzeigen und durch diese navigieren, indem Sie auf die Dropdown-Liste "File Selector" (Dateiauswahl) klicken.

Agent-Seite mit geöffneter und hervorgehobener Dropdown-Liste für die Dateiauswahl

Eintrags- und Abhängigkeitsdateien

Eingabedateien sind Codedateien, deren Klasse mit Setup- und Aufrufmethoden für einen als Code definierten Agent erwartet wird. In Oracle AI Data Platform Workbench müssen Sie eine Eingabedatei für Agents über Code festlegen.

Abhängigkeitsdateien sind Dateien, die Drittanbieter-Librarys enthalten, die von Ihrem als Code definierten Agent benötigt werden. Abhängigkeitsdateien sind in der Regel requirements.txt-Dateien, die eine Liste der erforderlichen Drittanbieterbibliotheken enthalten.

Hinweis:

Bibliotheken von Drittanbietern werden installiert, wenn Sie Ihren Code im Editor testen, indem Sie auf die Schaltfläche "Wiedergeben" klicken oder wenn Sie den Agent über die Registerkarte "Test" testen. Wir empfehlen, Bibliotheken von Drittanbietern zu installieren, indem Sie zuerst den Code testen. Fehler bei der Installation der Bibliotheken werden in der Ausgabezelle angezeigt.

Agent-Klasse

AgentBasic ist eine Vorlagenklasse zum Einrichten und Aufrufen eines einfachen Conversational Agents mit einem zustandsbehafteten LangGraph-Workflow. Es zeigt die Struktur, die für die minimale Wirkstoffentwicklung erforderlich ist, mit zwei Hauptmethoden:

setup(): Initialisiert den Agent-Workflow und definiert das Diagramm.
invoke(user_query, **kwargs): Führt den Agent für eine Benutzernachricht aus und gibt die Antwort zurück.

Sie kann direkt mit einer main()-Funktion ausgeführt und getestet werden, bevor sie in ein größeres System integriert wird.

Definition

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc())

Testaufruf

Dieser Testaufruf ist ideal für erste Funktionstests.

Hinweis:

Fügen Sie einen Haupteingangspunkt für Standalone-Tests hinzu.

import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())

Funktionsweise:

Das Skript erstellt einen Agent, richtet ihn ein und sendet eine Beispielbenutzermeldung.
Der Agent antwortet ({"messages": [{"role": "ai", "content": "hello world"}]} in diesem Beispiel).

Nutzungshinweis

Erstellen Sie eine Agent-Klasse mit den Setup- und Aufrufmethoden.

Setup()	Initialisiert den Agent-Workflow	agent.setup()
Aufrufen()	Führt den Agent mit einer Benutzernachricht aus	wait agent.invoke("Ihre Frage")

Asynchron: invoke() ist eine asynchrone Methode. Verwenden Sie sie mit await, oder führen Sie sie in einer asynchronen Schleife aus.
Testen: Der enthaltene main() Guard (if __name__ == "__main__":) erleichtert das Testen des Agent vor dem Deployment.

Agent durch Code durch Upload erstellen

Sie können Ihre End-to-End-Agent-Anwendung mit vorhandenem Code erstellen, indem Sie Ihre LangGraph-Codebasis hochladen.

Oracle AI Data Platform Workbench unterstützt LangGraph Version 1.0.1.

Hinweis:

Sie können einzelne Dateien und Ordner bis zu maximal 500 Dateien hochladen, jede Datei kann eine maximale Größe von 500 MB haben. Der Upload ist auf eine Gesamtgröße von 5 GB begrenzt.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Klicken Sie auf Hochladen.
Ziehen Sie eine Datei per Drag-and-Drop in den Bereich, oder klicken Sie, um eine Datei auszuwählen.
Klicken Sie auf Hochladen.

Agent durch Code erstellen, indem neuer Code erstellt wird

Sie können Ihre End-to-End-Agent-Anwendung mit vorhandenem Code erstellen, indem Sie Code direkt in Ihrem Agent über den Codeeditor erstellen.

Der Codeeditor unterstützt die folgenden Dateitypen:

Python (.py)
JSON
TXT
CSV
PSV
SH
Ordner

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Klicken Sie auf Neue Datei hinzufügen.
Geben Sie einen Namen für die Schlüsseldatei ein.
Wählen Sie einen Dateitypen aus der Dropdown-Liste aus.
Klicken Sie auf Create.

Eintragsdatei für Agents über Code festlegen

Für den AI-Agent durch Code ist eine Eingabedatei erforderlich, die über die für den Agent erwartete Klasse, das Setup und den Aufruf von Methoden verfügt.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Suchen Sie in der Registerkarte "Codeeditor" die Eingabedatei im linken Navigationsbereich. Wenn die Datei nicht vorhanden ist, können Sie sie hochladen, indem Sie auf Hochladen klicken oder sie erstellen, indem Sie auf Neue Datei hinzufügen klicken.
Klicken Sie mit der rechten Maustaste auf die Eingabedatei, und klicken Sie auf Eingabedatei festlegen. Sie können die Datei auch auswählen und auf die Schaltfläche Eintragsdatei festlegen oben rechts im Codeeditor klicken.

Abhängigkeitsdatei für Agents über Code festlegen

Sie müssen eine Abhängigkeitsdatei für Agents festlegen, die Code durchlaufen, der Librarys von Drittanbietern enthält, von denen Ihr Code abhängig ist.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Suchen Sie auf der Registerkarte "Codeeditor" die Abhängigkeitsdatei im linken Navigationsbereich, in der Regel requirements.txt. Wenn die Datei nicht vorhanden ist, können Sie sie hochladen, indem Sie auf Hochladen klicken oder sie erstellen, indem Sie auf Neue Datei hinzufügen klicken.
Klicken Sie mit der rechten Maustaste auf die Abhängigkeitsdatei, und klicken Sie auf Abhängigkeit festlegen. Sie können die Datei auch auswählen und auf die Schaltfläche Abhängigkeitsdatei festlegen oben rechts im Codeeditor klicken.

Testagentcode

Sie können den für Ihren Agent verwendeten Code auf der Registerkarte "Test" testen, um Code zu validieren und zu debuggen.

Zum Testen muss ein AI-Compute an Ihren Agent angeschlossen sein.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Klicken Sie auf die Registerkarte Playground.
Klicken Sie auf Wiedergeben, um die ausgewählte Codedatei zu testen.

In einer Ausgabezelle in der unteren Hälfte des Codeeditorfensters werden die Ausgaben von Druck- oder Logginganweisungen in Ihrem Code angezeigt. Fehler werden auch in der Ausgabezelle angezeigt.

Agent-Skills in Coding Experience

Mithilfe von Agent-Skills kann ein Agent aufgabenspezifische Anweisungen, Referenzdateien, Vorlagen, Assets und optionale ausführbare Skripte ermitteln und verwenden, ohne dieses Domainwissen in die Anweisungen des Agent zu programmieren.

Ein Skill wird als Ordner in Ihrer Agent-Codebasis gespeichert. Jeder Skill verfügt über eine erforderliche Datei SKILL.md, in der beschrieben wird, was der Skill tut und wie der Agent ihn verwenden soll. Ein Skill kann auch unterstützende Dateien wie Schemas, Beispiele, Prompts, Vorlagen, Assets oder Skripte enthalten.

Weitere Informationen finden Sie unter Überblick über Agent-Skills.

Agent-Skills unterstützen ein progressives Offenlegungsmodell:

Der Agent erkennt, dass ein Skill vorhanden ist.
Der Agent aktiviert den Skill nur, wenn er relevant ist.
Der Agent lädt zusätzliche Dateien nur bei Bedarf aus dem Skillordner.
Der Agent kann einen explizit deklarierten Skill-Eintragspunkt ausführen, wenn der Skill dies zulässt.

Einsatz von Agent Skills

Sie sollten Skills verwenden, wenn Sie wiederverwendbare Agent-Funktionen wie:

Domänenspezifische Anweisungen
Code- oder Datenanalyse-Workflows
Anleitung zur SQL-Generierung
Geschäftsprozess-Playbooks
Dateivorlagen
Schemareferenzen
Wiederverwendbare Skripte für sichere Berechnungen, Transformationen oder Lookups

Skills sind nützlich, wenn der Agent Zugriff auf spezialisiertes und wiederverwendbares Wissen haben sollte, Sie jedoch nicht alle diese Kenntnisse direkt in die Agent-Eingabeaufforderung einfügen möchten.

Wie Skills zur Laufzeit funktionieren

Zur Laufzeit bestimmt die Hostanwendung, welche Skillverzeichnisse verfügbar sind, wie z.B. Skillordner auf Projekt- und Benutzerebene. Die Plattform lädt die Metadaten jedes Skills aus SKILL.md und erstellt einen Katalog mit Schlüssel nach Skillname.

Der Agent kann dann kompetenzbezogene Tools verwenden:

Tool	Zweck
`activate_skill(name)`	Lädt die Skillanweisungen von SKILL.md.
`list_skill_files(name, path)`	Listet die in einem Skillordner verfügbaren Dateien auf.
`load_skill_file(name, path)`	Lädt eine unterstützende Datei aus dem Skillordner.
`run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)`	Führt einen explizit deklarierten Python-Eintragspunkt aus, wenn dies vom Skill zulässig ist.

Einige Umgebungen können auch eine Zusammenfassung der verfügbaren Skills direkt in die Systemaufforderung einbetten. In diesem Setup kann der Agent verfügbare Skills aus der Eingabeaufforderung ermitteln und dann activate_skill verwenden, wenn die vollständigen Anweisungen benötigt werden.

Skillordnerstruktur

Ein Skill verwendet ein Ordnerlayout im Stil von Agent Skills:

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

Nur SKILL.md ist erforderlich. Die anderen Ordner sind optional.

Ordner oder Datei	Erforderlich	Zweck
`SKILL.md`	Ja	Hauptmetadaten und -anweisungen für Skills.
`references/`	Nr.	Dokumentation, Schemas, Beispiele oder Vorlagen werden unterstützt.
`scripts/`	Nr.	Python-Skripte, die nur ausgeführt werden können, wenn sie explizit als Einstiegspunkte deklariert werden.
`assets/`	Nr.	Statische Assets, die vom Skill verwendet werden.

SKILL.md wird geschrieben

Jeder Skill muss YAML-Frontmatter am oberen Rand von SKILL.md enthalten, gefolgt von Markdown-Anweisungen.

Grundlegendes Beispiel

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

Tabelle 22-3 Unterstützte Frontmatter-Felder

Feld	Erforderlich	Beschreibung
name	Ja	Eindeutiger Skillname, der von Katalog und Tools verwendet wird.
description	Ja	Kurzbeschreibung für Discovery und Routing.
license	Nr.	Lizenz- oder Nutzungs-Policy für den Skill.
Kompatibilität	Nr.	Kompatibilitätshinweis für unterstützte Laufzeiten oder Plattformen.
Metadaten	Nr.	Metadatenzuordnung von Zeichenfolgen zu Zeichenfolgen.
zulässige Werkzeuge	Nr.	Durch Leerzeichen getrennte Liste der Tools, die dieser Skill zulässt.
Einstiegspunkte	Nr.	Liste der ausführbaren Eintragspunkte, die vom Skill deklariert wurden.

Unterstützende Dateien hinzufügen

Unterstützende Dateien ermöglichen es einem Skill, detaillierte Inhalte außerhalb der Hauptanweisungen zu behalten. Dadurch wird SKILL.md fokussiert und der Agent erhält weiterhin Zugriff auf einen umfassenderen Kontext. Beispiel:

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

Der Agent kann diese Dateien prüfen mit:

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")

Unterstützende Dateien für Inhalte wie:

Datenbankschemas
API-Beispiele
Prompt-Vorlagen
Stilleitfäden
Domainglossare
Schritt-für-Schritt-Wiedergabebücher
Testfälle oder Beispiele

Ausführbaren Skill erstellen

Ein Skill kann optional das Verhalten wiederverwendbarer ausführbarer Dateien über run_skill_entrypoint angeben. Dies ist für kontrollierte Vorgänge wie Berechnungen, Transformationen, Validierungen oder das Abrufen strukturierter Daten vorgesehen.

Ausführbare Skills müssen zwei Anforderungen erfüllen:

Der Skill muss run_skill_entrypoint in zulässige Tools enthalten.
Das Skript muss explizit im Entrypoints-Abschnitt von SKILL.md deklariert werden.

Beispiel für einen ausführbaren Skill

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

SKILL.md

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

Regeln für ausführbare Entrypoints

Ausführbare Einstiegspunkte sind absichtlich eingeschränkt. Die Plattform führt nur Python-Dateien aus, die:

Unter dem Skript/Verzeichnis des Skills
Deklariert in der Frontmatter der Einstiegspunkte des Skills
Durch die Einstellung allowed-tools des Skills zulässig

Die Plattform bietet keine willkürliche Skriptausführung für allgemeine Zwecke. Skripte, die nicht in SKILL.md deklariert sind, können nicht ausgeführt werden.

Der Skript-Runner verwendet einen Timeout, standardmäßig 10 Sekunden, führt Python mit isoliertem Modusverhalten aus und wendet Pfadbeschränkungen an. Die unterprozessbasierte Ausführung ist jedoch keine vollständige Betriebssystem-Sandbox. Für die Produktion sollte eine höhere Isolation wie Container, eingeschränkte Dateisysteme oder Netzwerkkontrollen in Betracht gezogen werden.

Toolberechtigungen mit allowed-tools

allowed-tools fungiert als Berechtigungsgate auf Skillebene. Für einen Nur-Dokumentation-Skill dürfen Sie nur Tools zum Lesen von Dateien zulassen:

allowed-tools: "load_skill_file list_skill_files"

Für einen Skill, der deklarierte Skripte ausführen kann, geben Sie run_skill_entrypoint an:

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"

Fügen Sie keinen run_skill_entrypoint hinzu, es sei denn, der Skill benötigt wirklich ausführbares Verhalten.

So lassen Sie Ihre Agenten Fähigkeiten entdecken und nutzen

Um Ihren Agent mit Skills zu ergänzen, müssen Sie einen Skillkatalog, eine Skill-Middleware instanziieren und Skills mithilfe der folgenden Objekte aus der helppUtils-Bibliothek in Tools konvertieren:

Tool	Zweck
`discover_skill_catalog`	Standardsuchorte für Skills festlegen (Projekt + Benutzer) SkillCatalog aus erkannten Verzeichnissen erstellen
`SkillMiddleware`	Hängen Sie die verfügbare Kompetenzübersicht und Routingregeln an den System-Prompt an. Stellen Sie Werkshelfer für die Workspace-gesteuerte Middleware-Konstruktion bereit.
`make_skill_tools`	Diese Methode gibt die Tools für die Skill-Erkennung zurück – activate_skill, list_skill_files, load_skill_file und run_skill_entrypoint. Diese Tools können vom Agent verwendet werden, um verschiedene Skills zu aktivieren und auszuführen.

Im Folgenden finden Sie ein Beispiel für Ihre Eingabedatei:

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

Sie können Ihren Kompetenzkatalog debuggen, indem Sie diese Logger-Anweisung zu Ihrem Code hinzufügen. Dadurch werden alle im Kompetenzkatalog erkannten Skills gedruckt:

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

Qualifikationspriorität

Die Plattform kann Skills aus mehreren Speicherorten laden, wie Verzeichnissen auf Projektebene und Benutzerebene. Der Katalog aggregiert diese Speicherorte in einer einzigen Liste mit Skills mit Namensschlüssel.

Wenn mehrere Filialen einen Skill mit demselben Namen enthalten, bestimmt die Priorität, welcher Skill verwendet wird. Spätere Speicher überschreiben frühere Speicher, sodass eine Hostanwendung steuern kann, ob Skills auf Benutzerebene, Skills auf Projektebene oder Skills auf Workspace-Ebene Priorität haben.

Best Practices für das Erstellen von Skills

Fokus auf SKILL.md halten

Verwenden Sie SKILL.md für die Kernanweisungen, die der Agent unmittelbar nach der Aktivierung benötigt. Setzen Sie lange Schemas, Beispiele und Referenzmaterial in Referenzen/.

Schreiben Sie klare Beschreibungen

Das Beschreibungsfeld wird für die Discovery verwendet. Machen Sie den Skill so spezifisch, dass der Agent weiß, wann er den Skill aktivieren soll.

Gut:

description: Helps generate BigQuery SQL using the finance warehouse schema.

Weniger nützlich:

description: Helps with data.

Explizite Eintragspunktnamen verwenden

Entrypoint-Namen sollten den Vorgang klar beschreiben:

entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv

Vermeiden Sie vage Namen wie:

entrypoints: 
   - name: run 
   - name: do_it

Strukturierte Ergebnisse zurückgeben

Ausführbare Skripte sollten nach Möglichkeit JSON-serialisierbare Ergebnisse zurückgeben. Dadurch wird die Ausgabe für den Agent einfacher zu prüfen und zu verwenden.

Vermeidung unnötiger Ausführung

Bevorzugt Anweisungen und Referenzdateien, wenn möglich. Verwenden Sie ausführbare Einstiegspunkte nur für Vorgänge, die wirklich Code erfordern.

Neuen Skill hinzufügen

Sie können neue Agent-Skills hinzufügen, indem Sie einen neuen Ordner im Skills-Verzeichnis erstellen und die erforderlichen Dateien und Ordner hinzufügen.

Erstellen Sie einen Ordner unter dem Skillverzeichnis: .agents/skills/<skill-name>/.

Fügen Sie eine SKILL.md-Datei mit der erforderlichen Frontmatter hinzu.

---
name: <skill-name>
description: <what this skill helps the agent do>
---

Schreibe die Skill-Anweisungen in Markdown unterhalb der Frontmatter.
Fügen Sie optionale Unterstützungsdateien hinzu unter:
```
references/
assets/
scripts/
```
Wenn der Skill ausführbar ist, fügen Sie run_skill_entrypoint zu allowed-tools hinzu, deklarieren Sie entrypoints in SKILL.md, und platzieren Sie die Python-Implementierung unter scripts/.

Neue ausführbare Fähigkeit zu einem vorhandenen Skill hinzufügen

Sie können einem vorhandenen Skill einen neuen ausführbaren Vorgang hinzufügen, um die Funktionen von SKILL.md zu erweitern.

1. Fügen Sie eine Python-Datei unter dem Verzeichnis scripts/ des Skills hinzu.
```
.agents/skills/<skill-name>/scripts/my_operation.py 
```

2. Implementieren Sie eine Funktion run(...).

def run(*, input_text: str) -> dict:
    return {
        "length": len(input_text),
        "uppercase": input_text.upper(),
    }

3. Fügen Sie SKILL.md einen übereinstimmenden Einstiegspunkt hinzu.

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: my_operation
    script: scripts/my_operation.py
    func: run
    description: Processes input text and returns structured output.

4. Testen Sie den Einstiegspunkt mit einem JSON-Objekt als Argumente.
```
{
  "input_text": "hello"
}
```

Agent-Skills - Fehlerbehebung

Wenn Probleme bei der Implementierung von Agent-Skills auftreten, prüfen Sie diese Liste, um Ihr Problem zu lösen.

Der Agent sieht meinen Skill nicht

Prüfen Sie Folgendes:

Der Skillordner befindet sich unter einem konfigurierten Skillverzeichnis.
Der Ordner enthält SKILL.md.
SKILL.md hat eine gültige YAML-Frontmatter.
Die Frontmatter enthält sowohl Name als auch Beschreibung.

Der Agent aktiviert den falschen Skill

Prüfen Sie, ob Skillnamen in verschiedenen Skillverzeichnissen doppelt vorhanden sind. Wenn zwei Skills denselben Namen haben, bestimmt die Katalogpriorität, welcher Skill verwendet wird.

Eine unterstützende Datei kann nicht geladen werden

Prüfen Sie Folgendes:

Die Datei befindet sich im Skillordner.
Der Pfad enthält keine Durchgänge wie ../.
Die Datei ist nicht ausgeblendet.
Die Datei ist nicht ausgeschlossen, z. B. __pycache__ oder .pyc.

Ein Einstiegspunkt wird nicht ausgeführt

Prüfen Sie Folgendes:

run_skill_entrypoint ist in allowed-tools enthalten.
Der Einstiegspunkt wird in SKILL.md deklariert.
Der Skriptpfad befindet sich unter "skripts/".
Das Skript ist eine .py-Datei.
Der Funktionsname in func ist im Skript vorhanden.
Die Argumente sind ein gültiges JSON-Objekt.

Ein Einstiegspunkt-Timeout

Erhöhen Sie timeout_seconds nur, wenn der Vorgang voraussichtlich länger dauert. Bei Vorgängen mit langer Ausführungszeit oder ressourcenintensiven Vorgängen sollten Sie den Vorgang in einen dedizierten Service oder eine isoliertere Ausführungsumgebung verschieben.

Beispiel: Agent-Skill abschließen

Dieses Beispiel zeigt, wie ein vollständiger Agent-Skill nach der Implementierung aussehen würde.

Ordnerstruktur

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

SKILL.md

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

Agent-Tests

Sie können Ihre Agents testen, um eine Vorschau ihrer Ausgabe anzuzeigen und sie zu debuggen. Sie können auch Testsessions erstellen und verwalten, um verschiedene Testszenarios für Ihre Agents zu untersuchen.

Der erste Schritt zum Testen eines Agent besteht darin, den Agent an ein AI-Compute anzuhängen. Durch das Anhängen eines Agent wird eine Kopie Ihres Agent an ein AI-Compute übertragen. Solange Ihr Agent an ein AI-Compute angehängt ist, werden alle Änderungen, die Sie an Ihrem Agent vorgenommen haben, jedes Mal an das angehängte Compute propagiert, wenn Sie auf die Schaltfläche "Test" klicken.

Nachdem Sie auf die Schaltfläche Test geklickt haben, gelangen Sie zum Test-Playground.

Agent-Seite geöffnet für Test Playground. Chat-, Traces- und Spans- und Explorerbereiche sind hervorgehoben

Der Testspielplatz hat folgende Komponenten:

Ein Chatfenster, in dem Sie eine Session initiieren und mit dem Agent chatten oder eine vorhandene Session fortsetzen können
Eine grafische Darstellung des Agent
Panel mit einem Traces- und Spans-Baum, der während der Session generiert wird
Ein Traces- und Spans-Explorer-Bereich, der Traces und Spans-Attribute, Eingabe/Ausgabe anzeigt. Die Registerkarte "Details" enthält IDs, Start- und Endzeit, Ausführungszeit, während die Registerkarten "Ereignisse" alle Fehler während der Ausführung hervorheben.

Mit dem Playground können Sie jeden Agent unabhängig voneinander interagieren und testen, wenn Sie dies wünschen. Standardmäßig ist der Supervisor-Agent ausgewählt. Sie können jedoch jeden Executor-Agent unabhängig chatten und testen. Dadurch können Sie das Verhalten eines Supervisor-Agents simulieren, der Anforderungen an Executor-Agents ausgibt. Wählen Sie dazu im Chatfenster im Dropdown-Menü den Agent aus, den Sie testen möchten.

Traces und Spans werden im zentralen Bereich angezeigt, sobald Sie Ihre erste Nachricht erstellen. Jede Aufgabe entspricht einer anderen Benutzernachricht. Sie können auf den linken Caret klicken, um das Trace zu erweitern und die Spans zu prüfen.

Testen Sie Ihre Agenten im Spielplatz

Sie können visuellen Builder und LangGraph-basierte Agents auf dem Testspielplatz testen, um Ihre Agents zu validieren und zu debuggen.

Zum Testen muss ein AI-Compute an Ihren Agent angeschlossen sein. Sie können ein neues AI-Compute-Cluster hinzufügen, indem Sie AI-Cluster für einen Agent erstellen befolgen oder ein vorhandenes AI-Compute-Cluster anhängen, indem Sie ein vorhandenes AI-Cluster an einen Agent anhängen.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Klicken Sie am oberen Rand der Leinwand auf Playground. Es kann einige Sekunden dauern, bis der Agent an das angeschlossene Compute übertragen wird.

Ihr Agent wird im Test-Playground angezeigt.

Agent-Testsession erstellen

Sie können eine Testsession erstellen, um eine neue Unterhaltung mit Ihrem Agent zu initiieren.

Alle Sessions, die im Test-Playground-Ziel erstellt wurden, werden auf dem angeschlossenen Compute gehostet. Sobald eine Session erstellt wurde, kann sie später fortgesetzt werden.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Klicken Sie oben auf der Leinwand auf Playground
Klicken Sie im Sessionselektor auf Session erstellen.
Starten Sie ein Dialogfeld mit Ihrem Agent, indem Sie eine Abfrage in das Chatfeld eingeben.

Agent-Testsession fortsetzen

Sie können Agent-Testsessions fortsetzen, die Sie zuvor erstellt haben.

Hinweis:

Sie können nur Sitzungen fortsetzen, die Sie erstellt haben.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace. Klicken Sie auf den Agent-Namen.
Klicken Sie oben auf der Leinwand auf Playground
Wählen Sie in der Session-Dropdown-Liste eine vorherige Session aus.
Setzen Sie Ihr Dialogfeld mit Ihrem Agent fort, indem Sie eine Abfrage in das Chatfeld eingeben.

Agent-Testsession löschen

Sie können Testsessions für Agents löschen, die auf dem angehängten AI-Compute gehostet werden, und Sessions, die auf einem bereitgestellten Agent erstellt wurden.

Navigieren Sie zu Ihrem Agent in Ihrem Workspace.
Klicken Sie auf die Registerkarte Sessions.
Klicken Sie neben der Session, die Sie löschen möchten, auf Aktionen und dann auf Löschen.
Klicken Sie auf Löschen.

Agent-Tools

Oracle AI Data Platform Workbench unterstützt Toolvorlagen, die so konfiguriert werden können, dass sie auf Ihre Daten zugreifen und für Ihre Anwendungsfälle geeignet sind.

Agents unterstützen Konfigurationen, die aus einem einzelnen Agent bestehen, der eine Schnittstelle zu einem oder mehreren Tools herstellen kann. Oracle AI Data Platform Workbench bietet drei Toolvorlagen, die zur Verwendung über visuelle Abläufe oder Code konfiguriert werden können:

Benutzerdefinierter Code: Mit dem Tool für benutzerdefinierten Code können KI-Entwickler ihr Tool mit Python implementieren. Entwickler verpacken ihr Tool in einer ZIP-Datei, laden es in ihren Workspace hoch und konfigurieren es als Knoten in ihrem Agent. Custom Code-Tools sind für Fälle gedacht, in denen integrierte Tools nicht die erforderliche Integration bieten.
HTTP-Anforderung: Mit den HTTP-Anforderungstools können Entwickler unterstützte REST-API-Aufrufe in ihren Agents verwenden und die AI Data Platform Workbench-APIs und die von ihnen bereitgestellten Funktionen nutzen. Agents können REST-APIs verwenden, um Workspace-Objekte zu erstellen, Details zu prüfen, Listen abzurufen oder vorhandene Objekte zu ändern. Eine vollständige Liste der verfügbaren APIs finden Sie unter REST-API für Oracle AI Data Platform Workbench.
Prompt: Mit dem Prompt-Tool kann der KI-Entwickler einen parametrisierten Prompt definieren, der an ein LLM zur Auswahl ausgegeben werden kann. Häufige Anwendungsfälle für ein Prompt-Tool sind E-Mail-Entwurfsaufgaben, Übersetzungsaufgaben, Stilkonvertierung, Git-Commit-Nachricht und Codeerklärungen.
RAG: Mit dem RAG-Tool können Agents relevantes externes Wissen abrufen, bevor sie eine Antwort generieren. In AI Data Platform Workbench fragt das RAG-Tool eine Wissensdatenbank ab (26ai Vector Search) und ruft semantisch relevante Dokument-Chunks ab. Diese Chunks werden dann zur Antwortgenerierung an den Agent übergeben.
SQL: Mit dem SQL-Tool können Agents SQL-Abfragen für strukturierte Datenquellen ausführen, die über externe Kataloge registriert sind, wie Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing oder Oracle AI Database. Das Tool ist für Szenarien gedacht, in denen die SQL-Abfragen vordefiniert sind und parametrisiert werden können. Ziel ist es, dass ein Agent den Parametern Werte zuweist. Dieses Tool ist kein NL2SQL-Tool, das eine SQL-Abfrage basierend auf einer Eingabeaufforderung in natürlicher Sprache generiert.

Hinweis:
Das SQL-Tool führt nur Abfragen für Daten in einem externen Katalog aus. Daten, die in einem Standardkatalog gespeichert sind, werden nicht unterstützt.

Agent-Flow-Tools durch Visual Flow

Wenn Sie Agents Tools über den visuellen Ablauf hinzufügen, finden Sie Tools unter Toolvorlagen in Ihrem Agent. Sie fügen Ihrem Agent ein Tool hinzu, indem Sie es per Drag-and-Drop in die visuelle Flussleinwand ziehen. Nachdem Sie den Werkzeugknoten auf die Leinwand gezogen haben, stellt der Knoten automatisch eine Verbindung zum Agent her.

Eine Agent-Seite mit hervorgehobenem Abschnitt "Toolvorlagen" und einem Pfeil, der von den Tools auf die Leinwand zeigt

Jedes Tool kann in der Registerkarte Parameter konfiguriert und unabhängig vom Agent getestet werden, indem Sie auf die Registerkarte Test klicken.

Hinweis:

Sie müssen Ihrem Agent eine AI Compute-Instanz zuordnen, bevor Sie ein Systemtool testen können. Wenn keine Compute-Instanz angeschlossen ist, ist die Registerkarte "Test" deaktiviert.

Agent-Flow-Tools über LangGraph-Code

Sie fügen Ihren LangGraph-codierten Agents über eine Instanz der Klasse AIDPToolConf() RAG-, SQL- und Prompt-Tools hinzu.

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class , conf, params)

Die Parameter spiegeln das visuelle Ablauferlebnis für Tools wider. Für jedes Tool müssen Sie Folgendes angeben:

Name: Ein aussagekräftiger Name, der Benutzern und dem LLM hilft, den Zweck des Tools zu verstehen.
Beschreibung: Eine gründliche Zusammenfassung, die ausreichende Informationen für Benutzer und LLMs bereitstellt, um zu verstehen, was das Tool tut.
tool_class: Der unterstützte Tooltyp, entweder PromptTool, SQLTool oder RAGTool.
conf: Die Tool-Konfiguration. Diese Informationen sind im LLM ausgeblendet.
params: Die Parameter, die dem LLM angezeigt werden.

Benutzerdefiniertes Werkzeug

Mit dem Tool für benutzerdefinierten Code können Agent-Entwickler AI Data Platform mit ihrem eigenen Python-Code erweitern.

Sie verpacken Ihre Toolimplementierung als ZIP-Datei, laden sie in Ihren Workspace hoch und konfigurieren sie als benutzerdefinierten Code-Toolknoten im Agent. Der Agent ruft Ihren Code als Tool auf, wobei Parameter zur Laufzeit vom LLM bereitgestellt werden.

Das Tool für benutzerdefinierten Code ist für Fälle gedacht, in denen die integrierten Tools (HTTP, SQL, RAG, MCP) die erforderliche Integration nicht abdecken. Beispiel: Sie müssen lokale Berechnungen durchführen, ein domänenspezifisches Format parsen oder mehrere Schritte erstellen, die dem Agent als einzelner Toolaufruf angezeigt werden sollen.

Beim Hochladen einer ZIP-Datei mit Python-Code für Ihr benutzerdefiniertes Codetool hat AI Data Platform Workbench die folgenden Limits:

Constraint	Grenzwert
Maximale ZIP-Größe	10 MB
Maximale Dateigröße innerhalb der ZIP-Datei	10 MB pro Datei
Maximale gesamte unkomprimierte Größe	500 MB
Pfaddurchlauf	Blockiert (../ abgelehnt)

Hinweis:

Benutzerdefinierte Codetools werden auf dem AI-Compute ausgeführt, das an Ihren Agent angehängt ist. Der Code hat je nach Workspace-Netzwerkkonfiguration Zugriff auf die Compute-Umgebung und den ausgehenden Netzwerkzugriff. Laden Sie nur Code aus vertrauenswürdigen Quellen hoch.

Benutzerdefinierte Code-Tool-Parameter

Auf der Registerkarte "Parameter" konfigurieren Sie die statischen Einstellungen für jede Werkzeugklasse im Paket. In der Dropdown-Liste "Werkzeugklasse" können Sie zwischen den im Paket erkannten Werkzeugen wechseln.

Die Toolseite für benutzerdefinierten Code ist geöffnet. Die Registerkarte "Parameter" ist ausgewählt. Der Bereich "Konfiguration" wird auf der linken Seite angezeigt. Der Definitionsbereich des AI-Tools wird auf der rechten Seite angezeigt.

Die Registerkarte "Parameter" des benutzerdefinierten Codetools enthält die folgenden Abschnitte:

Werkzeugklasse: Wählen Sie die zu konfigurierende Werkzeugklasse aus. Die Dropdown-Liste wird aus den in tool_implementation.py registrierten Klassen aufgefüllt.
Beschreibung: Eine klare, präzise Beschreibung der Funktionen des Tools. Die Beschreibung wird dem Agent zur Verfügung gestellt und hilft dem LLM, zu entscheiden, wann das Tool aufgerufen werden soll. Die Standardbeschreibung wird aus tool_config.json gelesen und kann hier außer Kraft gesetzt werden.
Konfiguration: Die statischen Einstellungen, die das Tool zur Laufzeit benötigt. Dies sind die Schlüssel, die im Konfigurationsobjekt von tool_config.json definiert sind. Beispiele sind Timeout, base_dir, max_output_lines und Zugangsdatenreferenzen. Konfigurationswerte unterstützen {{variable}} Laufzeitparameterreferenzen. Sessionvariablen werden derzeit nicht durch die Konfiguration eines benutzerdefinierten Tools ersetzt. Wenn Sie einen Sessionwert benötigen, übergeben Sie ihn als Laufzeitparameter vom Agent.
KI-Tooldefinition: Das dem Agent angegebene Schema, einschließlich Toolname, Beschreibung und Laufzeitparametern, die der Agent übergeben kann. Das Schema wird automatisch aus dem Schemaarray in tool_config.json gerendert.

Benutzerdefiniertes Code-Tool erstellen

Ein Toolpackage für benutzerdefinierten Code ist eine ZIP-Datei mit der folgenden Struktur:

my_tool.zip 
├── tool_implementation.py    # Required. Contains the tool class(es). 
├── tool_config.json          # Required. Tool metadata and schema. 
├── requirements.txt          # Optional. Python dependencies. 
├── utils/                    # Optional. Helper modules. 
│   ├── __init__.py 
│   └── helpers.py 
├── config/                   # Optional. Static configuration files. 
│   └── settings.yaml 
└── wheels/                   # Optional. Bundled wheel files for offline install. 
    └── humanize-4.15.0-py3-none-any.whl

tool_implementation.py

Jede Werkzeugklasse erweitert CustomToolBase und ist mit @BaseTool.register verziert. Die Klasse muss die _execute_tool-Klassenmethode implementieren, welche die Toolkonfiguration, die Laufzeitparameter vom Agent und die Systemkontextvariablen empfängt und einen Wert wie dict, str oder list zurückgibt.

Folgendes ist eine leere Beispielvorlage einer tool_implementation.py:

"""Custom Code tool implementation.""" 
from aidputils.agents.tools.custom_tools.base import CustomToolBase 
 
 
@BaseTool.register 
class MyTool(CustomToolBase): 
    """Brief description of what the tool does.""" 
 
    @classmethod 
    def _validate_config(cls, conf, runtime_params, **context_vars): 
        """Optional. Validate configuration before execution. 
        Raise ValueError to abort the call. 
        """ 
        # Example: require an api_key in the tool configuration 
        if not conf.get("conf", {}).get("api_key"): 
            raise ValueError("api_key is required") 
 
    @classmethod 
    def _execute_tool(cls, conf, runtime_params, **context_vars): 
        """Required. Implement the tool logic. 
 
        Args: 
            conf: the AIDPToolConf dict. User configuration values 
                live under conf["conf"] when the tool is invoked from 
                a deployed agent. During a Test run the tool may 
                receive a flat conf dict; the Developer Toolkit example 
                below uses a small _get_cfg helper that tolerates both 
                shapes. 
            runtime_params: the runtime parameters passed by the 
                agent at invocation time. 
            context_vars: system context (such as datalake_id). 
 
        Returns: 
            Any value (dict, str, list, ...). It will be wrapped into 
            the MCP response by the framework. 
 
            To signal a failure, raise an exception: 
              - ValueError -> INVALID_CONFIG 
              - any other exception -> TOOL_EXECUTION_ERROR 
            Do NOT return {"error": "..."}; the framework wraps a 
            successful return in {"response": ..., "success": True}, 
            so a returned error dict is treated as a normal payload 
            and the agent will not see it as a failure. 
        """ 
        tool_conf = conf.get("conf", conf) 
        param_value = runtime_params.get("my_param", "") 
        # Tool logic here 
        return {"output": f"Processed: {param_value}"} 
 
    @classmethod 
    def _transform_response(cls, response): 
        """Optional. Transform the response before MCP formatting.""" 
        return response

tool_config.json

In der Datei tool_config.json werden die Tools im Package beschrieben: Anzeigename, Beschreibung, Version, Laufzeitparameterschema und Standardkonfigurationswerte. Jedes in tool_implementation.py registrierte Tool muss einen entsprechenden Eintrag im Tools-Array aufweisen.

Folgendes ist eine leere Beispielvorlage einer tool_config.json:

{
   "displayName": "My Tool Package",
   "description": "Brief description of the tool package.",
   "tools": [
     {
       "toolClassName": "MyTool",
       "displayName": "My Tool",
       "description": "Clear description of when the agent should call this tool.",
       "version": "1.0.0",
       "schema": [
         {
           "name": "my_param",
           "type": "string",
           "description": "What this parameter is for."
         }
       ],
       "conf": {
         "timeout": 30
       }
     }
   ]
 }

Schemafeldtypen

Die Registerkarte "Parameter" im Visual Builder akzeptiert Zeichenfolge, Zahl und booleschen Wert. Die Laufzeit akzeptiert ein breiteres Set beim Erstellen von tool_config.json von Hand: int, integer, float, double, number, numeric, bytes, list, array, sequence, dict, map, mapping, set, tuple, none, null, plus generische Formulare wie list[int]. Diese breiteren Typen können aus JSON verwendet werden, werden jedoch nicht in der UI-Dropdown-Liste angezeigt.

Requirements.txt

In der Datei requirements.txt werden die Python-Abhängigkeiten aufgeführt, die Ihr Tool benötigt. Die Standardpip-Syntax wird unterstützt, einschließlich Versionsspezifikatoren und Kommentaren. Die Datei ist optional. Wenn Ihr Tool nur die Python-Standardbibliothek oder vorinstallierte Packages verwendet, benötigen Sie keine requirements.txt.

Im Folgenden finden Sie ein leeres Beispiel für requirements.txt:

# List third-party dependencies one per line. 
# Examples: 
# humanize>=4.0 
# python-dateutil>=2.8,<3.0 
# beautifulsoup4==4.12.3

AI Data Platform Workbench filtert die Abhängigkeiten in requirements.txt, bevor sie auf dem AI-Compute installiert werden, um Laufzeitkonflikte mit der Plattform selbst zu vermeiden. Die Filterregeln lauten wie folgt:

Kategorie	Beispiel	Aktion
Plattformpakete	langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml	Verworfen (bricht die Agent-Laufzeit).
Vorinstallierte Packages	oci, Requests, Requests-Toolbelt, Websockets, Kryptographie, certifi, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson	Übersprungen (bereits verfügbar, keine Deklaration erforderlich).
URL- oder VCS-Installationen	git+https://..., -e ./local_pkg	Blockiert (Sicherheit).
Alles weitere	humanize, beautifulsoup4, jmespath	installiert wird.

Hinweis:

Abhängigkeiten, die in requirements.txt deklariert werden, werden während des vollständigen Deployments des Agent installiert. Abhängigkeiten werden nicht während eines einzelnen Testlaufs im Konfigurationsbereich installiert. Wenn Ihr Tool von Paketen von Drittanbietern abhängt, stellen Sie zuerst den Agent bereit, und üben Sie dann das Tool aus dem Playground aus.

Für Tools, die Abhängigkeiten benötigen, die nicht vorinstalliert sind und bei denen eine deterministische Offline-Installation wichtig ist, können Sie WHL-Dateien in einem Wheels/Verzeichnis im Root-Verzeichnis der ZIP-Datei bündeln. Die Plattform wird zuerst aus dem lokalen Laufwerksverzeichnis installiert und fällt nur bei Bedarf wieder in den Paketindex zurück. Dies ist der empfohlene Ansatz für Produktionswerkzeuge.

Bündelräder für die Offline-Installation

pip download \
  --dest wheels/ \
  --platform manylinux_2_28_x86_64 \
  --python-version 3.11 \
  --only-binary=:all: \
  -r requirements.txt

Werkzeuglebenszyklus-Hooks

Custom Code-Tools unterstützen drei Lebenszyklusmethoden. Nur _execute_tool ist erforderlich.

Methode	Bei Aufruf	Zweck
validate_config	Vor _execute_tool	Validiert die Konfiguration. ValueError auslösen, um den Aufruf vor der Ausführung abzubrechen.
_execute_tool	Bei jedem Toolaufruf	Eingabe erforderlich. Implementiert das Verhalten des Tools. Gibt einen beliebigen Wert zurück (dict, str, list) und löst eine Ausnahme aus, um einen Fehler zu signalisieren (ValueError → INVALID_CONFIG, any other exception → TOOL_EXECUTION_ERROR). Verwenden Sie keinen zurückgegebenen {"error": "..."} diktieren, da es als normale Payload behandelt wird.
_transform_response	Nach _execute_tool	Transformieren Sie die Antwort, bevor sie im MCP-Format gewrappt und an den Agent zurückgegeben wird.
prompt_template	string (Zeichenfolgendatentyp)	Prompt-Vorlage, die vom LLM verwendet wird, mit Variablen im Format {{variable}} für dynamisches Einfügen

Konfigurationswerte im Vergleich zu Laufzeitparametern

Benutzerdefinierte Code-Tools verfügen über zwei verschiedene Eingabequellen, die leicht zu verwechseln sind. Konfigurationswerte stammen aus dem Abschnitt "Konfiguration" der Registerkarte "Parameter" und werden beim Deployment des Agent in das Tool eingebrannt. Laufzeitparameter stammen bei Aufrufzeit vom Agent und sind bei jedem Aufruf unterschiedlich.

Der Zugriff auf Konfigurationswerte erfolgt über conf.get("conf", conf). Verwenden Sie sie für Dinge, die sich nicht zwischen Aufrufen ändern – Basis-URLs, Zugangsdatenreferenzen, Timeouts, Ausgabelimits.
Der Zugriff auf Laufzeitparameter erfolgt über runtime_params.get("name"). Verwenden Sie sie für die Werte, die der Agent beim Aufruf tatsächlich entscheidet – die Abfrage, den Dateipfad, den Anforderungsbody.

Hinweis:

Konfigurationswerte können die Vorlagenersetzung durchlaufen und als Zeichenfolgen ankommen, selbst wenn Sie sie als Zahlen definiert haben. Numerische Konfigurationswerte immer defensiv erzwingen. Beispiel: int(tool_conf.get("timeout", 30)).

Mehrere Tools pro Paket

Eine einzelne ZIP-Datei kann mehrere Werkzeugklassen enthalten. Jede mit @CustomToolBase.register registrierte Klasse wird zu einem separaten Tool im Agent. Im Bereich "Tools" auf der Registerkarte "Package" werden alle erkannten Tools aufgeführt, und Sie können jedes Tool unabhängig aktivieren. Jedes Tool wird auf der Registerkarte "Parameter" über die Dropdown-Liste "Werkzeugklasse" separat konfiguriert.

Codetool durch LangGraph-Code

Im Code Builder wird ein benutzerdefiniertes Codetool über die Python-Library von aidpUtils registriert, indem das hochgeladene Package referenziert und eine seiner Toolklassen ausgewählt wird.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
 from aidputils.agents.toolkit.configs import AIDPToolConf
 
hello_tool_conf = AIDPToolConf(
     name="hello_tool",
     description="Returns a hello world greeting.",
     tool_class="HelloTool",  # the class registered with @BaseTool.register
     conf={},                  # values from tool_config.json "conf"; supports {{variable}} substitution
     params=[
         {"name": "name", "type": "string",
          "description": "Name to greet."}
     ],
 )
 
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())

tool_class muss der genaue Klassenname sein, der über @BaseTool.register in tool_implementation.py registriert ist. Das Framework sucht die Klasse in BaseTool.tool_class_registry[tool_class]. conf spiegelt das conf-Objekt des übereinstimmenden Eintrags in tool_config.json wider.

Hinweis:

Platzieren Sie package_path oder tool_class_name nicht in conf, da sie nicht verbraucht werden.

Benutzerdefinierte Code-Tools für Test-Agent

Auf der Registerkarte Test können Sie das Tool ausführen, ohne den vollständigen Agent auszuführen. Geben Sie Werte für alle Laufzeitparameter und Sessionvariablen an, die in der Konfiguration referenziert werden. Klicken Sie dann auf "Ausführen", um das Tool aufzurufen und die Antwort anzuzeigen.

Die Toolseite für benutzerdefinierten Code ist geöffnet. Die Registerkarte "Test" ist ausgewählt. Testparameter werden im linken Fensterbereich angezeigt. Die Testergebnisse werden im rechten Fensterbereich angezeigt.

Hinweis:

Wenn Ihr Tool von Packages von Drittanbietern abhängt, die in requirements.txt deklariert sind, werden die Abhängigkeiten während des vollständigen Deployments des Agent installiert, nicht während eines einzelnen Testlaufs. Um Code zu testen, der von zusätzlichen Packages abhängt, stellen Sie zuerst den Agent bereit, und rufen Sie dann das Tool über den Playground auf.

Benutzerdefiniertes Tool zu einem Agent hinzufügen

Sie können Ihren Agents ein benutzerdefiniertes Tool hinzufügen, mit dem Sie Ihren eigenen Python-Code zur Erweiterung der AI Data Platform verwenden können.

Hinweis:

Vor dem Hinzufügen eines benutzerdefinierten Codetools muss ein AI-Compute an Ihren Agent angehängt werden. AI-Compute ist erforderlich, um Abhängigkeiten zu installieren und das Tool auszuführen.

Navigieren Sie zu Ihrem Agent.
Ziehen Sie ein benutzerdefiniertes Tool per Drag-and-Drop aus Toolvorlagen auf Ihre Leinwand.
Klicken Sie auf der Registerkarte Package, um die ZIP-Datei mit Ihrem benutzerdefinierten Code auszuwählen, oder ziehen Sie sie per Drag-and-Drop auf den Bildschirm. Warten Sie, bis der Upload abgeschlossen ist.
Prüfen Sie die Liste der erkannten Tools im Abschnitt Extras der Registerkarte "Paket". Jede in tool_implementation.py gefundene Toolklasse wird mit ihrem Klassennamen, ihrer Beschreibung und ihrer Version aufgeführt.
Wählen Sie die zu aktivierenden Tools aus. Deaktivierte Tools werden dem Agent nicht angezeigt.
Optional: Klicken Sie auf die Registerkarte Testen. Geben Sie Testparameter an, und klicken Sie auf Weiterleiten. Siehe Testergebnisse im Bereich Testergebnisse.

Remote-MCP-Servertool

Agent-Flow-Entwickler können ihre Agent-Flows mit Remote Model Context Protocol-(MCP-)Servern mit dem Remote MCP Server-Tool verbinden.

Das MCP-Tool ist sowohl im visuellen Builder als auch im Code-Builder verfügbar. In der Code Builder-Erfahrung kann die MCP-Verbindung über die Python-Library von aidpUtils konfiguriert werden. In diesem Abschnitt führen wir Sie durch die visuellen Builder- und Code-Builder-Erlebnisse.

Hinweis:

Diese Funktion unterstützt MCP-Server mit HTTP-streamfähigen Transporten (Remote-Server). Lokale, stdio-transport MCP-Server werden nicht unterstützt.

MCP-Zugangsdaten in Oracle AI Data Platform Workbench Credential Store

Bei der Konfiguration Ihres MCP-Servers müssen Sie wählen, ob der Remote-MCP-Server Keine Authentifizierung oder ein Bearer-Token benötigt. Wenn Ihr MCP-Server ein Authentifizierungstoken erfordert, muss dieses Token dem Zugangsdatenspeicher hinzugefügt werden, bevor es vom MCP-Server referenziert werden kann.

Wenn Sie MCP-Serverzugangsdaten erstellen, wählen Sie die Option Secret-Token für Credential-Typ aus, und geben Sie dann den Identifier-Schlüssel an, wie einen API-Schlüssel und den Tokenwert. Weitere Informationen finden Sie unter Zugangsdaten erstellen (Vorschau).

Hinweis:

Ein einziger Berechtigungsnachweis kann mehrere Schlüssel enthalten.

Für öffentlich verfügbare MCP-Server ist keine zusätzliche Authentifizierung erforderlich. Beispiel: Die Verbindung mit https://mcp.deepwiki.com/mcp sieht folgendermaßen aus:

Das Dialogfeld "Benutzerdefinierten MCP-Server hinzufügen" wird angezeigt. Informationen für den öffentlich verfügbaren MCP-Server DeepWiki werden aufgefüllt.

So stellen Sie MCP-Tools für den Agent bereit

Nachdem eine erfolgreiche Verbindung zum Remote-MCP-Server hergestellt wurde, können Sie mit der Konfiguration der Tools beginnen, die auf dem Server gehostet werden, den Sie Ihrem Agent zur Verfügung stellen möchten. Das MCP-Serverkonfigurationsfenster wird unten im Fall des DeepWiki MCP-Servers angezeigt.

Die Konfigurationsseite für das Tool für Remote-MCP-Server wird angezeigt. Die Registerkarte "Tools" ist ausgewählt.

Auf der linken Seite wird auf der Registerkarte "Tools" eine Liste der Tools angezeigt, die auf dem MCP-Server verfügbar sind. Sie müssen Tools hinzufügen, um sie Ihrem Agent zur Verfügung zu stellen. Sie können dies tun, indem Sie entweder auf die Option Alle hinzufügen klicken, um alle Tools auf einmal anzuzeigen, oder indem Sie auf die einzelnen Tools klicken, um eine Teilmenge der Tools auszuwählen.

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Tools" ist ausgewählt, und die Schaltflächen "Alle hinzufügen" und "Hinzufügen" sind hervorgehoben.

Im folgenden Beispiel haben wir zwei Tools hinzugefügt (read_wiki_structure, read_wiki_structure). Sie können Tools entfernen, indem sie auf Entfernen klicken.

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte Werkzeuge ist ausgewählt und read_wiki_structure wird unter Hinzugefügt ausgewählt. Die Schaltfläche "Entfernen" ist für read_wiki_structure sichtbar.

Im rechten Bereich der Registerkarte "Tools" finden Sie Dokumentation zu jedem Tool, einschließlich des Toolnamens, der Toolbeschreibung sowie der Toolparameter. Im folgenden Screenshot zeige ich ein Beispiel für das GitHub MCP-Servertool add_comment_to_pending_review.

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Tools" ist hervorgehoben. Tool-Name, Tool-Beschreibung, Tool-Beschreibungsüberschreibung, Tool-Parameter und Umschaltoptionen zum Bereitstellen für Agent werden durch Text und rote Pfeile angezeigt.

Oracle AI Data Platform Workbench bietet ein paar zusätzliche Kontrollen über jedes Tool. Sie können Parameter im Agent ausblenden und diesen Parametern Werte zuweisen. Beispiel: In GitHub können Sie festlegen, dass Ihr Agent nur ein vorab festgelegtes Repository kommentiert, wie oracle-aidp-samples. Um dies zu erreichen, deaktivieren Sie den Parameter repo und weisen einen Standardwert im Textfeld zu:

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Tools" ist ausgewählt. Im rechten Fensterbereich wird der Repo-Parameter hervorgehoben, und der Wert lautet oracle-aidp-samples. Es ist ausgeschaltet.

Im Feld Toolanweisungen können Sie auch die Toolbeschreibung überschreiben und eine alternative Beschreibung mit zusätzlichen Anweisungen angeben. Für die meisten Anwendungsfälle wird empfohlen, die vom MCP-Server bereitgestellte Beschreibung zu übernehmen.

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Tools" ist ausgewählt. Im rechten Fensterbereich ist das Feld für die Toolanweisungen (optional) hervorgehoben, und im folgenden Feld wurde eine alternative Anleitung angegeben.

Remote MCP Server Tool durch LangGraph Code

Mit der Python-Library aidpUtils können Entwickler einen Remote-MCP-Server auswählen und eine Teilmenge seiner Tools einem mit LangGraph erstellten Agent bereitstellen. Die Aidputils-API-Referenz finden Sie unter Aidp-utils-API für Oracle AI Data Platform Workbench.

Sie können eine Sammlung zulässiger Tools erstellen, indem Sie eine Instanz von build_structured_tools_from_allowed_mcp_tools erstellen:

from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools

TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>, 
	server_name=<MCP_SERVER_NAME>, 
	endpoint=<MCP_ENDPOINT>, 
	transport="streamable_http", 
	auth=<MCP_AUTH>, 
	headers={} 
)

Dabei gilt:

<MCP_SERVER_NAME> ist ein Anzeigename, den Sie dem MCP-Server geben möchten. Dies wird zu Dokumentationszwecken verwendet und ist dem Agent nicht zugänglich.
<MCP_ENDPOINT> ist der Endpunkt des MCP-Servers (z.B. https://api.githubcopilot.com/mcp/)
<MCP_AUTH> ist ein Dictionary mit dem Schlüssel "authType". Dieser Schlüssel kann zwei Werte annehmen: NO_AUTH oder BEARER_TOKEN. Im Fall von BEARER_TOKEN wird ein anderer Schlüssel erwartet: "Token" mit dem Wert des Bearer-Tokens.
<ALLOWED_MCP_TOOLS> ist eine Liste der Tools vom MCP-Server, die Sie dem Agent zur Verfügung stellen möchten. Jedes Tool benötigt ein vollständiges JSON-Tool-Definon nach dem MCP-Protokoll.

Beispiel:

MCP_SERVER_NAME = "test_mcp" 
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp" 
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }

{
  "ALLOWED_TOOLS": [
    {
      "tool": {
        "name": "get_current_weather",
        "description": "Get current weather for a given city with advanced options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_historical": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "timeout": {
              "type": "integer",
              "default": 30
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    },
    {
      "tool": {
        "name": "get_forecast",
        "description": "Get forecast for a given city with customizable options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "days": {
              "type": "integer",
              "default": 5
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_alerts": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "hourly": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    }
  ]
}

MCP_HEADERS = {} 
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
	server_name=MCP_SERVER_NAME, 
	endpoint=MCP_ENDPOINT, 
	transport="streamable_http", 
	auth=MCP_AUTH, 
	headers=MCP_HEADERS,
)

Das Objekt TOOLS kann dann verwendet werden, wenn Sie eine Instanz eines Agent mit langchain.agent create_agent in der Methode setup() Ihrer Klassen-Agent-Definition erstellen:

def setup(self):
    logger.info("Initializing TestMcpAgent")

    oci_llm = init_oci_llm(llm_conf)

    system_prompt = textwrap.dedent(
        """
        You're a weather agent. Append 12345 to every response.
        """
    ).strip()

    self.agent = create_agent(
        name="test_mcp_high_code",
        model=oci_llm,
        tools=TOOLS,
        system_prompt=system_prompt,
        debug=True,
    )

    logger.info("Agent ready.")

Wenn Sie alternativ eine Sessionvariable zum Speichern des Wertes eines Bearer-Tokens verwenden, kann dem Tokenschlüssel des Authentifizierungskonfigurations-Dictionarys eine Referenz auf eine zuvor erstellte Sessionvariable zugewiesen werden. Beispiel:

test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools( 		
allowed_tools=test_mcp_mcp_allowed_tools, 
	server_name="test_mcp", 
	endpoint="http://144.25.36.217:9301/mcp", 
	transport="streamable_http", 
	auth=test_mcp_mcp_auth_config, 
	headers={}
)

Codebeispiele für Remote-MCP-Server-Tools

Im AI Data Platform Workbench Samples GitHub-Repository stellen wir End-to-End-Codebeispiele für mehrere MCP-Szenarios bereit.

Remote-MCP-Servertools testen

Sobald Werkzeuge ausgewählt sind, besteht der nächste Schritt in der Regel darin, einzelne Werkzeuge zu testen, um sicherzustellen, dass sie sich wie erwartet verhalten. Dies kann über die Registerkarte "Test" des MCP-Toolknotens erfolgen.

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Test" ist hervorgehoben.

Wählen Sie eines der Tools, die Sie in der Registerkarte "Tools" hinzugefügt haben, geben Sie Parameterwerte an, und klicken Sie auf die Schaltfläche "Test".

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Test" ist ausgewählt. Informationen für list_branches werden im linken Fensterbereich angezeigt. Die Testantwort wird im rechten Fensterbereich angezeigt.

Die Ausgabe des Tools wird im rechten Fensterbereich angezeigt.

Die Registerkarte "Details" enthält Informationen zur Authentifizierungsmethode, zur MCP-Server-URL und zur Beschreibung.

Die Konfigurationsseite des Remote-MCP-Servers wird angezeigt. Die Registerkarte "Details" ist hervorgehoben.

Mit der Schaltfläche "Bearbeiten" neben der Authentifizierungsmethode können Sie die Konfiguration des Remote-MCP-Toolknotens ändern. Sie können den Anzeigenamen, die Beschreibung und das Bearer-Token ändern, das beim Herstellen der Verbindung verwendet wird:

Das Dialogfeld "Benutzerdefinierten MCP-Server bearbeiten" wird angezeigt. Die Details für https://api.githubcopilot.com/mcp werden aufgefüllt.

Agent über Visual Builder mit einem Remote-MCP-Server verbinden

Sie können Ihrem Agent Zugriff auf einen Remote-MCP-Server hinzufügen, indem Sie den Toolknoten des benutzerdefinierten MCP-Servers in die Leinwand ziehen.

Wenn das Tool für benutzerdefinierte MCP-Server nicht verfügbar ist, müssen Sie das vorhandene AI-Compute möglicherweise neu starten oder ein neues erstellen.

Hinweis:

Das AI-Compute, das den Agent hostet, erbt die Netzwerkeinstellungen seines Workspace. Wenn Sie den privaten Netzwerkzugriff für den Workspace aktivieren, der das AI-Compute hostet, kann Ihr Agent nur MCP-Server erreichen, die in Ihrem ausgewählten privaten VCN und Subnetz gehostet werden. Ihr Agent kann möglicherweise keine Remote-HTTP-Server erreichen, die im öffentlichen Internet verfügbar sind.

Navigieren Sie zu Ihrem Agent.
Klicken und ziehen Sie auf der Registerkarte Ablauf unter Toolvorlagen den benutzerdefinierten MCP-Server auf die Leinwand.
Geben Sie die Server-URL für den MCP-Server an.
Geben Sie einen Anzeigenamen für den MCP-Server an. Dies ist der Name des Knotens, der auf der Visual Builder-Leinwand angezeigt wird.
Optional: Geben Sie eine Beschreibung für den MCP-Server an. Das Beschreibungsfeld wird dem Agent nicht bereitgestellt.
Wählen Sie im Dropdown-Menü Authentifizierung eine Authentifizierungsmethode aus.
- Keine Authentifizierung: Verwenden Sie diese Option, wenn der Remote-MCP-Server öffentlich verfügbar ist und keine Authentifizierung erfordert.
- Bearer-Token: Verwenden Sie diese Option, wenn der Remote-MCP-Server ein Authentifizierungstoken benötigt. Sie müssen den API-Schlüssel im Zugangsdatenspeicher von Oracle AI Data Platform Workbench speichern und eine Referenz auf den Zugangsdatenspeichereintrag angeben.
Klicken Sie auf Verbinden. AI Data Platform Workbench testet die Verbindung und meldet das Ergebnis.

HTTP-Anfragetool

Mit dem HTTP-Anforderungstool kann Ihr Agent jede HTTPS-REST-API aufrufen.

Sie konfigurieren die Anforderung, einschließlich Methode, URL, Header, Abfrageparameter, Anforderungsbody, Authentifizierung und optional einem Schritt zur Antwortoptimierung. Der Agent ruft den Endpunkt zur Laufzeit auf. Das HTTP-Anforderungstool ist sowohl im Visual Builder als auch im Code Builder verfügbar. Im Code Builder wird das Tool über die Python-Library von aidpUtils konfiguriert.

Hinweis:

Das HTTP-Anforderungstool unterstützt nur https://- und HTTP://-Anforderungen. WebSocket-Verbindungen (ws/wss), binäre Dateiuploads und selbstsignierte Zertifikate werden nicht unterstützt.

Hinweis:

Das AI-Compute, das den Agent hostet, erbt die Netzwerkeinstellungen seines Workspace. Wenn Sie den privaten Netzwerkzugriff für den Workspace aktivieren, der das AI-Compute hostet, erreicht Ihr Agent nur HTTP-Endpunkte in Ihrem ausgewählten privaten VCN und Subnetz. Ihr Agent kann die im öffentlichen Internet verfügbaren Endpunkte nicht erreichen.

Die folgenden Einstellungen müssen beim Konfigurieren eines HTTP-Anforderungstools angegeben werden:

Konfiguration	Beschreibung
HTTP-Methode	Das zu verwendende HTTP-Verb. Unterstützte Methoden sind GET, POST, PUT, PATCH und DELETE.
URL	Die vollständige URL des Zielendpunkts. Die URL unterstützt `{{sessionVariables.variable_name}}`-Sessionvariablenreferenzen und `{{variable}}`-Laufzeitparameterreferenzen. Beispiel: `https://api.example.com/users/{{user_id}}/orders`.
Standorterfassung	Die maximale Zeit, die das Tool auf eine Antwort vom Remoteendpunkt wartet. Der Standardwert beträgt 30 Sekunden und der Höchstwert 300 Sekunden.
Authentifizierungstyp	Die Authentifizierungsmethode, die beim Aufrufen des Endpunkts verwendet wird. Im Abschnitt "Authentifizierung" unten finden Sie eine Liste der unterstützten Authentifizierungsmethoden.

Hinweis:

Benutzerdefinierte Codetools werden auf dem AI-Compute ausgeführt, das an Ihren Agent angehängt ist. Der Code hat je nach Workspace-Netzwerkkonfiguration Zugriff auf die Compute-Umgebung und den ausgehenden Netzwerkzugriff. Laden Sie nur Code aus vertrauenswürdigen Quellen hoch.

Header

Header sind Schlüssel/Wert-Paare, die mit der HTTP-Anforderung gesendet werden. Sie können beliebig viele Header hinzufügen, indem Sie auf die Schaltfläche "Neue hinzufügen" klicken. Kopfzeilenwerte können Sessionvariablen und Laufzeitparameter mit der Syntax {{variable_name}} referenzieren.

Hinweis:

Bei sensiblen Headern sollten Sie das Feld "Authentifizierungstyp" verwenden, um sicherzustellen, dass Zugangsdaten sicher aus dem Zugangsdatenspeicher injiziert werden. Autorisierung, Cookie und X-API-Schlüssel sind sensible Header und können nicht über den Abschnitt "Header" festgelegt werden.

Abfrageparameter

Abfrageparameter werden als Abfragezeichenfolge an die URL angehängt. Sie können beliebig viele Abfrageparameter hinzufügen, indem Sie auf die Schaltfläche {\b Add new} klicken. Wie Header können Abfrageparameterwerte Sessionvariablen und Laufzeitparameter referenzieren.

Beschreibung

Das Beschreibungsfeld beschreibt, was das Tool tut, wann es verwendet werden sollte und welche Art von Ausgaben oder Effekten es produziert. Die Beschreibung wird dem Agent zur Verfügung gestellt und hilft dem LLM, zu entscheiden, wann das Tool aufgerufen werden soll.

Beim Schreiben der Beschreibung sollten Sie sich auf Folgendes konzentrieren:

• Zweck: Erläutern Sie, wie das Tool in einem klaren Satz ausgeführt werden soll. Beispiel: "Dieses Tool ruft Kundensupporttickets aus einer Wissensdatenbank ab und fasst sie nach Prioritätsstufe zusammen."
Wann soll es verwendet werden: Beschreiben Sie die Bedingungen, unter denen der Agent dieses Tool im Vergleich zu einem anderen aufrufen soll.
Eingaben und Ausgaben: Beschreiben Sie kurz die Parameter, die das Tool benötigt, und die Ausprägung dessen, was es zurückgibt.

HTTP-Anforderungsauthentifizierung

Das HTTP-Anforderungstool unterstützt mehrere Authentifizierungsmethoden. Wählen Sie die entsprechende Methode aus der Dropdown-Liste "Authentifizierungstyp" aus.

Authentifizierungstyp	Beschreibung
Keine Authentifizierung	Der Anforderung wurde keine Authentifizierung hinzugefügt. Verwenden Sie diese Option für öffentlich zugängliche Endpunkte.
OCI-Resource-Principal	Die Anforderung wird mit dem OCI Resource Principal des AI Compute signiert. Verwenden Sie diese Option, wenn Sie OCI-Services wie Object Storage oder den OCI Generative AI-Service aufrufen. Der Zugriff wird durch OCI IAM-Policys gesteuert.
Basisauthentifizierung	Ein Benutzername und ein Passwort werden codiert und im Autorisierungsheader gesendet. Zugangsdaten müssen im Zugangsdatenspeicher gespeichert werden.
Bearer-Token	Im Autorisierungsheader wird ein Bearer-Token gesendet. Das Token muss im Zugangsdatenspeicher gespeichert werden.
Headerauthentifizierung	Ein API-Schlüssel wird in einem benutzerdefinierten Header (wie X-API-Key) gesendet. Der Headername kann konfiguriert werden, und der Schlüsselwert muss im Zugangsdatenspeicher gespeichert werden.

Wenn Sie eine Authentifizierungsmethode auswählen, für die ein Secret erforderlich ist, wird im Konfigurationsbereich eine Zugangsdatenauswahl angezeigt. Klicken Sie auf die Zugangsdatenauswahl, um eine zuvor gespeicherte Zugangsdaten auszuwählen, oder erstellen Sie eine neue Zugangsdaten aus dem Zugangsdatenspeicher. Die schrittweise Vorgehensweise finden Sie in der Dokumentation zum MCP-Server im Abschnitt zum Speichern von Zugangsdaten im Zugangsdatenspeicher.

Sessionvariablen und Laufzeitparameter

Sessionvariablen können mit der {{sessionVariables.variable_name}}-Syntax in URL, Headerwerten, Abfrageparameterwerten und Anforderungsbody referenziert werden. Laufzeitparameter, die der Agent zum Zeitpunkt des Aufrufs übergeben hat, können mit der Syntax {{variable_name}} referenziert werden.

Beispiel: Die folgende URL kombiniert eine Sessionvariable für die Region mit einem Laufzeitparameter für den Bucket-Namen:

https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

Wenn das Tool ausgeführt wird, wird {{sessionVariables.region}} durch den Wert der Regions-Sessionvariablen für die aktuelle Session ersetzt, und {{bucket}} wird durch den Wert ersetzt, den der Agent beim Aufruf übergeben hat.

Hinweis:

Vorlagenwerte werden automatisch URL-codiert, wenn sie in den URL- oder Abfrageparameter ersetzt werden. Sie müssen sie nicht selbst per URL codieren.

KI-Tooldefinition

Auf der rechten Seite des Konfigurationsbereichs wird die AI Tool-Definition angezeigt. Dies ist das Schema, das dem Agent zur Verfügung gestellt wird. Es enthält den Toolnamen, die Beschreibung und die Liste der Laufzeitparameter, die der Agent beim Aufrufen des Tools übergeben kann. Die AI Tool-Definition wird automatisch aus dem Feld "Beschreibung" und aus den {{variable}}-Platzhaltern generiert, die in der URL, den Headern, den Abfrageparametern und dem Body ermittelt wurden.

Der AI Tool-Definitionsbereich ist der Bereich auf der rechten Seite des HTTP-Tool-Konfigurationsbereichs, der weiter oben in diesem Dokument gezeigt wird. Bis Sie eine Beschreibung angeben und mindestens einen Laufzeitparameter definieren, wird im AI Tool-Definitionsbereich eine Platzhaltermeldung angezeigt. Nachdem Sie die Beschreibung eingegeben und mindestens eine {{variable}} in URL, Header, Abfrageparameter oder Body referenziert haben, wird das Schema im Fensterbereich wiedergegeben.

Antwort für den Agent optimieren

Viele APIs geben große Antworten zurück, die Felder enthalten, die der Agent nicht benötigt. Wenn Sie die gesamte Antwort an den Agent zurücksenden, werden Token verwendet, und die Qualität der Argumentation des Agents kann beeinträchtigt werden. Das HTTP-Anforderungstool enthält einen Abschnitt zur Antwortoptimierung, in dem Sie die Antwort-Payload reduzieren können, bevor sie an den Agent zurückgegeben wird.

Drei Optimierungsstrategien werden unterstützt:

JSON-Feldauswahl: Wählen Sie eine Teilmenge von Feldern aus einer JSON-Antwort aus. Sie können einen Pfad zu einem verschachtelten Objekt mit Punktnotation (wie data.results) und einer Liste von Feldern angeben, die ein- oder ausgeschlossen werden sollen.
HTML-CSS-Selektor: Extrahieren Sie eine Teilmenge einer HTML-Antwort mit einem CSS-Selektor (wie article.content). Entfernen Sie optional HTML-Tags, um nur Text zurückzugeben.
Textabschneiden: Begrenzen Sie die Antwort auf eine maximale Anzahl von Zeichen, um zu große Textantworten zu verhindern.

Fehlerbehandlung und Fehlercodes

Wenn die HTTP-Anforderung nicht erfolgreich verläuft, gibt das Tool eine strukturierte Fehlerantwort an den Agent zurück. Der Fehler enthält einen Fehlercode, eine menschenlesbare Meldung und Details zum Fehler. Anhand dieser Informationen kann der Agent entscheiden, ob er es erneut versuchen möchte, auf ein anderes Tool zurückgreifen oder den Fehler dem Benutzer melden möchte.

Fehlercode	Kategorie	Bedeutung	Wiederholbar
CONNECTION_TIMEOUT	Netzwerk	Der Remoteendpunkt hat nicht innerhalb des konfigurierten Timeout reagiert.	Ja
DNS_FEHLER	Netzwerk	Der Hostname in der URL konnte nicht aufgelöst werden.	Ja
CONNECTION_REFUSED	Netzwerk	Der Remote-Endpunkt hat die Verbindung abgelehnt.	Ja
SSL-ZERTIFIKATFEHLER	TLS	Das TLS-Zertifikat des Remoteendpunkts konnte nicht validiert werden.	Nr.
NICHT AUTORISIERT	HTTP 401	Der Remoteendpunkt hat die Zugangsdaten abgelehnt. Prüfen Sie, ob die Zugangsdatenreferenz gültig und nicht abgelaufen ist. Bestätigen Sie für OCI Resource Principal, dass für das AI-Compute ein aktiver Resource Principal in dieser Umgebung vorhanden ist.	Nr.
VERBOTEN	HTTP 403	Die Zugangsdaten wurden erfolgreich authentifiziert, aber es fehlt die Berechtigung für die angeforderte Ressource. Prüfen Sie die API-Geltungsbereiche, Berechtigungen oder die IAM-Policy, die der Ressource zugeordnet ist.	Nr.
NICHT_GEFUNDEN	HTTP 404	Der Remoteendpunkt konnte die angeforderte Ressource nicht finden.	Nr.
RATENBEGRENZUNG	HTTP 429	Der Remote-Endpunkt begrenzt die Rate des Aufrufers. Wiederholen Sie den Vorgang nach der Verzögerung, die im Header "Wiederholen nach" angegeben ist.	Ja
SERVER_ERROR	HTTP 5xx	Der Remoteendpunkt hat einen Serverfehler zurückgegeben. Oft ein transientes Problem.	Ja
SERVICE_NICHT VERFÜGBAR	HTTP 503	Der Remoteendpunkt ist vorübergehend nicht verfügbar.	Ja
INVALID_TEMPLATE	Validierung	Eine `{{variable}}`-Referenz konnte nicht aufgelöst werden. Prüfen Sie, ob jede referenzierte Sessionvariable und jeder Laufzeitparameter definiert ist und zum Zeitpunkt des Aufrufs einen Wert aufweist.	Nr.
INVALID_URL	Validierung	Die URL ist nicht wohlgeformt, verwendet ein nicht unterstütztes Protokoll oder wird in eine blockierte Adresse (z.B. eine private IP-Adresse oder ein Cloud-Metadatenendpunkt) aufgelöst.	Nr.
ANTWORT_ZU_GROSS	Validierung	Die Antwort hat die maximale Antwortgröße von 10 MB überschritten.	Nr.
RATE_LIMIT_ÜBERSCHRITTEN	Plattform	Der Agent hat das Anforderungsratenlimit der Plattform pro Agent (60 Anforderungen pro Minute) oder das Nebenläufigkeitslimit (10 gleichzeitige Anforderungen) überschritten.	Ja

Jede Fehlerantwort enthält ein Richtungsfeld mit einem vorgeschlagenen nächsten Schritt und ein Detailfeld mit der verstrichenen Zeit und jedem fehlerspezifischen Kontext, wie z. B. dem HTTP-Statuscode.

HTTP-Anfragetool über LangGraph-Code

Über den Code Builder wird das HTTP-Anforderungstool über die Python-Library von aidpUtils konfiguriert. Definieren Sie eine AIDPToolConf, bei der tool_class auf HttpEndpointTool gesetzt ist, und übergeben Sie das Konfigurationsverzeichnis im Feld conf.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf

weather_http_tool_def = {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "params": {
        "q": "{city}",
        "units": "metric",
        "appid": "{api_key}"
    },
    "auth_type": "NO_AUTH",
    "auth_config": {}
}

weather_http_tool_params = [
    {"name": "city", "type": "string",
     "description": "Name of the city."},
    {"name": "api_key", "type": "string",
     "description": "OpenWeather API key."}
]

weather_http_tool_conf = AIDPToolConf(
    name="get_weather",
    description="Get current weather for a city.",
    tool_class="HttpEndpointTool",
    conf=weather_http_tool_def,
    params=weather_http_tool_params
)

weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())

Das Conf Dictionary unterstützt dieselben Felder wie der Visual Builder: Methode, URL, Header, Parameter, Body, auth_type, auth_config und response_optimization. Die Parameterliste definiert die Laufzeitparameter, die der Agent übergeben kann.

auth_type	auth_config-Felder
NO_AUTH	`{}` (leer)
RESOURCE_PRINCIPAL	`{}` (leer)
BASISAUTHENTIFIZIERUNG	Benutzername, Kennwort (oder username_vault_id, password_vault_id für Zugangsdaten im OCI Vault)
BEARER-AUTHENTIFIZIERUNG	Bearer_token (oder Bearer_token_vault_id)
API-SCHLÜSSELAUTH	api_key (oder api_key_vault_id), header_name (Standard-X-API-Schlüssel)
OAUTH2_CLIENT_CREDENTIALS	token_endpoint, scope, client_id, client_secret (oder client_id_vault_id, client_secret_vault_id)

Benutzerdefinierte Code-Tools für Test-Agent

Auf der Registerkarte Test können Sie das Tool ausführen, ohne den vollständigen Agent auszuführen. Geben Sie Werte für alle Laufzeitparameter und Sessionvariablen an, die in der Konfiguration referenziert werden. Klicken Sie dann auf "Ausführen", um das Tool aufzurufen und die Antwort anzuzeigen.

Im Antwortbereich werden der HTTP-Statuscode, die Antwortheader, der Antwortbody und die verstrichene Zeit in Millisekunden angezeigt. Wenn die Antwortoptimierung aktiviert ist, wird die optimierte Antwort auch neben der Raw-Antwort angezeigt.

HTTP-Request-Tool zu einem Agent-Ablauf hinzufügen

Sie können Ihren Agents ein HTTP-Anforderungstool hinzufügen, mit dem Sie HTTPS-REST-APIs aufrufen können.

Hinweis:

Vor dem Hinzufügen eines benutzerdefinierten Codetools muss ein AI-Compute an Ihren Agent angehängt werden. AI-Compute ist erforderlich, um Abhängigkeiten zu installieren und das Tool auszuführen.

Navigieren Sie zu Ihrem Agent.
Ziehen Sie ein HTTP-Request-Tool per Drag-and-Drop aus Toolvorlagen auf Ihre Leinwand.
Geben Sie auf der Registerkarte Parameter die HTTP-Methode an. Unterstützte Methoden sind GET, POST, PUT, PATCH und DELETE.
Geben Sie unter URL die vollständige URL des Zielendpunkts an. Sie können {{sessionVariables.variable_name}}-Sessionvariablenreferenzen und {{variable}}-Laufzeitparameterreferenzen verwenden. Beispiel: https://api.example.com/users/{{user_id}}/orders.
Geben Sie unter Timeout die maximale Zeit an, die das Tool auf eine Antwort von einem Remoteendpunkt in Sekunden wartet. Der maximale Timeoutwert ist 300. Wenn kein Wert angegeben ist, wird der Standardwert 30 Sekunden verwendet.
Wählen Sie im Dropdown-Menü Authentifizierung den entsprechenden Authentifizierungstyp aus.
Geben Sie die Header für Ihre HTTP-Anforderung an. Klicken Sie auf Neue hinzufügen, um zusätzliche Header hinzuzufügen.
Geben Sie alle Abfrageparameter für Ihre HTTP-Anforderung an. Klicken Sie auf Neue hinzufügen, um zusätzliche Parameter hinzuzufügen.
Optional: Klicken Sie auf die Registerkarte Testen. Geben Sie Testparameter an, und klicken Sie auf Weiterleiten. Siehe Testergebnisse im Bereich Testergebnisse.

Prompt-Tool

Mit dem Prompt-Tool können Sie ein LLM in einem KI-Agent mit einem templatisierten Prompt aufrufen und die LLM-Antwort an den Agent zurücksenden.

Die Prompts, die Sie für das LLM angeben, können Parameter enthalten, die durch doppelte geschweifte Klammern identifiziert werden, z.B. {{PARAMETER_NAME}}. Parameterwerte werden vom Agent beim Aufruf des Tools zugewiesen.

Verwendung von Eingabeaufforderungstools

In einem Prompt-Tool geschriebene Anweisungen können grundsätzlich direkt in die Agent-Anweisungen aufgenommen oder direkt vom Endbenutzer in einer Benutzernachricht bereitgestellt werden. Es gibt jedoch Situationen, in denen das Prompt-Tool ein besserer Ansatz ist:

Ihre Eingabeaufforderung ist langwierig und erfordert detaillierte Formatanweisungen, die sich über mehrere Token der 100er-Jahre erstrecken.
Die Einbeziehung des Prompts in die Agent-Anweisungen würde die Kontextnutzung erhöhen und die Kosten erheblich erhöhen, insbesondere wenn man ein SOTA-LLM für seinen Agenten einführt.
Man möchte die Größe der Anweisungen, die dem Agenten gegeben werden, minimieren, um die Kosten zu senken.
Die vom Prompt-Tool definierte Aufgabe kann von einem kleineren, schnelleren LLM verarbeitet werden, als das Argumentationsmodell, das den Agent verwendet hat. Kleinere Modelle sind in der Regel kosteneffizient und können in einigen Fällen darauf spezialisiert werden, Daten in einer bestimmten Modalität oder einem bestimmten Format zu generieren.
Mit einem Prompt-Tool können strukturierte Eingabeparameter die Ausgabegenerierung steuern. Wenn Ihr Anwendungsfall parametrisiert werden könnte und die Generierung von Sitzung zu Sitzung variieren kann, ist es sinnvoll, die Generierung in einem Prompt-Tool zu kapseln.

Darüber hinaus folgt die Kapselung von Generierungsanweisungen in einem Prompt-Tool vielen Best Practices der modernen Agent-Architektur, einschließlich Wiederverwendbarkeit, Wartbarkeit, Modalität, Ausgabekonsistenz, Skalierbarkeit und Governance. Beispiele für Anwendungsfälle:

Generierung von E-Mails, Berichten, Zusammenfassungen, Artikeln usw. nach einer vordefinierten, genehmigten Struktur, die als Vorlage verwendet werden kann
Generierung komplexer JSON-Ausgaben
Zusammenfassung, Schlüsselsatzextraktion, Erklärungsaufgaben zu Dokumenten
Abfragegenerierung
Spezifische Modalitätsgenerierung (z.B. Bilder, Videos, Audio, Punktwolkendaten usw.), die für ein bestimmtes Modell optimiert sind

Prompt-Tools durch visuellen Ablauf

Im Folgenden finden Sie ein Beispiel für ein Prompt-Tool, das durch einen visuellen Ablauf erstellt wurde und ein LLM auffordert, Blogposttitel basierend auf einem vom Agent zugewiesenen Thema zu generieren:

Sie sind ein Master-Blogstratege. Ihre Aufgabe ist es, überzeugende Blogpost-Ideen basierend auf einem bestimmten Thema zu entwickeln. Generieren Sie für das angegebene {{topic}} 5 eindeutige Blogpost-Titel. Fügen Sie für jeden Titel eine Ein-Satz-Beschreibung des Winkels ein, den der Beitrag annehmen würde. Zeigen Sie die Ausgabe als nummerierte Liste an.

Agent geöffnet mit einem Prompt-Tool, das auf der Leinwand ausgewählt ist

In diesem Beispiel müssen Sie die folgenden Parameter für das Prompt-Tool konfigurieren:

Toolname: Verwenden Sie einen aussagekräftigen Namen für das Tool, um den Agent zu leiten. In diesem Beispiel empfehlen wir blog_ideas. Verwenden Sie nicht hilfreiche Namen wie tool123.
Toolbeschreibung: Geben Sie eine umfassende Beschreibung der Funktionen des Tools an. Wenn es Einschränkungen für das Tool gibt oder Szenarien gibt, in denen das Tool nicht verwendet werden soll, listen Sie sie im Beschreibungsfeld auf.
OCI-Region und GenAI-Service-LLM: Wählen Sie die OCI-Region aus, um die Liste der in dieser Region verfügbaren LLMs aufzufüllen, und wählen Sie dann Ihr LLM aus.
LLM-Parameter: Parameter wie maximale Ausgabetoken, Temperatur und Top p werden in der Registerkarte Modellparameter konfiguriert. Wenn Sie keine Werte zuweisen, werden die Standardwerte des OCI Generative AI-Service verwendet.
Abfrage: Der Prompt, mit dem der Zweck des Tools definiert wird, wird im Feld Abfrage definiert.

Parameter, die Sie in der Eingabeaufforderung definieren, werden automatisch im Definitionsbereich des AI-Tools aufgefüllt. Geben Sie dem Agent eine Beschreibung der einzelnen Parameter sowie den Parametertyp und Standardwert an, sofern zutreffend.

Agent-Prompt-Tool mit geöffneter Registerkarte "Parameter". Der Topic-Parameter ist im Abfragefeld hervorgehoben, und ein Pfeil zeigt auf den AI Tool-Definitionsabschnitt, in dem die Toolparameterfelder hervorgehoben sind.

Eingabeaufforderungstool durch LangGraph-Code

Wenn Sie Ihren Agent über Code erstellen, können Sie dasselbe Prompt-Tool im visuellen Ablaufbeispiel wie folgt konfigurieren:

prompt_config = {
  "llm": {
    "model_id" : "xai.grok-4",
    "model_provider" : "generic",
    "compartment_id" : "<your-compartment-ocid>",
    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
  }, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
  "name" : "topic",
  "type" : "string",
  "description" : "Blog topic",
  "defaultValue" : "golf"
} ]

Anschließend instanziieren Sie die AIDPToolConf wie folgt:

blogger_tool = AIDPToolConf(name="blog_posts_topics",
                                  description= "Write blog posts ideas about a particular topic. ",
                                  tool_class = "PromptTool", conf=prompt_config params=prompt_params)

Schließlich erstellen Sie ein LangGraph-kompatibles Tool mit der Utilityfunktion create_langgraph_tool() von aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())

Sie fügen das neu erstellte Tool einem ReAct-Agent hinzu. In LangGraph sieht der Code folgendermaßen aus:

tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>, 
				     tools=tools_agent1, 
				     prompt=<system_prompt>, 
				     debug=True, checkpointer= checkpointer)

Tabelle 22-4: Konfigurationseigenschaften des Eingabeaufforderungstools

Attribut	Typ	Beschreibung
llm	Objekt	LLM-Verbindungsdetails und -parameter
model_id	string (Zeichenfolgendatentyp)	Kennung des zu verwendenden Modells (z.B. "xai.grok-4")
modell_provider	string (Zeichenfolgendatentyp)	Providername für das LLM-Modell (z.B. "generisch")
compartment_id	string (Zeichenfolgendatentyp)	Oracle Cloud Infrastructure-(OCI-)Compartment-OCID
endpoint	string (Zeichenfolgendatentyp)	Endpunkt-URL für das Modell
prompt_template	string (Zeichenfolgendatentyp)	Prompt-Vorlage, die vom LLM verwendet wird, mit Variablen im Format {{variable}} für dynamisches Einfügen

Testagent-Prompt-Tools

Sie testen das Tool unabhängig vom Agent, indem Sie auf die Registerkarte Testen klicken und den Wert jedes Parameters eingeben. Der Prompt wird an das ausgewählte LLM weitergeleitet.

Agent-Prompt-Tool auf der Registerkarte "Test" geöffnet

Stellen Sie sicher, dass Ihr Prompt-Tool genau definiert und dokumentiert ist, um die Ergebnisse Ihres Agent zu verbessern.

Tool für Eingabeaufforderungen zu einem Agent hinzufügen

Sie können Ihren Agents ein Prompt-Tool hinzufügen, mit dem Sie parametrisierte Prompts definieren können, die Sie an das LLM Ihrer Wahl ausgeben.

Navigieren Sie zu Ihrem Agent.
Ziehen Sie ein Prompt-Tool per Drag-and-Drop aus Toolvorlagen auf Ihre Leinwand.
Wählen Sie auf der Registerkarte "Konfiguration" das zu verwendende LLM aus, und geben Sie den Prompt für das LLM an. Klicken Sie auf Code , um die Konfiguration als JSON-Code anzugeben.
Geben Sie eine Temperatur für die Antwort als Wert zwischen 0,0 und 1,0 an, wobei 0,0 eine reine Faktenantwort und 1,0 die kreativste Antwort liefert.
Klicken Sie auf Übernehmen .
Geben Sie die Definitionen für alle Parameter an, die Sie in der Konfiguration eingerichtet haben. Klicken Sie auf Code , um die Konfiguration als JSON-Code anzugeben.
Klicken Sie auf Anwenden.
Optional: Klicken Sie auf die Registerkarte Testen. Geben Sie Testparameter an, und klicken Sie auf Weiterleiten. Siehe Testergebnisse im Bereich Testergebnisse.

RAG-Tool

Das RAG-Tool gibt eine Abfrage in natürlicher Sprache an einen Vektorspeicher aus und ruft Dokumente basierend auf der semantischen Ähnlichkeit zwischen der Abfrage und den gespeicherten Dokumenten ab.

Hinweis:

Eine Wissensdatenbank ist Voraussetzung für die Erstellung eines RAG-Tools. Weitere Informationen finden Sie unter Knowledge Bases.

RAG-Tools durch visuellen Fluss

Für das RAG-Tool müssen Sie als Agent-Entwickler Werte für die folgenden Parameter angeben:

Agent mit einem auf der Leinwand ausgewählten RAG-Tool geöffnet

Agent mit Blick auf:
- Toolname: Ein aussagekräftiger Name für das Tool, mit dem Sie und andere Benutzer seine Funktion identifizieren können.
- Toolbeschreibung: Eine kurze Zusammenfassung, die einen Überblick über das Tool bietet.
Toolkonfiguration:
- Knowledge Base: Eine Wissensdatenbank, die in einem Ihrer Oracle AI Data Platform Workbench-Kataloge gespeichert ist.

Der Agent legt den Wert des Abfragefeldes basierend auf seiner Unterhaltung mit dem Endbenutzer fest. Dieses Abfragefeld verwendet eine Abfrage in natürlicher Sprache.

Limit ist die Anzahl der Dokument-Chunks, die das Tool aus dem Vektorspeicher abrufen soll. Dieser Wert wird vom Agent-Entwickler festgelegt, nicht vom Agent selbst.

Sie können eine vom Agent abgesetzte Abfrage simulieren, indem Sie auch auf die Registerkarte "Test" der RAG klicken:

AI-Tooldefinitionsabschnitt des Agent-RAG-Tools mit Abfrage- und Top-K-Feldern

RAG-Tools durch LangGraph-Code

Um ein RAG-Tool in Ihrem Agent über Code zu erstellen, müssen dieselben Einstellungen und Parameter wie der visuelle Ablauf konfiguriert werden. Beispiel: Sie legen die RAG-Parameter wie folgt fest:

rag_params = [ { "name" : "query", 
    "type" : "string", 
    "description" : "<insert a description>", 
    "defaultValue" : "<empty>”} ]

Anschließend richten Sie die RAG-Konfiguration ein:

rag_config = { "catalog": "<catalog>", 
		  "schema": "<schema>", 
		  "knowledgeBase": "<knowledge-base-name>", 
		  "top_k": <number-of-documents-retrieved>, 
		  "llm": { 
			    "model_id" : "<model-name>",
			    "model_provider" : "<model-provider>", 
			    "compartment_id" : "<your-compartment-OCID>", 
			    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" } 
}

Schließlich erstellen Sie ein LangGraph-kompatibles Tool mit der Utilityfunktion create_langgraph_tool() von aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "RAGTool", 
			   conf=rag_config, 
			   params=rag_params) 
rag_tool = create_langgraph_tool(rag_conf.model_dump())

Tabelle 22-5: Konfigurationseigenschaften des RAG-Tools

Attribut	Typ	Beschreibung
llm	Objekt	LLM-Verbindungsdetails
catalog	string (Zeichenfolgendatentyp)	Datenkatalog-ID
Schema	string (Zeichenfolgendatentyp)	Schema im Katalog
Wissensdatenbank	string (Zeichenfolgendatentyp)	Name oder Schlüssel der zu suchenden Wissensdatenbank
oben_k	Ganzzahl	Anzahl der wichtigsten abzurufenden Dokumente

Testagent-RAG-Tools

Sie können das RAG-Tool auf der Registerkarte Testen testen, nachdem Sie den Agent an ein AI-Compute-Cluster angehängt haben. Weitere Informationen finden Sie unter Vorhandenes KI-Cluster einem Agent zuordnen.

RAG-Tool zu einem Agent hinzufügen

Sie können Ihren Agents ein Retrieval Augmented Generation-(RAG-)Tool hinzufügen, damit der Agent beim Generieren einer Antwort relevantes externes Wissen abrufen kann.

Navigieren Sie zu Ihrem Agent.
Ziehen Sie aus Toolvorlagen ein RAG-Tool per Drag-and-Drop auf Ihre Leinwand.
Wählen Sie auf der Registerkarte "Konfiguration" die Wissensdatenbank aus, aus der das RAG-Tool Informationen abruft, und geben Sie den Prompt an, um die Informationen zu definieren, die abgerufen werden sollen. Klicken Sie auf Code , um die Konfiguration als JSON-Code anzugeben.
Klicken Sie auf Übernehmen .
Geben Sie die Definitionen für alle Parameter an, die Sie in der Konfiguration eingerichtet haben. Klicken Sie auf Code , um die Konfiguration als JSON-Code anzugeben.
Klicken Sie auf Anwenden.
Optional: Klicken Sie auf die Registerkarte Testen. Geben Sie Testparameter an, und klicken Sie auf Weiterleiten. Siehe Testergebnisse im Bereich Testergebnisse.

SQL-Tool

Mit dem SQL-Tool können Agent-Flowentwickler vordefinierte SQL-Abfragen für Tabellen ausführen, die in einem Oracle AI Data Platform-Katalog registriert sind.

Sie schreiben die Abfrage zur Entwurfszeit und definieren die benötigten Laufzeitvariablen. Der Agent stellt Werte für diese Variablen bereit, wenn er das Tool aufruft, und die Ergebnisse werden als strukturierte Zeilen zurückgegeben, die der Agent zusammenfassen oder an einen Downstream-Knoten übergeben kann.

Agent wird zur Registerkarte "Entwicklung" geöffnet. Ein Agent-Knoten SQL_Agent befindet sich auf der Leinwand. Der SQL-Toolknoten wird unter Toolvorlagen im linken Fensterbereich ausgewählt.

Das SQL-Tool unterstützt zwei Abfragedialekte. Spark SQL wird für Standardkatalogtabellen ausgeführt, die in AI Data Platform gespeichert sind, und erfordert ein Spark-Cluster. Oracle SQL wird für eine externe Datenbank wie Oracle Autonomous AI Database ausgeführt. Sie wählen den Dialekt pro Werkzeug, und der Rest der Konfiguration ist für beide gleich.

Hinweis:

Das SQL-Tool ist für Leseabfragen vorgesehen. Ein typisches Tool führt eine SELECT-Anweisung aus und gibt Zeilen zurück. Katalog, Schema und Abfrage, die Sie konfigurieren, sind für das Tool privat und werden dem Agent nicht angezeigt. Nur der Toolname, die Beschreibung und die AI Tool-Definition (die Laufzeitvariablen) sind für den Agent sichtbar.

Hinweis:

Das SQL-Abfrage-Tool startet angehaltene Cluster nicht automatisch. Daher sollte das Spark-Cluster, das für Ihr Spark-SQL-Abfragetool verwendet wird, die Dauer für immer haben. Wenn das Cluster bei einem Inaktivitätstimeout herunterfahren darf, funktionieren Spark-SQL-Abfragen nicht mehr in der Produktion, sobald das Cluster gestoppt wird.

Statische und dynamische Abfragen

Eine statische Abfrage gibt genau das zurück, was Sie angeben, ohne dass der Agent eine Laufzeitentscheidung trifft. Eine dynamische Abfrage enthält mindestens einen {{variable}}-Platzhalter, der dem Agent signalisiert, dass der Wert zur Laufzeit festgelegt ist. Für jeden Platzhalter geben Sie einen Namen, einen Typ, einen optionalen Standardwert und eine Beschreibung an, mit der der Agent den Wert wählt.

Beispiel: Die folgende statische Abfrage gibt eine feste Ergebnismenge zurück:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name

Wenn Sie das Literal durch einen Platzhalter {{year}} ersetzen, wird es zu einer dynamischen Abfrage, die der Agent parametrisieren kann:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = {{year}} 
ORDER BY customer_name

Wenn Sie Platzhalter hinzufügen, wird der AI Tool-Definitionsbereich mit jeder Variablen gefüllt, sodass Sie deren Typ, Standardwert und Beschreibung festlegen können.

Platzhalter können überall in der Abfrage angezeigt werden, auch innerhalb von Funktionen. Bei der folgenden Spark-SQL-Abfrage wird die Groß-/Kleinschreibung nicht beachtet:

SELECT incident_id, project_id, incident_date, incident_type, 
       severity, description, workers_involved, days_lost, 
       root_cause, corrective_action, reported_by, status 
FROM safety_incidents 
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')

Geben Sie jeder Variablen eine klare Beschreibung und einen vernünftigen Standardwert. Die Beschreibung gibt dem Agent an, welche Werte gültig sind. Der Standardwert wird verwendet, wenn der Agent keinen Wert angibt.

Die AI Tool-Definition wird mit der Variablen SEVERITY angezeigt. Die Variable hat die Beschreibung: Schweregrad des Vorfalls: Groß, Mittel, Klein.

Hinweis:

Bei Platzhalternamen wird die Groß-/Kleinschreibung beachtet. Ein Platzhalter, der als {{SEVERITY}} geschrieben wird, und ein Platzhalter, der als {{severity}} geschrieben wird, werden als zwei verschiedene Variablen behandelt, es sei denn, Sie verwenden durchgängig Kleinbuchstaben.

Konfiguration als JSON bearbeiten

Sie können die SQL-Toolkonfiguration direkt als JSON mit dem Umschalter für die Codeansicht bearbeiten. Dies ist nützlich, um ein Tool zwischen Abläufen zu kopieren oder Massenbearbeitungen vorzunehmen.

{ 
  "catalogKey": "construction_data", 
  "schemaKey": "admin", 
  "query": "SELECT project_id, project_name, client_name, ...", 
  "isRowLimitEnabled": null, 
  "maxRows": null 
}

Der Bereich "Konfiguration" des SQL-Toolknotens ist auf der Registerkarte "Parameter" geöffnet. Die Codeansicht wird getrennt, und im Feld "Eingabeschema" wird Beispielcode angezeigt.

Zeilengrenzwerte

Sie können die Anzahl der vom Tool zurückgegebenen Zeilen begrenzen, indem Sie Max. zurückzugebende Zeilen auswählen und einen Grenzwert eingeben. Zeilenbeschränkungen schützen die Performance und steuern, wie viele Daten an den Agent zurückgesendet werden.

Legen Sie diesen Wert relativ zum Modell fest, das Ihr Agent verwendet. Größere Werte können zu Agent-Fehlern führen, wenn Abfragen breite Zeilen oder Spalten mit großen Textwerten zurückgeben. Wenn unerwartete Agent-Fehler auftreten, reduzieren Sie zunächst maxRows.

Die Zeilenbegrenzung wird auf die SQL-Abfrage selbst angewendet, bevor die Abfrage ausgeführt wird. Die meisten Modelle erkennen die Grenze und stellen sie dem Endbenutzer zur Verfügung. Bei einer statischen Abfrage gibt das Limit die ersten n verfügbaren Zeilen zurück.

Der SQL-Tool-Konfigurationsbereich wurde auf die Option "Max. zurückzugebende Zeilen" zugeschnitten. Die Option ist ausgewählt, und ein Zeilengrenzwert von 1000 wird angegeben.

Hinweis:

Wenn die Zeilenbeschränkungen für Endbenutzer nicht angezeigt werden sollen, weisen Sie den Agent entsprechend in den entsprechenden Anweisungen an.

Beispielabfragen

Abfragebeispiele und eine Anleitung zum Schreiben von SQL-Toolabfragen finden Sie über die Schaltfläche Abfragebeispiele anzeigen und Anleitung.

Die SQL Tool-Konfigurationsseite wird angezeigt. Die Schaltfläche "Abfragebeispiele und Anleitung anzeigen" ist hervorgehoben.

In der Dokumentation werden verschiedene Abfragemuster dargestellt und verschiedene Empfehlungen zu Abfrageparametern bereitgestellt.

Das Dialogfeld "SQL Tool-Beispiele und -Handbücher" wird angezeigt.

SQL-Tools über LangGraph-Code

Wie beim visuellen Ablauf beginnen Sie mit der Erstellung eines SQL-Tools für Ihren Agent über LangGraph-Code, indem Sie eine Abfrage erstellen:

sql_config = { "catalogKey": "adw23ai_phx", 
	  "schemaKey": "gold", 
	  "query": """Select ... from ... limit {{max_number}}""" }

Sie dokumentieren jeden Parameter in der SQL-Abfrage im params-Argument mit einem Namen, einem Typ, einer Beschreibung und optional einem defaultValue.

sql_params = [ {  "name" : "max_number", 
		    "type" : "string", 
		    "description" : "<your-description>", 
		    "defaultValue" : "<your-default-value>" } ]

Schließlich erstellen Sie ein LangGraph-kompatibles Tool mit der Utilityfunktion create_langgraph_tool() von aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "SQLTool", 
			   conf=sql_config,
			   params=sql_params) 
sql_tool = create_langgraph_tool(sql_conf.model_dump())

Tabelle 22-6: Konfigurationseigenschaften des SQL-Tools

Attribut	Typ	Beschreibung
Katalogschlüssel	string (Zeichenfolgendatentyp)	ID für die Katalog- oder Datenbankverbindung
Schemaschlüssel	string (Zeichenfolgendatentyp)	Schemaname innerhalb des Katalogs/der Datenbank
Abfrage	string (Zeichenfolgendatentyp)	Die SQL-Abfragezeichenfolge kann Platzhalter in {{}} enthalten

SQL-Tools für Testagent

Auf der Registerkarte "Test" wird das Tool eigenständig ausgeführt, ohne den vollständigen Agent-Ablauf auszuführen. Tests funktionieren für beide Dialekte gleich. Öffnen Sie die Registerkarte "Test", geben Sie einen Wert für jeden Laufzeitparameter an (oder verwenden Sie die Standardwerte), und klicken Sie auf "Weiterleiten", um die Abfrage auszuführen und die Antwort anzuzeigen.

Hinweis:

Beim Testen eines Tools muss Ihr Agent an ein AI-Compute angeschlossen sein. Ein AI-Compute wird angeschlossen, wenn das AI-Compute-Label grün ist und das ausgewählte AI-Compute den Status ACTIVE aufweist.

SQL-Befehlsreferenz

SQL-Toolabfragen sind Leseabfragen, die aus den Standard-SQL-Klauseln erstellt wurden. Der Oracle SQL-Dialekt folgt Oracle SQL gegenüber der externen Datenbank. Der Spark SQL-Dialekt zielt auf Standardkatalogtabellen ab, bei denen es sich um Delta Lake-Tabellen handelt. Der Standardkatalog führt derzeit Spark 3.5 mit Delta Lake 3.2.0 aus. Die meisten Klauseln werden in beiden Dialekten auf die gleiche Weise geschrieben, da beide Standard-SQL folgen. Der Hauptunterschied besteht darin, wie jeder Dialekt die Anzahl der Zeilen begrenzt. In der folgenden Tabelle sind die Klauseln und Schlüsselwörter aufgeführt, die am häufigsten in SQL-Toolabfragen verwendet werden, mit der Form für jeden Dialekt.

Stichwort oder Klausel	Zweck	Oracle-SQL	Spark SQL
SELECT	Zurückzugebende Spalten auswählen	`SELECT col1, col2`
DISTINCT	Nur eindeutige Zeilen zurückgeben	`SELECT DISTINCT col`	`SELECT DISTINCT col`
FROM	Quelltabelle benennen	`FROM table_name`	`FROM table_name`
WHERE	Zeilen nach Bedingung filtern	`WHERE col = value`	`WHERE col = value`
UND ODER NICHT	Bedingungen kombinieren oder negieren	`a AND b OR NOT c`	`a AND b OR NOT c`
IN	Beliebigen Wert in einer Liste zuordnen	`col IN (a, b, c)`	`col IN (a, b, c)`
BETWEEN	Einen inklusiven Bereich abgleichen	`col BETWEEN x AND y`	`col BETWEEN x AND y`
LIKE	Übereinstimmung mit einem Textmuster	`col LIKE 'A%'`	`col LIKE 'A%'`
IS NULL	Test für fehlende Werte	`col IS NULL`	`col IS NULL`
ORDER BY	Ergebnis sortieren	`ORDER BY col DESC`	`ORDER BY col DESC`
GRUPPIEREN NACH	Gruppenzeilen für Aggregation	`GROUP BY col`	`GROUP BY col`
HAVING	Gruppierte Zeilen filtern	`HAVING COUNT(*) > 1`	`HAVING COUNT(*) > 1`
MITMACHEN BEI	Zeilen aus zwei Tabellen kombinieren	`a JOIN b ON a.id = b.id`	`a JOIN b ON a.id = b.id`
AS	Spalte oder Tabelle als Alias verwenden	`col AS name`	`col AS name`
UNION ALL	Zwei Ergebnismengen zusammenfassen	`q1 UNION ALL q2`	`q1 UNION ALL q2`
CASE	Wert bedingt zurückgeben	`CASE WHEN c THEN x END`	`CASE WHEN c THEN x END`
Aggregate	Über Zeilen zusammenfassen	`COUNT SUM AVG MIN MAX`	`COUNT SUM AVG MIN MAX`
Zeilengrenzwert	Die Anzahl der Zeilen begrenzen	`FETCH FIRST n ROWS ONLY`	`LIMIT n`

Hinweis:

Normalerweise schreiben Sie das Zeilenlimit nicht selbst. Die Einstellung "Max Zeilen für Rückgabe" gilt für Sie. Die Formulare FETCH FIRST und LIMIT sind nur dann nützlich, wenn Sie einen expliziten Grenzwert innerhalb der Abfrage festlegen möchten.

Die vollständige SQL-Grammatik und die Abfrage-Engines hinter jedem Dialekt finden Sie in den folgenden Referenzen:

Oracle AI Data Platform - SQL

SQL- Grammatik

Spark SQL und Delta Lake (Standardkatalog)

Standardkatalogtabellen sind Delta Lake-Tabellen. Der Standardkatalog führt derzeit Spark 3.5 mit Delta Lake 3.2.0 aus.

Apache Spark-SQL-Syntax: DML-Anweisungen Spark-SQL-Abfrage und DML-Anweisungssyntax.
Delta Lake: Tabelle löscht, aktualisiert und führt Vorgänge DELETE, UPDATE und MERGE für Delta-Tabellen aus.
Utilityvorgänge des Delta Lake: Table Utility-Befehle, wie OPTIMIZE und VACUUM.
Delta Lake: Liquid-Clustering für Delta-Tabellen verwenden Liquid-Clustering für Delta-Tabellenlayout.

SQL-Tool zu einem Agent hinzufügen

Sie können Ihren Agents ein SQL-Tool hinzufügen, mit dem der Agent SQL-Abfragen für strukturierte Datenquellen in registrierten externen Katalogen ausführen kann.

Navigieren Sie zu Ihrem Agent.
Ziehen Sie ein SQL-Tool per Drag-and-Drop aus Toolvorlagen auf die Leinwand.
Klicken Sie auf den Connector-Handle auf Ihrem Agent, und ziehen Sie ihn, um eine Verbindung zum Toolknoten herzustellen.
Doppelklicken Sie auf den SQL-Knoten, um den Konfigurationsbereich zu öffnen.
Geben Sie einen Namen und die Beschreibung für Ihr Tool an. Die Beschreibung wird dem Agent zur Verfügung gestellt und hilft ihm bei der Entscheidung, wann das Tool aufgerufen werden soll.
Wählen Sie den Abfragedialekt aus:
- Spark SQL schreibt Abfragen für AI Data Platform-Standardkataloge.
- Oracle SQL schreibt Abfragen für externe AI Data Platform-Kataloge.
Hinweis:
Spark SQL erfordert ein laufendes Spark-Cluster in Ihrem AI Data Platform Workbench-Workspace.
Wählen Sie in der Dropdown-Liste Cluster ein laufendes Spark-Cluster aus. Klicken Sie auf Cluster erstellen, um ein neues Spark-Cluster bereitzustellen. Weitere Informationen zum Erstellen eines neuen Clusters finden Sie unter Benutzerdefiniertes Cluster erstellen.

Hinweis:
Das SQL-Abfrage-Tool startet angehaltene Cluster nicht automatisch. Daher sollte das Spark-Cluster, das für Ihr Spark-SQL-Abfragetool verwendet wird, die Dauer für immer haben. Wenn das Cluster bei einem Inaktivitätstimeout herunterfahren darf, funktionieren Spark-SQL-Abfragen nicht mehr in der Produktion, sobald das Cluster gestoppt wird.
Verwenden Sie unter Katalog durchsuchen das Suchfeld, um einen Katalog nach Namen zu suchen, oder klicken Sie durch den Katalogmanager, um den Katalog zu suchen.
Geben Sie im Feld Abfrage Ihre Abfrage ein. Klicken Sie auf Abfragebeispiele und -anleitung anzeigen, um einen Bereich zu öffnen, der vorgefertigte Muster enthält, die Sie kopieren oder anpassen können.
Wählen Sie Max. zurückzugebende Zeilen aus, um die Anzahl der von den Abfrageergebnissen zurückgegebenen Zeilen zu begrenzen.

Hinweis:
Wenn Ihre Abfrage mehr Zeilen als diesen Grenzwert zurückgeben kann, sollten Sie Suchparameter wie {{customer_name}} oder {{region}} hinzufügen, damit der Agent spezifischere Daten finden kann.
Legen Sie im Bereich AI-Tooldefinition den Typ, den Standardwert und die Beschreibung für die in der Abfrage festgelegten Variablen fest.
Optional: Klicken Sie auf die Registerkarte Testen. Geben Sie Testparameter an, und klicken Sie auf Weiterleiten. Siehe Testergebnisse im Bereich Testergebnisse.

Agent-Speicher

Der Agent-Speicher ist Teil eines AI-Agent-Systems, mit dem der Agent Informationen über Turns, Aufgaben oder Sessions hinweg beibehalten und wiederverwenden kann.

Im Gegensatz zum Kontextfenster des Modells, das temporär ist und auf den aktuellen Prompt beschränkt ist, kann der Speicher Fakten, Voreinstellungen, vorherige Entscheidungen, Werkzeugausgaben, Zwischenpläne oder Beobachtungen über die Umgebung beibehalten.

Agent-Speicher in AI Data Platform

AI Data Platform bietet Kurzzeitspeicher, der auf die Dauer einer Session beschränkt ist. Auf der Registerkarte "Speicher" Ihres Agent können Sie konfigurieren, was im Speicher gespeichert werden kann.

Speicherkonfiguration für einen einzelnen Agent

Die Speicherkonfiguration eines einzelnen Agent-Systems finden Sie auf der Registerkarte "Speicher" des Agent-Knotens.

Die visuelle Builder-Leinwand wird mit einem einzelnen Agent-Knoten, InvoiceAnalyst, angezeigt. Der Knoten wird ausgewählt, und die Registerkarte "Speicher" wird hervorgehoben.

Speicherkonfiguration	Beschreibung
Agent-Speicher aktivieren	Diese Einstellung aktiviert den Agent-Speicher. Bei Deaktivierung ist der Agent im Wesentlichen ein zustandsloses System. Jeder Zug wird unabhängig behandelt, und es können keine Nachfragen gestellt werden. Es wird empfohlen, den Speicher zu aktivieren.
Unterhaltungshistorie begrenzen	Wenn diese Auswahl deaktiviert ist, füllen frühere Umdrehungen den Speicher aus, bis das Modell keinen Kontext mehr hat und ein Fehler zurückgegeben wird. Wenn kurze Sitzungen erwartet werden, ist es in Ordnung, diese Einstellung zu deaktivieren. Für die meisten Anwendungsfälle wird jedoch empfohlen, den Unterhaltungsverlauf zu begrenzen.
Abschneidungskonfiguration	Wenn Sie die Konversationshistorie einschränken möchten, können Sie die Historie folgendermaßen abschneiden: Nur die letzten N Nachrichten (Benutzer + Agent) werden beibehalten Einstellen eines Gesamttokenbudgets (First-In, First-Out) Oder beides, je nachdem, welcher Vorgang zuerst eintritt, löst das Leeren des Agent-Speichers aus
Maximale Anzahl Nachrichten	Wenn Sie die letzten N Nachrichten beibehalten möchten, können Sie den Wert N festlegen.
Tokenbudget	Alternativ können Sie ein Gesamtbudget für Token festlegen. Die ersten Token werden eliminiert, um die neuesten im Speicher zu halten.

Systemspeicherkonfiguration mit mehreren Agents (Supervisor-Muster)

Der Speicher eines Multi-Agent-Systems wird auf der Registerkarte "Speicher" des Supervisor-Agents konfiguriert.

$Auf der visuellen Builder-Leinwand wurde ein Multi-Agent angezeigt. Der Knoten {\b AccountsManager} wird ausgewählt, und die Registerkarte {\b Memory} wird angezeigt.$

Speicher für ein Multi-Agent-System wird durchgesetzt und kann nicht deaktiviert werden. Die im Supervisor-Agent-Knoten angezeigten Speicherabschreibungsoptionen werden nur auf den Supervisor-Agent-Speicher angewendet. Jede Executor-Agent-Speicherabschreibungs-Policy kann auf der Registerkarte "Speicher" des Executor-Knotens basierend auf der für das gesamte System ausgewählten Zustandsisolations-Policy konfiguriert werden.

Mit der Speicherkonfiguration für Multi-Agent-Systeme können Sie auch die Speicherfreigabe-Policy der Executor-Agents auswählen. Drei Optionen sind möglich: Stateless, Private und Shared. Beachten Sie, dass die Policy auf alle Executor-Agents angewendet wird.

Zustandsisolierung für Executor-Agents	Beschreibung
Zustandslos	Jeder Executor-Agent sieht nur die Aufgabe, die vom Supervisor zugewiesen wurde. Zwischen den Anrufen wird keine Historie übertragen. Der Executor-Agent kann keine Nachfassanforderung an den Supervisor-Agent senden. Wenn "Zustandslos" ausgewählt ist, ist der Speicher jedes Executor-Agents deaktiviert.
Privat	Jeder Executor-Agent sieht nur seine eigenen vergangenen Interaktionen. Andere Executor-Agents oder die ursprüngliche Benutzerunterhaltung mit dem Supervisor-Agent können nicht angezeigt werden.
Gemeinsam	Executor-Agents können die vollständige Unterhaltungshistorie über Agents und Benutzer hinweg anzeigen. Alle Agents arbeiten aus einem gemeinsamen Kontext. Wenn "Shared" ausgewählt ist, können Sie die Speicherabschreibungs-Policy für jeden Executor-Agent in jeder Speicherregisterkarte des Agent-Knotens separat konfigurieren.

Sessionvariablen

Mit benutzerdefinierten, vom Agent definierten Sessionvariablen können Sie Ihren Agents während einer Benutzersession zusätzliche kontextbezogene Datenpunkte bereitstellen.

Was ist Sessionvariablen?

Benutzerdefinierte, vom Agent definierte Sessionvariablen stellen zusätzliche kontextbezogene Datenpunkte für den Agent während einer Benutzersession bereit. Die Variablen können für eine Vielzahl von Zwecken verwendet werden, einschließlich der Einstellung von Parametern in Tools, der Angabe allgemeiner Anweisungen an einen Agent und der Bereitstellung kontextbezogener Informationen über den Aufrufer und/oder die Anwendung, in die der Agent eingebettet ist.

Im Folgenden finden Sie ein vereinfachtes Szenario, in dem wir einen Kundensupport-Agent erstellen. Der Customer Support Agent ist in eine Retail-Website integriert. Wenn sich ein Benutzer auf der Retail-Website anmeldet, werden Informationen zu diesem Benutzer von der Client-Anwendung erfasst (Benutzer-ID, Benutzername, Geostandort, verwendetes Gerät, Warenkorb-ID usw.) und diese Informationen könnten vom nachgelagerten Support-Agent verwendet werden. Beispiel für die Verwendung dieser Sessionparameter im Feld "Agent-Anweisungen" in AIDP:

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?

Im obigen Beispiel werden drei Sessionvariablen verwendet:

userName
Bevorzugte Salutation
aktueller BenutzerGeo

Der Agent hat keine Vorkenntnisse über den Benutzer, der mit der Retail-Website interagiert, weiß nicht, was der Benutzerstandort ist oder keinen Kontext darüber hat, was im Warenkorb des Benutzers enthalten ist. Grundsätzlich kann die Client-Anwendung alle oder eine Teilmenge dieser Werte kennen und diese Werte in einer Anforderung an den Agent übergeben. Im Folgenden finden Sie ein Beispiel dafür, wie eine Anforderung an den Agent aussehen könnte, einschließlich der Sessionparameter.

Hinweis:

Dieses Beispiel veranschaulicht, wie diese Anforderung aussehen könnte. Es ist kein Vertreter einer Implementierungsentscheidung.

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
]

Der Agent antwortete zurück: "Hallo Herr Paul, wie ist das Wetter heute in Cancun, Mx?"

Eine weitere Verwendung dieser Sessionparameter besteht in der Einstellung von Parameterwerten in Tools. Beispiel: Mit dem Sessionparameter {{sessionParam.CartID}}} kann eine SQL-Abfrage den Inhalt eines Warenkorbs abrufen:

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}

Die Sessionvariablen werden vom Agent-Entwickler definiert, wenn er ihre Agents erstellt, und die Werte dieser Attribute werden von der Clientanwendung festgelegt, wenn eine Session erstellt oder fortgesetzt wird.

Beim Erstellen einer neuen Sessionvariablen können Sie die folgenden Einstellungen konfigurieren:

Einstellung	Beschreibung
Erforderliche Variable	Aktivieren Sie diese Option, um diese Sessionvariable für jeden Aufruf des Agent erforderlich zu machen. Durch die Deaktivierung wird die Sessionvariable für jeden Aufruf optional.
Logvariable	Aktivieren Sie diese Option, um den Wert der Sessionvariablen in Logs und Traces zu erfassen. Durch Deaktivieren wird verhindert, dass die Variable in Logs angezeigt wird. Wir empfehlen, diese Einstellung für Variablen mit sensiblen Daten zu deaktivieren.
Name	Name der Sessionvariablen. Verwenden Sie einen beschreibenden Namen, um es Ihnen und anderen Benutzern zu erleichtern, den Zweck der Variablen zu bestimmen.
Standardwert	Wenn der Standardwert definiert ist, wird er der Sessionvariablen zugewiesen, wenn kein anderer Wert im Aufrufaufruf definiert ist. Wenn kein Wert angegeben wird, muss ein Wert als Teil des Aufrufaufrufs zugewiesen werden.
Beschreibung	Beschreibung der Sessionvariable. Geben Sie eine hilfreiche Beschreibung an, damit Sie und andere Benutzer die Funktion der Sessionvariable verstehen können.

Beispiel: Sessionvariablen in der Tools-Konfiguration verwenden

Sie können eine Sessionvariable in einer SQL-Toolkonfiguration als Teil der SQL-Abfrage selbst verwenden.

In diesem Beispiel wird die Sessionvariable geo verwendet, um das Ergebnis der SQL-Abfrage zu filtern:

Das SQL-Toolfenster für ein Agent-Tool wird angezeigt. Die Registerkarte "Parameter" ist ausgewählt, und der Benutzer gibt {{sessionvariables.ge} ein, um sessionvariables.geo auszuwählen.

Sie können Sessionvariablen und Toolparameter in derselben Abfrage verwenden. Im folgenden Beispiel wird der Parameter titleID vom Agent festgelegt, während die Sessionvariable geo von der aufrufenden Anwendung bereitgestellt wird.

$Das SQL-Toolfenster für einen Agent wird angezeigt. Die Registerkarte "Parameter" ist geöffnet. Im Abfragefeld hat der Benutzer "where market_code= {{sessionvariables.geo}} und title= {{titleID}}" definiert.$

Systemgenerierte Sessionvariablen

Sessionvariablen werden automatisch generiert, wenn ein Remote-MCP-Server mit einem Agent verbunden ist und der MCP-Server wie ein Bearer-Token eine Authentifizierung erfordert.

Das Dialogfeld "Benutzerdefinierten MCP-Server hinzufügen" wird angezeigt. Die Warnmeldung

Die Sessionvariable enthält den Wert des Bearer-Tokens. Der Name dieser systemgenerierten Sessionvariablen kann nicht geändert werden und ist eine erforderliche Variable. Die Systemvariable wird gelöscht, wenn der MCP-Knoten aus der Leinwand entfernt wird.

Die Registerkarte "Variablen" eines Agent wird angezeigt. Die Details für sessionvariables.cred.mcp.GitHub.bearer sind hervorgehoben.

Im Playground geben Sie einen Wert für die systemgenerierte Sessionvariable an. In diesem Fall müssen Sie ein Bearer-Token angeben, um den MCP-Server zu verwenden. Sie können dasselbe (oder ein anderes) Token auswählen, das Sie während der MCP-Knotenkonfiguration verwendet haben.

Das Dialogfeld "Sessionvariablen" wird angezeigt. "sessionvariables.cred.mcp.GitHub.bearer" wird hervorgehoben, und eine Dropdown-Liste mit Authentifizierungstoken wird angezeigt.

Gleiches gilt, wenn Sie den Agent bereitstellen. Sie müssen ein Autorisierungstoken angeben. Weitere Informationen finden Sie unter Sessionvariablen aus dem Playground Werte zuweisen.

Beispiel: Sessionvariablen beim Aufrufen eines bereitgestellten Endpunkts Werte zuweisen

In diesem Beispiel haben Sie zwei Sessionvariablen: userLocation und UserName, die Clientanwendung übergibt Sessionvariablenwerte durch das Feld metadata der body. Wir zeigen, wie Sie Werte über Python und über die OCI-CLI zuweisen können.

Wenn Sie die Python-Anforderungsbibliothek verwenden, ist die Payload wie folgt:

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)

Wenn Sie die OCI-CLI verwenden, lautet die Payload alternativ:

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>"

Sessionvariablen in der Registerkarte "Agent-Variablen" erstellen

Sie können eine neue Sessionvariable erstellen und dem Agent über die Registerkarte "Variablen" hinzufügen.

Navigieren Sie zu dem Agent, dem Sie eine Sessionvariable hinzufügen möchten.
Klicken Sie auf die Registerkarte Variablen.
Klicken Sie auf Sessionvariable hinzufügen.
Aktivieren Sie dieses Kontrollkästchen, wenn die Sessionvariable eine erforderliche Variable ist.
Wählen Sie aus, ob der Wert der Sessionvariable in Logs und Traces aufgezeichnet werden soll. Lassen Sie diese Einstellung für sensible Daten deaktiviert.
Geben Sie einen aussagekräftigen Namen und die Beschreibung für die Sessionvariable an.
Geben Sie einen Standardwert für die Sessionvariable an. Der Standardwert wird der Sessionvariable zugewiesen, wenn im Rahmen des Aufrufs kein anderer Wert zugewiesen wird.
Klicken Sie auf Create.

Sessionvariablen in Agent Flow-Anweisungen referenzieren

Sie können auf Sessionvariablen in Agent-Anweisungen und Toolkonfigurationen verweisen, einschließlich der SQL- und Prompt-Toolabfrage.

Navigieren Sie zu Ihrem Agent-Ablauf.
Klicken Sie im Playground auf den Werkzeugknoten "SQL" oder "Prompt".
Geben Sie im Feld Abfrage {{sessionvariables} ein.
Wählen Sie die Sessionvariable aus der Liste der vorhandenen Sessionvariablen aus.

Agents und Tools mit Sessionvariablen anzeigen

Auf der Registerkarte "Variable" im Agent-Ablauf können Sie eine Liste der Agents und Tools mit einer bestimmten Sessionvariable anzeigen.

Navigieren Sie zu einem Agent-Ablauf, indem Sie die Sessionvariable verwenden, für die Sie zugehörige Agents und Tools anzeigen möchten.
Klicken Sie auf das Register Variable.
Klicken Sie neben Verwendet in: für die Sessionvariable auf das Dropdown-Menü. Eine Liste der Agents und Tools, die diese Sessionvariable verwenden, wird angezeigt.

Sessionvariablen aus dem Playground Werte zuweisen

Auf der Registerkarte Playground können Sie Sessionvariablen jederzeit Werte zuweisen.

Navigieren Sie zu Ihrem Agent-Ablauf.
Klicken Sie oben im Playground auf Sessionparameter. Eine Liste aller Sessionvariablen in Ihrem Agent-Ablauf wird angezeigt.
Ändern Sie die Sessionvariablen. Nach der Fortsetzung der Playground-Session werden die zuletzt zugewiesenen Sessionvariablenwerte verwendet.

Limits

Leitschienen sind Sicherheitsmechanismen, mit denen das Verhalten von KI-Agenten gesteuert und gesteuert wird.

In Oracle AI Data Platform Workbench werden Guardrails konfiguriert, um die Generierung oder den Verbrauch von toxischen und böswilligen Inhalten durch Agent-Flows zu verhindern. Leitplanken verhindern auch das Auslaufen von personenbezogenen Daten (PII) durch den Agent-Fluss. Die in Ihrer AI Data Platform Workbench verfügbaren spezifischen Guardrails gelten für Inhaltsmoderation, Prompt Injection und PII.

Hinweis:

Die von Oracle AI Data Platform Workbench angebotenen Guardrails sind nur in englischer Sprache verfügbar.

Die in der AI Data Platform Workbench angebotenen Guardrails werden vom OCI Generative AI-Serviceteam implementiert. Siehe Guardrails für OCI Generative AI. Basierend auf Ihrer Guardrails-Konfiguration ruft der AI Data Platform Workbench-Service die Apply Guardrails-API in Ihrem OCI-Mandanten auf.

Geländer in Visual Flow Canvas

Standardmäßig werden keine Leitschienen über die nativen Sicherheitskontrollen des Modellanbieters hinaus auf Ihr System angewendet. Um Leitschienen hinzuzufügen, müssen Sie einen Leitschienenknoten an den visuellen Ablaufgenerator Ihres Agent ziehen und mit dem Agent verbinden.

Ein Guardrails-Knoten kann den Datenverkehr zwischen einem Chat-Trigger und einem Agent-Knoten, zwischen einem Supervisor und Executor-Agents oder zwischen Agent- und Toolknoten filtern. In den meisten Szenarios wird ein einzelner Guardrails-Knoten zwischen dem Chattrigger und dem Agent-Knoten empfohlen. Dadurch wird sichergestellt, dass alle Nachrichten des eingehenden Benutzers und Nachrichten, die vom Agent generiert werden, über die Leitplanken gefiltert werden.

Ein Agent, der für den visuellen Builder geöffnet ist. Der Leitplankenknoten ist in der Palette hervorgehoben.

Der Leitplankenknoten kann nur zwischen folgenden Bereichen eingefügt werden:

Ein Chattriggerknoten und ein Agent (Supervisor oder Executor)

Welche Leitplanken sind verfügbar?

Das folgende Diagramm zeigt eine einfache Interaktion zwischen einem Endbenutzer und einem Agent. In diesem Szenario werden alle Guadrails angewendet (Inhaltsmoderation – CM, prompte Injektionsprävention – PI und PII-Erkennung – PII). PI wird nur auf die Benutzerabfrage angewendet.

Nach der zweiten vom Endbenutzer ausgegebenen Nachricht wurde ein PI-Versuch erkannt, und die Benutzernachricht wurde nach der ausgewählten Aktion des Agent-Entwicklers bei der PI-Erkennung (Block) blockiert.

Diagramm zur Beschreibung eines Beispiels für AI-Agent-Flow Guardrails

Inhaltsmoderation

Content Moderation ist eine gängige Implementierung von Leitplanken in den meisten generativen KI. Ungeprüft können LLMs schädliche Inhalte generieren, gewalttätige, rassistische und sexuell explizite Inhalte fördern. Es ist unerlässlich, Agent-Entwicklern vollständige Transparenz und Kontrolle darüber zu geben, wie Benutzerinteraktionen mit Agents überwacht und auf potenziell schädliche Inhalte gescannt werden. Inhaltsmoderation verhindert, dass hasserfüllte, sexuelle, gewalttätige, toxische, abwertende oder belästigungsbasierte Inhalte vom Agentenfluss berücksichtigt oder generiert werden. Unser Leitplankenmodell klassifiziert Inhalte entlang der sechs Kategorien und kennzeichnet Inhalte, die zu einer dieser Kategorien gehören.

Sie können eine Aktion für die Benutzereingabeabfrage oder die Modellantwort ausführen:

Blockieren: Sie verhindern, dass der Agent die Benutzereingabe verarbeitet und eine Antwort generiert. Benutzer erhalten eine Fehlerantwort vom Agent-Ablauf.
Informieren: Sie gestatten dem Agent-Ablauf, die Benutzereingabe zu verarbeiten und eine Antwort zu generieren. Der Agent benachrichtigt den Benutzer, dass die Eingabe oder die Antwort Inhalt enthält, der Guardrail-Kriterien erfüllt.
Zulassen: Sie ermöglichen die Verarbeitung und/oder Generierung potenziell schädlicher Inhalte durch den Agent-Ablauf.

Die Aktion Blockieren wird für die Inhaltsmoderation ausgewählt, wenn Sie einen Agent-Ablauf erstellen. Oracle empfiehlt, Block als Guardrail-Auswahl für die Inhaltsmoderation beizubehalten.

Prompt-Injektion

Prompt Injection Guardrails für AI-Agenten sind ein Schutzmechanismus, der böswillige oder unbeabsichtigte Anweisungen erkennt, verhindert und mindert, die in Benutzereingaben eingebettet sind. Bei Prompt-Injection-Angriffen wird versucht, die ursprünglichen Anweisungen, Richtlinien oder Ziele des Agent zu überschreiben oder umzukehren, indem ausgeblendeter Text eingefügt wird, der das Modell anweist, vorherige Regeln zu ignorieren, Secrets zu exfiltrieren oder nicht autorisierte Aktionen auszuführen.

Sie können dieselben Aktionen auswählen, die Sie für die Inhaltsmoderation ausführen können: blockieren, informieren oder zulassen. Die Prompt Injection Guardrails gelten nur für die Benutzereingabeabfrage.

Blockieren: Sie verhindern, dass der Agent die Benutzereingabe verarbeitet. Benutzer erhalten eine Fehlerantwort vom Agent-Ablauf.
Informieren: Sie lassen zu, dass der Agent-Ablauf die Benutzereingabe verarbeitet. Der Agent benachrichtigt den Benutzer, dass die Eingabe Inhalte enthält, die Guardrail-Kriterien erfüllen.
Zulassen: Sie ermöglichen die Verarbeitung potenziell schädlicher Inhalte durch den Agent-Ablauf.

Die Blockierungsaktion wird beim Erstellen eines Agent-Ablaufs als Prompt Injection ausgewählt. Oracle empfiehlt, Block als Guardrail-Auswahl für Prompt Injection beizubehalten.

Personenbezogene Daten (PII)

Die PII-Schutzschienen erkennen, blockieren oder maskieren PII automatisch aus den Benutzereingabeabfragen oder den Antworten der Agents. Diese Leitplanke verhindert, dass der Agent sensible Benutzerinformationen auf eine Weise offenlegt, die gegen Datenschutzbestimmungen oder Organisationsrichtlinien verstößt.

PII-Leitschienen unterstützen vier Entitätstypen:

Email
Telephone number
Physische Anschrift
Personenname

Für jede dieser vier Entitys wählen Sie aus, welche der folgenden Aktionen der Agent für die eingegebene Benutzerabfrage oder Agent-Antwort ausführt:

Blockieren: Sie verhindern, dass der Agent die Benutzereingabe verarbeitet und eine Antwort generiert. Benutzer erhalten eine Fehlerantwort vom Agent-Ablauf.
Informieren: Sie gestatten dem Agent-Ablauf, die Benutzereingabe zu verarbeiten und eine Antwort zu generieren. Der Agent benachrichtigt den Benutzer, dass die Eingabe oder die Antwort personenbezogene Daten enthielt.
Maske: Sie gestatten dem Agent-Ablauf, die Eingabe zu verarbeiten und eine maskierte Antwort zu generieren. Alle verwendeten personenbezogenen Daten werden verdeckt, um eine Exposition zu verhindern.
Zulassen: Sie erlauben die Verarbeitung und/oder Generierung von PII-Daten durch den Agent-Ablauf.

In einem neuen Agent-Ablauf sind personenbezogene Daten standardmäßig sowohl in der Benutzereingabe als auch in der Antwort zulässig. Oracle empfiehlt, den Guardrail für PII basierend auf Ihren Sicherheitsanforderungen sorgfältig auszuwählen.

Spezifische Guardrails in einem Knoten aktivieren

Sie können wählen, welche Leitplanken aktiviert werden sollen und wie sie konfiguriert werden sollen, wenn Sie Ihrer visuellen Leinwand einen Leitplankenknoten hinzufügen.

Navigieren Sie zum Agent-Ablauf in Ihrem Workspace.
Ziehen Sie einen Knoten Schutzschienen von der Palette auf die Leinwand.
Geben Sie einen aussagekräftigen Namen und die Beschreibung für den Knoten an.
Umschalten einer Leitplanke, um sie zu aktivieren und mit der Konfiguration zu beginnen. Wenn Sie den Umschalter erneut drücken, werden die Leitplanke und ihre Konfigurationen deaktiviert.
Wählen Sie die erforderliche Leitplankenkonfiguration für jede Kategorie aus.

AI-Cluster für einen Agent erstellen

Sie können ein neues KI-Cluster direkt über die Agent-Schnittstelle erstellen und sofort anhängen.

Weitere Informationen finden Sie unter AI Compute.

Navigieren Sie auf der Homepage zu Ihrem Agent.
Klicken Sie auf Compute und dann auf Neues AI-Compute erstellen.
Geben Sie einen Namen und eine Beschreibung für das AI-Compute-Cluster an.
Wählen Sie die Anzahl der OCPUs und die Arbeitsspeichergröße für Ihr AI-Compute-Cluster aus.
Klicken Sie auf Create.

Vorhandenes AI-Cluster an einen Agent anhängen

Sie können ein KI-Cluster, das Sie zuvor erstellt haben, an einen Agent anhängen, für den Sie mindestens Benutzerberechtigungen haben.

Navigieren Sie auf der Homepage zu Ihrem Agent.
Klicken Sie auf Compute und dann auf An AI Compute anhängen.
Klicken Sie in der Liste auf das Cluster, das Sie verwenden möchten.
Der Agent zeigt AIcompute: (ClusterName) running an, wenn er erfolgreich angehängt wurde. Dieser Vorgang kann mehrere Minuten dauern.

Agent von AI Compute trennen

Sie können einen Agent von einem AI-Compute trennen. Durch das Trennen der AI-Compute wird der Agent-Code entfernt, der auf dem angeschlossenen Compute ausgeführt wird, und das Testen wird verhindert.

Hinweis:

Wenn Sie einen Agent von AI-Compute trennen, wird der Agent nicht gelöscht. Sie können die Erstellung und das Testen des Agents fortsetzen, indem Sie ihn an dasselbe oder ein anderes AI-Compute anhängen.

Navigieren Sie auf der Homepage zu Ihrem Agent.
Klicken Sie auf Compute und dann auf Zuordnung zu AI Compute aufheben.

A2A-Agent-Deployment

Das Agent2Agent-Protokoll (A2A) ist ein offener Standard für die Kommunikation zwischen unabhängigen KI-Agents, einschließlich Agents, die mit verschiedenen Frameworks erstellt, von verschiedenen Anbietern gehostet oder als undurchsichtige Remote-Systeme ausgeführt werden.

Der Zweck besteht darin, diesen Agents ein gemeinsames Interaktionsmodell zu geben, damit sie die Fähigkeiten des jeweils anderen erkennen, unterstützte Eingabe-/Ausgabeformate aushandeln, Aufgaben delegieren oder gemeinsam bearbeiten und Informationen sicher austauschen können, ohne internen Speicher, Tools oder Implementierungsdetails verfügbar zu machen. Weitere Informationen finden Sie unter Agent2Agent (A2A)-Protokoll.

A2A soll die Agent-Interoperabilität lösen: Anstatt dass jede Agent-Integration benutzerdefiniert ist, kann ein Client oder ein anderer Agent mit jedem A2A-konformen Remote-Agent mit einem allgemeinen Satz von Konzepten und Vorgängen interagieren. Die Spezifikation konzentriert sich auf Nachrichten, Aufgaben, Teile, Artefakte, Streaming-Updates und Push-Benachrichtigungen. Sie unterstützt synchrone Antworten, asynchrone Arbeit mit langer Ausführungszeit, Streaming und Authentifizierungs-/Sicherheitsmuster im Enterprise-Stil.

In Oracle AI Data Platform erhalten alle bereitgestellten Agents einen /A2A-Aufrufpfad, der von A2A-Clientanwendungen aufgerufen werden kann.

Was ist eine Agent Card?

Eine Agent Card ist ein JSON-Metadatendokument, das von einem A2A-Server veröffentlicht wird. In AIDP ist der A2A-Server der AI-Compute, der Ihr Agent-Deployment hostet.

Die Karte beschreibt die Identität des Agent, den Serviceendpunkt, unterstützte Protokolle/Transporte, Fähigkeiten, Fähigkeiten, unterstützte Eingabe-/Ausgabemodi und Authentifizierungsanforderungen. Clients ermitteln damit, ob der Agent geeignet ist und wie er aufgerufen werden kann. Eine ordnungsgemäß dokumentierte Agent-Karte ist eine Anforderung des A2A-Protokolls.

Agent-Karten in AI Data Platform Workbench haben entweder den Status "Entwurf", d.h. der Agent wurde nicht bereitgestellt, oder "Veröffentlicht", d.h. die Karte wurde neben dem Agent bereitgestellt.

Agent-Kartenaktionen

Während der Entwicklung eines Agent ist die Karte im Menü "Aktionen" des Agent verfügbar.

Auf zwei Agent-Karten kann zugegriffen werden:

Der Kartenentwurf spiegelt den aktuellen Status des Agenten in der Entwicklung wider.
Die veröffentlichte Karte entspricht einem Snapshot der Karte, die beim Deployment des Agent erstellt wurde. Die veröffentlichte Karte gibt den Status des bereitgestellten Agent an.

Agent-Kartenfelder

AI Data Platform Workbench unterstützt eine Teilmenge der aktuellen A2A-Protokoll-Agent-Kartenfelder, die hier verfügbar sind: A2A-Protokoll - Agent-Karte.

Feld	Erforderlich	Beschreibung
`name`	Ja	Ein menschenlesbarer Name für den Agent. Beispiel: "Rezept-Agent"
`description`	Ja	Eine menschenlesbare Beschreibung des Agenten, die Benutzer und andere Agenten dabei unterstützt, seinen Zweck zu verstehen. Beispiel: "Agent, der Benutzern beim Kochen und Rezepten hilft."
`Agent Version`	Ja	Die Version des Agent. Beispiel: "1.0.0"
`Documentation URL`	Nr.	Eine URL mit zusätzlicher Dokumentation zum Agent.
`Provider - Organization`	Nr.	Der Serviceprovider des Agent.
`Provider - URL`	Nr.	Die URL des Serviceproviders.
`Capabilities`	Ja	A2A-Fähigkeitssatz, der vom Agent unterstützt wird. Nur `streaming` kann konfiguriert werden (True/False)
`Skills`	Ja	Skills stellen die Fähigkeiten eines Agents dar. Es ist weitgehend ein beschreibendes Konzept, stellt aber eine fokussiertere Gruppe von Verhaltensweisen dar, bei denen der Agent wahrscheinlich erfolgreich sein wird. Skills stellen ein Array von AgentSkill dar.

Jede AgentSkill besteht aus mehreren Feldern, in denen die Fähigkeiten des Agent dokumentiert werden. Die Definition der Agent-Skills auf der Agent-Karte ist der zeitaufwendigste Vorgang und ein iterativer Prozess. Skills können (zusammen mit dem Rest der Agent-Karte) vor dem Deployment in der Entwurfs-Agent-Karte bearbeitet werden.

Hinweis:

inputModes, outputModes und securityRequirements werden von AI Data Platform Workbench bereitgestellt und können nicht geändert werden.

Feld	Erforderlich	Beschreibung
`Skill ID`	Ja	Eine eindeutige ID für den Skill des Agents.
`Skill Name`	Ja	Ein menschenlesbarer Name für den Skill.
`Description`	Ja	Eine detaillierte Beschreibung des Skills.
`Tags`	Ja	Eine Gruppe von Schlüsselwörtern, die die Fähigkeiten des Skills beschreiben.
`Examples`	Nr.	Beispiel-Prompts oder Szenarios, die dieser Skill verarbeiten kann.

Agent-Deployment-Endpunkt A2A-Pfad

Ein /a2a-Pfad wird zusätzlich zu /chat in der URL eines bereitgestellten Agent angezeigt.

Beispiel: Ein Agent stellt diese Pfade externen Clients zur Verfügung:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chat
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a

Beide Pfade (/chat, /a2a) können von separaten Clients belegt werden.

Sessionvariablen in A2A

Werte von Sessionvariablen können an einen A2A-Agent im Feld metadata der Nachricht übergeben werden. Im folgenden JSON-Snippet wird die Payload einer Benutzernachricht angezeigt, die an den a2a-Agent mit drei Sessionvariablen ausgegeben wurde: userName, geoLocation und os:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "contextId": "session_12345",
    "taskId": "task_67890",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What is the current status of my order?",
        }
      ],
      "metadata": {
        "sessionvariables.userName": "George",
        "sessionvariables.geoLocation": “Dallas, TX”,
        "sessionvariables.os": "mobile_ios"
      }
    }
  },
  "id": "rpc-99821"
}

Beispiel: A2A-Agent mit OCI-CLI aufrufen (Nicht-Streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": "<your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<your-user-principal>"
  }' \
  --target-uri " <your-a2a-agent-endpoint-url>"

Beispiel: A2A-Agent mit OCI-CLI (Streaming) aufrufen

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": " <your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<user-principal>"
  }' \
  --target-uri "<your-a2a-agent-endpoint-url>"

Beispiel: A2A Client SDK

import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
    AgentCard,
    Message,
    Part,
    Role,
    TextPart,
    SendMessageRequest,
    MessageSendParams,
    MessageSendConfiguration,
    Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)

class OCIAuth(httpx.Auth):
    """httpx auth implementation using OCI signer via requests auth adapter."""

    def __init__(self, signer: oci.signer.AbstractBaseSigner):
        self._requests_auth = _OCIRequestsAuth(signer)

    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
        req = RequestsRequest(
            method=request.method,
            url=str(request.url),
            headers=dict(request.headers),
            data=request.content,
        )
        prepared: RequestsPreparedRequest = req.prepare()
        prepared = self._requests_auth(prepared)
        request.headers.update(dict(prepared.headers))
        yield request



def getOCIAuth():
    conf = oci.config.from_file(profile_name="DEFAULT")
    token_file = conf['security_token_file']
    token = None
    with open(token_file, 'r') as f:
        token = f.read()
    private_key = oci.signer.load_private_key_from_file(conf['key_file'])
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    auth = OCIAuth(signer=signer)
    return auth


async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
    """Call an agent using the A2A protocol."""
    try:
        # Initialize OCI signer
        #headers = {"dh-user-principal": "dh-user"}
        headers = {"Accept": "*/*",
                   "dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

        async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
            agent_card = await _get_agent_card(agent_url,auth)
            print(f"Agent card is {agent_card}")

            client =  A2AClient(httpx_client=hc, agent_card=agent_card)
            # Create message
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
                metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
            )
            request = SendMessageRequest(
                id=str(uuid.uuid4()),  # Add the required id field
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            #json_string = json.dumps(message, indent=4)
            print(f"Send request : {request}")

            response = await client.send_message(request)

            logging.info("Received response from A2A server: %s", response.root.result)
            # Extract response
            result = response.root.result
            # Handle different response types


            if isinstance(result, Task):
                # Task response
                if result.artifacts:
                    # Extract text from artifacts
                    texts = []
                    for artifact in result.artifacts:
                        for part in artifact.parts:
                            if hasattr(part, "root") and hasattr(part.root, "text"):
                                texts.append(part.root.text)
                    return "\n".join(texts) if texts else "Task completed with no text response"
                elif result.status and result.status.message:
                    logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
                    if  result.status.state== "failed":
                        print("Failure observed in Task invocation")
                        for m_part in result.status.message.parts:
                           print(f"Error message  { m_part.root.text}")

                    return get_message_text(result.status.message)
                else:
                    return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"

            elif isinstance(result, Message):
                return get_message_text(result)
            else:
                logging.warning(f"Unexpected response type: {type(result)}")
                return "Received response but unable to extract text"
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"


async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
    """Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
    try:
        async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
            agent_card = await _get_agent_card(agent_url)
            if not agent_card:
                return "No Agent Card Found"
            print(f"Agent card is {agent_card}")

            client = A2AClient(httpx_client=hc, agent_card=agent_card)
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
            )
            request = SendStreamingMessageRequest(
                id=str(uuid.uuid4()),
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            print("Invoking Remote Agent request (beautified JSON):")
            print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
            # Expected event types:
            # - TaskStatusUpdateEvent (working/in-progress)
            # - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
            final_artifact_text_parts: list[str] = []

            async for event in client.send_message_streaming(request):
                # Print each SSE event as-is (SDK object)
                print(f"[A2A stream event] {event}")

                try:
                    result = getattr(event.root, "result", None)
                    if not result:
                        continue

                    # TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
                    # extract by attribute presence.
                    artifact = getattr(result, "artifact", None)
                    if artifact and getattr(artifact, "parts", None):
                        for part in artifact.parts:
                            root = getattr(part, "root", None)
                            txt = getattr(root, "text", None)
                            if txt:
                                final_artifact_text_parts.append(txt)
                except Exception:
                    # Keep streaming even if an event can't be parsed
                    continue

            return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"

Agent-Entwurfskarte bearbeiten

Sie können die Agent-Karte für einen Agent bearbeiten, der noch nicht bereitgestellt ist.

Navigieren Sie zu Ihrem Agent.
Klicken Sie auf Aktionen und dann auf Agent-Karte anzeigen und Agent-Karte entwerfen.
Klicken Sie auf Edit.
Sie können die Ansicht wechseln, indem Sie oben rechts auf Formular oder JSON klicken. Die JSON-Ansicht ist vollständiger, aber schreibgeschützt. Sie können Felder nur in der Formularansicht bearbeiten.
Ändern Sie die Felder nach Bedarf.
Klicken Sie auf Skill hinzufügen, um Skills hinzuzufügen, die Sie für A2A-Clients verfügbar machen möchten.
Klicken Sie auf Speichern.

Veröffentlichte Agent-Karte bearbeiten

Sie können eine veröffentlichte Agent-Karte ändern, ohne dass das Deployment eines Agents rückgängig gemacht oder erneut bereitgestellt wird.

Die veröffentlichte Karte entspricht einem Snapshot der Entwurfskarte zum Zeitpunkt der Bereitstellung.

Hinweis:

Änderungen, die Sie an einer veröffentlichten Karte vornehmen, werden sofort in der Datei agent-card.json wiedergegeben, auf die A2A-Clients zugreifen können.

Navigieren Sie zu Ihrem Agent.
Klicken Sie auf Aktionen, Agent-Karte anzeigen und Veröffentlichte Agent-Karte.
Sie können die Ansicht wechseln, indem Sie oben rechts auf Formular oder JSON klicken. Die JSON-Ansicht ist vollständiger, aber schreibgeschützt. Sie können Felder nur in der Formularansicht bearbeiten.
Klicken Sie auf Edit.
Ändern Sie die Felder nach Bedarf.
Klicken Sie auf Skill hinzufügen, um Skills hinzuzufügen, die Sie für A2A-Clients verfügbar machen möchten.
Klicken Sie auf Änderungen veröffentlichen.

Veröffentlichte Agent-Karten sind nicht öffentlich verfügbar. Ein Benutzer muss authentifiziert werden und über die richtige Berechtigung (READ) verfügen, um den Inhalt von agent-card.json zu prüfen. Andere Agents können die Funktionen und Metadaten Ihrer Agents über eine HTTP-GET-Anforderung auf dem Standardpfad ermitteln:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json

Agent Deployment

Wenn Sie einen Agent bereitstellen, wird Ihr Agent zu einer gehosteten Anwendung.

Sie können einen Agent in demselben AI-Compute bereitstellen, das an seinen Playground angeschlossen ist, oder in einem anderen AI-Compute. Wenn Sie die neuesten Änderungen an Ihrem Agent in dem angehängten AI-Compute bereitstellen, stellt der bereitgestellte Agent einen Snapshot des Agent zum Zeitpunkt des Deployments dar. Um den bereitgestellten Agent auf die neueste Version zu aktualisieren, müssen Sie den Agent erneut bereitstellen.

Jeder Agent verfügt über eine stabile Deployment-URL, die vom eindeutigen Agent-Schlüssel abhängt. Wenn Sie den Agent mehrmals erneut bereitstellen, wird der Agent hinter der Deployment-URL überschrieben.

Für das Deployment Ihrer Agents gelten die folgenden Einschränkungen:

Ein Agent kann jeweils nur in einem AI-Compute-Cluster bereitgestellt werden.
Wenn Sie denselben Agent mehrmals in demselben AI-Compute-Cluster bereitstellen, wird die zuvor bereitgestellte Iteration des Agent überschrieben.

Nachdem Sie einen Agent bereitgestellt haben, können Sie die Chat-URI abrufen, um programmgesteuert Abfragen abzufragen und Antworten vom Agent über die Registerkarte Details Ihres Agent abzurufen.

Agent-Seite geöffnet, wobei die Registerkarte "Details" geöffnet und markiert ist. In AI Compute bereitgestellt und Endpunkt-URL hervorgehoben

Die Endpunkt-URL ist stabil und an jeden Agent gebunden. Die URL enthält die eindeutige Agent-ID, die jedem Agent zugewiesen ist. Mit anderen Worten: Wenn Sie das Deployment eines Agent rückgängig machen und ihn erneut bereitstellen, bleibt die URL unverändert. Der Vorteil ist, dass Sie den Clientcode, der den Endpunkt aufruft, nicht ändern müssen. Der Nachteil besteht darin, dass Sie einen Agent in der Produktion überschreiben können.

Die URL hat die folgende Struktur:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}

Hierbei gilt:

oci-region entspricht der AI Data Platform-Instanzregion;
agentId ist die eindeutige ID, die dem Agent zugeordnet ist
protocol ist das Kommunikationsprotokoll: chat, das dem OpenAI Responses-API-Format folgt, und a2a, das dem Agent-zu-Agent-Kommunikationsprotokoll folgt. Beide Protokolle sind für jeden Agent-Endpunkt verfügbar. Weitere Informationen finden Sie unter A2A-Agent-Deployment.

Hinweis:

Auf der Registerkarte "Details" werden zwei AI-Berechnungen aufgeführt. Mit An AI Compute angehängt wird der Agent im Playground getestet. Das Deployment in AI Compute hostet den bereitgestellten Agent.

Das Feld "Endpunkt-URL" wird aufgefüllt, nachdem Sie Ihren Agent bereitgestellt haben. Sie können diese Endpunkt-URL über Ihre Produktionsanwendung aufrufen.

Agent bereitstellen

Sie stellen Agents bereit, die Sie erstellt und konfiguriert haben, damit andere Benutzer sie in Ihrer AI Data Platform-Instanz anzeigen und verwenden können.

Navigieren Sie auf der Homepage zu dem Ordner, der den Agent enthält, den Sie bereitstellen möchten.
Klicken Sie neben dem Agent auf Aktionen und dann auf Bereitstellen. Sie können auch auf den Agent-Namen klicken und oben rechts auf Bereitstellen klicken.
Wählen Sie die AI-Compute aus, die an den bereitgestellten Agent angehängt werden soll.
Wählen Sie AIDP Workbench als Autorisierungstyp aus.
Wählen Sie eine Sessiondatenaufbewahrungs-Policy aus.
- Geben Sie unter Aufbewahrungszeitraum die Anzahl der Tage an, für die Sessiondaten aufbewahrt werden.
- Geben Sie unter Grenzwert für Sessiongröße die maximale Größe an, die eine Session erreichen kann.
- Geben Sie unter Grenzwert für die Anzahl der Threads die maximale Anzahl der beibehaltenen Sessionthreads an.
Klicken Sie auf Bereitstellen.

Agent mit OAuth2 bereitstellen

Sie können Agents bereitstellen, die Sie erstellt und für die Verwendung der OAuth2-Authentifizierung konfiguriert haben, um eine Verbindung zu externen Identitätsprovidern herzustellen.

Navigieren Sie auf der Homepage zu dem Ordner, der den Agent enthält, den Sie bereitstellen möchten.
Klicken Sie neben dem Agent auf Aktionen und dann auf Bereitstellen. Sie können auch auf den Agent-Namen klicken und oben rechts auf Bereitstellen klicken.
Wählen Sie die AI-Compute aus, die an den bereitgestellten Agent angehängt werden soll.
Wählen Sie OAuth2 als Autorisierungstyp aus.
Geben Sie den Zielgruppenanspruch an. AI Data Platform Workbench füllt dieses Feld automatisch aus. Sie können es jedoch durch einen Zielgruppenanspruch von Ihrem Identitätsprovider ersetzen.
Geben Sie den Ausstelleranspruch und den URI zum Abrufen von JWKS an. Diese Informationen werden von Ihrem Identitätsprovider abgeleitet.
Wählen Sie eine Sessiondatenaufbewahrungs-Policy aus.
Klicken Sie auf Bereitstellen.

Bereitgestellten Agent aufrufen

Sie können die Endpunkt-URL des Agent über die Produktionsanwendung aufrufen.

Unabhängig von der programmgesteuerten Schnittstelle, die zum Aufrufen des Agent-Endpunkts verwendet wird, müssen Sie mit OCI authentifiziert werden und über die entsprechenden Berechtigungen verfügen. Bei Agent Flow-Endpunkten muss der Aufrufer mindestens die Berechtigung USE für den Agent-Endpunkt besitzen.

Die Endpunkt-URI ist auf der Registerkarte "Details" der Agent-UI dokumentiert. Sie können diese Endpunkt-URI in Ihren Code kopieren, um den Agent aufzurufen.

Detailseite für einen Agent, der mit hervorgehobenem Endpunkt-URI-Feld geöffnet ist

Methoden zum Aufrufen von Endpunkt-URIs

Sie können die Agent-Endpunkt-URI über verschiedene Tools, SDKs und CLIs aufrufen.

Mit den folgenden Methoden können Sie den Endpunkt-URI in Oracle AI Data Platform Workbench-Agents aufrufen.

Mit OCI-CLI aufrufen

Das angegebene Beispiel zeigt, wie Sie die OCI-CLI verwenden und sich mit einem Sicherheitstoken authentifizieren. Ersetzen Sie <your-agent-flow-endpoint-uri> durch die Agent-Endpunkt-URI und <security_token> durch das OCI-Sicherheitstoken.

oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>

Mit Python-Anforderungsbibliothek aufrufen

Mit dem OCI-Python-SDK können Sie einen Signaturgeber zur Authentifizierung bei OCI erstellen. Mit der Python-Anforderungsbibliothek kann eine Anforderung an die Agent-Endpunkt-URI gepostet und eine Antwort zurückgegeben werden. Das folgende Beispiel zeigt, wie Sie Ihren Benutzer-Principal über die OCI-Konfigurations- und Private-Key-Dateien verwenden können:

import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
 self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
    return self.signer
 
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
    body = {
        "isStreamEnabled" : False,
        "sessionKey" : self.sessionKey,
        "trace" : False,
        "input" :[{
            "role":"User",
            "content":[{
                "type" : "INPUT_TEXT",
                "text" : input                   
            }]
        }]
    }

    response:Request = requests.post(
        url =self.chat_url,
        params = None,
        auth = self.authsigner,
        json=body,
        headers={}
    )
    return response

Sie können die Agent-Endpunkt-URI aufrufen, indem Sie die MyRawJsonRPCClient-Klasse instanziieren und einen OCI-Profilwert (in der OCI-Konfigurationsdatei gefunden), den Agent-Endpunkt-URI (chat_url) und einen sessionKey angeben. Sie können beliebige sessionKey angeben. sessionKey ist die eindeutige ID der Benutzersession mit dem Agent. Wenn Sie denselben sessionKey weiterhin verwenden, werden Benutzernachrichten und Agent-Antworten an denselben Schutz angehängt.

client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
   oci_profile = "DEFAULT",
   sessionKey= “<your-session-key>”,
   use_security_token = False )

Sie können auch eine Benutzernachricht angeben und die Nachricht mit dem Client an den Agent-Endpunkt-URI senden:

user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()

Über APEX

Sie können das Codebeispiel verwenden, das im AI Data Platform Workbench Samples Github-Repository verfügbar ist. Das Beispiel führt Sie durch den Prozess zum Aufrufen eines Agent-Deployment-Endpunkts aus einer APEX-Anwendung.

Durch Streamlit

Sie können das Codebeispiel verwenden, das im AI Data Platform Workbench Samples Github-Repository verfügbar ist. Das Beispiel führt Sie durch den Prozess zum Aufrufen eines Agent-Deployment-Endpunkts aus einer Streamlit-Anwendung.

Best Practices – Asynchrone und nicht-asynchrone Antworten

Wir empfehlen, dass Sie Ihren Clientcode unter Annahme asynchroner Antworten schreiben. Beispiel:

import httpx 
 
async def fetch_data(): 
    async with httpx.AsyncClient() as client: 
        response = await client.get(URL) 
        return response.json()

Deployment eines Agent aufheben

Sie können das Deployment von Agents aufheben, für die Sie MANAGE-Berechtigungen haben, sodass sie nicht mehr verwendet werden können.

Navigieren Sie auf der Homepage zu dem Ordner, der den Agent enthält, dessen Deployment Sie aufheben möchten.
Klicken Sie neben dem Agent auf Aktionen, und klicken Sie auf Deployment aufheben.
Klicken Sie auf Bereitstellung aufheben.

Agents überwachen

Sie können Details zu den Sessions und Metriken Ihrer Agents überwachen, um Informationen darüber anzuzeigen, wie sie verwendet werden, welche Ressourcen sie verbrauchen und mehr.

Sie haben in Ihrem Agent mehrere Registerkarten zum Verfolgen von Nutzungsdetails, die Registerkarte Sessions, die Registerkarte Metriken und die Registerkarte Aktivität. Sie finden sie oben auf Ihrer Agent-Leinwand.

Traces und Spans

Traces bieten Beobachtbarkeit für Ihre Agents, indem sie den Ablauf von Agent-Anforderungen erfassen und anzeigen. Spans sind die Objekte, aus denen ein Trace besteht. Jeder Span ist ein anderer Schritt im Ablauf, z.B. Chat-Prompts von einem Benutzer, Agent-Aufrufe und Workflowaufgaben.

Sie können Traces für die aktuelle Session, den Testlauf oder vorherige Sessions anzeigen. Um das Trace der aktuellen Session anzuzeigen, wechseln Sie zur Registerkarte "Flow", und klicken Sie auf "Playground". Im Bereich "Details" unten auf der Seite wird die Verfolgung der aktuellen Sitzung im linken Bereich angezeigt. Sie können auf Objekte im Trace klicken, um sie einzublenden oder detailliertere Informationen anzuzeigen. Im rechten Fensterbereich können Sie auf die Registerkarten "Info", "Details" oder "Ereignisse" klicken, um mehr über das ausgewählte Span-Objekt zu erfahren.

Sie können Traces für vorherige Sessions in der Registerkarte Sessions anzeigen, indem Sie auf den Namen der Session klicken.

Sessions

Auf der Registerkarte Sessions wird eine Historie der Sessions für diesen Agent angezeigt. Sie können sehen, ob jede Session erfolgreich oder nicht erfolgreich war, den URI-Ursprung, den Start der Session, die Dauer der Session und die in der Session verwendeten Token. Sie können auf die Session-ID klicken, um spezifischere Details zu dieser Session anzuzeigen und Traces für diese spezifischen Sessions anzuzeigen.

Sie können die angezeigten Sessions filtern, indem Sie die Suchleiste verwenden, um nach Session-ID oder URI-Ursprung zu filtern. Verwenden Sie die Datumsfilter, um nur einen bestimmten Datumsbereich anzuzeigen, und das Dropdown-Menü "Sessionstatus", um nach der erfolgreichen oder nicht erfolgreichen Session zu filtern.

Metriken

Auf der Registerkarte Metriken wird eine Übersicht der Nutzungsdaten für alle Agent-Sessions angezeigt. In der Dropdown-Liste "Datumsbereich" wird der Zeitraum gefiltert, der in den angezeigten Karten zusammengefasst werden soll. Die URI-Auswahl filtert die URI-Auswahlquelle, für die Sie die Details anzeigen möchten. Sie können ändern, welche Karten angezeigt werden und ob sie Diagramme als visuelle Darstellungen der Verwendung enthalten.

Aktivität

Auf der Registerkarte Aktivität wird eine Übersicht über den Agent-Deployment-Status angezeigt. In der Spalte "Vorgang" wird der Typ des Deployment-Vorgangs (Bereitstellen oder Aufheben des Deployments) angegeben, und in der Spalte "Status" wird das Ergebnis des Vorgangs angegeben (Erfolgreich, Fehler, Warnung, Nicht erfolgreich). Sie können sehen, wer den Vorgang initiiert hat und wann sowie die Statusmeldung, die dem Vorgangsergebnis zugeordnet ist.

Agent-Sessions anzeigen

Sie können eine Historie der Sessions für Ihren Agent anzeigen und die Ergebnisse filtern, um Trends anzuzeigen und die Fehlerbehebung zu unterstützen.

Navigieren Sie auf der Homepage zu Ihrem Agent.
Klicken Sie auf die Registerkarte Sessions.
Verwenden Sie die Filter, um die angezeigten Sessions zu ändern.

Agent-Metriken anzeigen

Sie können zusammengefasste Details zu dem verwendeten Agent anzeigen, wie Tokenverwendung, Sessiondauer, Latenz und mehr.

Navigieren Sie auf der Homepage zu Ihrem Agent.
Klicken Sie auf die Registerkarte Metriken.
Wählen Sie in der Dropdown-Liste Datumsbereich andere Optionen aus, um zu sehen, wie sich die Metrik über Zeitleisten hinweg unterscheidet.
Wählen Sie in der Dropdown-Liste URI-Auswahl andere Optionen aus, um nach bestimmten URI-Quellen zu filtern.

Agent verschieben

Sie können Agents verschieben, deren Eigentümer Sie sind oder für die Sie über MANAGE-Berechtigungen verfügen.

Navigieren Sie auf der Homepage zu dem Ordner mit dem Agent, den Sie verschieben möchten.
Klicken Sie neben dem Agent, den Sie ändern möchten, auf Aktionen, und klicken Sie auf Verschieben.
Wählen Sie den neuen Workspace-Speicherort für den Agent aus. Klicken Sie auf Verschieben.

Agent kopieren

Sie können einen Agent, dessen Eigentümer Sie sind, oder MANAGE-Berechtigungen für einen verfügbaren Workspace an einen anderen Speicherort kopieren.

Sie können Agents in denselben oder einen anderen Ordner kopieren. Agent-Abläufe können in Ordner in verschiedenen Workspaces kopiert werden, auf die Sie Zugriff haben. Die Agent-Konfiguration sowie Tool- und Guardrail-Einstellungen werden kopiert. AI-Compute-Clusteranhänge werden nicht kopiert, und Sie müssen den Agent an ein neues AI-Compute-Cluster anhängen, um die Entwicklung fortzusetzen.

Navigieren Sie auf der Homepage zu dem Ordner mit dem Agent, den Sie verschieben möchten.
Klicken Sie neben dem Agent, den Sie ändern möchten, auf Aktionen und dann auf In Workspace kopieren.
Geben Sie gegebenenfalls einen neuen Namen und eine Beschreibung für den kopierten Agent an.
Klicken Sie auf Durchsuchen, und wählen Sie einen neuen Speicherort im Workspace aus, in den der Agent kopiert werden soll. Klicken Sie auf Auswählen.
Klicken Sie auf Kopieren.

Agent-Dateien herunterladen

Sie können Agent-Dateien und deren Guardrail-Dateien herunterladen, die Definitionen für diesen Agent enthalten.

Agent-Dateien sind JSON-Dateien mit der Dateierweiterung AFLOW und enthalten die Definitionen für Ihren Agent. Guardrails-Dateien haben das Label _guardrails.JSON und enthalten die Guardrail-Definitionen für den Agent.

Navigieren Sie zum Agent-Ordner in Ihrem Workspace.
Klicken Sie auf den Namen des Agent, den Sie herunterladen möchten.
Klicken Sie neben der AFLOW-Datei für den Agent auf Aktionen und dann auf Herunterladen. Die Datei wird auf den lokalen Rechner heruntergeladen.
Klicken Sie neben der Datei _guardrails.JSON auf Aktionen und dann auf Herunterladen. Die Datei wird auf den lokalen Rechner heruntergeladen.

22 KI-Agents

Multi-Agent-Systeme und Supervisor-Muster

Informationen zur Visual Flow Canvas

Agent erstellen

Chattrigger und -Agent zur Visual Builder-Leinwand hinzufügen

Supervisor-Agent konfigurieren

Vorgeschlagene Anweisungen des Vorgesetzten

Supervisor-Agent-Speicher und Statusisolierung konfigurieren

Registerkarte "Parameter" für Modelle

Guardrails zu einem Agent hinzufügen

Executor-Agents und -Tools zu einem Agent hinzufügen

Executor-Agent-Konfiguration

Checkliste für Agents über Visual Builder

Agent-Durchlaufcode

Agent durch Code durch Upload erstellen

Agent durch Code erstellen, indem neuer Code erstellt wird

Eintragsdatei für Agents über Code festlegen

Abhängigkeitsdatei für Agents über Code festlegen

Testagentcode

Agent-Skills in Coding Experience

Neuen Skill hinzufügen

Neue ausführbare Fähigkeit zu einem vorhandenen Skill hinzufügen

Agent-Skills - Fehlerbehebung

Beispiel: Agent-Skill abschließen

Agent-Tests

Testen Sie Ihre Agenten im Spielplatz

Agent-Testsession erstellen

Agent-Testsession fortsetzen

Agent-Testsession löschen

Agent-Tools

Benutzerdefiniertes Werkzeug

Benutzerdefiniertes Tool zu einem Agent hinzufügen

Remote-MCP-Servertool

Agent über Visual Builder mit einem Remote-MCP-Server verbinden

HTTP-Anfragetool

HTTP-Request-Tool zu einem Agent-Ablauf hinzufügen

Prompt-Tool

Tool für Eingabeaufforderungen zu einem Agent hinzufügen

RAG-Tool

RAG-Tool zu einem Agent hinzufügen

SQL-Tool

SQL-Tool zu einem Agent hinzufügen

Agent-Speicher

Sessionvariablen

Sessionvariablen in der Registerkarte "Agent-Variablen" erstellen

Sessionvariablen in Agent Flow-Anweisungen referenzieren

Agents und Tools mit Sessionvariablen anzeigen

Sessionvariablen aus dem Playground Werte zuweisen

Limits

Spezifische Guardrails in einem Knoten aktivieren

AI-Cluster für einen Agent erstellen

Vorhandenes AI-Cluster an einen Agent anhängen

Agent von AI Compute trennen

A2A-Agent-Deployment

Agent-Entwurfskarte bearbeiten

Veröffentlichte Agent-Karte bearbeiten

Agent Deployment

Agent bereitstellen

Agent mit OAuth2 bereitstellen

Bereitgestellten Agent aufrufen

Methoden zum Aufrufen von Endpunkt-URIs

Deployment eines Agent aufheben

Agents überwachen

Agent-Sessions anzeigen

Agent-Metriken anzeigen

Agent verschieben

Agent kopieren

Agent-Dateien herunterladen