# 调用任务MCP App工具

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

调用原任务中允许应用访问的工具。该动作可产生业务副作用，返回结果需同时检查is_error。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-runtime-tasks/{task_id}/mcp-apps/call
```

## 调用前准备

准备当前环境的个人访问令牌、工作区ID，以及已返回应用描述的运行任务。使用原任务的工具ID、应用资源URI或工具名称；当前身份仍须有智能体使用权限和相应连接/服务权限。参见[任务范围与结果](scope-and-results.md)。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-runtime-tasks/$TASK_ID/mcp-apps/call" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{"tool_name":"weather","arguments":{"city":"杭州"}}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | 当前环境的工作区ID，与X-Workspace-ID一致。 |
| `task_id` | string | 是 | 该应用所属的智能体运行任务ID。 |
| `X-Workspace-ID` | string | 是 | 请求所属工作区。 |
| `X-API-Key` | string | 是 | 当前环境的个人访问令牌。 |
| `tool_id` | string | 与tool_name至少一个 | 原任务工具ID；没有tool_name时使用。 |
| `tool_name` | string | 与tool_id至少一个 | 应用调用的工具名称；同时提供时优先按名称匹配。 |
| `arguments` | JSON值 | 按工具schema | 调用参数；示例为对象。省略/null不等于满足所选工具输入要求。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "content": [
      {
        "type": "text",
        "text": "示例结果"
      }
    ],
    "structured_content": {
      "city": "杭州"
    },
    "is_error": false
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功为0。 |
| `data.content` | JSON值（数组）或null | 工具返回的内容块，按具体内容类型读取。 |
| `data.structured_content` | JSON值 | 可选结构化结果；使用snake_case，与上游structuredContent区分。 |
| `data.is_error` | boolean | 工具是否报告执行失败；即使HTTP200也必须检查此值。 |

:::::
::::::
:::::::

## 错误响应

| HTTP / code | 条件与处理 |
| --- | --- |
| 400 / 2 | JSON或字段、URI、选择器不合法。 |
| 403 / 5 | 当前智能体使用或相应权限被拒绝。 |
| 404 / 3 | 任务不在当前范围，或工具/URI未绑定。 |
| 409 / 2 | 任务已failed、canceled或rejected，不能继续应用操作。 |
| 503 / 15 | 运行时或提供方不可用。 |
| 500 / 1 | 未分类内部或持久化失败；消息使用本地化通用说明。 |

错误使用本地化message；认证层还可能返回字符串code/msg。恢复及环境状态见 [任务内知识检索](../../../../developer/cli/tasks/runtime-knowledge.md)。
