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, agent.failed o agent.awaiting_approval 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. Añade response_format al cuerpo del webhook para recibir JSON. Es el mismo objeto que el campo de Salida JSON en invoke y se aplica solo a esta llamada. Si lo omites, el callback contiene texto.

{
  "message": "List three competitors",
  "async": { "callback_url": "https://example.com/callback" },
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "competitors",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "competitors": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["competitors"],
        "additionalProperties": false
      }
    }
  }
}

agent.completed mantiene data.response como el texto JSON y añade data.output_json, el objeto ya interpretado. output_json no se envía en agent.awaiting_approval ni en agent.failed.

{
  "event_type": "agent.completed",
  "request_id": "req_123",
  "data": {
    "response": "{\"competitors\":[\"Acme\",\"Globex\",\"Initech\"]}",
    "output_json": { "competitors": ["Acme", "Globex", "Initech"] }
  }
}

Si el esquema no es válido, el modelo no puede devolver JSON Schema, o la respuesta sigue sin coincidir tras un reintento, la ejecución falla y Fetch Hive entrega agent.failed con el error en data.error. 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. agent.awaiting_approval incluye pending_tool_approvals y un review_url del panel. Un agent.completed posterior incluye resumed_from_run_id cuando la ejecución continuó tras la aprobación. Consulta Aprobaciones de herramientas.

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.
`decided_tool_approvals`	array	No	Ids de aprobación de una respuesta anterior `awaiting_approval`. Cada elemento es `{ "approval_id": string }`. Las llamadas con clave de API se reanudan en el servidor; no envíes este campo. Un cliente de streaming de primera parte vuelve a invocar el mismo `thread_id`. Consulta Aprobaciones de herramientas.
`tool_approval`	string	No	`policy` o `auto_approve`. Omítelo, o envía `policy`, para seguir las reglas del workspace y cualquier interruptor de aprobación automática guardado. `auto_approve` se aplica solo a esta llamada cuando la clave de API tiene permiso para aprobar acciones automáticamente. Cualquier otro valor devuelve `400` `invalid_tool_approval` antes de que empiece la ejecución.
`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.
`async`	object	No	Opciones de flujo en segundo plano. `callback_url` recibe el evento firmado `agent.delegation.completed`. `allow_background` es true por defecto si hay `thread_id` o `callback_url`; si no, es false.

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://example.com/customer-brief.pdf"
]

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. 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.

Aprobación automática para una llamada

tool_approval: "auto_approve" solo se acepta desde una clave de API cuyo propietario o administrador activó “Permitir que esta clave apruebe acciones automáticamente” en Configuración → Claves de API. La llamada no cambia el ajuste guardado del agente ni escribe una política. Una clave sin ese permiso, un token del editor con sesión iniciada y un webhook devuelven 403 antes de cualquier llamada al modelo, comprobación previa o facturación:

{
  "error_code": "tool_approval_override_not_permitted",
  "error": "This API key is not allowed to auto-approve actions. A workspace owner or admin can enable it in Settings → API keys.",
  "message": "This API key is not allowed to auto-approve actions. A workspace owner or admin can enable it in Settings → API keys."
}

Cuando la aprobación automática está desactivada para el workspace, se devuelve el mismo error_code con el mensaje Auto-approve is not available for this workspace. Las acciones destructivas siguen pidiendo aprobación. Las reglas de denegación siguen bloqueando la acción. Un subagente iniciado por esta llamada recibe el mismo tool_approval y la misma clave de API. Un flujo de trabajo que inicia el agente no lo recibe. Una respuesta correcta repite tool_approval como auto_approve o policy. Cuando una acción se ejecutó por una excepción, el cuerpo también incluye auto_approved_tool_calls: [{ "summary": string, "tool_name": string }]. Una llamada con streaming pone ambos campos en el evento usage final.

Salida JSON

response_format pertenece a esta llamada. Si lo omites, el agente devuelve texto. Si envías un esquema, el mismo agente devuelve JSON.

{
  "agent": "YOUR_AGENT_ID",
  "message": "Lista tres competidores",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "competitors",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "competitors": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["competitors"],
        "additionalProperties": false
      }
    }
  }
}

type es json_schema o text. La raíz del esquema debe ser un objeto. El documento no puede superar 100000 bytes. Si strict se omite o es true, cada objeto queda con additionalProperties: false. strict: false deja el esquema tal como lo enviaste. Los clientes anteriores pueden enviar is_json_schema_response_format: true y json_schema. Si llegan ambas formas, gana response_format. Un modelo que no admite JSON Schema responde 422 json_schema_unsupported antes de empezar. Un esquema que no es un objeto, o que supera 100000 bytes, responde 422 json_schema_invalid. El esquema se aplica a la respuesta final. Las herramientas siguen ejecutándose. Si la respuesta no coincide, Fetch Hive pide la respuesta una vez más. Un segundo fallo responde 422 json_schema_output_invalid. El mensaje guardado en el hilo es el texto JSON. Una respuesta sin streaming mantiene response como ese texto y añade output_json, el objeto analizado. Una llamada en streaming sigue enviando deltas de texto. El evento final usage incluye output_json. Usa output_json si una reparación cambió el texto después de esos deltas. response_format también funciona en los disparadores webhook de agente. El callback incluye entonces output_json en agent.completed.

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:

{
  "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,
      "cached_read_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed",
  "status": "completed",
  "run_id": "req_019d52846ea37682b03522fd0695cc43",
  "thread_id": null
}

Evento de aprobación de herramienta:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "tool_approval",
  "approval": {
    "type": "tool_approval",
    "approval_id": "0b6c8f0e-0000-4000-8000-000000000001",
    "summary": "Send a Slack message to #general",
    "expires_at": "2026-10-07T01:00:00Z",
    "tool_name": "SLACK_SEND_MESSAGE",
    "status": "pending"
  },
  "done": false
}

Evento final de uso mientras espera una aprobación:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "stop_reason": "completed",
  "status": "awaiting_approval",
  "run_id": "req_019d52846ea37682b03522fd0695cc43",
  "thread_id": "ticket-42",
  "pending_tool_approvals": [
    {
      "approval_id": "0b6c8f0e-0000-4000-8000-000000000001",
      "tool_name": "SLACK_SEND_MESSAGE",
      "summary": "Send a Slack message to #general",
      "arguments": { "channel": "#general", "text": "hello" },
      "expires_at": "2026-10-07T01:00:00Z",
      "review_url": "https://app.fetchhive.com/WORKSPACE_ID/approvals?approval=0b6c8f0e-0000-4000-8000-000000000001"
    }
  ]
}

status y run_id siempre están presentes. thread_id es el valor que enviaste, o null. pending_tool_approvals solo está presente cuando status es awaiting_approval. denied_tool_calls solo está presente cuando una política denegó una llamada en el turno. stop_reason conserva el valor del proveedor. Consulta Aprobaciones de herramientas. 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,
      "cached_read_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed",
  "status": "completed",
  "run_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "thread_id": null
}

Una respuesta sin streaming en pausa usa la misma forma de pending_tool_approvals que el evento de uso de arriba, y el texto de response incluye [Waiting for approval: …].

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

Fetch Hive API

REST API

Invoke

Invocar agente

Autenticación

Cuerpo de la solicitud

Disparador webhook

Aprobación automática para una llamada

Salida JSON

Respuesta

Ejemplo

Relacionado

​Invocar agente

​Autenticación

​Cuerpo de la solicitud

​Disparador webhook

​Aprobación automática para una llamada

​Salida JSON

​Respuesta

​Ejemplo

​Relacionado

Invocar agente

Autenticación

Cuerpo de la solicitud

Disparador webhook

Aprobación automática para una llamada

Salida JSON

Respuesta

Ejemplo

Relacionado