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 Get Code en la barra de control del 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 Get Code en la barra de control del editor.

Solicitud

Usa este formato de solicitud:

Campo	Tipo	Requerido	Descripción
`agent`	string	Sí	El ID del agente
`message`	string	Sí	El mensaje que quieres enviar al agente
`streaming`	boolean	No	Si la respuesta debe transmitirse como eventos
`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.
`messages`	array	No	Turnos 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 }`.
`attachments`	array	No	URLs 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í.
`metadata`	object	No	Metadatos 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. 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. 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.

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,
      "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:

{
  "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,
      "cached_read_tokens": 0,
      "cache_write_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

Referencias de artefactos

En sesiones administradas por el cliente, envía hasta 50 UUID de Assets de la cuenta o espacio de trabajo en known_artifact_refs. Coloca los seleccionados para el turno actual en artifact_refs; attachments más artifact_refs admite un máximo de cinco elementos. Cada referencia activa también debe aparecer en known_artifact_refs. Los hilos persistentes obtienen los artefactos del chat guardado. Las URL externas de documentos e imágenes siguen usando attachments; el audio externo no es compatible. El streaming puede emitir eventos artifact y las respuestas no streaming incluyen artifacts.

Primeros pasos

Live Chat

Prompts

Flujos de trabajo

Hive Agents

Agentes

Bases de conocimientos

Experimentos

Tu espacio de trabajo

Monitoreo

Seguimiento de usuarios

Recursos

Ejecutar con API

Ejecutar con API

Autenticación

Endpoint

Solicitud

Ejemplo básico

Respuesta

Respuesta en streaming

Respuesta sin streaming

Conversaciones de múltiples turnos

Hilos persistentes (Fetch Hive administra el historial)

Historial sin estado (el llamador administra el historial)

Próximos pasos

Referencias de artefactos

​Ejecutar con API

​Autenticación

​Endpoint

​Solicitud

​Ejemplo básico

​Respuesta

​Respuesta en streaming

​Respuesta sin streaming

​Conversaciones de múltiples turnos

​Hilos persistentes (Fetch Hive administra el historial)

​Historial sin estado (el llamador administra el historial)

​Próximos pasos

​Referencias de artefactos

Ejecutar con API

Autenticación

Endpoint

Solicitud

Ejemplo básico

Respuesta

Respuesta en streaming

Respuesta sin streaming

Conversaciones de múltiples turnos

Hilos persistentes (Fetch Hive administra el historial)

Historial sin estado (el llamador administra el historial)

Próximos pasos

Referencias de artefactos