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

# 6.2 从业务系统调用员工

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

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

## 创建集成凭据

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

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

```sh
npm install @teloa/sdk
```

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