Tools API 提供对 Shannon 工具注册表的直接访问。您可以浏览可用工具、查看参数 Schema，以及绕过完整的任务工作流直接执行工具。
功能特性
- 工具发现 — 浏览所有可用工具，支持按类别过滤
- JSON Schema 查看 — 获取任意工具的完整参数 Schema
- 直接执行 — 在 Agent 工作流之外直接调用工具
- 危险工具拦截 — 被标记为危险的工具在 Gateway 层自动隐藏和拦截
- 用量追踪 — 每次执行记录 Token 消耗和成本
- Session 上下文 — 可选绑定到 Session（仅保留
session_id 和 user_id）
安全模型
Shannon 对标记为 dangerous 的工具实施严格的安全边界：
- List 端点自动应用
exclude_dangerous=true — 危险工具永远不会暴露
- Get 和 Execute 端点对危险工具返回
403 Forbidden
- 工具元数据在每个 Gateway 实例中缓存 5 分钟
- 工具执行的 HTTP 客户端超时时间为 120 秒
危险工具无法通过任何公共 API 端点访问。此限制在 Gateway 层强制执行，客户端无法绕过。
列出工具
列出所有可用工具。危险工具会自动排除。
curl http://localhost:8080/api/v1/tools \
-H "Authorization: Bearer <token>"
查询参数
| 参数 | 类型 | 必填 | 描述 |
|---|
category | string | 否 | 按类别过滤工具（如 "search"、"code"） |
按类别过滤示例
curl "http://localhost:8080/api/v1/tools?category=search" \
-H "Authorization: Bearer <token>"
[
{
"name": "web_search",
"description": "Search the web for current information",
"category": "search",
"version": "1.0",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results",
"default": 10
}
},
"required": ["query"]
},
"timeout_seconds": 30,
"cost_per_use": 0.004
}
]
获取工具
获取指定工具的元数据和参数 Schema。
curl http://localhost:8080/api/v1/tools/web_search \
-H "Authorization: Bearer <token>"
路径参数
{
"name": "web_search",
"description": "Search the web for current information",
"category": "search",
"version": "1.0",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results",
"default": 10
}
},
"required": ["query"]
},
"timeout_seconds": 30,
"cost_per_use": 0.004
}
执行工具
使用提供的参数直接执行指定工具。
curl -X POST http://localhost:8080/api/v1/tools/web_search/execute \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"arguments": {
"query": "latest AI news",
"max_results": 5
},
"session_id": "optional-session-id"
}'
路径参数
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|
arguments | object | 是 | 与工具参数 Schema 匹配的工具特定参数 |
session_id | string | 否 | 用于上下文绑定的 Session ID |
提供 session_id 时，仅 session_id 和 user_id 会传递给工具。出于安全考虑，tenant_id 等其他 Session 字段会被剥离。
{
"success": true,
"output": {
"results": [
{
"title": "Major AI Breakthrough Announced",
"url": "https://example.com/ai-news",
"snippet": "Researchers announce a significant advancement in..."
}
]
},
"text": "Found 5 results for 'latest AI news'",
"error": null,
"metadata": {
"source": "searchapi"
},
"execution_time_ms": 1234,
"usage": {
"tokens": 7500,
"cost_usd": 0.004
}
}
响应字段
| 字段 | 类型 | 描述 |
|---|
success | boolean | 执行是否成功完成 |
output | object | 工具返回的结构化输出 |
text | string | 人类可读的结果摘要 |
error | string | null | 执行失败时的错误消息 |
metadata | object | 工具特定的元数据（如数据来源） |
execution_time_ms | integer | 执行耗时（毫秒） |
usage.tokens | integer | 本次执行的 Token 数量 |
usage.cost_usd | number | 预估成本（美元） |
用量以异步方式（fire-and-forget）记录到 token_usage 表。Token 数量为合成值：max(100, int(cost_usd / 0.000002))。
工具响应对象
| 字段 | 类型 | 描述 |
|---|
name | string | 工具标识符 |
description | string | 人类可读的描述 |
category | string | 工具类别（如 "search"、"code"、"data"） |
version | string | 工具版本 |
parameters | object (JSON Schema) | 工具的参数 Schema |
timeout_seconds | integer | 允许的最大执行时间 |
cost_per_use | number | 每次调用的预估成本（美元） |
错误响应
| 状态码 | 错误 | 描述 |
|---|
| 400 | Bad request | 缺少工具名称或请求体无效 |
| 401 | Unauthorized | 缺少或无效的认证信息 |
| 403 | Forbidden | 工具被标记为危险，无法访问 |
| 404 | Tool not found | 指定名称的工具不存在 |
| 502 | Bad gateway | LLM Service（工具后端）不可用 |
{
"error": "error message here"
}
危险工具错误
尝试通过 Get 或 Execute 访问危险工具时返回：
{
"error": "Tool not available via direct execution"
}
后续步骤
