# Skillspace 企业 Agent 接入指南

Skillspace 提供企业技能、知识与系统连接、业务工作流、企业对外 Agent 的人工评估与定制服务。公开服务目录是能力与商业边界的唯一来源。当前目录中的 assessment_available 表示可以评估定制，不表示已有可直接操作客户系统的工具。

- 服务目录（无需 JavaScript）：https://ai.runxian.top/api/v1/agent/services
- A2A Agent Card：https://ai.runxian.top/.well-known/agent-card.json
- A2A 1.0 JSON-RPC：https://ai.runxian.top/api/v1/agent/a2a
- MCP Streamable HTTP：https://ai.runxian.top/api/v1/agent/mcp
- 人工确认页面：https://ai.runxian.top/enterprise

## A2A

发送 POST，Content-Type: application/json、A2A-Version: 1.0。只支持 SendMessage 即时 Message，不支持持久任务、流式或推送。首轮可传文本；messageId 只用于关联，不是凭据。纯文本首轮重试会创建新会话；需要幂等重试时请在 data 中显式传递高熵随机 requestKey。例：

```json
{"jsonrpc":"2.0","id":"r1","method":"SendMessage","params":{"message":{"messageId":"replace-with-random-uuid","role":"ROLE_USER","parts":[{"text":"我们希望建设一个向客户介绍服务的企业 Agent，需要准备什么？"}]}}}
```

回复 result.message.parts[0].data 包含咨询结果及 conversationId、conversationToken、revision。服务端不把 contextId 当成凭据。继续咨询时，使用一个 data part：

```json
{"message":"主要通过官网接待，希望先介绍产品再转人工。","conversationId":"上次返回值","conversationToken":"上次返回值","revision":1,"requestKey":"每条新消息使用随机UUID"}
```

将它放入 SendMessage 的 parts:[{"data":上述对象,"mediaType":"application/json"}]，并设置 message.contextId 为同一 conversationId。重复请求使用相同 requestKey 和内容；新消息使用新 key。可选 data action 为 list_services 或 prepare_handoff；prepare_handoff 需 conversationId 和 conversationToken。

## MCP

向支持远程 Streamable HTTP 的客户端添加上述 MCP 地址。使用官方 Go SDK v1.7.0，支持协议版本 2026-07-28、2025-11-25、2025-06-18、2025-03-26、2024-11-05。旧版客户端先 initialize；2026-07-28 按协议发送请求版本 metadata。HTTP 不保持 MCP session；业务咨询使用独立会话凭据。提供三个工具：

- list_services：无参数，读取目录。
- consult_services：message、requestKey；继续咨询还需 conversationId、conversationToken，可传 revision 防止陈旧更新。
- prepare_handoff：conversationId、conversationToken，生成客户待确认的转交链接。

## 直接 HTTP

POST https://ai.runxian.top/api/v1/agent/consult，JSON 字段与 consult_services 相同。
POST https://ai.runxian.top/api/v1/agent/handoff，JSON 为 conversationId、conversationToken。
POST https://ai.runxian.top/api/v1/agent/handoff/read，JSON 为 token，由企业咨询页面读取草稿。

所有消息 1–2000 字；requestKey 为 16–80 位字母数字、下划线或短横线，必须使用高熵随机值。首轮重试的 requestKey 可取回本轮会话，必须保密。conversationToken 为独立访问凭据，数据库仅存哈希；它不会进入模型上下文。会话保存 24 小时、最多 12 轮。使用模型时仅发送咨询消息和公开目录，勿发送密钥、联系方式或未授权的保密资料。mode=guided 表示预设引导，没有调用模型；mode=model 表示模型回复，仍需核实。

prepare_handoff 只创建不可变摘要快照，链接有效 24 小时，不会提交销售线索。链接含短期 bearer token，应仅交给客户本人；网页让客户核对摘要、填写联系方式并同意后才提交。原始对话不会自动成为咨询线索。报价、交付周期、采购、合同与实际系统操作始终需要人工确认。

限额：共用每 IP 每分钟 10 次咨询/转交、每分钟 120 次全局咨询配额；单进程最多 3 个并发咨询。模型体验另有每天每 IP 20 次、全局 100 次限额。未配置 Redis 时限额按进程并在重启后重置。客户端应遵守 429/错误中的重试提示。HTTP 网站来源限制和 SDK 的本地 Host 检查仍生效。

地址为部署的 APP_URL；127.0.0.1 仅本机可访问，正式供外部 Agent 使用必须部署到可访问的 HTTPS 域名并设置 APP_URL。本实现未声明已与任何特定外部客户端完成互操作验证。