发现和管理工具¶
工具让智能体读取外部数据或执行具体动作。管理工具时，重点不是“接口能否创建资源”，而是确认工具从哪里执行、需要什么凭据、输入输出是否清楚，以及调用是否会产生副作用。
开始之前¶
请准备 Product API Base URL、个人访问令牌和工作区 ID。若工具访问第三方服务，还需要该服务提供的凭据和最小必要权限。
选择系统工具或工作区工具¶
类型 |
何时使用 |
管理方式 |
|---|---|---|
系统工具 |
平台已经提供且当前运行时支持的通用能力 |
查询并检查是否可绑定，不修改系统定义。 |
工作区工具 |
当前团队创建或从 MCP 服务导入的能力 |
在工作区内创建、更新、配置凭据和归档。 |
使用 catalog=system 或 catalog=workspace 查询对应目录。列表中的 bindable 和 bindability_reason 用于判断工具当前是否可以绑定；不要只根据工具名称推断可用性。
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 描述稳定契约：
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。归档工具不会撤销工具已经产生的外部动作。