17Agent-Erstellung
In diesem Abschnitt wird die Erstellung von KI-Agents über den visuellen Flow Builder oder über Code behandelt.
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
- 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.
| 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.
- Klicken Sie auf
Agent erstellen, oder klicken Sie oben rechts auf Erstellen.
- Wählen Sie unter Agent-Flow-Authoring-Modus die Option Visueller Builder aus.
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.
- Klicken und ziehen Sie einen Supervisor-Agent auf die Leinwand.
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.
| 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.
| 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:
|
| 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.
|
- 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.
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.
| Limit | Optionen | Wann verwendet |
|---|---|---|
| Personenbezogene Daten (PII) |
|
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. |
- 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.
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.
- 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.
Tabelle 17-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:
|
| 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.
|
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 17-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. |
Agents durch Code
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.
Sie erstellen einen Agent über Code, indem Sie entweder eine vorhandene Codedatei hochladen oder Codedateien direkt in Ihrem Agent über den Inline Editor erstellen.
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- Ordner
Sie können die verfügbaren Codedateien anzeigen und durch diese navigieren, indem Sie auf die Dropdown-Liste "File Selector" (Dateiauswahl) klicken.
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())
- 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 mitawait, 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.
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.- 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.
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- Ordner
- Klicken Sie auf Neue Datei hinzufügen.
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.
- 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.
- 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.
- Klicken Sie auf die Registerkarte Playground.
- Klicken Sie auf Wiedergeben, um die ausgewählte Codedatei zu testen.
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.
- 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
- 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
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 17-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")
- 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.
- Der Skill muss
run_skill_entrypointin zulässige Tools enthalten. - Das Skript muss explizit im Entrypoints-Abschnitt von
SKILL.mddeklariert 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
- Unter dem Skript/Verzeichnis des Skills
- Deklariert in der Frontmatter der Einstiegspunkte des Skills
- Durch die Einstellung
allowed-toolsdes 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.
description: Helps generate BigQuery SQL using the finance warehouse schema.description: Helps with data.Explizite Eintragspunktnamen verwenden
entrypoints:
- name: validate_query
- name: summarize_numbers
- name: transform_csventrypoints:
- 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.
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.
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
- 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
- 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
- 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.
- 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.
- Klicken Sie am oberen Rand der Leinwand auf Playground. Es kann einige Sekunden dauern, bis der Agent an das angeschlossene Compute übertragen wird.
Agent-Testsession erstellen
Sie können eine Testsession erstellen, um eine neue Unterhaltung mit Ihrem Agent zu initiieren.
- 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.- Wählen Sie in der Session-Dropdown-Liste eine vorherige Session aus.
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.
- Klicken Sie auf die Registerkarte Sessions.
- Klicken Sie neben der Session, die Sie löschen möchten, auf
Aktionen und dann auf Löschen.