Tool Agent 内部接口文档

1. 数据模型

1.1 枚举类型

枚举	值	说明
RuntimeType	`local`, `docker`, `api`, `browser`	运行时类型
SchedulingMode	`cold`, `hot`, `stateless`	调度模式
ToolState	`running`, `sleeping`, `stopped`, `degraded`	工具状态
ToolStatus	`active`, `inactive`, `staging`, `building`	工具生命周期
MessageType	`tool_request`, `tool_ready`, `tool_error`, `health_alert`	内部消息类型
ContainerStatus	`running`, `destroyed`	容器状态

1.2 ToolMeta（工具元信息）

{
  "tool_id": "image_compress_api",
  "name": "图片压缩 API",
  "category": "cv",
  "description": "基于 PIL 的图片压缩服务",
  "input_schema": {
    "type": "object",
    "properties": {
      "image_path": {"type": "string"},
      "quality": {"type": "integer", "minimum": 1, "maximum": 100}
    },
    "required": ["image_path"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "compressed_size": {"type": "integer"},
      "compression_ratio": {"type": "number"}
    }
  },
  "stream_support": false,
  "runtime": {
    "type": "docker",
    "entry": "",
    "container_id": "25e884ca6cec...",
    "host_dir": "C:/Users/user/staging/image_tool",
    "container_dir": "/app",
    "host_port": 9001,
    "internal_port": 8080,
    "endpoint_path": "/api/compress",
    "http_method": "POST",
    "env": {},
    "resource_limits": {"cpu": "1.0", "memory_mb": 512, "gpu": false}
  },
  "scheduling": {
    "mode": "hot",
    "idle_timeout_s": 300,
    "state": "running"
  },
  "stats": {
    "last_used_time": "2026-03-20T10:30:00Z",
    "call_count": 42,
    "avg_latency_ms": 125.5,
    "error_rate": 0.02
  },
  "fallback_strategy": [],
  "status": "active"
}

1.3 RuntimeInfo（运行时信息）

字段	类型	默认值	说明
`type`	RuntimeType	`"local"`	运行环境类型
`container_id`	str	`""`	Docker 容器 ID
`host_dir`	str	`""`	宿主机工作目录
`container_dir`	str	`"/app"`	容器内工作目录
`host_port`	int	`0`	宿主机映射端口（Router 调用入口）
`internal_port`	int	`0`	容器/进程内服务端口
`endpoint_path`	str	`"/"`	HTTP API 路径
`http_method`	str	`"POST"`	HTTP 方法
`env`	dict	`{}`	环境变量
`resource_limits`	ResourceLimits	`{}`	资源限制

1.4 ContainerInfo（容器信息）

{
  "container_id": "25e884ca6cecfa87e19ea737315a8773d...",
  "tool_id": "test_git_tool",
  "image": "ubuntu:22.04",
  "port_mapping": {"8080": 9001, "3306": 9002},
  "volumes": {"C:/staging/project": "/app"},
  "mem_limit": "1g",
  "nano_cpus": 1000000000,
  "use_gpu": false,
  "gpu_count": -1,
  "status": "running",
  "created_at": "2026-03-20T07:31:50.421101Z",
  "last_accessed": "2026-03-20T07:33:16.214642+00:00",
  "destroyed_at": null
}

2. 工具注册表格式 (registry.json)

路径：data/registry.json

{
  "tools": [
    { /* ToolMeta 对象，见 1.2 */ }
  ],
  "version": "1.0"
}

Registry 查询接口

get_endpoint(tool_id) 返回格式：

Docker 类型：

{
  "type": "docker",
  "url": "http://localhost:9001/api/compress",
  "host_port": 9001,
  "internal_port": 8080,
  "container_id": "abc123...",
  "host_dir": "C:/staging/project",
  "http_method": "POST"
}

Local 类型：

{
  "type": "local",
  "host_dir": "C:/tools/local/my_tool",
  "http_method": "POST",
  "endpoint_path": "/"
}

3. 容器状态表格式 (containers.json)

路径：data/containers.json

{
  "containers": [
    { /* ContainerInfo 对象，见 1.4 */ }
  ]
}

4. 任务书格式 (task_spec)

Router Agent 生成任务书，通过 MessageBus 发送给 Coding Agent。

4.1 GitHub 项目接入任务

{
  "type": "github_deploy",
  "repo_url": "https://github.com/user/project",
  "tool_name": "project_api",
  "runtime": "docker",
  "image": "python:3.12-slim",
  "ports": [8080],
  "description": "将该项目部署为 HTTP API 工具",
  "requirements": {
    "gpu": false,
    "memory_mb": 512
  },
  "api_spec": {
    "endpoint_path": "/api/run",
    "http_method": "POST",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {"type": "string"}
      }
    }
  }
}

