> ## Documentation Index > Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt > Use this file to discover all available pages before exploring further. # Ejecutar con API > Invoca un agente con la API pública usando tu clave de API del espacio de trabajo, un ID de agente y un mensaje # 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 ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` Consulta [Claves de API](../workspace/api-keys) 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: | 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: ```json theme={null} [ "https://example.com/customer-brief.pdf", "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v" ] ``` También pueden usar este formato de objeto cuando quieras proporcionar metadatos: ```json theme={null} { "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 ``; 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: ```json theme={null} { "agent": "AGENT_UUID", "message": "Your message here", "streaming": true, "metadata": { "customer_id": "cus_123", "plan": "enterprise" } } ``` ## Ejemplo básico ```bash theme={null} 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](../user-tracking/invoke-metadata) 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): ```json theme={null} { "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: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "reasoning", "response": "Looking at the latest model releases..." } ``` Evento de respuesta: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "response", "response": "Teams are standardizing around evals, routing, and observability.", "done": false } ``` Evento de herramienta: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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. ```bash theme={null} # 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. ```bash theme={null} 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 * [Registros](./logs) * [Pruebas con Chat](./testing-with-chat) * [Ejecutar con el SDK de Python](./run-with-python-sdk) * [Ejecutar con el SDK de Node.js](./run-with-nodejs-sdk) * [Ejecutar con el SDK de Ruby](./run-with-ruby-sdk) * [Ejecutar con el SDK de PHP](./run-with-php-sdk)