WeKnora/website-docs/04-api/02-api-agent-mcp.md

398 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# API 参考:Agent、MCP 与技能
管理智能体、MCP 服务及其凭据、技能和资源收藏。智能体的工具范围与调用审批配置通过本组接口维护。
## Agent(/api/v1/agents)
读:Viewer+(API key `read_agents`/`manage_agents`/`chat`/full);写:创建者 OR Admin+(API key `manage_agents`/full);内置 Agent(`is_builtin=true`)始终 Admin+。
### GET /api/v1/agents/placeholders
用途:提示词占位符定义(须先于 `/:id` 注册)。权限:Viewer+。
响应:200 `{"success":true,"data":{"all":{...},"system_prompt":{...},"agent_system_prompt":{...},"context_template":{...},"rewrite_system_prompt":{...},"rewrite_prompt":{...},"fallback_prompt":{...}}}`
```bash
curl $BASE/api/v1/agents/placeholders -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/agents/type-presets
用途:智能推理 Agent 类型预设(rag-qa / wiki-qa / hybrid / custom 等)。权限:Viewer+。
响应:200 `{"success":true,"data":[{type,system_prompt,allowed_tools,kb_compatibility}]}`
```bash
curl $BASE/api/v1/agents/type-presets -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/agents
用途:创建自定义 Agent。权限:Contributor+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是(`binding:"required"`) | 名称 |
| `description` | string | 否 | 描述 |
| `avatar` | string | 否 | 头像/emoji |
| `config` | object | 否 | Agent 配置(`types.CustomAgentConfig`,见下) |
`config` 主要字段:`agent_mode`(`quick-answer`/`smart-reasoning`)、`agent_type`(`rag-qa/wiki-qa/hybrid-rag-wiki/data-analysis/custom`)、`system_prompt`、`model_id`、`temperature`(0-2,非法返回 code 2103)、`max_iterations`(1-20,非法返回 code 2102)、`allowed_tools`(智能推理必填至少一个,code 2101)、`mcp_selection_mode`/`mcp_services`、`skills_selection_mode`、`kb_selection_mode`/`knowledge_bases`、`web_search_enabled`、`question_suggestions` 等(完整定义见 `internal/types/custom_agent.go`)。
响应:201 `{"success":true,"data":{id,name,description,avatar,is_builtin,created_by,config,creator_name,...}}`
```bash
curl -X POST $BASE/api/v1/agents -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"售后助手","config":{"agent_mode":"quick-answer","kb_selection_mode":"selected","knowledge_bases":["kb-1"]}}'
```
### GET /api/v1/agents
用途:Agent 列表(含内置)。权限:Viewer+。查询参数:`creator`(`mine`/`others`,可选)。
响应:200 `{"success":true,"data":[Agent],"disabled_own_agent_ids":[...]}`
```bash
curl $BASE/api/v1/agents -H "X-API-Key: $API_KEY"
```
### GET /api/v1/agents/:id
用途:Agent 详情。权限:Viewer+。
响应:200 `{"success":true,"data":{Agent}}`
```bash
curl $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/agents/:id
用途:更新 Agent。权限:创建者 OR Admin+。请求体:`name/description/avatar/config`(均可选)。Agent 已分享到组织时,新加入知识库范围的知识库须是调用者可分享的(知识库创建者或 Admin+,改为 `all` 需要 Admin+),否则 403。
响应:200 `{"success":true,"data":{Agent}}`
```bash
curl -X PUT $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"description":"更新描述"}'
```
### DELETE /api/v1/agents/:id
用途:删除 Agent。权限:创建者 OR Admin+。
响应:200 `{"success":true,"message":"Agent deleted successfully"}`
```bash
curl -X DELETE $BASE/api/v1/agents/agent-1 -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/agents/:id/copy
用途:复制 Agent(副本归调用者)。权限:Contributor+。无请求体。
响应:201 `{"success":true,"data":{新 Agent}}`
```bash
curl -X POST $BASE/api/v1/agents/agent-1/copy -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/agents/:id/suggested-questions
用途:Agent 起始建议问题(注册在组外以避免与 `/agents/:id/shares` 冲突)。权限:Viewer+;API key `read_agents`/`manage_agents`/`chat`/full。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `knowledge_base_ids` | string | 否 | 逗号分隔 KB |
| `knowledge_ids` | string | 否 | 逗号分隔知识 ID |
| `tag_scopes` | string | 否 | JSON 数组的标签范围 |
| `limit` | int | 否 | 上限 30 |
响应:200 `{"success":true,"data":{"questions":[{question,source,knowledge_base_id}]}}`
```bash
curl "$BASE/api/v1/agents/agent-1/suggested-questions?limit=6" -H "X-API-Key: $API_KEY"
```
## MCP 服务(/api/v1/mcp-services)
空间级外部工具服务集成。读:Viewer+;写/测试/审批策略:Admin+。API key:`manage_mcp_services`/full。Handler: `internal/handler/mcp_service.go`
### POST /api/v1/mcp-services
用途:创建 MCP 服务。权限:Admin+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 名称 |
| `description` | string | 否 | 旧版描述,兼容保留;管理界面统一编辑 `usage_instructions` |
| `usage_instructions` | string | 配置完成时必填 | 服务用途、适用场景和关键约束;第一步仅保存连接时可省略 |
| `enabled` | bool | 否 | 启用 |
| `transport_type` | string | 是 | `sse` / `http-streamable` / `stdio` |
| `url` | *string | 否 | 服务 URL(SSE/HTTP) |
| `headers` | map[string]string | 否 | HTTP 头 |
| `auth_config` | object | 否 | `auth_type`(`api_key/bearer/oauth`)、`api_key_header`、`custom_headers`、`scopes`、`auth_server_metadata_url`(密钥走 credentials 子资源) |
| `advanced_config` | object | 否 | 超时/重试 |
| `stdio_config` | object | 否 | stdio 命令与参数 |
| `env_vars` | map[string]string | 否 | 环境变量 |
响应:200 `{"success":true,"data":{MCPServiceResponse}}`(含 `credentials:{api_key:{configured},token:{configured}}`)
```bash
curl -X POST $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"github","transport_type":"sse","url":"https://mcp.example.com/sse"}'
```
### GET /api/v1/mcp-services
用途:MCP 服务列表。权限:Viewer+。响应:200 `{"success":true,"data":[MCPServiceResponse]}`
```bash
curl $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/mcp-services/:id
用途:详情。权限:Viewer+。响应:200 `{"success":true,"data":{MCPServiceResponse}}`
```bash
curl $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/mcp-services/:id
用途:部分更新(map 语义;`auth_config` 中不可携带 api_key/token)。权限:Admin+。字段同创建(均可选)。
提交 `usage_instructions` 时必须为去除首尾空白后非空的字符串,最长 16000 字符。仅修改连接或启用状态时可省略该字段,原值保持不变。
响应:200 `{"success":true,"data":{MCPServiceResponse}}`
```bash
curl -X PUT $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"enabled":false}'
```
### POST /api/v1/mcp-services/:id/usage-instructions/generate
用途:根据已同步、未过期的 MCP 工具目录生成精简使用说明。权限:Admin+;API key 需要 `manage_mcp_services` 或 full。
请求:`{"language":"zh-CN"}`。支持 `zh-CN`、`en-US`、`ja-JP`、`ko-KR`、`ru-RU`,默认中文。
优先使用空间默认的可用对话模型,否则使用首个可用对话模型。输入包括服务名称、服务端说明和已启用工具的名称、描述;OAuth 目录沿用当前用户的授权范围。不会连接 MCP、调用工具或自动保存生成结果。
响应:200 `{"success":true,"data":{"usage_instructions":"按模块和时间范围查询远程日志;已有查询 ID 时读取对应日志。"}}`。生成目标为 2–3 句简短说明,最多 500 字符;用户可编辑后通过 PUT 保存。目录未同步、过期、无启用工具或无可用对话模型时返回 400。
### DELETE /api/v1/mcp-services/:id
用途:删除。权限:Admin+。响应:200 `{"success":true,"message":"MCP service deleted successfully"}`
```bash
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1 -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/mcp-services/:id/test
用途:连接测试(探测外部服务)。权限:Admin+。响应:200 `{"success":true,"data":{"success","message","oauth_required","tools":[...],"resources":[...]}}`
```bash
curl -X POST $BASE/api/v1/mcp-services/mcp-1/test -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/mcp-services/:id/tools
用途:工具列表。权限:Viewer+。响应:200 `{"success":true,"data":[{name,description,inputSchema,require_approval}]}`
```bash
curl $BASE/api/v1/mcp-services/mcp-1/tools -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/mcp-services/:id/resources
用途:资源列表。权限:Viewer+。响应:200 `{"success":true,"data":[{uri,name,description,mimeType}]}`
```bash
curl $BASE/api/v1/mcp-services/mcp-1/resources -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/mcp-services/:id/credentials
用途:设置密钥(`api_key`/`token`,指针字段,省略保留)。权限:Admin+。Handler: `internal/handler/mcp_credentials.go`
响应:200 `{"success":true,"data":{"fields":{"api_key":{"configured"},"token":{"configured"}}}}`
```bash
curl -X PUT $BASE/api/v1/mcp-services/mcp-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"token":"ghp_..."}'
```
### DELETE /api/v1/mcp-services/:id/credentials/:field
用途:删除凭证字段(`api_key` 或 `token`)。权限:Admin+。响应:204。
```bash
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/credentials/token -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/mcp-services/:id/tool-approvals
用途:工具启停与人工审批策略列表。权限:Viewer+。响应:200 `{"success":true,"data":[{service_id,tool_name,require_approval,enabled,...}]}`
```bash
curl $BASE/api/v1/mcp-services/mcp-1/tool-approvals -H "Authorization: Bearer $TOKEN"
```
### PUT /api/v1/mcp-services/:id/tool-approvals/:tool_name
用途:更新某工具的 enabled(启停)和 require_approval(人工审批)。权限:Admin+。两者至少提供一个,省略的字段保持原值;无记录默认启用且不要求审批。
响应:200 `{"success":true}`
```bash
curl -X PUT $BASE/api/v1/mcp-services/mcp-1/tool-approvals/create_issue \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"require_approval":true}'
```
## MCP OAuth
Handler: `internal/handler/mcp_oauth.go`
### GET /api/v1/mcp-oauth/callback
用途:第三方 OAuth 授权回调(免认证,靠单次 `state` 参数认证;注册在 `/mcp-services` 组之外)。查询参数:`code`、`state`、`error`。
响应:302 重定向到前端(成功 `#mcp_oauth_result=success`,失败 `#mcp_oauth_error=<code>`)。
```bash
curl -i "$BASE/api/v1/mcp-oauth/callback?code=xxx&state=yyy"
```
### POST /api/v1/mcp-services/:id/oauth/authorize-url
用途:生成用户级授权 URL。权限:Viewer+。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `redirect_uri` | string | 是 | 后端回调 URL(绝对地址) |
| `frontend_redirect` | string | 否 | 回调后前端跳转(默认 `/`) |
响应:200 `{"success":true,"data":{"authorization_url","authorization_attempt"}}`
```bash
curl -X POST $BASE/api/v1/mcp-services/mcp-1/oauth/authorize-url -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"redirect_uri":"'$BASE'/api/v1/mcp-oauth/callback"}'
```
### GET /api/v1/mcp-services/:id/oauth/status
用途:查询本人授权状态。权限:Viewer+。查询参数:`authorization_attempt`(可选)。
响应:200 `{"success":true,"data":{"authorized","state":"authorized|pending","refresh_available","expires_at"}}`
```bash
curl $BASE/api/v1/mcp-services/mcp-1/oauth/status -H "Authorization: Bearer $TOKEN"
```
### DELETE /api/v1/mcp-services/:id/oauth/token
用途:吊销本人 OAuth token。权限:Viewer+。响应:204。
```bash
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/oauth/token -H "Authorization: Bearer $TOKEN"
```
## Agent 运行时交互(/api/v1/agent)
对话中的人工审批与 OAuth 恢复;权限均 Viewer+(发起会话的人才有上下文),API key 默认拒绝。
### POST /api/v1/agent/tool-approvals/:pending_id
用途:裁决待审批的工具调用。Handler: `internal/handler/mcp_service.go` 的 `ResolveToolApproval`。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `decision` | string | 是(`binding:"required"`) | `approve` / `reject` |
| `modified_args` | JSON | 否 | 修改后的工具参数 |
| `reason` | string | 否 | 理由 |
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/agent/tool-approvals/p-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"decision":"approve"}'
```
### POST /api/v1/agent/mcp-oauth-resolutions/:pending_id
用途:恢复因 MCP OAuth 暂停的 Agent 运行。Handler: `internal/handler/mcp_oauth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `service_id` | string | 是(`binding:"required"`) | MCP 服务 ID |
| `decision` | string | 否 | `authorize`(默认)/ `cancel` |
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"service_id":"mcp-1"}'
```
### POST /api/v1/agent/mcp-oauth-resolutions/:pending_id/cancel
用途:取消暂停中的 OAuth 流程。无请求体。
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1/cancel -H "Authorization: Bearer $TOKEN"
```
## 技能、沙箱与个人变量
`GET /api/v1/skills?sandbox_config_id=...` 返回指定配置下可用技能的名称/说明及 skills_available。目录收录、安装、模板、进度、文件与个人变量的完整接口见[沙箱与技能 API](02-api-sandbox-skills.md)。
智能体 config 增加 `sandbox_config_id`;与 skills_selection_mode、selected_skills 一起决定可用技能。shell/文件工具按后端能力注册,旧 read_skill / execute_skill_script 不再注册。
## 长期记忆
智能体 config 的 `memory_enabled` 为 nil 时继承空间,false 禁用本智能体的记忆读写。个人管理、主题/文档偏好、导出与立即整理见[长期记忆 API](02-api-memory.md),使用步骤见[跨会话长期记忆](../03-features/23-memory.md)。
## 用户收藏(/api/v1/user/favorites)
按用户维度存储(非资源创建者维度);权限均 Viewer+,仅 JWT(API key 默认拒绝)。Handler: `internal/handler/user_resource_favorite.go`
### GET /api/v1/user/favorites
用途:收藏列表。查询参数:`type`(必填,`kb` 或 `agent`)。
响应:200 `{"success":true,"data":[{type,id,created_at}]}`
```bash
curl "$BASE/api/v1/user/favorites?type=kb" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/user/favorites
用途:添加收藏。请求体:`{"type":"kb|agent","id":"<资源ID>"}`(均必填)。
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/user/favorites -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"type":"kb","id":"kb-1"}'
```
### DELETE /api/v1/user/favorites/:type/:id
用途:取消收藏。路径参数:`type`、`id`。
响应:200 `{"success":true}`
```bash
curl -X DELETE $BASE/api/v1/user/favorites/kb/kb-1 -H "Authorization: Bearer $TOKEN"
```
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterCustomAgentRoutes`、`RegisterMCPServiceRoutes`、`RegisterSkillRoutes`、`RegisterUserFavoriteRoutes`。Handler:`internal/handler/custom_agent.go`、`internal/handler/mcp_service.go`、`internal/handler/mcp_credentials.go`、`internal/handler/mcp_oauth.go`、`internal/handler/skill_handler.go`、`internal/handler/user_resource_favorite.go`。