18 Agent-Tools
Oracle AI Data Platform Workbench unterstützt Toolvorlagen, die so konfiguriert werden können, dass sie auf Ihre Daten zugreifen und zu Ihren Anwendungsfällen passen.
Agents unterstützen Konfigurationen, die aus einem einzelnen Agent bestehen, der eine Schnittstelle zu einem oder mehreren Tools herstellen kann. 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 Autonomous 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.
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-Tools über LangGraph-Code
Sie fügen Ihren LangGraph-codierten Agents Tools über eine Instanz der Klasse AIDPToolConf() hinzu.
from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool = AIDPToolConf(name, description, tool_class, conf, params)
- 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,
PromptTool,SQLTool,RAGTool,HTTPToolundMCPTool. - 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.
- Werkzeugklasse: Wählen Sie die zu konfigurierende Werkzeugklasse aus. Die Dropdown-Liste wird aus den in
tool_implementation.pyregistrierten 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.jsondefiniert 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.jsongerendert.
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 responsetool_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.
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 inrequirements.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 Siepackage_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.
Hinweis:
Wenn Ihr Tool von Packages von Drittanbietern abhängt, die inrequirements.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.- 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.pygefundene Toolklasse wird mit ihrem Klassennamen, ihrer Beschreibung und ihrer Version aufgeführt.
- 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:
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.
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.
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.
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.
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:
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.
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={}
)- <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_AUTHoderBEARER_TOKEN. Im Fall vonBEARER_TOKENwird 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.
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 Ausgabe des Tools wird im rechten Fensterbereich angezeigt.
Die Registerkarte "Details" enthält Informationen zur Authentifizierungsmethode, zur MCP-Server-URL und zur Beschreibung.
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:
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.
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.
- • 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.
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/oWenn 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.
- 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-Anfragetool zu einem Agent 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.- Ziehen Sie ein HTTP-Request-Tool per Drag-and-Drop aus Toolvorlagen auf Ihre Leinwand.
- 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
- 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.
- 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.
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 18-1: 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.
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 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.
- 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:
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 18-2: 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-Entwickler 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.
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.
SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = 2025
ORDER BY customer_name {{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.
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.
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
{
"catalogKey": "construction_data",
"schemaKey": "admin",
"query": "SELECT project_id, project_name, client_name, ...",
"isRowLimitEnabled": null,
"maxRows": null
}
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.
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.
In der Dokumentation werden verschiedene Abfragemuster dargestellt und verschiedene Empfehlungen zu Abfrageparametern bereitgestellt.
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 18-3: SQL-Tool - Konfigurationseigenschaften
| 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 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:
Spark SQL und Delta Lake (Standardkatalog)
- 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.
- Klicken Sie auf den Connector-Handle auf Ihrem Agent, und ziehen Sie ihn, um eine Verbindung zum Toolknoten herzustellen.
- 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.
- 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.