convez.ai
AgenteAutomaçãoAvançado
Jouryjc

Env-Agent

Jouryjc/env-agent

Orquestra agents em múltiplos ambientes via Gateway com MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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-agent

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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_TOKENchange-me认证 token,必须与所有环境 agent 保持一致
ENV_AGENT_WS_HOST127.0.0.1WS 监听地址
ENV_AGENT_WS_PORT8766WS 监听端口
ENV_AGENT_MCP_HOST127.0.0.1MCP HTTP 监听地址
ENV_AGENT_MCP_PORT8765MCP 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) — 查询任务状态、进度日志、产物 id
  • list_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 地址,若在同一局域网填内网 IP
  • token:必须与 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 内部的调用链:

  1. find_environments("drawio") — 找到有 drawio 能力的环境(如 A)
  2. dispatch("drawio", "画订单服务架构图", by_capability=True) — 把意图派发到环境 A
  3. 环境 A 上的 agent 执行,产出 .drawio 文件,分片上传回 Gateway
  4. Gateway 组装文件,dispatch 返回 status: done
  5. list_artifacts(task_id=...) — 查看产物列表
  6. 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

步骤:

  1. 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
    
  2. 环境机器上启动 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://...)。

  3. PC 上确认 MCP 连通:

    在该项目目录的 Claude Code 里运行:

    claude mcp list
    

    或 /mcp,应看到 env-agent 状态为 connected。

  4. 发送任务:

    在 Claude Code 里说:

    「用环境 A 画一个简单的订单服务架构图,输出 .drawio 文件」

  5. 预期结果:

    • dispatch 返回 status: done
    • list_artifacts 看到 *.drawio 文件
    • open_artifact 在 PC 上用 drawio 打开文件并显示架构图
  6. 失败排查:

    如果任务未正常完成,用 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 秒)
Ver o original no GitHub

Bom para

Relacionados