Human In The Loop Agent

“Human-in-the-Loop (Goop)”可以翻译为“人在环中（或人机协作）（Goop）”，但这里“Goop”一词在常规语境下并不直接与“人在环中”相关联，且可能是一个特定上下文或品牌名称中的术语。如果“Goop”在这里没有特殊含义或是一个误写（比如原意可能是“Loop”但误写为“Goop”），那么更简洁的翻译可以是“人在环中（Human-in-the-Loop）”。如果“Goop”确实有其特定的含义或背景，请根据具体情境进行调整。因此，一个较为通用的翻译是“人在环中（Human-in-the-Loop）（注：此处‘Goop’若无特殊含义则省略或根据上下文解释）”

一个基于LangGraph和MCP（模型上下文协议）构建的最小化人类参与式代理。它实时流式传输响应，对敏感工具调用进行人工审批控制，并使用Docker化的MCP文件系统服务器来安全访问文件。

特点/功能

• 受保护工具的人工审核： create_directory， edit_file， move_file， write_file.
• 流式输出 带有清晰的工具调用注释。
• YOLO模式切换 在需要时跳过人工审批。
• MCP文件系统服务器 通过Docker，沙箱化到一个可配置的工作空间。

要求

• python3.13+
• Docker已安装并运行（拉取 mcp/filesystem （图像自动）
• OpenAI API密钥对于默认设置 ChatOpenAI 模型

安装

cd /Users/m_warid/Desktop/dev/human-in-the-loop
python -m venv .venv && source .venv/bin/activate
pip install -U pip
# Project deps + a small runtime extra used by the CLI
pip install -e . nest_asyncio

工作流图

flowchart LR
  start((START))
  finish((END))

  assistant["assistant_node
LLM: respond or call tools"]
  tools["Tools (ToolNode wrapper)"]
  human["human_tool_review_node
interrupt() and wait"]

  d_toolcalls{Tool calls present?}
  d_yolo{yolo_mode?}
  d_protected{Any protected tool?}
  d_review{Review action?}

  legend["protected_tools:
- create_directory
- edit_file
- move_file
- write_file"]

  start --> assistant
  assistant --> d_toolcalls

  d_toolcalls -->|no| finish
  d_toolcalls -->|yes| d_yolo

  d_yolo -->|yes| tools
  d_yolo -->|no| d_protected

  d_protected -->|yes| human
  d_protected -->|no| tools

  tools -->|after tool result| assistant

  human --> d_review

  d_review -->|continue / update| tools
  d_review -->|feedback / reject / default| assistant

  assistant -.-> legend

配置

设置MCP文件系统服务器可访问的工作区目录，并提供您的OpenAI密钥。

export WORKSPACE="/absolute/path/you/want/to/expose"   # e.g., $PWD
export OPENAI_API_KEY="sk-..."

跑

python -m frontend.chat_local

• 该应用程序会实时打印出助手的消息。
• 当请求使用受保护的工具时，系统会提示您进行选择： reject， continue， update，或 feedback。
• 类型 exit 或者 quit 在用户提示下停止。

它是如何工作的

• src/goop/graph.py 构建一个与从MCP服务器发现的工具绑定的LangGraph代理（通过 MultiServerMCPClient）。
• 受保护的工具会触发一个在人工审核节点中处理的中断；您的决定将控制该工具是否执行以及如何执行。
• frontend/chat_local.py 运行图表，流式传输令牌，并管理人工审批流程。

项目布局

/frontend/
  chat_local.py        # CLI runner with streaming + approvals
/src/goop/
  graph.py             # LangGraph definition and human review node
  config.py            # Loads and resolves env vars in mcp_config.json
  mcp_config.json      # Dockerized MCP filesystem server binding ${WORKSPACE}
pyproject.toml         # Project metadata and dependencies
README.md              

安全

• 基于Docker的工具沙盒文件系统工具在Docker容器中运行（mcp/filesystem（仅使用绑定挂载到） WORKSPACE该代理无法在该路径之外进行读写操作。
• 人类对敏感操作的批准： create_directory， edit_file， move_file，以及 write_file 除非启用了YOLO模式，否则需经过人工审核节点。
• 故障时关闭的环境处理： src/goop/config.py 解决 ${VAR} 占位符，并在缺少所需的环境变量时抛出异常。
• 不执行任意外壳命令工具是从MCP服务器中发现的；代理代码中没有直接的shell执行路径。
• 检查点会话LangGraph 检查点机制（使用 thread_id）使流程可恢复且可审计。

示例运行（首先构建镜像）：

# Build image (create a Dockerfile suited to your environment)
docker build -t goop .

# Run: pass through Docker socket and mount the workspace
docker run -it --rm \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -e WORKSPACE="$(pwd)" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)":"$(pwd)" \
  -w "$(pwd)" \
  goop

未来的改进/增强

功能

• 并行工具调用审查目前一次只能审查一个工具调用。请实现一个工具队列系统以处理多个同时进行的工具调用。
• 额外的MCP服务器除了文件系统操作外，集成更多MCP服务器（数据库、网页搜索、代码分析等）。
• 持续检查点记录替换 MemorySaver 采用数据库支持的检查点机制（SQLite、PostgreSQL）以实现会话在重启后的持久性。
• 多模型支持添加配置以在OpenAI、Anthropic、本地模型（Ollama）和其他提供商之间进行切换。
• 自定义工具定义允许用户通过配置定义自定义工具及其保护级别。

安全与权限

• 细粒度的工具权限将二进制受保护/不受保护替换为基于角色的权限（只读、管理员、特定操作）。
• 审计日志记录记录所有工具调用、审批和拒绝操作，并附上时间戳和合规性理由。
• 每个会话的独立工作区隔离为每个（用户/项目）创建独立的工作区目录 thread_id 以防止跨会话文件访问。
• 资源限制为Docker容器添加CPU、内存和磁盘使用限制。
• 工具执行超时为长时间运行的工具操作设置超时机制。

用户体验

• 网页界面用基于网页的聊天界面替换命令行界面（CLI），该界面提供丰富的工具调用预览和审批工作流。
• 移动支持适用于移动审批工作流的响应式网页用户界面。
• 工具调用预览在要求批准之前，显示每个工具将执行的操作的详细预览。
• 审批模板预配置的审批规则（例如，“始终批准读取操作”）。
• 会话管理列出、概览和管理多个对话线程。

监控与可观测性

• 指标仪表板追踪工具使用情况、审批率、会话时长和错误率。
• 与可观测性工具的集成OpenTelemetry追踪、Prometheus指标、结构化日志记录。
• 性能分析监控并优化图形执行时间和内存使用。
• 健康检查用于监控MCP服务器和主应用程序健康状况的API端点。

配置与部署

• 动态MCP服务器管理在不重启应用程序的情况下添加/移除MCP服务器。
• 特定环境的配置开发、部署、生产配置文件。
• Kubernetes 部署容器编排的Helm图表和清单文件。
• API模式用于与聊天界面一起进行程序化访问的REST/GraphQL API。
• 插件架构允许第三方插件在不改变核心代码的情况下扩展功能。

故障排除

• 环境变量未设置如果一个必需的变量在 mcp_config.json （例如。， WORKSPACE如果（某部分）缺失，启动时将抛出明确的错误。
• Docker 错误确保 Docker 正在运行，并且能够拉取/运行（镜像） mcp/filesystem 图像。
• OpenAI 认证设置 OPENAI_API_KEY要使用本地模型，请切换至 ChatOllama 在 src/goop/graph.py。