Narzędzia REST API

Agenci Sinaptic® DROID+ mogą wywoływać zewnętrzne punkty końcowe HTTP jako narzędzia. Pozwala to agentom na interakcję z dowolnym interfejsem REST API — usługami wewnętrznymi, zewnętrznymi API firm trzecich, webhookami — bez konieczności pisania własnego kodu.

Konfiguracja

Dodaj narzędzia REST API bezpośrednio w konfiguracji YAML swojego agenta:

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

tools:
  - name: "get-weather"
    type: "rest_api"
    description: "Pobierz aktualną pogodę dla miasta"
    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: "Utwórz zgłoszenie do pomocy technicznej"
    url: "https://api.example.com/tickets"
    method: "POST"
    headers:
      Content-Type: "application/json"
      Authorization: "Bearer ${INTERNAL_API_KEY}"
    timeout: "15s"

Pola

Pole	Typ	Wymagane	Opis
name	string	tak	Identyfikator narzędzia (używany przez model LLM)
type	string	tak	Musi być rest_api
description	string	zalecane	Opis widoczny dla modelu LLM, pomagający mu zdecydować, kiedy użyć tego narzędzia
url	string	tak	URL punktu końcowego (obsługuje ${VAR} dla zmiennych środowiskowych)
method	string	tak	Metoda HTTP: GET, POST, PUT, DELETE
headers	map	nie	Nagłówki HTTP do dołączenia do żądania
timeout	string	nie	Przekroczenie czasu żądania (domyślnie: 30s)

Jak to działa

1. Model LLM decyduje o wywołaniu narzędzia REST API na podstawie jego name i description.
2. Sinaptic® DROID+ wykonuje żądanie HTTP przy użyciu skonfigurowanej metody, adresu URL, nagłówków i ewentualnego body dostarczonego przez model LLM.
3. Odpowiedź jest zwracana do modelu LLM jako wynik działania narzędzia.
4. Model LLM włącza wynik do swojej odpowiedzi udzielanej użytkownikowi.

Bezpieczeństwo

• Narzędzia REST API respektują ustawienia SinapticAI agenta — dane wejściowe i wyjściowe narzędzi są skanowane pod kątem PII (danych osobowych) oraz prób wstrzyknięcia kodu (injection).
• Używaj zmiennych środowiskowych (${VAR}) dla kluczy API i sekretów w nagłówkach — nigdy nie wpisuj ich bezpośrednio w kodzie.
• Pole timeout zapobiega nieskończonemu zawieszaniu się narzędzi na powolnych punktach końcowych.

Przykłady

Wywoływanie wewnętrznego mikrousługi

tools:
  - name: "lookup-order"
    type: "rest_api"
    description: "Sprawdź status zamówienia na podstawie identyfikatora zamówienia"
    url: "https://internal-api.example.com/orders/${order_id}"
    method: "GET"
    headers:
      X-Service-Token: "${INTERNAL_TOKEN}"
    timeout: "5s"

Wysyłanie webhooka

tools:
  - name: "notify-slack"
    type: "rest_api"
    description: "Wyślij powiadomienie do kanału Slack"
    url: "${SLACK_WEBHOOK_URL}"
    method: "POST"
    headers:
      Content-Type: "application/json"
    timeout: "10s"