---
title: 从业务系统调用员工
description: 使用 HTTP API、TypeScript SDK、MCP 与签名回调接入现有 AI 员工。
lastVerified: 2026-10-23
---

# 6.6 从业务系统调用员工

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

这是**调用 Teloa 员工**的入口；让员工读取外部服务，见[员工使用 MCP](https://docs.teloa.ai/markdown/develop/mcp.md)。

## 创建集成凭据

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

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

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

[![创建员工集成凭据前的权限与范围表单；尚未创建密钥或执行工作。](https://docs.teloa.ai/assets/screenshots/employee-api-024.971227cf2aa8.png)](https://docs.teloa.ai/assets/screenshots/employee-api-024.971227cf2aa8.png)

*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字符作为上下文。旧结果可按原版本读取。

## 运行完整的三入口示例

[下载开发示例](https://docs.teloa.ai/examples/developer-toolkit-028.zip)，使用 Node.js 24，在解压目录安装固定依赖：

```sh
npm install
```

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

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

```sh
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

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

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

```js
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 的持久记录、租约和重试实现。