Agent Monitor MCP

代理监视器MCP

用于代理的混合监控系统，具有MCP状态接收、FastAPI REST API和浏览器仪表板。

设置

1. 使用Poetry安装依赖项：

   poetry install

1. 配置环境变量（可选）：

   cp .env.example .env

电报通知

当代理任务完成时，监视器可以向Telegram聊天发送通知。

1. 使用创建机器人 @植物学家 并得到 机器人令牌.
2. 得到你的 聊天ID （您可以使用 @用户信息机器人).
3. 将以下内容添加到您的 .env 文件：

   TELEGRAM_BOT_TOKEN="your_bot_token"
   TELEGRAM_CHAT_ID="your_chat_id"
   TELEGRAM_PROGRESS_NOTIFY_ENABLED=true

竣工条件： 只有在以下情况下才会触发通知：

• 状态转换为 completed.
• 进展正是 100.
• 两者 branch 和 working_dir 已提供（非空白）。
• 针对该特定情况的通知 instance_id 尚未发送。

系统会特别通知最终结果 completed 状态达到100%进度。如果代理在静止时报告100%的进度 running 随后过渡到 completed，它将在最终过渡时通知。如果有多个，它可以避免双重通知 completed 接收同一实例的更新。

运行服务器

启动FastAPI服务器：

poetry run python -m app.main

服务器将在以下时间可用 http://localhost:8000.

• 仪表板： http://localhost:8000/
• API文件： http://localhost:8000/docs/

MCP 服务器

MCP服务器设计用于 stdio 当前MVP中的运输。您可以通过以下方式运行它：

poetry run python -m app.mcp_server

或者使用以下命令在LLM客户端（例如Claude Desktop）中配置它： poetry run python -m app.mcp_server

OpenCode配置

要在OpenCode中连接到此MCP服务器，请将以下内容添加到您的 opencode.json （或等效的客户端配置）：

{
  "mcpServers": {
    "agent-monitor": {
      "type": "local",
      "command": ["poetry","--directory","/path/to/agent-monitor-mcp", "run", "python", "-m", "app.mcp_server"],
      "enabled": true
    }
  }
}

可用工具

• report_status(agent_id, run_id, task_name, status, progress, message, metadata, instance_id=None, branch=None, working_dir=None)：更新代理状态。

- instance_id：代理实例的唯一标识符。如果省略，则合成一个 agent_id 和 run_id. - branch：当前git分支名称。 - working_dir：代理工作目录的绝对路径。

• get_all_status()：返回所有代理实例的当前快照。
• get_agent_status(instance_id)：返回特定代理实例的当前快照。

主要代理的建议提示

主代理或编排代理应指示子代理调用 report_status 任务开始时、进度更新期间、完成时和失败时。使用规范的小写状态值： running, completed, failed, cancelled，或 queued.

编排器可以使用 get_all_status() 或 get_agent_status(instance_id) 监督工人。

When executing tasks, use the `agent-monitor` MCP server to report your status:
1. Call `report_status` with status="running" when starting.
2. Provide periodic updates with `progress` (0-100) and a `message`.
3. Call `report_status` with status="completed" or "failed" upon finishing.

或

## 📊 Status Reporting (Mandatory)

You must use the `agent-monitor` MCP tool to report status for every non-trivial user job. This is mandatory for transparency and orchestration.

1.  **Start:** Immediately call `agent-monitor_report_status` with `status='running'`, `progress=0`, and a clear `message` describing the task.
2.  **Updates:** Send progress updates (0-100) and messages after each major phase, delegation, or every few meaningful steps.
3.  **Stalls:** If a task stalls or awaits user input, report it in the `message` while remaining `status='running'`.
4.  **Finish:** Conclude with `status='completed'` or `status='failed'`.
5.  **Required Fields:** Every call must include `agent_id`, `run_id`, `task_name`, `status`, `progress`, and `message`. 
6.  **Context (Strongly Recommended):** Include `branch` (current git branch) and `working_dir` (absolute path to current directory) to distinguish instances across branches/projects.

代理人身份和隐私

显示器使用 instance_id （明确或综合）作为国家和历史的主要关键。这允许系统区分相同的多个实例 agent_id （例如在不同的分支或不同的工作目录中运行）。

隐私边界

• 仪表板列表和CLI：仅显示 agent_id, branch和a 紧凑型位置标签 （最后两个路径组件 working_dir 在可能的情况下，而不仅仅是基本名称）。
• 实例详细信息：显示完整的绝对值 working_dir, instance_id以及其他元数据。
• API：The /api/agents 列表端点提供简洁的摘要数据（包括 location_label)并排除完整路径；规范的完整细节，请访问 /api/agents/instances/{instance_id}.

