Referencia de la API

Referencia de la API de Kova

API REST completa construida sobre Axum, más de 35 endpoints, formato JSON unificado —— cubre Agent, tareas, Workflow, Swarm, WAL y administración del sistema.

35+Endpoints REST

AxumRuntime

JSONFormato unificado

SSEFlujo de eventos en tiempo real

Base URLBase URLLa dirección raíz de la API. La Base URL de Lurus es https://hub.lurus.cn/v1.

http://localhost:3000/api/v1

Autenticación

Todas las solicitudes pasan la API key mediante el header X-API-Key obligatorio:

X-API-Key: sk-kova-<64位十六进制>

Formato de la key: ^sk-kova-[a-f0-9]{64}$, generada por create-tester.sh, almacenada en testers/<NAME>/.env (chmod 600).

Límite de tasa

Ventana de idempotencia

POST /agents/:id/run reenviar el mismo agent dentro de 15 s devuelve 409 Conflict.

Límite de contrapresión

Cuando la cola de dispatch alcanza el 80 % devuelve 429 Too Many Requests (con Retry-After: 5).

---

Administración de Agent

POST/api/v1/agentsCrear Agent

GET/api/v1/agentsListar Agent (admite status / limit / offset)

GET/api/v1/agents/:idObtener detalles del Agent

PUT/api/v1/agents/:idActualizar Agent

DELETE/api/v1/agents/:idEliminar Agent

Cuerpo de la solicitud de creación:

{ "name": "researcher", "system_prompt": "你是一个专业的研究员...", "model": "deepseek-chat",
  "tools": ["web_search", "file_write"],
  "config": { "max_tokens": 4096, "temperature": 0.7, "max_iterations": 20 } }

Respuesta (201): { "id": "agt_a1b2c3d4", "name": "researcher", "status": "idle", "created_at": "2026-03-17T10:00:00Z" }

Al listar se pueden usar los parámetros de query GET /api/v1/agents?status=idle&limit=20&offset=0.

WARNING

Solo se pueden eliminar Agent en estado idle o completed. Los que están en ejecución deben detenerse primero.

---

Ejecución de tareas

POST/api/v1/agents/:id/runDisparar la ejecución de una tarea por el Agent

GET/api/v1/eventsFlujo de eventos SSE (envía en tiempo real todos los eventos de los agent)

POST/api/v1/tasks/:id/stopDetener tarea

GET/api/v1/tasksListar tareas (admite agent_id / status / limit)

Cuerpo de la solicitud para disparar la ejecución:

{ "message": "研究 WebAssembly 在服务端的最新发展",
  "context": { "output_format": "markdown", "max_length": 2000 } }

Respuesta (200): { "task_id": "tsk_e5f6g7h8", "status": "running", "agent_id": "agt_a1b2c3d4" }

Idempotencia

Reenviar al mismo agent dentro de 15 s devuelve 409 Conflict; cuando la cola de dispatch está ≥80 % devuelve 429 Too Many Requests (con Retry-After: 5).

Flujo de eventos en tiempo real (SSE)

GET /api/v1/events envía todos los eventos de los agent, con los parámetros de query opcionales ?workflow_id=<id>&tenant=<slug>. Headers de la solicitud:

Accept: text/event-stream
X-API-Key: sk-kova-<64位十六进制>

Ejemplo de frame SSE:

{"type": "thinking", "content": "正在分析搜索结果..."}
{"type": "tool_call", "tool": "web_search", "input": {"query": "WASM server-side 2026"}}
{"type": "tool_result", "tool": "web_search", "output": "..."}
{"type": "output", "content": "根据搜索结果..."}
{"type": "completed", "task_id": "tsk_e5f6g7h8"}

Al listar tareas se pueden usar los parámetros de query GET /api/v1/tasks?agent_id=agt_a1b2c3d4&status=completed&limit=20.

---

Administración de workflows

POST/api/v1/workflowsCrear workflow

POST/api/v1/workflows/:name/runEjecutar workflow

GET/api/v1/workflows/:name/runs/:run_idConsultar el estado de ejecución

GET/api/v1/workflowsListar workflows

Cuerpo de la solicitud de creación:

{ "name": "content-pipeline", "description": "内容创作管道",
  "steps": [
    { "name": "research", "agent": "researcher", "prompt": "调研主题：{{input.topic}}" },
    { "name": "write", "agent": "writer", "prompt": "基于研究结果撰写文章：\n{{steps.research.output}}",
      "error_policy": "retry", "max_retries": 2 }
  ] }

El cuerpo de la solicitud al ejecutar es { "input": { "topic": "边缘计算趋势" } }.

---

Administración de Swarm

POST/api/v1/swarmsCrear Swarm

POST/api/v1/swarms/:name/tasksEnviar una tarea al Swarm

Cuerpo de la solicitud de creación:

{ "name": "dev-team", "coordinator": "project-manager", "agents": ["researcher", "coder", "tester"],
  "config": { "max_rounds": 10, "consensus_required": false } }

---

Administración de WAL

GET/api/v1/wal/statusConsultar el estado del WAL

POST/api/v1/wal/compactDisparar la compactación del WAL

Ejemplo de respuesta de estado:

{ "total_entries": 1024, "pending_entries": 0, "corrupted_entries": 0, "buffer_usage": 0.35, "last_compaction": "2026-03-17T08:00:00Z" }

---

Administración del sistema

GET/api/v1/healthComprobación de salud

GET/api/v1/metricsMétricas del sistema (formato Prometheus)

---

Respuestas de error

Formato unificado: { "error": { "code": "agent_not_found", "message": "Agent with id 'agt_xxx' not found", "details": null } }

HTTP	Código de error	Descripción
400	invalid_request	Parámetros de la solicitud incorrectos
401	unauthorized	X-API-Key ausente o inválida
404	agent_not_found	El Agent no existe
409	agent_busy	Reenvío dentro de la ventana de idempotencia de 15 s
422	workflow_invalid	Definición del workflow errónea
429	queue_full	Cola de dispatch ≥80 %, dispara el límite por contrapresión
500	internal_error	Error interno
503	wal_error	Anomalía del sistema WAL

---

Siguientes pasos

Siguientes pasos

Inicio rápido — Lanza tu primer Agent en 5 minutosConceptos básicos — Diseño de WAL / Workflow / Swarm

Productos relacionados

Suele combinarse con

LumenReproduce cualquier ejecución de un agente, contabiliza el coste de uso y reanuda desde un punto de control tras una interrupción · Piloto inicial

MemXMotor de memoria para IA · extracción, deduplicación, decaimiento, recuperación híbrida · Piloto inicial

Lurus APIGateway LLM multiinquilino desplegado en el entorno propio del cliente · Basado en el proyecto de código abierto New API, AGPLv3

ForgeLienzo visual para construir flujos de trabajo de agentes arrastrando y soltando, y ejecutarlos · Herramienta interna, sin comercialización externa