Saltar al contenido principal

​
Ejecutar con API

Usa el endpoint público de invocación de agentes cuando quieras enviar un mensaje a un agente desde tu propia aplicación o servicio. En Fetch Hive, puedes copiar el formato de la solicitud desde More -> Get Code en la barra lateral de agentes o desde Code Snippet en el editor del agente.

​
Autenticación

Authorization: Bearer YOUR_API_KEY
Consulta Claves de API para saber cómo crear y administrar claves.

​
Endpoint

POST https://api.fetchhive.com/v1/agent/invoke Si quieres que Fetch Hive genere el ejemplo cURL por ti, abre Agents y luego usa More -> Get Code. Si ya estás en el editor de un agente específico, haz clic en Code Snippet en su lugar.

​
Solicitud

Usa este formato de solicitud:
CampoTipoRequeridoDescripción
agentstringSíEl ID del agente
messagestringSíEl mensaje que quieres enviar al agente
streamingbooleanNoSi la respuesta debe transmitirse como eventos
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.
messagesarrayNoTurnos previos de la conversación proporcionados por quien llama. Se usan como contexto sin persistir en la base de datos. Cada elemento: { "content": string, "role": "user" | "assistant" | "system", "attachments"?: array, "image_urls"?: array }.
attachmentsarrayNoURLs HTTPS de archivos adjuntos al message actual. Cada elemento puede ser una cadena URL o un objeto con file_url. Los archivos de documentos admitidos son CSV, XLSX, PDF, DOCX y texto/Markdown por extensión. También se pueden pasar imágenes aquí.
image_urlsarrayNoVersión abreviada compatible con versiones anteriores para adjuntos de imagen HTTPS en el message actual. Úsala para integraciones solo de imágenes, especialmente cuando la URL de la imagen no tiene extensión.
metadataobjectNoMetadatos planos definidos por quien llama para auditoría y filtrado de registros. Esto no se agrega al prompt del agente.
metadata debe ser plano y solo escalar: cadenas, números, booleanos o null. Los objetos anidados y los arrays devuelven un error de validación antes de iniciar la ejecución. Los elementos de attachments pueden ser cadenas URL simples: 
[
  "https://example.com/customer-brief.pdf",
  "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v"
]
También pueden usar este formato de objeto cuando quieras 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 archivos adjuntos por mensaje, contando tanto attachments como image_urls. Los adjuntos de documentos se exponen al agente a través de la herramienta de sistema read_file como un manifiesto <available_files>; el agente llama a read_file antes de basarse en el contenido del documento. Si una URL o tipo de adjunto no es válido, Fetch Hive devuelve un error de validación 422 en lugar de abrir el stream. El error usa los campos estándar error_code, error y message; error y message se localizan según el idioma de la cuenta autenticada cuando está disponible. Adjuntos de documentos 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 Fetch Hive Media Library, 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. El fragmento dentro de la aplicación muestra el mismo formato del cuerpo: 
{
  "agent": "AGENT_UUID",
  "message": "Your message here",
  "streaming": true,
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise"
  }
}

​
Ejemplo básico

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"
    },
    "attachments": [
      "https://example.com/customer-brief.pdf"
    ],
    "streaming": true
  }' \
  --compressed
Esto coincide con el fragmento cURL que se muestra en el producto. El cuadro de diálogo de invocación muestra actualmente cURL, mientras que Python y TypeScript todavía aparecen como Coming Soon. Usa metadata para los campos de auditoría que quieras ver o filtrar en los registros, como IDs de clientes, nombres de planes, regiones o nombres de experimentos. Se almacena con la ejecución y se muestra en User metadata en los registros. Consulta Metadatos de invocación para ejemplos y detalles de filtrado de registros.

​
Respuesta

Si streaming es true, la ruta devuelve un stream de eventos en lugar de un único objeto JSON final. Si el proveedor falla después de que el stream se haya abierto, la ruta envía un evento error final antes de cerrar el stream.

​
Respuesta en streaming

