6.6 从业务系统调用员工

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

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

创建集成凭据

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

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

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

0.2.4 真实界面，示例数据。

HTTP 与 OpenAPI

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

http

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

写操作必须先在业务系统保存幂等键。网络断开或未取得回包时，沿用相同 UUID 和相同正文重试；不同正文、动作、目标、permissionMode 或 model 复用原键会返回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?, permissionMode?, model?}；input 最多6000字符，标题最多120字符。继续正文为 {expectedVersion, input, permissionMode?, model?}，停止正文为 {expectedVersion}。额外字段会被拒绝。写操作返回202受理，不表示工作已经完成。

执行模式与模型

permissionMode：本轮执行边界，可选 danger-full-access、workspace-write、read-only。新工作未指定时默认 danger-full-access；续做未指定时继承上一轮。它不能绕过集成的 execute 权限、员工工具授权和工作台审批。
model：本轮模型选择，格式为 {provider, model, reasoningEffort?}。未指定时使用员工配置的默认模型；模型/provider 必须已配置且可用，否则工作以 model_unavailable 失败，不会静默换模型。
预设当前不可用时以 permission_mode_unavailable 失败；同一幂等键重试时，正文、权限模式和模型选择都必须与首次受理一致，否则返回409。

固定成功结果会自动创建正式成果、完成关联任务并更新工作进展；读取 result 得到固定正文，任务与成果版本在同一事务中落定。失败或交付不满足条件时不会留下半个成果，调用方可按原幂等键恢复。

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

运行完整的三入口示例

下载开发示例，使用 Node.js 24，在解压目录安装固定依赖：

npm install

准备一位独立测试员工，配置可用模型，在集成凭据中授予 read、execute、cancel。把 TELOA_BASE_URL 和 TELOA_API_KEY 放进可信的服务端环境：前者是你的 Teloa 地址，如 http://127.0.0.1:3100；后者是这次集成密钥，不是模型密钥。不要放进浏览器、示例源文件或命令历史。

按要验证的入口选择一条命令。每条都会运行真实模型，产生用量：

node employee-api.mjs
node employee-sdk.mjs
node employee-mcp.mjs

文件	实际调用方式
`employee-api.mjs`	Fetch 直接调用 HTTP API
`employee-sdk.mjs`	`@teloa/sdk@0.2.4`
`employee-mcp.mjs`	官方 MCP 客户端，通过 Streamable HTTP 调用七个员工工具
`employee-demo.mjs`	三入口共用的请求记录、轮询、续做、结果核验与取消流程

每个示例都执行：发现获准员工；提交虚构订单；等待并读取结果；在同一 work ID 下续做；核对旧结果仍可读取；再提交一项有界的长文本工作并请求取消。

预期订单小计为 115，优惠后为 110；续轮新增 6，得到 116。输出包含工作 ID、两轮结果和实际取消终态。结果及其校验和保存在 demo-output/<入口>/results.json。

每条写请求在发送前写入 commands.jsonl，保留 requestId、正文和回执，不保存密钥。已有输出目录会使示例在发请求前停止，避免误运行两次。网络失败后先查看已有工作，重试时沿用记录里的同一身份与正文；不要删除记录后重新发起。示例没有实现生产系统的恢复队列。

轮询超时不会停止服务端工作，waiting 需要本人回工作台处理。取消任务若已先完成，示例报告真实终态，不能把它算作取消成功。

在自己的代码中使用 SDK

npm install --save-exact @teloa/sdk@0.2.4

下面是可直接保存为 .mjs 的只读连接检查：

import {TeloaClient} from '@teloa/sdk'
const baseUrl = process.env.TELOA_BASE_URL
const apiKey = process.env.TELOA_API_KEY
if (!baseUrl || !apiKey) throw Error('Configure the integration URL and key first.')
const client = new TeloaClient({baseUrl, apiKey})
const {items} = await client.listEmployees()
console.log(items.map(employee => ({id: employee.id, name: employee.name})))

写入与恢复直接参考下载包中的完整代码。SDK 使用 Fetch，支持 AbortSignal 和超时，不自动重试写操作。其他语言按 OpenAPI 实现相同请求即可。

状态、成果与错误

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

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

result.text 是员工生成的文本，不保证符合你在提示词中请求的 JSON Schema。模型可能附带 Markdown 代码围栏；业务系统需要结构化数据时，应独立解析与校验字段、数值和业务约束，失败时保留原结果并明确处理，不直接将文本作为可信业务写入。

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

员工 API 还会用以下 error.code 说明可调整的原因：permission_mode_unavailable（请求的权限模式当前不可用）、model_unavailable（请求的 provider/model 不可用）、employee_changed（员工版本已变化，需重新授权）、work_busy（当前轮仍在执行）、result_not_ready（结果尚未固定）。这些错误不会静默换成别的模式或模型；调整配置后用新的请求处理，不要复用旧请求身份猜测结果。

供其他 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；teloa_start_work/teloa_continue_work 同样接受 permissionMode 和 model，继续和停止还须带工作版本。长任务快速返回工作 ID，再查询状态或成果，不把整个任务挂在一次工具连接上。当前未声明 MCP Tasks 扩展或 A2A 支持。

CloudEvents 签名回调

回调地址由本人创建集成时固定，不能由外部工作请求临时指定。状态变化通过 application/cloudevents+json 发送 CloudEvents 1.0 事件，类型为 ai.teloa.work.changed.v1。事件包含 Work 的状态、结果版本、权限模式、模型引用与链接等字段；不携带输入、密钥或成果正文。

请求头为 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.6 从业务系统调用员工 ​

创建集成凭据 ​

HTTP 与 OpenAPI ​

执行模式与模型 ​

运行完整的三入口示例 ​

在自己的代码中使用 SDK ​

状态、成果与错误 ​

供其他 Agent 调用的 MCP Server ​

CloudEvents 签名回调 ​