CLI监视器

要从终端查看代理状态：

# Watch status with 1s interval
poetry run python -m cli.monitor --interval 1

# Only show the 5 most recently updated agents
poetry run python -m cli.monitor --limit 5

选项：

• --once：获取一次并退出。
• --json：输出原始JSON。
• --url：指定其他API URL。
• --interval：初始轮询间隔（秒）（默认值：2.0）。
• --max-interval：回退的最大轮询间隔（默认值：60.0）。
• --backoff-factor：未检测到变化时的回退倍数（默认值：1.5）。
• --limit：限制显示的代理数量（按最近更新的顺序排序）。

CLI监视器提供 冷静的摘要视图 默认情况下，显示位置、分支、状态和进度。

主要特点：

• 清洁桌子：严格显示4个最关键的列，以减少认知负荷。
• 隐私第一：完整的工作目录路径隐藏在摘要视图中，以保护本地文件结构。如果 location_label 从目录路径导出紧凑版本（例如。， parent/current)而不是显示完整路径。
• 自适应轮询：实现自适应退避机制。如果没有检测到语义状态变化，则会增加轮询间隔。在稳定的渲染中，背景线被抑制，以获得更清晰的体验。
• 身份安全：使用内部 instance_id （包括 location_label)处理不同分支或目录中同名的多个代理。

特性

• 持久耐用：WAL模式下的SQLite存储当前快照和事件历史。
• 实时更新：仪表板使用服务器发送事件（SSE）进行增量更新。
• 腐烂检测：60秒内未报告的代理（可配置）会自动标记为 STALE 在仪表板和API中（除非处于终端状态）。
• 混合接口：共享服务层确保MCP、REST和Web UI之间的一致性。
• 单实例设计：当前MVP是为单实例设计的 stdio 运输。服务逻辑是共享的，但为MCP工具执行和FastAPI web应用程序独立初始化，以避免脆弱的导入时全局状态。
• 自适应CLI轮询：CLI监视器在状态空闲时使用语义变化检测来减少轮询频率。
• 电报通知：代理任务完成时，可选同步电报通知（100%进度和 completed 状态）在特定分支和工作目录上。

部署和生产指导

反向代理配置（SSE）

在反向代理（如Nginx或Caddy）后面部署时，需要特定的配置来确保服务器发送事件（SSE）正常运行：

• 禁用缓冲：代理不得缓冲响应。对于Nginx，使用 proxy_buffering off; 和 proxy_cache off;.
• 超时：确保代理超时时间长于预期的心跳/保持活动时间间隔。
• 标头：服务器发出 Content-Type: text/event-stream 和 Cache-Control: no-cache.

公众曝光限制

• 无内置身份验证：API和仪表板没有内置身份验证。
• 明确警告: 请勿将此服务器暴露于公共互联网 没有外部身份验证层（例如，Authelia、Google IAP或代理级别的基本身份验证）和TLS加密。
• 仅根路径：当前的MVP是为在根路径上部署而设计和测试的(/).部署到子路径（例如。， /monitor/)目前不支持或测试。

持久性清理

应用程序在项目根目录中生成SQLite运行时文件：

• agent_monitor.db
• agent_monitor.db-wal
• agent_monitor.db-shm

这些通过以下方式排除在版本控制之外 .gitignore.

自动启动保留

您可以通过设置配置启动时自动清理旧数据 STATUS_RETENTION_SECONDS 在你的 .env 文件。

• 如果设置为正整数（例如。， 86400 在24小时内），服务器将修剪严格早于初始化时的截止时间的事件历史和当前状态快照。
• 事件根据其 reported_at 时间戳。
• 当前状态快照会根据其 updated_at 时间戳（最后一次看到）。
• 如果设置为 0 （默认），禁用自动清理。

手动复位

要手动重置系统状态，请停止服务器并删除 .db* 文件夹。

限制和人为审查

作为MVP，该系统有几个局限性：

• 无内置身份验证\*依靠外部基础设施保障安全。
• 单实例：专为单进程/单实例部署而设计。SSE广播在内存中，未在多个工作进程或进程之间同步。
• 手动仪表板验证：虽然核心逻辑和SSE流由自动化测试覆盖，但仪表板UI的最终视觉组装需要手动验证。
• 人工智能生成的生命周期：核心应用程序生命周期和存储库模式是在人工智能的帮助下搭建的，并且已经过MVP使用审查。

测试

使用Poetry运行测试：

poetry run pytest