Skip to content

API.md

Latest commit

 

History

History
197 lines (139 loc) · 4.3 KB

API.md

File metadata and controls

197 lines (139 loc) · 4.3 KB

genworker API Guide

1. Overview

genworker 默认暴露一组面向本地 Agent Runtime 的 HTTP 接口，核心能力集中在：

  • 对话流式输出
  • Worker 任务流式输出
  • 健康与就绪检查
  • 运行时诊断

默认服务地址：

http://127.0.0.1:8000

2. Core Endpoints

2.1 Chat Stream

POST /api/v1/chat/stream
Content-Type: application/json

用途：

  • 发起或继续一段对话
  • 以 SSE 方式接收模型与运行时事件

典型请求体：

{
  "message": "你好，帮我总结今天的任务重点",
  "thread_id": "chat-001",
  "tenant_id": "demo",
  "worker_id": "analyst-01"
}

2.2 Worker Task Stream

POST /api/v1/worker/task/stream
Content-Type: application/json

用途：

  • 触发一次面向 Worker 的任务执行
  • 适合自动化、集成或外部系统调用

典型请求体：

{
  "task": "检查我的收件箱并整理待办",
  "tenant_id": "demo",
  "worker_id": "analyst-01"
}

2.3 Health

GET /health

用途：

  • 进程级存活探针
  • 适合负载均衡器或容器探针

2.4 Readiness

GET /readiness

用途：

  • 判断默认聊天主链路是否已经可服务
  • 比 /health 更接近真实运行态

2.5 Runtime Debug

GET /api/v1/debug/runtime

用途：

  • 查看运行时 profile
  • 查看默认 worker
  • 查看 Redis / MySQL / OpenViking / IM 开关状态
  • 查看当前关键组件的 backend 与降级状态

2.6 Worker Dashboard API

所有 Worker Dashboard 查询接口均为只读 GET，默认 tenant_id=demo，并复用 API_BEARER_TOKEN / API_KEY 鉴权。

领域接口：

GET /api/v1/workers/{worker_id}/profile?tenant_id=demo
GET /api/v1/workers/{worker_id}/tasks?tenant_id=demo&status=running,pending&limit=50
GET /api/v1/workers/{worker_id}/calendar?tenant_id=demo&range=day|week|month&date=2026-04-29
GET /api/v1/workers/{worker_id}/goals?tenant_id=demo&status=active
GET /api/v1/workers/{worker_id}/activity?tenant_id=demo&limit=20
GET /api/v1/workers/{worker_id}/pending-actions?tenant_id=demo
GET /api/v1/workers/{worker_id}/channels/status?tenant_id=demo

聚合接口：

GET /api/v1/workers/{worker_id}/dashboard?tenant_id=demo&range=day&date=2026-04-29

示例：

curl -s "http://127.0.0.1:8000/api/v1/workers/analyst-01/dashboard?tenant_id=demo&range=week&date=2026-04-29"

响应结构：

{
  "worker_id": "analyst-01",
  "tenant_id": "demo",
  "range": "week",
  "date": "2026-04-29",
  "generated_at": "2026-04-29T08:00:00Z",
  "blocks": {
    "profile": { "data": { "worker_id": "analyst-01" }, "error": null },
    "calendar": { "data": { "events": [], "parse_errors": [] }, "error": null },
    "running_tasks": { "data": [], "error": null },
    "goals": { "data": [], "error": null },
    "activity": { "data": [], "error": null },
    "pending_actions": { "data": { "suggestions": 0, "approvals": 0, "top_items": [] }, "error": null },
    "channels": { "data": { "adapters": [], "im_enabled": false }, "error": null }
  }
}

聚合接口会对单个 block 失败做局部降级：整体仍返回 200，对应 block 的 data 为 null 或空占位，error 写明失败原因。

3. Authentication

如果你启用了以下任一配置，API 将进入鉴权模式：

  • API_BEARER_TOKEN
  • API_KEY

示例：

curl -s http://127.0.0.1:8000/api/v1/debug/runtime \
  -H "Authorization: Bearer your-token"

4. Streaming Notes

/api/v1/chat/stream 与 /api/v1/worker/task/stream 默认是流式接口。

调用方需要注意：

  • 连接会持续到本轮执行结束
  • 中途可能收到阶段事件、增量文本和结束事件
  • 反向代理需要允许流式透传，不要强制缓冲

5. Quick Verification

curl -s http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/readiness
curl -s http://127.0.0.1:8000/api/v1/debug/runtime

6. Troubleshooting

6.1 /health 正常但 /readiness 失败

说明进程已启动，但默认运行链路尚未准备完成。优先检查：

  • Worker 是否正确加载
  • Skill 是否正确加载
  • LLM / Session / Memory 依赖是否进入可服务状态

6.2 流式接口在代理后不返回增量

优先检查代理层是否启用了响应缓冲。对于 Nginx，这通常意味着需要关闭 proxy_buffering。