MCP 与外部工具

通过 MCP 或工具连接外部能力，让智能体在授权范围内执行任务。

MCP 和外部工具可以把第三方系统能力接入智能体，例如查询内部系统、读取文件、调用业务接口或执行自动化动作。

接入设置

工具权限应按工作区和业务场景收敛。
敏感操作需要有明确确认或权限控制。
工具返回应结构化，方便智能体判断下一步。

测试工具

绑定智能体后，用真实任务测试工具调用，确认入参、返回、错误提示和日志记录都符合预期。

外部 Agent 调用平台 Runtime

外部 Agent 可以通过平台的 MCP 服务发现当前 Runtime 中获准访问的 Module，并调用其方法。使用目标环境登记的 API 地址，MCP 路径为 /agent/v1/agent-api-service/api/mcp，传输方式为 Streamable HTTP。连接使用当前工作区签发的 Agent 执行凭据；工作区、执行用户及权限由凭据确定。

工具	用途	资源选择参数
`search_resources`	按名称、描述或 Locator 搜索可见资源，每页最多 20 项	`applicationRuntimeId`、`query`，后续页使用返回的 `nextOffset`
`describe_resource`	读取资源的方法和参数定义	`applicationRuntimeId`、完整 `resourceLocator`，可选 `method`
`execute_resource_method`	调用已授权的方法	`applicationRuntimeId`、完整 `resourceLocator`、`method`、`params`

先搜索资源，再使用返回的完整 Locator 查询方法定义并调用。例如，source/orders/MODULE/order-service 表示来源环境 source、Bundle orders 中的 order-service Module。Locator 不包含版本；实际调用使用 Runtime Owner 当前选择的版本和执行入口。

查询成功不代表获得方法执行权限。每次调用都会检查当前授权；撤销授权后，后续调用会失败。业务参数中的 userId 等字段不改变执行主体。写入调用超时后结果可能未知，应先查询业务结果，再决定是否重试。

HTTP 调用

同一执行凭据也可调用 /agent/v1/agent-api-service/api/runtime-resources/query 和 /agent/v1/agent-api-service/api/runtime-resources/execute。请求需要完整 Runtime 身份，workspaceId 必须与凭据所属工作区一致。

查询一个 Module 的方法：

{
  "contractVersion": "1.0.0",
  "workspaceId": 42,
  "applicationRuntimeId": "owner-returned-runtime-id",
  "scope": {
    "kind": "RESOURCE",
    "resourceLocator": "source/orders/MODULE/order-service"
  },
  "method": "readOrder"
}

调用方法：

{
  "contractVersion": "1.0.0",
  "workspaceId": 42,
  "applicationRuntimeId": "owner-returned-runtime-id",
  "resourceLocator": "source/orders/MODULE/order-service",
  "method": "readOrder",
  "params": { "orderId": "example-order" }
}

查询结果中的资源使用 resourceLocator 标识，返回当前方法定义；调用保留方法自身的 CModel 结果和业务错误。迁移期间，原有 search_services、describe_service、execute_method 及其 HTTP 入口继续保持原合同。新接入使用上面的 Locator 入口。

接入设置

测试工具

外部 Agent 调用平台 Runtime

HTTP 调用

本页内容