Référence de l’API Kova
API REST complète construite sur Axum, plus de 35 points de terminaison, format JSON unifié — couvrant Agent, tâches, Workflow, Swarm, WAL et administration système.
Base URLBase URLAdresse racine de l'API. La Base URL de Lurus est https://hub.lurus.cn/v1.
http://localhost:3000/api/v1Authentification
Toutes les requêtes transmettent la clé API via l’en-tête X-API-Key obligatoire :
X-API-Key: sk-kova-<64位十六进制>Format de la clé : ^sk-kova-[a-f0-9]{64}$, générée par create-tester.sh, stockée dans testers/<NAME>/.env (chmod 600).
Limitation de débit
Fenêtre d’idempotence
POST /agents/:id/run renvoie 409 Conflict en cas de soumission répétée du même agent dans un délai de 15 s.Limite de contre-pression
429 Too Many Requests (avec Retry-After: 5).Gestion des Agents
/api/v1/agentsCréer un Agent/api/v1/agentsLister les Agents (prend en charge status / limit / offset)/api/v1/agents/:idObtenir les détails d’un Agent/api/v1/agents/:idMettre à jour un Agent/api/v1/agents/:idSupprimer un AgentCorps de la requête de création :
{ "name": "researcher", "system_prompt": "你是一个专业的研究员...", "model": "deepseek-chat",
"tools": ["web_search", "file_write"],
"config": { "max_tokens": 4096, "temperature": 0.7, "max_iterations": 20 } }Réponse (201) : { "id": "agt_a1b2c3d4", "name": "researcher", "status": "idle", "created_at": "2026-03-17T10:00:00Z" }
Lors du listage, les paramètres de requête disponibles sont GET /api/v1/agents?status=idle&limit=20&offset=0.
WARNING
Seuls les Agents à l’état idle ou completed peuvent être supprimés. Ceux en cours d’exécution doivent d’abord être arrêtés.
Exécution des tâches
/api/v1/agents/:id/runDéclencher l’exécution d’une tâche par l’Agent/api/v1/eventsFlux d’événements SSE (diffusion en temps réel de tous les événements d’agents)/api/v1/tasks/:id/stopArrêter une tâche/api/v1/tasksLister les tâches (prend en charge agent_id / status / limit)Corps de la requête de déclenchement d’exécution :
{ "message": "研究 WebAssembly 在服务端的最新发展",
"context": { "output_format": "markdown", "max_length": 2000 } }Réponse (200) : { "task_id": "tsk_e5f6g7h8", "status": "running", "agent_id": "agt_a1b2c3d4" }
Idempotence
Une soumission répétée pour le même agent dans un délai de 15 s renvoie 409 Conflict ; lorsque la file dispatch atteint ≥ 80 %, renvoie 429 Too Many Requests (avec Retry-After: 5).
Flux d’événements en temps réel (SSE)
GET /api/v1/events diffuse tous les événements d’agents, avec les paramètres de requête optionnels ?workflow_id=<id>&tenant=<slug>. En-têtes de la requête :
Accept: text/event-stream
X-API-Key: sk-kova-<64位十六进制>Exemple de trame 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"}Pour lister les tâches, les paramètres de requête disponibles sont GET /api/v1/tasks?agent_id=agt_a1b2c3d4&status=completed&limit=20.
Gestion des Workflows
/api/v1/workflowsCréer un workflow/api/v1/workflows/:name/runExécuter un workflow/api/v1/workflows/:name/runs/:run_idConsulter l’état d’exécution/api/v1/workflowsLister les workflowsCorps de la requête de création :
{ "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 }
] }Lors de l’exécution, le corps de la requête est { "input": { "topic": "边缘计算趋势" } }.
Gestion des Swarms
/api/v1/swarmsCréer un Swarm/api/v1/swarms/:name/tasksEnvoyer une tâche à un SwarmCorps de la requête de création :
{ "name": "dev-team", "coordinator": "project-manager", "agents": ["researcher", "coder", "tester"],
"config": { "max_rounds": 10, "consensus_required": false } }Gestion du WAL
/api/v1/wal/statusInterroger l’état du WAL/api/v1/wal/compactDéclencher la compaction du WALExemple de réponse d’état :
{ "total_entries": 1024, "pending_entries": 0, "corrupted_entries": 0, "buffer_usage": 0.35, "last_compaction": "2026-03-17T08:00:00Z" }Administration système
/api/v1/healthContrôle de santé/api/v1/metricsMétriques système (format Prometheus)Réponses d’erreur
Format unifié : { "error": { "code": "agent_not_found", "message": "Agent with id 'agt_xxx' not found", "details": null } }
| HTTP | Code d’erreur | Description |
|---|---|---|
| 400 | invalid_request | Paramètres de requête incorrects |
| 401 | unauthorized | X-API-Key manquante ou invalide |
| 404 | agent_not_found | L’Agent n’existe pas |
| 409 | agent_busy | Soumission répétée dans la fenêtre d’idempotence de 15 s |
| 422 | workflow_invalid | Définition de workflow erronée |
| 429 | queue_full | File dispatch ≥ 80 %, déclenche la limitation par contre-pression |
| 500 | internal_error | Erreur interne |
| 503 | wal_error | Anomalie du système WAL |