Invocar agente

POST /v1/agent/invoke Envía un mensaje a un agente desde tu propia app o servicio.

Autenticación

Envía tu clave de API del espacio de trabajo en el encabezado Authorization.

Authorization: Bearer YOUR_API_KEY

Los disparadores webhook de agente usan el secreto webhook del agente en lugar de una clave de API. Consulta Disparador webhook.

Cuerpo de la solicitud

Abre un agente en el editor y haz clic en Code Snippet para ver la forma actual de la solicitud pública en Fetch Hive.

Disparador webhook

POST /v1/agent/webhooks/{agent_id} Usa un disparador webhook de agente cuando un servicio externo deba iniciar la ejecución de un agente sin una clave de API del espacio de trabajo. La solicitud debe incluir el secreto webhook del agente en X-Fetch-Hive-Webhook-Secret. Si una herramienta de terceros no puede establecer encabezados personalizados, usa ?secret=YOUR_WEBHOOK_SECRET como alternativa. Los disparadores webhook de agente siempre usan entrega por callback. Incluye async.callback_url; Fetch Hive devuelve 202 con request_id y run_status: "running", y luego entrega agent.completed o agent.failed a la URL de callback.

curl 'https://api.fetchhive.com/v1/agent/webhooks/YOUR_AGENT_ID' \
  -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "message": "Summarize the latest ticket",
    "thread_id": "external-thread-123",
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "user": "external-user-1",
    "async": {
      "callback_url": "https://example.com/callback"
    }
  }'

message es obligatorio. thread_id es opcional y puede reutilizarse para reanudar un hilo administrado por el llamador. metadata sigue la misma regla plana de solo escalares que las invocaciones normales de agente y aparece en el filtrado de registros. Fetch Hive firma el callback saliente con el mismo secreto webhook usado para la autenticación del disparador entrante. El data del callback contiene response en agent.completed y error en agent.failed; usa el event_type y el request_id de nivel superior para el estado terminal y la correlación.

Campo	Tipo	Requerido	Descripción
`agent`	string	Sí	El ID del agente
`message`	string	Sí	El mensaje que deseas enviar
`streaming`	boolean	No	Transmite eventos de respuesta en lugar de esperar una única respuesta JSON final
`thread_id`	string	No	Una cadena arbitraria que identifica el hilo de conversación. Fetch Hive crea un nuevo hilo en el primer uso y lo reanuda en llamadas posteriores con el mismo valor. Ideal para conversaciones persistentes de múltiples turnos.
`messages`	array	No	Turnos previos de la conversación para usar como contexto sin persistir el historial en la base de datos. Cada elemento: `{ "content": string, "role": "user" \| "assistant" \| "system", "attachments"?: array }`. Úsalo cuando administres el estado de la conversación por tu cuenta.
`attachments`	array	No	URLs HTTPS de archivos adjuntos al `message` actual. Cada elemento puede ser una cadena de URL o un objeto con `file_url`. Los archivos de documento admitidos son CSV, XLSX, PDF, DOCX y texto/Markdown por extensión. Las imágenes también pueden pasarse aquí.
`metadata`	object	No	Metadatos planos definidos por el llamador para auditoría y filtrado de registros. Esto no se agrega al prompt del agente.

metadata debe ser un objeto plano. Las claves deben ser cadenas no vacías y los valores deben ser cadenas, números, booleanos o null. Los arreglos y objetos anidados se rechazan antes de iniciar la ejecución. Los elementos de attachments pueden ser cadenas de URL simples:

[
  "https://example.com/customer-brief.pdf",
  "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v"
]

También pueden usar esta forma de objeto cuando deseas proporcionar metadatos:

{
  "file_url": "https://example.com/customer-brief.pdf",
  "file_name": "customer-brief.pdf",
  "file_type": "application/pdf"
}

Solo se aceptan URLs https://. Se permiten hasta cinco adjuntos por mensaje. Los adjuntos de documento se exponen al agente a través de la herramienta del sistema read_file como un manifiesto <available_files>; el agente llama a read_file antes de confiar en el contenido del documento. Si una URL o tipo de adjunto es inválido, Fetch Hive devuelve 422 Unprocessable Entity en lugar de abrir el flujo. Adjuntos de documento admitidos:

