6.2 从业务系统调用员工

业务系统可以把订单核对、资料整理、工单分析等工作交给已有 AI 员工，并按工作 ID 跟进结果。HTTP、SDK 和 MCP 共用员工、业务范围、BYOK 与 Task/Run 执行链路。

这是调用 Teloa 员工的入口；让员工读取外部服务，见员工使用 MCP。

创建集成凭据

在设置 > 员工对外调用选择一名在岗且职责完整的员工，确定业务范围与有效期。默认只允许读取；本人勾选后，才允许发起、继续或请求停止工作。创建凭据不会自动执行任务，也不会增加员工的工具权限。

API Key 只显示一次，放进业务系统服务端的密钥管理器。不要贴进会话、浏览器前端或代码仓库。回调地址可选；若填写，另有只显示一次的回调签名密钥，应一起保存。回调签名密钥丢失时，撤销并新建集成。

密钥绑定员工配置版本与一个业务范围；修改职责、工具授权或恢复在岗等导致版本变化后，需本人重新授权。
每个集成同时最多允许1至4项未结束工作，由本人创建时选择；实际执行仍经过平台容量与原工作额度检查。
轮换立即使旧 API Key 失效，同一集成的工作和结果保留，回调签名密钥不随 API Key 轮换。
撤销或过期后拒绝新请求，停止尚未派发的队列及后续回调。已接受的执行需在工作台另行停止；已在途的外部请求可能完成。
不接受浏览器启动令牌或 Cookie 代替集成密钥，不允许接口调用方代批工具、修改员工或选择 Full access。

HTTP 与 OpenAPI

宿主提供 /api/v1/openapi.json，采用 OpenAPI 3.1，内含请求与响应 JSON Schema。业务 API 请求使用：

http

Authorization: Bearer <集成密钥>
Content-Type: application/json
Idempotency-Key: <调用方持久保存的 UUID>

写操作必须先在业务系统保存幂等键。网络断开或未取得回包时，沿用相同 UUID 和相同正文重试；不同正文、动作或目标复用原键会返回409。SDK 不自动生成新请求身份或重试写操作。

操作	HTTP 路径	权限
发现获准员工	`GET /api/v1/employees`	read
发起工作	`POST /api/v1/works`	execute
查询状态与版本	`GET /api/v1/works/{workId}`	read
补充下一轮要求	`POST /api/v1/works/{workId}/inputs`	execute
请求停止	`POST /api/v1/works/{workId}/cancel`	cancel
读取固定成果	`GET /api/v1/works/{workId}/result?version=1`	read
恢复事件读取	`GET /api/v1/works/{workId}/events?after=0`	read

发起正文为 {employeeId, input, title?}；input 最多6000字符，标题最多120字符。继续正文为 {expectedVersion, input}，停止正文为 {expectedVersion}。额外字段会被拒绝。写操作返回202受理，不表示工作已经完成。

继续工作须等当前轮结束，再提交最新 expectedVersion。工作 ID 保持不变，新增一轮 Task/Run；本轮应提供完整要求，宿主附带上一轮固定结果最多1500字符作为上下文。旧结果可按原版本读取。

TypeScript / JavaScript SDK

npm install @teloa/sdk

import {TeloaClient} from '@teloa/sdk'

const client = new TeloaClient({baseUrl, apiKey})
const {items: employees} = await client.listEmployees()
// requestId 已由业务系统持久保存。
const work = await client.startWork({
  employeeId: employees[0].id,
  input: '请核对下面这批已授权的订单资料……',
}, {requestId})

const current = await client.getWork(work.id)
if (current.state === 'succeeded') {
  const result = await client.getResult(work.id)
  // 保存 result.version、sha256、review 与业务回写收据。
}

SDK 无额外运行依赖，使用 Fetch，支持 AbortSignal 与超时。远程使用 HTTPS，本机回环可用 HTTP；不跟随重定向。其他语言可依据 OpenAPI 调用 HTTP，无需模拟内部 RPC。

状态、成果与错误

状态	含义
queued	工作已保存，尚未派发
running	原生执行已受理或正在运行
waiting	等待审批、本人恢复或处理阻断
succeeded	本轮正常结束，并固定了非空结果
failed	本轮未取得有效结果或配置已失效
cancel_requested	已请求停止，尚未确认收口
cancelled	已确认取消，或派发前已撤回

固定结果包含工作 ID、轮次、版本、正文、SHA-256 与 review: accepted|unreviewed。执行成功不等于成果复核通过；复核状态也不替代业务系统或本人的最终验收。需要审批时由本人在工作台处理，API 不代替本人批准工具。

错误以 {error:{code,message,requestId}} 返回。401表示凭据无效、过期或被轮换/撤销；403表示操作未授权；404表示工作不属于此集成或版本不存在；409表示版本、幂等正文或工作状态冲突；413/415表示正文过大或类型不符；429表示达到本集成并发上限；503表示服务暂不可用。超时后使用原幂等身份恢复，不能默认重新执行。

供其他 Agent 调用的 MCP Server

MCP 地址为宿主 /mcp，使用 Streamable HTTP，以同一个集成 Bearer Key 鉴权。工具为：

teloa_list_employees、teloa_start_work、teloa_get_work、teloa_continue_work、teloa_cancel_work、teloa_get_result、teloa_list_work_events。

只公布此密钥获准的操作，直接猜测未公布的工具名也不能扩大权限。写工具携带持久 requestId，继续和停止还须带工作版本。长任务快速返回工作 ID，再查询状态或成果，不把整个任务挂在一次工具连接上。当前未声明 MCP Tasks 扩展或 A2A 支持。

CloudEvents 签名回调

回调地址由本人创建集成时固定，不能由外部工作请求临时指定。状态变化通过 application/cloudevents+json 发送 CloudEvents 1.0 事件，类型为 ai.teloa.work.changed.v1。事件只有工作状态与成果版本，不携带输入、密钥或成果正文。

请求头为 teloa-webhook-id、teloa-webhook-timestamp、teloa-webhook-signature。签名是：

text

v1=<HMAC-SHA256(signingSecret, timestamp + "." + rawBody) 的十六进制值>

先用原始正文验证签名与时间窗口，再解析 JSON。SDK 的 verifyWebhook 默认接受前后5分钟的时间窗口。接收方应持久保存事件 ID 去重，并按工作版本处理可能乱序的通知；一次签名验证本身不提供去重。

单次投递上限10秒，不跟随重定向，失败最多自动尝试5次。每次重试沿用固定事件 ID，成功须返回2xx。可在设置中查看投递状态并手动重投失败事件；队列、游标、固定结果与待投递事件保留到重启之后。CloudEvents 规定事件信封，投递可靠性由 Teloa 的持久记录、租约和重试实现。

6.2 从业务系统调用员工 ​

创建集成凭据 ​

HTTP 与 OpenAPI ​

TypeScript / JavaScript SDK ​

状态、成果与错误 ​

供其他 Agent 调用的 MCP Server ​

CloudEvents 签名回调 ​