REST-API-Tools

Sinaptic® DROID+-Agenten können externe HTTP-Endpunkte als Tools aufrufen. Dies ermöglicht es Agenten, mit jeder REST-API zu interagieren — interne Dienste, Drittanbieter-APIs, Webhooks — ohne eigenen Code schreiben zu müssen.

Konfiguration

Fügen Sie REST-API-Tools direkt in der YAML-Konfiguration Ihres Agenten hinzu:

# configs/agents/my-agent.yaml
name: "my-agent"

tools:
  - name: "get-weather"
    type: "rest_api"
    description: "Aktuelles Wetter für eine Stadt abrufen"
    url: "https://api.weather.example.com/current?city=${city}"
    method: "GET"
    headers:
      Authorization: "Bearer ${WEATHER_API_KEY}"
    timeout: "10s"

  - name: "create-ticket"
    type: "rest_api"
    description: "Support-Ticket erstellen"
    url: "https://api.example.com/tickets"
    method: "POST"
    headers:
      Content-Type: "application/json"
      Authorization: "Bearer ${INTERNAL_API_KEY}"
    timeout: "15s"

Felder

Feld	Typ	Erforderlich	Beschreibung
name	string	ja	Tool-Identifikator (wird vom LLM verwendet)
type	string	ja	Muss rest_api sein
description	string	empfohlen	Beschreibung, die dem LLM angezeigt wird, um die Entscheidung zu erleichtern, wann dieses Tool verwendet werden soll
url	string	ja	Endpunkt-URL (unterstützt ${VAR} für Umgebungsvariablen)
method	string	ja	HTTP-Methode: GET, POST, PUT, DELETE
headers	map	nein	HTTP-Header, die in die Anfrage aufgenommen werden sollen
timeout	string	nein	Zeitüberschreitung der Anfrage (Standard: 30s)

Wie es funktioniert

1. Das LLM entscheidet basierend auf dem name und der description des Tools, ein REST-API-Tool aufzurufen.
2. Sinaptic® DROID+ führt die HTTP-Anfrage mit der konfigurierten Methode, URL, den Headern und einem eventuellen vom LLM bereitgestellten Body aus.
3. Die Antwort wird als Tool-Ergebnis an das LLM zurückgegeben.
4. Das LLM bindet das Ergebnis in seine Antwort an den Benutzer ein.

Sicherheit

• REST-API-Tools berücksichtigen die SinapticAI-Einstellungen des Agenten — Tool-Eingaben und -Ausgaben werden auf PII (personenbezogene Daten) und Injektionsversuche gescannt.
• Verwenden Sie Umgebungsvariablen (${VAR}) für API-Keys und Secrets in Headern — kodieren Sie diese niemals fest im Quelltext.
• Das Feld timeout verhindert, dass Tools bei langsamen Endpunkten unendlich lange hängen bleiben.

Beispiele

Aufruf eines internen Microservices

tools:
  - name: "lookup-order"
    type: "rest_api"
    description: "Bestellstatus anhand der Bestell-ID abfragen"
    url: "https://internal-api.example.com/orders/${order_id}"
    method: "GET"
    headers:
      X-Service-Token: "${INTERNAL_TOKEN}"
    timeout: "5s"

Senden eines Webhooks

tools:
  - name: "notify-slack"
    type: "rest_api"
    description: "Benachrichtigung an einen Slack-Kanal senden"
    url: "${SLACK_WEBHOOK_URL}"
    method: "POST"
    headers:
      Content-Type: "application/json"
    timeout: "10s"