CSV: text/csv, .csv
XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, .xlsx
PDF: application/pdf, .pdf
DOCX: application/vnd.openxmlformats-officedocument.wordprocessingml.document, .docx
Texto y Markdown por extensión: .txt, .md, .markdown

Para URLs sin extensión, como las URLs de la Biblioteca de Medios de Fetch Hive, pasa la URL directamente. Fetch Hive incluye la URL en la lista de permitidos para read_file, y la herramienta de archivos detecta el tipo real cuando obtiene el archivo. Válido:

{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}

Inválido:

{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}

El diálogo de fragmento de código usa esta forma de cuerpo:

{
  "agent": "AGENT_UUID",
  "message": "Your message here",
  "streaming": true,
  "attachments": [
    "https://example.com/customer-brief.pdf"
  ],
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise"
  }
}

Cuando uses thread_id para conversaciones persistentes:

{
  "agent": "AGENT_UUID",
  "message": "What did we discuss last time?",
  "streaming": true,
  "thread_id": "user-456-support-session"
}

Cuando uses messages para historial administrado por el llamador (sin estado):

{
  "agent": "AGENT_UUID",
  "message": "What else should I know?",
  "streaming": true,
  "messages": [
    {
      "content": "What are the latest AI trends?",
      "role": "user",
      "attachments": [
        "https://example.com/market-data.csv"
      ]
    },
    { "content": "Teams are focusing on evals, routing, and observability.", "role": "assistant" }
  ]
}

Si un turno previo del asistente generó un archivo, pasa ese archivo de vuelta en el mensaje del historial correspondiente a través de messages[].attachments. Fetch Hive usa las URLs de adjuntos estructurados en los mensajes actuales e históricos para autorizar el acceso de read_file en turnos posteriores; las URLs mencionadas solo en texto plano no se tratan como adjuntos de la herramienta de archivos.

Respuesta

Si streaming es true, Fetch Hive devuelve un flujo de eventos. Si el proveedor falla después de que se haya abierto el flujo, Fetch Hive envía un evento error final antes de cerrar el flujo. Si el cliente se desconecta primero, Fetch Hive lo trata como una cancelación silenciosa y no crea una ejecución fallida del agente, no factura uso ni reporta un evento de error del proveedor, salvo que el proveedor ya haya completado y confirmado el uso. Evento de razonamiento de ejemplo:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "response": "Looking at the latest model releases..."
}

Evento de respuesta de ejemplo:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "response": "Teams are standardizing around evals, routing, and observability.",
  "done": false
}

Evento de herramienta de ejemplo:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "tool",
  "tool_id": "tool_123",
  "tool": "google_search",
  "tool_input": {
    "query": "latest AI infrastructure trends 2026"
  },
  "observation": {
    "results": []
  }
}

Evento final de uso de ejemplo:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "input_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0,
      "cached_read_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}

Evento de error de ejemplo:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "error",
  "id": "msg_019d52846ea37682b03522fd0695cc43",
  "error": "openai provider stream error: HTTP 400: invalid request",
  "message": "openai provider stream error: HTTP 400: invalid request",
  "provider": "openai",
  "error_type": "provider_stream_error",
  "status_code": 502
}

Si streaming es false, Fetch Hive devuelve una sola respuesta JSON. Los fallos de ejecución del proveedor devuelven 502 Bad Gateway con un mensaje error.

{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "response": "Teams are moving from simple wrappers to systems with evals, tool routing, and tighter cost controls.",
  "reasoning": "The request asks for a short summary of current infrastructure trends.",
  "usage": {
    "input_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0,
      "cached_read_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}

Ejemplo

curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Summarize the latest AI infrastructure trends",
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "streaming": true
  }' \
  --compressed

Relacionado

Consulta Autenticación para configurar la clave de API
Consulta Agentes para la configuración del agente y el contexto de runtime
Consulta Pruebas con Chat para el flujo de pruebas dentro del editor
Consulta Ejecutar con API para una guía centrada en el agente

Fetch Hive API

REST API

Invoke

Invocar agente

Autenticación

Cuerpo de la solicitud

Disparador webhook

Respuesta

Ejemplo

Relacionado

​Invocar agente

​Autenticación

​Cuerpo de la solicitud

​Disparador webhook

​Respuesta

​Ejemplo

​Relacionado

Invocar agente

Autenticación

Cuerpo de la solicitud

Disparador webhook

Respuesta

Ejemplo

Relacionado