4.2 自主编写工具任务

{
  "type": "build_tool",
  "tool_name": "text_summarizer_api",
  "runtime": "uv",
  "description": "编写一个文本摘要工具，接受文本输入，返回摘要",
  "requirements": {
    "gpu": false,
    "memory_mb": 256,
    "dependencies": ["transformers", "torch"]
  },
  "api_spec": {
    "endpoint_path": "/summarize",
    "http_method": "POST",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {"type": "string", "description": "待摘要文本"},
        "max_length": {"type": "integer", "description": "摘要最大长度"}
      },
      "required": ["text"]
    }
  }
}

4.3 工具修复任务

{
  "type": "repair_tool",
  "tool_id": "image_compress_api",
  "error": "HTTP 503: Service Unavailable",
  "container_id": "abc123...",
  "description": "工具健康检查失败，需要诊断并修复"
}

5. 内部消息格式 (AgentMessage)

Router Agent 与 Coding Agent 通过 asyncio.Queue 通信。

{
  "type": "tool_request | tool_ready | tool_error | health_alert",
  "payload": { }
}

5.1 tool_request（Router → Coding）

{
  "type": "tool_request",
  "payload": {
    "task_spec": "{ /* 任务书 JSON，见第 4 节 */ }",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "callback_url": "http://caller/callback"
  }
}

5.2 tool_ready（Coding → Router）

{
  "type": "tool_ready",
  "payload": {
    "tool_id": "image_compress_api",
    "result": "部署成功，工具已注册",
    "url": "http://localhost:9001/api/compress",
    "task_id": "550e8400-..."
  }
}

5.3 tool_error（Coding → Router）

{
  "type": "tool_error",
  "payload": {
    "tool_id": "failed_tool",
    "error": "依赖安装失败：torch 需要 CUDA 但未检测到 GPU",
    "task_id": "550e8400-..."
  }
}

5.4 health_alert（Router → Coding）

{
  "type": "health_alert",
  "payload": {
    "tool_id": "image_compress_api",
    "container_id": "abc123...",
    "error": "HTTP 503",
    "last_healthy": "2026-03-20T10:00:00Z"
  }
}

6. 对外 HTTP 接口

基础地址：http://localhost:8001

GET /health

// Response
{"status": "ok"}

GET /tools

返回工具目录（按类别）。

// Response
{
  "tools": [
    {
      "tool_id": "image_compress_api",
      "name": "图片压缩 API",
      "category": "cv",
      "description": "基于 PIL 的图片压缩",
      "status": "active"
    }
  ]
}

GET /tools/{tool_id}/schema

// Response
{
  "tool_id": "image_compress_api",
  "input_schema": { /* JSON Schema */ },
  "output_schema": { /* JSON Schema */ }
}

POST /tools/{tool_id}/invoke

// Request
{
  "params": {"image_path": "/path/to/img.jpg", "quality": 85},
  "stream": false
}

// Response（非流式）
{
  "status": "success",
  "result": {"compressed_size": 256000, "compression_ratio": 0.25},
  "error": null
}

// Response（流式 SSE，Accept: text/event-stream）
data: {"chunk": "处理中...", "done": false}
data: {"chunk": "完成", "done": true}

POST /tools/request

提交新工具需求（异步）。

// Request
{
  "description": "需要一个图片压缩工具",
  "callback_url": "http://caller/callback"
}

// Response
{
  "task_id": "550e8400-...",
  "status": "pending"
}

GET /tasks/{task_id}/status

// Response
{
  "task_id": "550e8400-...",
  "status": "completed",
  "result": {"tool_id": "image_compress_api", "url": "http://localhost:9001/api/compress"}
}

7. Coding Agent 工具接口

Coding Agent 通过 claude_agent_sdk 暴露以下 10 个工具：

Docker 环境

工具	必填参数	可选参数	返回
`create_docker_env`	`image`	`mem_limit`, `nano_cpus`, `ports`, `volumes`, `use_gpu`	`container_id`, `port_mapping`
`run_in_docker`	`container_id`, `command`	`is_background`, `timeout`	`exit_code`, `stdout`, `stderr` 或 `log_file`
`rebuild_docker_ports`	`container_id`, `ports`	`mem_limit`, `nano_cpus`	`new_container_id`, `port_mapping`
`destroy_docker_env`	`container_id`	—	`status`, `message`

