API Server
API server 将 kopi-ai-agent 暴露为一个 OpenAI 兼容的 HTTP endpoint。任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 以及数百种其他前端——都可以连接到 kopi-ai-agent 并将其用作后端。
你的 agent 会使用其完整的工具集(终端、文件操作、web 搜索、memory、skill)处理请求并返回最终响应。在流式传输时,工具进度指示器会内联显示,以便前端展示 agent 正在执行的操作。
Kopi Agent 本身需要配置 provider(服务提供商)和工具后端,API server 才能发挥作用。订阅 KOPI Proxy 即可同时解决这两者——提供 300+ 模型,以及通过 Tool Gateway 提供的 web/图片/TTS/浏览器工具。在启动 API server 前运行一次 kopi setup --portal,Open WebUI 或 LobeChat 等前端就能获得一个配备了完整工具的后端。
快速开始
1. 启用 API server
将以下内容添加到 ~/.kopi/.env:
API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: only if a browser must call Kopi Agent directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000
2. 启动 gateway
kopi gateway
你会看到:
[API Server] API server listening on http://127.0.0.1:8642
3. 连接前端
将任意 OpenAI 兼容的客户端指向 http://localhost:8642/v1:
# Test with curl
curl http://localhost:8642/v1/chat/completions \
-H "Authorization: Bearer change-me-local-dev" \
-H "Content-Type: application/json" \
-d '{"model": "kopi-ai-agent", "messages": [{"role": "user", "content": "Hello!"}]}'
或者连接 Open WebUI、LobeChat 或其他任何前端——参见 Open WebUI 集成指南 获取分步操作说明。
Endpoints
POST /v1/chat/completions
标准的 OpenAI Chat Completions 格式。无状态——完整对话通过 messages 数组包含在每个请求中。
请求:
{
"model": "kopi-ai-agent",
"messages": [
{"role": "system", "content": "You are a Python expert."},
{"role": "user", "content": "Write a fibonacci function"}
],
"stream": false
}
响应:
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1710000000,
"model": "kopi-ai-agent",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "Here's a fibonacci function..."},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}
内联图片输入: user 消息可以将 content 发送为由 text 和 image_url 部分组成的数组。远程 http(s) URL 和 data:image/... URL 均受支持:
{
"model": "kopi-ai-agent",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What is in this image?"},
{"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
]
}
]
}
上传的文件(file / input_file / file_id)以及非图片的 data: URL 会返回 400 unsupported_content_type。
流式传输("stream": true):返回 Server-Sent Events (SSE),逐 token 返回响应片段。对于 Chat Completions,流使用标准的 chat.completion.chunk 事件,外加 Kopi Agent 自定义的 kopi-agent.tool.progress 事件,用于工具启动的 UX 展示。对于 Responses,流使用 OpenAI Responses 事件类型,例如 response.created、response.output_text.delta、response.output_item.added、response.output_item.done 和 response.completed。
流中的工具进度:
- Chat Completions:Kopi Agent 发出
event: kopi-agent.tool.progress,以实现工具启动的可视化,同时不会污染持久化的 assistant 文本。 - Responses:Kopi Agent 在 SSE 流中发出符合规范的原生
function_call和function_call_output输出项,因此客户端可以实时渲染结构化的工具 UI。
POST /v1/responses
OpenAI Responses API 格式。通过 previous_response_id 支持服务端会话状态——服务器存储完整的对话历史(包括工具调用和结果),因此多轮上下文得以保留,无需客户端自行管理。
请求:
{
"model": "kopi-ai-agent",
"input": "What files are in my project?",
"instructions": "You are a helpful coding assistant.",
"store": true
}
响应:
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"model": "kopi-ai-agent",
"output": [
{"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
{"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
],
"usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}
内联图片输入: input[].content 可以包含 input_text 和 input_image 部分。远程 URL 和 data:image/... URL 均受支持:
{
"model": "kopi-ai-agent",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "Describe this screenshot."},
{"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
]
}
]
}
上传的文件(input_file / file_id)以及非图片的 data: URL 会返回 400 unsupported_content_type。
使用 previous_response_id 进行多轮对话
串联响应以跨轮次保持完整上下文(包括工具调用):
{
"input": "Now show me the README",
"previous_response_id": "resp_abc123"
}
服务器从存储的响应链中重建完整对话——所有之前的工具调用和结果都会被保留。串联的请求还会共享同一 session,因此多轮对话在 dashboard 和 session 历史中只显示为单个条目。
命名对话
使用 conversation 参数替代自行跟踪 response ID:
{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}
服务器会自动串联到该对话中最新的响应。类似于 gateway session 的 /title 命令。
GET /v1/responses/{id}
按 ID 检索之前存储的响应。
DELETE /v1/responses/{id}
删除存储的响应。
GET /v1/models
将该 agent 列为可用模型。所声明的模型名称默认为 profile 的名称(对于默认 profile 则为 kopi-ai-agent)。大多数前端进行模型发现时都需要此接口。
GET /v1/capabilities
以机器可读的形式返回 API server 稳定接口的描述,供外部 UI、编排器和 plugin 桥接使用。
{
"object": "kopi-agent.api_server.capabilities",
"platform": "kopi-ai-agent",
"model": "kopi-ai-agent",
"auth": {"type": "bearer", "required": true},
"features": {
"chat_completions": true,
"responses_api": true,
"run_submission": true,
"run_status": true,
"run_events_sse": true,
"run_stop": true
}
}
在集成 dashboard、浏览器 UI 或控制平面时使用此 endpoint,这样它们就能发现当前运行的 Kopi Agent 版本是否支持 runs、流式传输、取消和 session 连续性,而无需依赖私有的 Python 内部实现。
GET /health
健康检查。返回 {"status": "ok"}。对于期望 /v1/ 前缀的 OpenAI 兼容客户端,也可通过 GET /v1/health 访问。
GET /health/detailed
扩展健康检查,还会报告活跃的 session、运行中的 agent 以及资源使用情况。适用于监控/可观测性工具。
Runs API(适合流式场景的替代方案)
除了 /v1/chat/completions 和 /v1/responses,服务器还提供了一个 runs API,用于长时间会话场景——客户端希望订阅进度事件,而不是自己管理流式传输。
POST /v1/runs
创建一个新的 agent run。返回一个 run_id,可用于订阅进度事件。
{
"run_id": "run_abc123",
"status": "started"
}
Runs 接受一个简单的 input 字符串,以及可选的 session_id、instructions、conversation_history 或 previous_response_id。当提供了 session_id 时,Kopi Agent 会在 run 状态中显示它,方便外部 UI 将 run 与自己的会话 ID 关联起来。
GET /v1/runs/{run_id}
轮询当前 run 状态。这对于需要获取状态但不想保持 SSE 连接打开的仪表板很有用,或者用于在导航后重新连接的 UI。
{
"object": "kopi-agent.run",
"run_id": "run_abc123",
"status": "completed",
"session_id": "space-session",
"model": "kopi-ai-agent",
"output": "Done.",
"usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}
在进入终态(completed、failed 或 cancelled)之后,状态会短暂保留,以供轮询和 UI 对账使用。
GET /v1/runs/{run_id}/events
Server-Sent Events 流,传输该 run 的工具调用进度、token 增量和生命周期事件。专为希望在不丢失状态的情况下随时附加/断开的仪表板和重型客户端设计。
POST /v1/runs/{run_id}/stop
中断正在运行的 agent 回合。该端点会立即返回 {"status": "stopping"},同时 Kopi Agent 会让活动 agent 在下一个安全中断点停止。
POST /v1/runs/{run_id}/approval
处理一个正在等待人工决策的 run 的待定审批(例如,受审批策略门控的工具调用)。请求体携带审批决定;决定记录后 run 将恢复运行。该端点在 /v1/capabilities 中以 run_approval 特性的形式公布,以便外部 UI 在显示审批提示前检测到支持情况。
Jobs API(后台定时任务)
服务器提供了一个轻量级的 jobs CRUD 接口,用于通过远程客户端管理定时/后台 agent run。所有端点都受相同的 bearer 认证保护。
GET /api/jobs
列出所有定时任务。
POST /api/jobs
创建一个新的定时任务。请求体接受与 kopi cron 相同的结构——prompt、schedule、skills、provider 覆盖项、交付目标。
GET /api/jobs/{job_id}
获取单个任务的定义及其最近一次运行状态。
PATCH /api/jobs/{job_id}
更新现有任务的字段(prompt、schedule 等)。部分更新会被合并。
DELETE /api/jobs/{job_id}
删除任务。同时会取消所有进行中的 run。
POST /api/jobs/{job_id}/pause
暂停任务但不删除它。下次计划运行的时间戳将被挂起,直到恢复为止。
POST /api/jobs/{job_id}/resume
恢复之前暂停的任务。
POST /api/jobs/{job_id}/run
立即触发任务运行,不受计划时间限制。
Sessions API(通过 REST 进行会话控制)
外部 UI 可以通过 REST 管理 Kopi Agent 会话,而无需搭建仪表板。所有端点均由 API_SERVER_KEY 保护,并位于 /api/sessions/* 之下。
| 方法 | 路径 | 描述 |
|---|---|---|
GET | /api/sessions | 列出会话(分页——limit、offset、source、include_children) |
POST | /api/sessions | 创建一个空会话 |
GET | /api/sessions/{id} | 读取会话元数据 |
PATCH | /api/sessions/{id} | 更新标题或 end_reason |
DELETE | /api/sessions/{id} | 删除会话 |
GET | /api/sessions/{id}/messages | 获取某会话的消息历史记录 |
POST | /api/sessions/{id}/fork | 通过 SessionDB 血缘关系分支会话(与 CLI /branch 的语义一致) |
POST | /api/sessions/{id}/chat | 运行一个同步的 agent 回合 |
POST | /api/sessions/{id}/chat/stream | 针对单个回合的 SSE 封装——发出 assistant.delta、tool.started、tool.completed、run.completed 事件 |
/v1/capabilities 通过 session_* 特性标志和 endpoints.session_* 条目公布完整的接口面,以便外部 UI 检测支持情况并安全回退。chat 和 chat/stream 载荷中支持内联图片(支持多模态的路径)。
# fork a session and run one turn
curl -X POST http://localhost:8642/api/sessions/$ID/fork \
-H "Authorization: Bearer $API_SERVER_KEY" \
-d '{"title": "explore alt path"}'
# stream a turn over SSE
curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \
-H "Authorization: Bearer $API_SERVER_KEY" \
-d '{"input": "what files changed in the last hour?"}'
Skills 与 toolsets 发现
GET /v1/skills 和 GET /v1/toolsets 让外部客户端能够通过 REST 确定性地枚举 agent 的能力,而无需询问模型。两者都是只读的,并由 API_SERVER_KEY 保护。
curl http://localhost:8642/v1/skills \
-H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...]
curl http://localhost:8642/v1/toolsets \
-H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "core", "label": "...", "description": "...", "enabled": true,
# "configured": true, "tools": ["read_file", "write_file", ...]}, ...]
/v1/skills 返回与 skills hub 内部使用的相同元数据。/v1/toolsets 返回为 api_server 平台解析出的 toolsets,以及每个 toolset 展开后得到的具体 tools 列表。两者都以 endpoints.* 的形式在 /v1/capabilities 中公布。
长期记忆作用域(X-Kopi Agent-Session-Key)
像 Open WebUI 这样的多用户前端需要一个稳定的按频道标识符,用于长期记忆(Honcho 等),且该标识符独立于以转录为作用域的 X-Kopi Agent-Session-Id(它会在 /new 时轮换)。在 /v1/chat/completions、/v1/responses 或 /v1/runs 上传递 X-Kopi Agent-Session-Key,Kopi Agent 会将其一路透传到 AIAgent(gateway_session_key=...),Honcho 的 memory provider 会用它来推导出稳定的作用域。
POST /v1/chat/completions HTTP/1.1
Authorization: Bearer ***
X-Kopi Agent-Session-Id: transcript-alpha
X-Kopi Agent-Session-Key: agent:main:webui:dm:user-42
规则:最长 256 个字符,控制字符(\r、\n、\x00)会被拒绝,且该值会在响应中原样返回(JSON + SSE)。/v1/capabilities 通过 "session_key_header": "X-Kopi Agent-Session-Key" 公布对此的支持。如果不带该键,Honcho 的 per-session 策略会为每个 session_id 生成不同的作用域——这正是 Kopi Agent 之前的行为。
System Prompt 处理
当前端发送 system 消息(Chat Completions)或 instructions 字段(Responses API)时,kopi-ai-agent 会将其叠加在其核心 system prompt 之上。你的 agent 会保留所有工具、记忆和 skill——前端的 system prompt 只是添加额外的指令。
这意味着你可以按前端定制行为,而不会失去任何能力:
- Open WebUI system prompt:"You are a Python expert. Always include type hints."
- agent 仍然拥有终端、文件工具、网页搜索、记忆等功能。
认证
通过 Authorization 请求头进行 Bearer token 认证:
Authorization: Bearer ***
通过 API_SERVER_KEY 环境变量配置密钥。如果你需要通过浏览器直接调用 Kopi Agent,还需将 API_SERVER_CORS_ORIGINS 设置为明确的允许列表。
API server 会授予对 kopi-ai-agent 工具集的完全访问权限,包括终端命令。API_SERVER_KEY 在每次部署中都是必需的,包括默认的 127.0.0.1 回环绑定。当你显式允许浏览器调用方时,请将 API_SERVER_CORS_ORIGINS 保持在最小范围以控制浏览器访问。
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
API_SERVER_ENABLED | false | 启用 API server |
API_SERVER_PORT | 8642 | HTTP 服务器端口 |
API_SERVER_HOST | 127.0.0.1 | 绑定地址(默认仅限 localhost) |
API_SERVER_KEY | (必需) | 用于认证的 Bearer token |
API_SERVER_CORS_ORIGINS | (无) | 以逗号分隔的允许浏览器来源 |
API_SERVER_MODEL_NAME | (配置文件名称) | /v1/models 上的模型名称。默认为配置文件名称,对于默认配置文件则为 kopi-ai-agent。 |
config.yaml
# Not yet supported — use environment variables.
# config.yaml support coming in a future release.
安全响应头
所有响应都包含安全响应头:
X-Content-Type-Options: nosniff— 防止 MIME 类型嗅探Referrer-Policy: no-referrer— 防止 referrer 泄露
CORS
API server 默认不启用浏览器 CORS。
如需直接通过浏览器访问,请设置明确的允许列表:
API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
启用 CORS 后:
- 预检响应包含
Access-Control-Max-Age: 600(10 分钟缓存) - SSE 流式响应包含 CORS 头,使浏览器 EventSource 客户端能正常工作
Idempotency-Key是被允许的请求头 — 客户端可以发送它用于去重(响应会按键缓存 5 分钟)
大多数已记录的前端(如 Open WebUI)都通过服务器到服务器的方式连接,完全不需要 CORS。
兼容的前端
任何支持 OpenAI API 格式的前端都可以使用。已测试/已记录的集成:
| 前端 | Stars | 连接方式 |
|---|---|---|
| Open WebUI | 126k | 提供完整指南 |
| LobeChat | 73k | 自定义 provider 端点 |
| LibreChat | 34k | 在 librechat.yaml 中设置自定义端点 |
| AnythingLLM | 56k | 通用 OpenAI provider |
| NextChat | 87k | BASE_URL 环境变量 |
| ChatBox | 39k | API Host 设置 |
| Jan | 26k | 远程模型配置 |
| HF Chat-UI | 8k | OPENAI_BASE_URL |
| big-AGI | 7k | 自定义端点 |
| OpenAI Python SDK | — | OpenAI(base_url="http://localhost:8642/v1") |
| curl | — | 直接 HTTP 请求 |
使用 profile 的多用户设置
如果要为多个用户提供各自独立的 Kopi Agent 实例(独立的配置、记忆、skill),请使用 profiles:
# Create a profile per user
kopi profile create alice
kopi profile create bob
# Configure each profile's API server on a different port. API_SERVER_* are env
# vars (not config.yaml keys), so write them to each profile's .env:
cat >> ~/.kopi/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
API_SERVER_KEY=alice-secret
EOF
cat >> ~/.kopi/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8644
API_SERVER_KEY=bob-secret
EOF
# Start each profile's gateway
kopi -p alice gateway &
kopi -p bob gateway &
每个 profile 的 API server 会自动将 profile 名称作为 model ID 进行广播:
http://localhost:8643/v1/models→ modelalicehttp://localhost:8644/v1/models→ modelbob
在 Open WebUI 中,将它们各自添加为单独的连接。模型下拉菜单会显示 alice 和 bob 两个不同的模型,每个模型都由完全独立的 Kopi Agent 实例支撑。详情请参阅 Open WebUI 指南。
限制
- 响应存储 — 存储的响应(用于
previous_response_id)会持久化到 SQLite 中,并在网关重启后保留。最多存储 100 条响应(LRU 淘汰)。 - 不支持文件上传 —
/v1/chat/completions和/v1/responses都支持内联图片,但上传的文件(file、input_file、file_id)以及非图片的文档输入不支持通过 API 使用。 - model 字段仅为展示用途 — 请求中的
model字段会被接受,但实际使用的 LLM 模型是在 config.yaml 中于服务端配置的。
代理模式
API server 同时充当网关代理模式的后端。当另一个 Kopi Agent 网关实例被配置为通过 GATEWAY_PROXY_URL 指向此 API server 时,它会将所有消息转发到这里,而不是运行自己的 agent。这实现了分离式部署 — 例如,一个处理 Matrix E2EE 的 Docker 容器将消息转发给宿主机侧的 agent。
完整的设置指南请参阅 Matrix 代理模式。