Agent runs

Una agent run es una tarea autónoma: el modelo planifica, llama a herramientas (web, código, los datos del workspace, creación de archivos, un navegador real), verifica y entrega un resultado, transmitido paso a paso. A diferencia del chat, es dueña de la tarea de extremo a extremo.

Iniciar una run

POST/v1/workspaces/{workspace_id}/agent/runs —

inicia la run. La run está desacoplada de la conexión: este endpoint devuelve de inmediato un pequeño objeto JSON y el motor sigue trabajando de forma independiente. Sigue el stream en vivo con GET …/attach (más abajo).

Integración mínima: un solo campo. Envía únicamente {"task": "…"} y listo. La plataforma enruta automáticamente al mejor modelo, elige y llama a las herramientas adecuadas (búsqueda web, tu knowledge base, código, navegador…) y transmite el resultado de vuelta. Tú nunca conectas herramientas, modelos ni prompts; todos los demás campos del cuerpo son sobrescrituras opcionales para cuando quieres más control. Consulta el Cookbook para ejemplos listos para copiar.

POST devuelve {"run_id", "trace_id"}: el run id es todo lo que necesitas para seguir la run. Una desconexión del cliente nunca termina la run; la facturación, la persistencia y la respuesta final siempre se completan.

Obligatorio:

task: qué hacer, en lenguaje natural (hasta 20.000 caracteres). Es el único campo que debes enviar.

Opcional (todos tienen valores por defecto razonables; sobrescribe solo cuando lo necesites):

model: vacío deja que la plataforma elija un driver con capacidad de herramientas. Fíjalo solo para forzar uno concreto.
max_steps: límite de iteraciones de herramientas/pensamiento (1–50).
budget_usd: un techo de coste estricto (> 0, hasta 100).
pro: desbloquea un razonamiento más profundo y multihilo (sub-agents en paralelo en tareas complejas).
project_id: ejecuta con las instrucciones y archivos de un project inyectados como contexto.
conversation_id: encadena esta run bajo una conversación de chat existente (el resultado se escribe de vuelta en ese hilo). Omítelo para una tarea independiente.
skills: slugs de skills que el usuario eligió explícitamente (hasta 8); vacío ejecuta la línea base pura (las skills nunca se adjuntan automáticamente).
persona_slug: un role de especialista de la librería agency-agents; se inyecta como cabecera de identidad para esta run. Como máximo uno.
history: turnos recientes ({role, content}, donde role es user o assistant) para continuidad entre turnos. Se ignora cuando se establece conversation_id (el historial se reconstruye entonces en el servidor).
mode: sugerencia de carril del composer (auto deja que el router elija entre chat / agent / cowork / code). Solo se consulta cuando el router unificado está habilitado.
approval_mode: postura ante acciones peligrosas en la máquina local: ask (por defecto, pausa esperando el OK del usuario) o auto (ejecuta sin pausar).

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Compare the fee schedules of Wise and Airwallex; output a table.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

Seguir la run (Server-Sent Events)

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/attach —

sigue el stream de eventos de la run (text/event-stream). Cada frame es un objeto JSON en una línea data:.

Es reconexión-segura: la línea id: lleva un id de entrada del stream, por lo que EventSource rastrea lastEventId de forma nativa y lo reenvía como Last-Event-ID al reconectar. Un refrescado, un corte de WiFi o un segundo dispositivo abriendo la run se reanudan exactamente donde se quedó (el backlog se repite desde el último id visto). El generador se cierra tras el frame terminal de la run; los periodos de inactividad reciben un heartbeat : ping para que los proxies no corten la conexión.

Tipos de eventos type:

type	campos	cuándo
`step_start`	`step_no`	comenzó una iteración del bucle
`llm_delta`	`step_no`, `text`	texto del modelo en streaming
`reasoning` / `reasoning_delta`	`step_no`, `text`	la cadena de razonamiento del paso (completa al final del turno; los deltas la transmiten en vivo)
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	el modelo solicitó una herramienta (los deltas transmiten los argumentos)
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	una herramienta larga reporta progreso intermedio
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	una herramienta terminó (puede traer `artifacts`, `sources`, `screenshot_url`)
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	una acción local peligrosa está esperando (o recibió) una decisión del usuario
`step_end`	`step_no`, `cost_usd`	iteración finalizada
`context_compacted`	`step_no`, `summary`	turnos anteriores se resumieron para caber en la ventana de contexto
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	terminal: la respuesta final está en `final_text`
`error`	`message`	fallo terminal

Cada evento lleva también run_id (y step_no), de modo que un consumidor multiplexado puede enrutar frames sin estado por conexión. El stream termina con el frame terminal run_end (o error); no existe marcador [DONE].

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs/$RUN_ID/attach \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# id: 1719900000-0
# data: {"type":"step_start","run_id":"…","step_no":1}
# id: 1719900000-1
# data: {"type":"llm_delta","run_id":"…","step_no":1,"text":"…"}
# …
# data: {"type":"run_end","run_id":"…","status":"succeeded","final_text":"…",…}

Prefiere GET …/attach antes que repercutir el POST: es reanudable desde Last-Event-ID, así que los clientes que se reconectan nunca pierden frames. La run sigue adelante tanto si alguien está conectado como si no.

Gestionar runs

GET/v1/workspaces/{workspace_id}/agent/runs —

lista runs (query: limit, project_id, scheduled_only, include_archived).

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

obtiene una: estado, el final_text persistido, la trayectoria completa de steps, coste y artifacts producidos.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/cancel —

detiene una tarea en ejecución. Cooperativo y entre workers (pone un flag que el bucle comprueba en su próximo límite de paso); idempotente: cancelar una run finalizada es un no-op que devuelve su estado terminal.

PATCH/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

edita la entrada de recientes: title, archived, favorited, o muévela de project_id (un project_id nulo la saca del proyecto).

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

elimina una run del historial (sus pasos se eliminan en cascada). Cancela primero la run si está en ejecución.

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/artifacts.zip —

descarga todos los artifacts que produjo la run como un único .zip.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

crea / revoca un enlace público de solo lectura para repetir la run (body: expires_in_days opcional).

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/approvals/{approval_id} —

responde una aprobación de acción local peligrosa (body: {approved: true|false}), del tipo que presenta un evento approval_request.

Estado de la run

run_end.status (y GET …/runs/{run_id}) es uno de pending, running, succeeded, failed, cancelled o partial (la tarea terminó con un resultado parcial que sigue siendo útil). Los estados terminales son succeeded, failed, cancelled y partial.

Los archivos que el agent produce (documentos, hojas, diapositivas, gráficos, web apps) vuelven como artifacts asociados a la run. Una run está acotada tanto por budget_usd como por el saldo del workspace, así que nunca puede descontrolarse.