Env-Agent
Jouryjc/env-agent
Orquestra agents em múltiplos ambientes via Gateway com MCP
Ver no GitHubAgent de orquestração de ambientes em cascata que distribui intenções de um Claude Code central (PC) através de um Gateway para agents especializados em diferentes ambientes, coletando e retornando artefatos. Ideal para coordenar múltiplas máquinas ou contextos de execução com diferentes capacidades.
Instalação
npx convez-ai Jouryjc/env-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Distribuir tarefas para execução em múltiplos PCs/ambientes com capacidades diferentes
- Coordenar fluxos de trabalho que precisam rodar em máquinas específicas (drawio, docker, etc)
- Centralizar controle via Claude Code enquanto distribui execução conforme capacidades disponíveis
Veredito

Arquitetura sofisticada para orquestração distribuída que resolve o problema real de coordenar Claude em múltiplos contextos. Bem implementada com MCP e WebSocket, mas exige setup complexo e conhecimento avançado de arquiteturas multi-agente.
README
A tradução para o português deste README ainda está na fila.
env-agent
单 PC 的级联环境管理 agent。Claude Code(管理大脑)经 Gateway 把意图派发给各环境上的独立 agent,产物回传到 PC 查看。
架构概览:
Claude Code (PC)
↓ MCP (streamable-http)
Gateway (PC 常驻进程)
↓ WebSocket
Environment Agent A ─┐
Environment Agent B ─┤ (各环境独立运行)
Environment Agent … ─┘
安装
python3 -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"
注意:本项目的所有运行命令都使用
.venv/bin/python或先激活 venv 再执行,确保不受 shell 中python别名的影响。
跑 Gateway(PC 上,常驻)
ENV_AGENT_TOKEN=<你的token> .venv/bin/python -m env_agent.gateway.main
Gateway 启动后会同时监听两个端口:
- WS:
ws://127.0.0.1:8766(环境 agent 连这里) - MCP:
http://127.0.0.1:8765/mcp(Claude Code 连这里,见.mcp.json)
环境变量
Gateway 通过以下环境变量配置,均有默认值:
| 变量 | 默认值 | 说明 |
|---|---|---|
ENV_AGENT_TOKEN | change-me | 认证 token,必须与所有环境 agent 保持一致 |
ENV_AGENT_WS_HOST | 127.0.0.1 | WS 监听地址 |
ENV_AGENT_WS_PORT | 8766 | WS 监听端口 |
ENV_AGENT_MCP_HOST | 127.0.0.1 | MCP HTTP 监听地址 |
ENV_AGENT_MCP_PORT | 8765 | MCP HTTP 监听端口 |
ENV_AGENT_ARTIFACTS_DIR | ~/.env-agent/artifacts | 产物存储目录 |
重要:Gateway 与所有环境 agent 必须使用相同的 token,认证不匹配的连接会被立即断开。
接入 Claude Code
项目根已有 .mcp.json,内容如下:
{
"mcpServers": {
"env-agent": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
在该项目目录里启动 Claude Code,运行 /mcp 或 claude mcp list 应看到 env-agent 处于 connected 状态。
可用 MCP 工具:
list_environments()— 列出所有已知环境及其能力与在线状态find_environments(capability)— 按能力(软件、skill 名、manual 标签)查找在线环境dispatch(target, intent, by_capability, timeout)— 把意图派发给某环境并等待结果get_task(task_id)— 查询任务状态、进度日志、产物 idlist_artifacts(task_id?)— 列出已存储的产物,可按 task_id 过滤open_artifact(artifact_id)— 在 PC 上用默认应用打开产物文件
跑环境 Agent(每个环境上)
1. 准备配置文件 env-agent.yaml
env_id: A
gateway_url: ws://<PC内网IP>:8766
token: <同一个token>
software_probe: [drawio, node, python3, docker, git]
manual_capabilities:
role: 业务后端环境
字段说明:
env_id:环境唯一标识,Gateway 和 Claude Code 通过它路由任务gateway_url:Gateway 的 WS 地址,若在同一局域网填内网 IPtoken:必须与 Gateway 的ENV_AGENT_TOKEN一致software_probe:自动探测这些命令是否存在,探测结果作为software能力上报manual_capabilities:手动声明的能力标签,用于find_environments()检索
2. 启动
环境上需先安装好 Claude Code CLI 并完成登录(或设置 ANTHROPIC_API_KEY):
# 在环境机器上(首次:创建 venv 并安装,同「安装」一节)
python3 -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"
.venv/bin/python -m env_agent.agent.main env-agent.yaml
Agent 启动后会自动连接 Gateway 并注册能力,Gateway 端会打印 registered。断连后会自动重试。
用法
在 Claude Code 里直接用自然语言描述意图,例如:
「用能力 drawio 的环境画订单服务架构图,画完打开给我看」
Claude Code 内部的调用链:
find_environments("drawio")— 找到有 drawio 能力的环境(如A)dispatch("drawio", "画订单服务架构图", by_capability=True)— 把意图派发到环境 A- 环境 A 上的 agent 执行,产出
.drawio文件,分片上传回 Gateway - Gateway 组装文件,dispatch 返回
status: done list_artifacts(task_id=...)— 查看产物列表open_artifact(artifact_id)— 在 PC 上用 drawio 打开文件
开发与测试
# 激活 venv
. .venv/bin/activate
# 跑全量测试(含端到端集成测试)
.venv/bin/pytest -q
# 只跑端到端测试
.venv/bin/pytest tests/test_end_to_end.py -v
预期:49 passed。
真机 drawio 冒烟测试(手动验收)
完整的人工端到端验收流程:
前提:
- PC 上已安装本项目并完成
pip install -e ".[dev]" - 至少一台环境机器上安装好 Claude Code CLI 并登录(或配置
ANTHROPIC_API_KEY) - 环境机器的
.claude/skills/目录下有能产出.drawio文件的 skill
步骤:
-
PC 上启动 Gateway:
ENV_AGENT_TOKEN=mytoken .venv/bin/python -m env_agent.gateway.main确认控制台输出:
[gateway] WS listening on ws://127.0.0.1:8766 [gateway] MCP (streamable-http) on http://127.0.0.1:8765/mcp -
环境机器上启动 agent:
准备
env-agent.yaml(gateway_url填 PC 内网 IP,token与上面一致),然后:.venv/bin/python -m env_agent.agent.main env-agent.yaml确认 Gateway 端控制台打印
registered(或 agent 端打印registered with ws://...)。 -
PC 上确认 MCP 连通:
在该项目目录的 Claude Code 里运行:
claude mcp list或
/mcp,应看到env-agent状态为 connected。 -
发送任务:
在 Claude Code 里说:
「用环境 A 画一个简单的订单服务架构图,输出 .drawio 文件」
-
预期结果:
dispatch返回status: donelist_artifacts看到*.drawio文件open_artifact在 PC 上用 drawio 打开文件并显示架构图
-
失败排查:
如果任务未正常完成,用
get_task(task_id)查看progress日志和error字段定位问题。常见原因:- token 不匹配:检查 Gateway 的
ENV_AGENT_TOKEN与env-agent.yaml中的token - 环境未注册:检查 agent 是否成功启动并与 Gateway 建立 WS 连接
- skill 缺失:检查环境机器
.claude/skills/下是否有对应的 drawio skill;若 skill 放在非默认路径,在env-agent.yaml中设置skills_dirs: ["/your/path/skills"] - 超时:适当调大
dispatch的timeout参数(默认 600 秒)
- token 不匹配:检查 Gateway 的