> ## 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. # Invoke > Envía un mensaje a un agente con la API pública de Fetch Hive usando un ID de agente y un mensaje # 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`. ```bash theme={null} 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](#webhook-trigger). ## 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. ```bash theme={null} 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: ```json theme={null} [ "https://example.com/customer-brief.pdf", "https://uploads.fetchhive.com/uploads/grme67114iieusl54m3u4swipr3v" ] ``` También pueden usar esta forma de objeto cuando deseas 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 adjuntos por mensaje. Los adjuntos de documento se exponen al agente a través de la herramienta del sistema `read_file` como un manifiesto ``; 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: ```json theme={null} { "metadata": { "customer_id": "cus_123", "plan": "enterprise", "trial": false, "invoice_count": 12, "region": null } } ``` Inválido: ```json theme={null} { "metadata": { "customer": { "id": "cus_123" }, "tags": ["enterprise"] } } ``` El diálogo de fragmento de código usa esta forma de cuerpo: ```json theme={null} { "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: ```json theme={null} { "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): ```json theme={null} { "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: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "reasoning", "response": "Looking at the latest model releases..." } ``` Evento de respuesta de ejemplo: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "type": "response", "response": "Teams are standardizing around evals, routing, and observability.", "done": false } ``` Evento de herramienta de ejemplo: ```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 de ejemplo: ```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 de ejemplo: ```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 } ``` 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`. ```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" } ``` ## Ejemplo ```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" }, "streaming": true }' \ --compressed ``` ## Relacionado * Consulta [Autenticación](./authentication) para configurar la clave de API * Consulta [Agentes](../agents/overview) para la configuración del agente y el contexto de runtime * Consulta [Pruebas con Chat](../agents/testing-with-chat) para el flujo de pruebas dentro del editor * Consulta [Ejecutar con API](../agents/run-with-api) para una guía centrada en el agente