Saltar al contenido principal

​
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.
CampoTipoRequeridoDescripción
agentstringSíEl ID del agente
messagestringSíEl mensaje que deseas enviar
streamingbooleanNoTransmite eventos de respuesta en lugar de esperar una única respuesta JSON final
thread_idstringNoUna 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.
messagesarrayNoTurnos 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, "image_urls"?: array }. Úsalo cuando administres el estado de la conversación por tu cuenta.
attachmentsarrayNoURLs 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í.
image_urlsarrayNoForma abreviada compatible con versiones anteriores para adjuntos de imagen HTTPS en el message actual. Úsalo para integraciones solo de imagen, especialmente cuando la URL de la imagen no tiene extensión.
metadataobjectNoMetadatos 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, contando tanto attachments como image_urls. 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. 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
    },
    "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
    },
    "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