---
docStatus: current
---

# 外部 Agent Runtime 接入

使用独立执行 Token 发现并调用当前授权的 Runtime 方法。

外部 Agent 使用独立的 `lc_agent_` 执行 Token，通过平台公网 `/agent/v1/agent-api-service/api/**`
访问 Runtime 能力。平台内部 Agent 使用 Session 授权；两个入口使用同一套 Runtime 授权目录和方法执行协议。

## 身份与授权

执行 Token 由 Access Credential Service 按已授权用户签发，绑定用户、工作区、有限的 `accessGrantId` 和到期时间。
Token 只在签发时返回明文。`accessGrantId` 是授权记录的标识，不能当作 Bearer Token。
执行凭证始终受签发用户的权限和凭证撤销状态约束。

每次发现或执行都检查 Token、Grant 和当前工作区 IAM。撤销 Token、撤销 Grant 或收回用户权限后，后续请求拒绝。
调用方不能通过提交 `userId`、`accessGrantId`、`credentialId` 或 `context_map` 改变执行身份。
`workspaceId` 只是与凭据绑定核对的业务选择器。

配置中的 `all`、`selected`、`none` 只控制候选方法范围，不能绕过授权。
`all` 形成授权时的方法快照，后来安装的方法不会自动进入已有 Grant。

## 发现服务与方法

向 `POST /agent/v1/agent-api-service/api/runtime-services/query` 发送 JSON，并在标准
`Authorization: Bearer <执行 Token>` 中携带凭据。公网地址从所属平台环境的 API 配置读取。

```json
{
  "contractVersion": "1.0.0",
  "workspaceId": 42,
  "applicationRuntimeId": "your-runtime-id"
}
```

工作区和 Runtime ID 必须替换为实际授权目标。结果使用 [CModel](/integration/cmodel-error-model/) 信封，
`data.services` 只包含当前允许访问的方法。每个服务含 `businessId`、`serviceName` 和 `methods`；
方法含 `methodName` 与完整的 `method_definition`，调用前按其中的参数和返回类型准备数据。

需要查询指定服务或方法时，可增加 `businessId`，以及该服务下的 `method`。没有可用方法的服务不会出现在结果中。
空目录表示本次授权范围中没有可用方法，不能单凭空目录断言工作区未安装服务。

## 执行方法

向 `POST /agent/v1/agent-api-service/api/runtime-methods/execute` 发送：

```json
{
  "contractVersion": "1.0.0",
  "workspaceId": 42,
  "applicationRuntimeId": "your-runtime-id",
  "businessId": "service-from-discovery",
  "method": "method-from-discovery",
  "params": {}
}
```

`params` 必须是符合目标 `method_definition` 的对象。服务在执行前重新校验该准确方法的授权，
不会把上一次发现结果当作后续调用的授权证明。未知字段、未知合同版本和工作区冲突会拒绝。

成功和失败均使用 CModel 信封，消费方检查 `errorCode`；下游业务错误保留原 Owner 的错误码与错误内容。
调用不自动重试。连接超时可能发生在业务副作用已经完成之后，是否重试应遵循目标方法自身的幂等合同。

执行入口只提供 Runtime 发现和执行；管理、会话创建、员工/设备登记、健康探针及 `/inner/**` 不属于此入口。