Herramientas de API REST

Los agentes de Sinaptic® DROID+ pueden llamar a endpoints HTTP externos como herramientas. Esto permite que los agentes interactúen con cualquier API REST (servicios internos, API de terceros, webhooks) sin necesidad de escribir código personalizado.

Configuración

Añada herramientas de API REST directamente en la configuración YAML de su agente:

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

tools:
  - name: "get-weather"
    type: "rest_api"
    description: "Obtener el clima actual para una ciudad"
    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: "Crear un ticket de soporte"
    url: "https://api.example.com/tickets"
    method: "POST"
    headers:
      Content-Type: "application/json"
      Authorization: "Bearer ${INTERNAL_API_KEY}"
    timeout: "15s"

Campos

Campo	Tipo	Requerido	Descripción
name	string	sí	Identificador de la herramienta (utilizado por el LLM)
type	string	sí	Debe ser rest_api
description	string	recomendado	Descripción que se muestra al LLM para ayudarlo a decidir cuándo usar esta herramienta
url	string	sí	URL del endpoint (admite ${VAR} para variables de entorno)
method	string	sí	Método HTTP: GET, POST, PUT, DELETE
headers	map	no	Cabeceras HTTP a incluir en la solicitud
timeout	string	no	Tiempo de espera de la solicitud (por defecto: 30s)

Cómo funciona

1. El LLM decide llamar a una herramienta de API REST basándose en el name y la description de la herramienta.
2. Sinaptic® DROID+ realiza la solicitud HTTP con el método, la URL, las cabeceras configuradas y cualquier cuerpo proporcionado por el LLM.
3. La respuesta se devuelve al LLM como resultado de la herramienta.
4. El LLM incorpora el resultado en su respuesta al usuario.

Seguridad

• Las herramientas de API REST respetan la configuración de SinapticAI del agente: las entradas y salidas de las herramientas se analizan en busca de PII (información de identificación personal) e intentos de inyección.
• Utilice variables de entorno (${VAR}) para las claves API y secretos en las cabeceras; nunca los escriba directamente en el código.
• El campo timeout evita que las herramientas se queden colgadas indefinidamente en endpoints lentos.

Ejemplos

Llamar a un microservicio interno

tools:
  - name: "lookup-order"
    type: "rest_api"
    description: "Consultar el estado del pedido por ID de pedido"
    url: "https://internal-api.example.com/orders/${order_id}"
    method: "GET"
    headers:
      X-Service-Token: "${INTERNAL_TOKEN}"
    timeout: "5s"

Enviar un webhook

tools:
  - name: "notify-slack"
    type: "rest_api"
    description: "Enviar una notificación a un canal de Slack"
    url: "${SLACK_WEBHOOK_URL}"
    method: "POST"
    headers:
      Content-Type: "application/json"
    timeout: "10s"