El stream puede incluir un evento de resumen, fragmentos de razonamiento, fragmentos de respuesta, eventos de herramienta, un evento final de uso o un evento de error. Los eventos llegan en este orden cuando todos los eventos exitosos están presentes: summary → reasoning → response → tool → usage. Un evento error puede llegar en lugar de usage si el proveedor falla a mitad del stream. Evento de resumen (solo se emite en hilos con resumen automático habilitado): 
{
  "type": "summary",
  "summary_text": "The conversation covered AI infrastructure trends. The user asked about evals and tool routing...",
  "original_token_count": 15234,
  "context_limit": 200000,
  "model": "gpt-4.1",
  "provider": "openai"
}
Este evento se dispara al inicio del stream cuando el historial acumulado del hilo ha cruzado el umbral de resumen automático. Significa que la conversación previa se comprimió en un resumen antes de enviarse al modelo: el agente conserva el contexto, pero el historial sin procesar se ha condensado. original_token_count es el conteo de tokens antes de la compresión; context_limit es la ventana de contexto total del modelo. Puedes mostrarlo a los usuarios como un indicador de “conversación resumida” o ignorarlo: el comportamiento de tu aplicación no se ve afectado de ninguna manera. Evento de razonamiento: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "response": "Looking at the latest model releases..."
}
Evento de respuesta: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "response": "Teams are standardizing around evals, routing, and observability.",
  "done": false
}
Evento de herramienta: 
{
  "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: 
{
  "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: 
{
  "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
}

​
Respuesta sin streaming

Si streaming es false, la ruta devuelve una respuesta JSON con la salida generada, los datos de uso y el ID de solicitud que puedes usar para inspeccionar la ejecución en Logs. Las fallas de ejecución del proveedor devuelven 502 Bad Gateway con un mensaje error. El campo de salida exacto puede variar según el proveedor, pero la respuesta incluye los metadatos de ejecución que necesitas. Por ejemplo: 
{
  "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"
}
Si el agente usa herramientas, la respuesta sin streaming también puede incluir detalles de la ejecución de las herramientas.

​
Conversaciones de múltiples turnos

El endpoint de invocación admite dos enfoques para las conversaciones de múltiples turnos.

​
Hilos persistentes (Fetch Hive administra el historial)

Pasa un thread_id —cualquier cadena que elijas— y Fetch Hive creará automáticamente el hilo en la primera llamada y lo reanudará en cada llamada posterior con el mismo valor. El historial de mensajes se almacena en Fetch Hive y se incluye en el contexto automáticamente. 
# First turn
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "What are the main AI infrastructure trends right now?",
    "streaming": true,
    "thread_id": "user-456-support-session"
  }'

# Second turn — same thread_id resumes the conversation
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Which of those trends have the most enterprise adoption?",
    "streaming": true,
    "thread_id": "user-456-support-session"
  }'
Puedes usar cualquier cadena como thread_id: un ID de usuario, ID de sesión, número de ticket o cualquier otro identificador que tenga sentido para tu caso de uso.

​
Historial sin estado (el llamador administra el historial)

Si prefieres administrar el estado de la conversación tú mismo, pasa los turnos previos en el array messages. Fetch Hive usa el historial proporcionado como contexto, pero no lo persiste. 
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Which of those trends have the most enterprise adoption?",
    "streaming": true,
    "messages": [
      {
        "content": "What are the main AI infrastructure trends right now?",
        "role": "user",
        "attachments": [
          {
            "file_url": "https://example.com/market-data.csv",
            "file_name": "market-data.csv",
            "file_type": "text/csv"
          }
        ]
      },
      { "content": "Teams are focusing on evals, tool routing, and observability.", "role": "assistant" }
    ]
  }'
Si un turno anterior del asistente generó un archivo, pásalo de vuelta en el mensaje histórico correspondiente a través de messages[].attachments. Fetch Hive usa las URLs estructuradas de adjuntos en los mensajes actuales e históricos para adjuntar la herramienta read_file orientada al proveedor y autorizar el acceso para turnos posteriores; las URLs mencionadas solo en texto plano no se tratan como adjuntos de la herramienta de archivos. Usa messages cuando ya mantengas tu propio estado de chat y no necesites que Fetch Hive almacene el historial de la conversación.

​
Próximos pasos