# 发现和管理工具

工具让智能体读取外部数据或执行具体动作。管理工具时，重点不是“接口能否创建资源”，而是确认工具从哪里执行、需要什么凭据、输入输出是否清楚，以及调用是否会产生副作用。

## 开始之前

请准备 Product API Base URL、个人访问令牌和工作区 ID。若工具访问第三方服务，还需要该服务提供的凭据和最小必要权限。

## 选择系统工具或工作区工具

| 类型 | 何时使用 | 管理方式 |
| --- | --- | --- |
| 系统工具 | 平台已经提供且当前运行时支持的通用能力 | 查询并检查是否可绑定，不修改系统定义。 |
| 工作区工具 | 当前团队创建或从 MCP 服务导入的能力 | 在工作区内创建、更新、配置凭据和归档。 |

使用 `catalog=system` 或 `catalog=workspace` 查询对应目录。列表中的 `bindable` 和 `bindability_reason` 用于判断工具当前是否可以绑定；不要只根据工具名称推断可用性。

```bash
curl "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/tools?catalog=system&limit=50&offset=0" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 创建工作区工具

下面定义一个从远程 HTTP 服务读取工单的工具。`source_ref` 描述执行来源，`input_schema` 和 `output_schema` 描述稳定契约：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/tools" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get-ticket",
    "description": "Read one support ticket by ID.",
    "status": "active",
    "kind": "http_api",
    "category": "support",
    "source_ref": {
      "type": "http_api",
      "uri": "<HTTPS_TOOL_ENDPOINT>"
    },
    "input_schema": {
      "type": "object",
      "properties": {
        "ticket_id": {"type": "string"}
      },
      "required": ["ticket_id"]
    },
    "output_schema": {
      "type": "object"
    },
    "side_effect_class": "read"
  }'
```

成功后保存 `data.id`。创建工具不会验证远程服务一定可达，也不会把工具自动绑定到智能体。

## 检查绑定条件

读取工具详情，至少确认：

- `input_schema` 是否足以让模型正确构造参数；
- `output_schema` 是否能让后续步骤判断结果；
- `side_effect_class` 是否与真实行为一致；
- `credential_ref` 是否已经配置且权限足够；
- `supported_runtimes` 是否包含目标智能体使用的运行时；
- `bindable` 是否为可绑定状态。

写入、发送、删除或触发部署等操作应标记真实副作用，并配置批准和脱敏策略。Schema 不能代替服务端权限检查。

## 连接第三方服务

Product API 为 GitHub、邮件和 Grafana 等工具提供专用连接入口。连接请求中的密钥只用于创建凭据引用；后续查询应返回连接状态或 `credential_ref`，不应回显明文密钥。

连接完成后，重新读取工具详情并运行一次只读验证。断开连接前，先检查引用该凭据的智能体、技能和自动化任务。

## 更新和归档

修改工具名称、Schema、来源或策略后，重新验证所有绑定方。确认没有运行中的任务依赖该工具后，将状态更新为 `archived`。归档工具不会撤销工具已经产生的外部动作。

## 下一步

- [连接 MCP 服务并导入工具](../mcp-connections/connect-import-tools.md)
- [创建和管理技能](../skills/manage-skills.md)
- [查询工具 API](api-reference.md)