105 lines
5.4 KiB
Markdown
105 lines
5.4 KiB
Markdown
# Agent 执行器（Agent Runtime）
|
||
|
||
Agent 是蜂群系统中的执行单元（worker）。每个 Agent 作为独立进程运行（在 Kubernetes 中通常是一个 Pod），通过 WebSocket 连接到 Orchestrator，领取任务、调用大模型完成编码工作，并把结果写回 Git 分支。
|
||
|
||
## 职责概览
|
||
|
||
- 通过 WebSocket 连接 Orchestrator，并以自身**能力（capabilities）**注册，例如 `python`、`testing`、`technical-writing`。
|
||
- 接收 Orchestrator 下发的任务，使用 **OpenAI 兼容**的大模型完成子任务。
|
||
- 在隔离的「按任务工作目录」中生成/修改文件，并提交到独立的结果分支。
|
||
- 支持与其它 Agent **协作（peer collaboration）**与**移交（handoff）**。
|
||
- 持续上报心跳、状态与执行结果，并暴露 Prometheus 指标。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
agent/
|
||
├── main.py # Agent 主循环：连接、注册、心跳、消息处理、并发与重连
|
||
├── task_executor.py # 任务执行引擎：调用 OpenAI 兼容模型，应用文件改动
|
||
├── handoff_logic.py # 移交决策逻辑（复杂度 / 能力 / 预估时长）
|
||
├── git_operations.py # Git 克隆、建分支、提交、推送
|
||
└── requirements.txt # Python 依赖
|
||
```
|
||
|
||
## 核心模块
|
||
|
||
### 主循环（`main.py`）
|
||
- **连接与重连**：断线后按指数退避自动重连并重新注册。
|
||
- **有界并发**：通过信号量限制同时执行的任务数（`MAX_CONCURRENT_TASKS`），并在注册/心跳中上报剩余容量 `available_slots`。
|
||
- **任务受理**：对每个分配先做校验，重复任务返回 `task_accepted(status=duplicate)`，超出容量返回 `task_rejected`，由 Orchestrator 重新入队。
|
||
- **执行保护**：单任务超时（`TASK_TIMEOUT_SECONDS`）与任务取消（`cancel_task`）。
|
||
- **心跳**：每 15 秒上报一次存活与容量信息。
|
||
- **优雅退出**：收到 SIGINT/SIGTERM 时停止接单并清理在执行的任务。
|
||
|
||
### 任务执行器（`task_executor.py`）
|
||
- 使用 **OpenAI 兼容 API**（可指向自定义 `base_url`）完成子任务。
|
||
- 根据上下文中的**依赖产物（dependency_artifacts）**与**专家角色（specialist_role）**对齐输出：测试与文档以实现产物的行为/异常语义为准。
|
||
- 将模型返回的文件改动安全地写入工作目录（带路径越界校验）。
|
||
- 记录用量并附带计费/审计归属（`usage` 与 `X-Agent/X-Agnet` 模型归属头），供 Orchestrator 上报。
|
||
|
||
### 移交逻辑（`handoff_logic.py`）
|
||
当子任务满足以下条件时建议移交给更合适的 Agent：
|
||
- 复杂度为 `high`；
|
||
- 需要当前 Agent 不具备的专业能力；
|
||
- 预估耗时超过 60 分钟。
|
||
|
||
### Git 操作（`git_operations.py`）
|
||
- 自动识别仓库根目录（`repo_root`），使按任务子目录也能在父级 Git 仓库中正确执行。
|
||
- 为每个任务创建结果分支（形如 `agent/{agent-id}/{task}-{timestamp}`），提交并推送。
|
||
|
||
## 配置（环境变量）
|
||
|
||
凭据通过同目录的 `.env`（已被 `.gitignore` 忽略）加载，亦可由部署环境/`secret_ref` 注入。**请勿将密钥写入代码或提交记录。**
|
||
|
||
```bash
|
||
# 模型（OpenAI 兼容）
|
||
OPENAI_API_KEY=... # 或 MODEL_API_KEY
|
||
OPENAI_API_BASE=https://api.openai.com/v1 # 或 MODEL_API_BASE，可指向自定义端点
|
||
OPENAI_MODEL=gpt-4o-mini # 或 MODEL_NAME / MODEL_ID
|
||
|
||
# 连接与身份
|
||
ORCHESTRATOR_URL=ws://localhost:8000 # Orchestrator 的 WebSocket 地址
|
||
AGENT_ID=worker-1 # 不填则自动生成
|
||
AGENT_CAPABILITIES=python,testing # 逗号分隔的能力列表
|
||
WORKSPACE_DIR=/workspace # 工作目录
|
||
|
||
# 可选
|
||
GIT_REPO_URL=https://... # 需在仓库内工作时设置
|
||
GIT_USERNAME / GIT_PASSWORD / GIT_TOKEN# 推送凭据
|
||
GIT_BASE_BRANCH=main # 结果分支的基线
|
||
MAX_CONCURRENT_TASKS=4 # 最大并发任务数
|
||
TASK_TIMEOUT_SECONDS=60 # 单任务超时
|
||
METRICS_PORT=9000 # 设置后暴露 Prometheus 指标
|
||
ENABLE_SUBTASK_HANDOFF=false # 是否启用动态子任务移交
|
||
```
|
||
|
||
## 本地运行
|
||
|
||
```bash
|
||
pip install -r agent/requirements.txt
|
||
|
||
# 准备 .env（含 OPENAI_API_KEY 等），然后从仓库根目录运行：
|
||
set "ORCHESTRATOR_URL=ws://localhost:8000"
|
||
set "AGENT_ID=worker-1"
|
||
set "AGENT_CAPABILITIES=python,code_generation,testing,pytest,technical-writing,general"
|
||
set "WORKSPACE_DIR=...\tmp-workspace\worker-1"
|
||
python -m agent.main
|
||
```
|
||
|
||
## 任务执行流程
|
||
|
||
1. **注册**：连接 Orchestrator 并上报能力与可用容量。
|
||
2. **心跳**：每 15 秒上报存活与剩余容量。
|
||
3. **受理**：校验分配，必要时拒绝（容量不足）或忽略（重复）。
|
||
4. **执行**：在独立的按任务工作目录中调用模型完成子任务；如启用，可向同伴 Agent 咨询或移交。
|
||
5. **提交**：若为 Git 工作区，提交并推送到结果分支。
|
||
6. **回报**：将结果（含用量）发送回 Orchestrator，并将状态置为空闲。
|
||
|
||
## 协作（Peer Collaboration）
|
||
|
||
当上下文提供了 `peer_agents` 时，测试/文档等角色可向实现角色发起咨询；被咨询方会回复自己最近一次完成任务的摘要，帮助各专家在重叠领域保持一致。
|
||
|
||
## 监控
|
||
|
||
Agent 暴露的 Prometheus 指标包括：已执行/失败任务数、任务时长、移交次数、重连次数、被拒/重复任务数、当前活跃任务数与 Agent 状态。
|