Tool_Agent/docs/internal_api.md

Tool Agent 内部接口文档

目录

1. 数据模型
2. 工具注册表格式
3. 容器状态表格式
4. 任务书格式
5. 内部消息格式
6. 对外 HTTP 接口
7. Coding Agent 工具接口
8. 资源监控格式
9. 配置参数
10. 工作日志格式
11. 财务记录格式

---

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	拒绝，通知预算超限