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

# Invocar desde codigo

> Inicia ejecuciones de Hive Agent desde la API publica con entrega por callback

Usa la API publica cuando tu app necesite iniciar una ejecucion de Hive Agent fuera del dashboard. La API inicia la ejecucion de forma asincrona, devuelve identificadores de inmediato y envia un callback firmado cuando finaliza.

La invocacion de Hive Agent no transmite eventos y no espera la respuesta final en la respuesta HTTP. Abre [Registros](./logs) para revisar estado, traza, costes, salida de nodos, resultados parciales, intentos de callback y respuesta final.

## Endpoint

```http theme={null}
POST /v1/stream/hive_agent/invoke
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Cuerpo de la solicitud

```json theme={null}
{
  "hive_agent": "agent_task_uuid",
  "objective": "Research competitors and summarize verified findings",
  "sources": {
    "website_urls": [],
    "asset_ids": [],
    "knowledge_base_ids": [],
    "knowledge_base_item_ids": []
  },
  "metadata": {},
  "async": {
    "enabled": true,
    "callback_url": "https://example.com/hive-agent-callback"
  }
}
```

`hive_agent` es el ID del Hive Agent en el dashboard. La API key debe pertenecer al mismo workspace que el Hive Agent. Solo se pueden invocar por este endpoint los Hive Agents creados por el cliente en tu workspace.

`objective` debe ser lo bastante especifico para que el planificador cree nodos de trabajo utiles.

`sources` es opcional, pero se recomienda cuando la ejecucion necesita contexto fundamentado. Pasa URLs de sitios, IDs de assets, IDs de knowledge bases o IDs de items de knowledge base que ya existan en el workspace.

Usa `GET /v1/public/workspaces/{workspace_id}/knowledge_bases` para listar knowledge bases, `GET /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items` para listar items y `GET /v1/public/workspaces/{workspace_id}/assets` para listar assets. Sube un archivo con `POST /v1/public/workspaces/{workspace_id}/assets` antes de pasar su `asset.id` en `sources.asset_ids`.

`metadata` es opcional y sirve para tu propia correlacion, como un customer ID o job ID.

`async.callback_url` es obligatorio. Fetch Hive envia el callback terminal a esta URL HTTPS cuando la ejecucion se completa, falla o se cancela. `async.enabled` debe ser `true`.

## Respuesta

Fetch Hive devuelve `202 Accepted` cuando la ejecucion queda en cola para ejecutarse.

```json theme={null}
{
  "run_id": "agent_task_run_uuid",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "status": "pending",
  "webhook_secret": "whsec_..."
}
```

Guarda `request_id` si necesitas encontrar la ejecucion luego en logs. Guarda `webhook_secret` para que tu receptor pueda verificar `X-Fetch-Hive-Signature`. El estado inicial normalmente es `pending`; el runtime actualiza el estado mientras prepara fuentes, planifica, ejecuta, verifica y compone.

## Ejemplo cURL

```bash theme={null}
curl https://api.fetchhive.com/v1/stream/hive_agent/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hive_agent": "agent_task_uuid",
    "objective": "Research competitors and summarize verified findings",
    "sources": {
      "website_urls": ["https://example.com"],
      "asset_ids": [],
      "knowledge_base_ids": [],
      "knowledge_base_item_ids": []
    },
    "metadata": {
      "customer_id": "cus_123"
    },
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/hive-agent-callback"
    }
  }'
```

## Payload del callback

Fetch Hive envia un payload JSON firmado a `async.callback_url` cuando la ejecucion llega a un estado terminal. `event_type` es `hive_agent.completed`, `hive_agent.failed` o `hive_agent.cancelled`.

```json theme={null}
{
  "event_type": "hive_agent.completed",
  "request_id": "req_018c9f8ea1b2c3d4e5f6g7h8i9j0k1l2",
  "data": {
    "run_id": "agent_task_run_uuid",
    "hive_agent_id": "agent_task_uuid",
    "hive_agent_name": "Competitor Research",
    "status": "completed",
    "success": true,
    "objective": "Research competitors and summarize verified findings",
    "final_response": {},
    "error_message": null,
    "metadata": {
      "customer_id": "cus_123"
    },
    "sources": []
  }
}
```

Los callbacks usan los mismos headers de firma que otros webhooks salientes de Fetch Hive: `X-Fetch-Hive-Signature`, `X-Fetch-Hive-Timestamp` y `X-Fetch-Hive-Webhook-Id`. Consulta [Callback Delivery and Webhook Triggers](../workflows/async-and-webhooks) para la verificacion.

## Encontrar resultados

Abre **Hive Agents** > **Logs** y busca por nombre de Hive Agent, objetivo, estado o request ID. Abre la ejecucion para revisar trabajo de nodos, feedback del verificador, manejo de fuentes, eventos de presupuesto, spans de traza y respuesta final.

El detalle de la ejecucion tambien muestra intentos de callback y estado de reintento. En esta version no hay espera sincrona ni opcion de streaming para la invocacion publica de Hive Agents.