本地 uv 环境

工具	必填参数	可选参数	返回
`create_uv_project`	`name`	`python_version`	`project_dir`
`run_in_uv`	`project_dir`, `command`	`timeout`	`exit_code`, `stdout`, `stderr`
`uv_add_dependency`	`project_dir`, `package`	`dev`	`status`, `message`

文件操作

工具	必填参数	返回
`write_file`	`path`, `content`	`status`, `path`, `size`
`read_file`	`path`	`status`, `path`, `content`

注册

工具	必填参数	可选参数	返回
`register_tool`	`tool_id`, `name`, `description`, `runtime_type`, `host_port`, `internal_port`	`category`, `input_schema`, `output_schema`, `container_id`, `host_dir`, `endpoint_path`, `http_method`	`status`, `tool_id`, `url`

8. 资源监控格式

SystemInfo（系统概览）

{
  "cpu_count": 16,
  "cpu_percent": 11.1,
  "memory_total_mb": 15653,
  "memory_available_mb": 2606,
  "memory_percent": 83.4,
  "disk_total_gb": 924.3,
  "disk_free_gb": 327.3
}

ResourceUsage（单工具资源占用）

{
  "cpu_cores": 1.0,
  "memory_mb": 512.0,
  "gpu_memory_mb": 0.0
}

资源分配检查规则

CPU：已分配 + 新请求 ≤ 系统总核数
内存：已分配 + 新请求 ≤ 系统总内存 × 80%（保留 20% 安全余量）

9. 配置参数

Settings（环境变量前缀：`TOOL_AGENT_`）

参数	类型	默认值	说明
`fastapi_port`	int	`8001`	对外 HTTP 端口
`mcp_port`	int	`8001`	MCP Server 端口
`docker_port_start`	int	`9001`	Docker 端口起始
`docker_base_image`	str	`"agent-sandbox:latest"`	默认基础镜像
`docker_mem_limit`	str	`"1g"`	默认容器内存
`docker_nano_cpus`	int	`1000000000`	默认 CPU（1 核）
`docker_ttl_seconds`	int	`1800`	容器自动清理 TTL
`cold_tool_idle_timeout_s`	int	`300`	冷工具空闲超时
`hot_tool_max_containers`	int	`5`	最大热工具容器数
`eviction_policy`	str	`"lru"`	置换策略
`monthly_limit_usd`	float	`100.0`	月预算上限
`single_tx_limit_usd`	float	`20.0`	单笔上限
`require_approval_above_usd`	float	`10.0`	需审批阈值
`health_check_interval_s`	int	`60`	健康检查间隔

运行时配置覆盖 (data/config.json)

{
  "cold_tool_idle_timeout_s": 300,
  "hot_tool_max_containers": 5,
  "eviction_policy": "lru",
  "budget": {
    "monthly_limit_usd": 100,
    "single_tx_limit_usd": 20,
    "require_approval_above_usd": 10,
    "spent_this_month_usd": 0
  }
}

10. 工作日志格式

LocalRunner 命令日志 (last_run.log)

路径：{project_dir}/last_run.log

Command: python main.py
Exit Code: 0
--- STDOUT ---
Server started on port 8080
--- STDERR ---
WARNING: Using development server

Coding Agent 执行日志（stdout）

2026-03-20 15:09:32 [tool_agent.tool.agent] INFO: [CodingAgent] Starting task: 部署 flask 项目...
2026-03-20 15:09:35 [tool_agent.tool.agent] INFO: [TOOL_USE] create_docker_env | {"image":"python:3.12-slim","ports":[8080]}
2026-03-20 15:09:40 [tool_agent.tool.agent] INFO: [TEXT] 正在创建 Docker 环境...
2026-03-20 15:10:15 [tool_agent.tool.agent] INFO: [TOOL_USE] register_tool | {"tool_id":"flask_api",...}
2026-03-20 15:10:16 [tool_agent.tool.agent] INFO: [DONE] duration=44000ms
2026-03-20 15:10:16 [tool_agent.tool.agent] INFO: [COST] $0.12

11. 财务记录格式

路径：data/billing_log.json

{
  "transactions": [
    {
      "provider": "openai",
      "amount_usd": 5.0,
      "description": "API Key 充值"
    }
  ]
}

预算检查规则

条件	行为
`amount ≤ single_tx_limit_usd`	Agent 自主完成
`amount > require_approval_above_usd`	暂停，通知用户审批
`spent_this_month + amount > monthly_limit_usd`	拒绝，通知预算超限

internal_api.md 13 KB История Исходник