# work-agent

**Repository Path**: lctinks/work

## Basic Information

- **Project Name**: work-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-10-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agent

个人 Agent 智能体：本地/远程大模型 + RAG 知识库 + ReAct 推理循环 + 工具调用 + MCP + 多 Agent 协作 + 四层护栏 + 可观测性。

## 软件架构

```
main.py               CLI 入口：控制台多轮对话
app.py                FastAPI 生产服务（阶段 7）
agent_graph.py        ReAct 编排：Thought → Action → Observation 循环 + 失败重试 + 记忆
tools.py              工具层：calculator / get_weather / search_knowledge
mcp_server.py         MCP Server：工具 / 资源 / Prompt 标准化（阶段 4）
multi_agent.py        多 Agent 编排：pipeline / router / council（阶段 6）
a2a.py                A2A 协议：AgentCard + JSON-RPC 任务收发（阶段 6）
memory.py             记忆工程：短期 / 长期 / 共享记忆（阶段 5）
reranker.py           检索重排序：CrossEncoder / LLM / 不重排（阶段 5）
knowledgeBoundary.py  知识边界：分块 → 向量化 → 持久化 → 阈值检索 → 重排
safetyFence.py        四层护栏：输入 / 行为 / 输出 / 运行时
observability.py      可观测性：埋点 + Token 成本 + 指标（阶段 7）
evaluate.py           离线评估：DeepEval 或内置关键词评分（阶段 7）
config.py             配置层：读取 .env
knowledge.txt         知识库语料
eval_dataset.jsonl    评估数据集
.env / .env.example   配置文件
Dockerfile            生产镜像（uvicorn）
```

单 Agent 执行流程：

```
intent ──blocked──────────────────────────► compliance ──► END
  │
  ├─(需查资料)─► retrieve ─┐
  │                        ▼
  └────────────────────► think ──(Answer)──► finalize ──► compliance ──► END
                           ▲                     │
                           │                     └─(校验失败且可重试)──┘
                        observe ◄── act
```

## 安装教程

1. 启动本地大模型：
   ```bash
   docker compose up -d ollama
   docker exec -it ollama ollama pull llama3.1:8b
   docker exec -it ollama ollama pull nomic-embed-text
   ```
2. 准备配置文件：
   ```bash
   cd agent && cp .env.example .env   # 按需修改模型接口与模型 ID
   ```
3. 安装依赖：
   ```bash
   pip install -r agent/requirements.txt
   ```
4. 启动：
   ```bash
   cd agent && python main.py                      # 控制台
   uvicorn app:app --host 0.0.0.0 --port 8000      # HTTP 服务
   ```

## 使用说明

### CLI

```
你：设备不通电怎么办
🛠️ 解决方案：分类标签: 硬件故障
详细分析: ...
🔁 推理步数：2
```

命令：`new` 开新会话，`mode <single|pipeline|router|council>` 切换编排，`退出` 结束。

### HTTP（FastAPI）

```bash
# 单 Agent
curl -X POST http://localhost:8000/generate \
  -H 'Content-Type: application/json' \
  -d '{"input_text": "设备不通电怎么办", "session_id": "user-1"}'

# 多 Agent：串行流水线 / 路由分发 / 协作讨论
curl -X POST http://localhost:8000/generate \
  -H 'Content-Type: application/json' \
  -d '{"input_text": "给一份设备离线的排查方案", "mode": "council"}'

curl http://localhost:8000/health
curl http://localhost:8000/metrics
curl http://localhost:8000/cost
curl http://localhost:8000/memory/user-1
```

| 端点 | 说明 |
| --- | --- |
| `POST /generate` | 对话，`mode` = single / pipeline / router / council |
| `GET /health` | 健康检查与生效配置 |
| `GET /metrics` | Prometheus 格式指标 |
| `GET /cost` | 各会话 Token / 成本 |
| `GET /memory/{sid}` | 查看长期记忆与共享黑板 |
| `DELETE /memory/{sid}` | 清除该会话长期记忆 |
| `GET /.well-known/agent.json` | A2A 能力名片 |
| `POST /a2a` | A2A 协议入口（`method=tasks/send`） |

### MCP Server（阶段 4）

```bash
pip install "mcp[cli]"
python mcp_server.py                        # stdio
npx @modelcontextprotocol/inspector python mcp_server.py   # Inspector 调试
MCP_TRANSPORT=sse python mcp_server.py      # SSE 模式
```

暴露：`search_knowledge` / `calculator` / `get_weather` 三个工具，`kb://stats`、`config://model` 两个资源，`troubleshoot` 一个 Prompt 模板。

### 多 Agent（阶段 6）

| 模式 | 说明 |
| --- | --- |
| `pipeline` | 串行流水线：起草 → 分析 → 审校 |
| `router` | 路由分发：Router 判断意图后交给对应专家 |
| `council` | 协作讨论：多专家共享黑板多轮讨论后汇总 |

A2A 跨进程协作：设 `A2A_ENABLED=1`、`A2A_PEER_URLS=http://host-a:8000`，对端即可通过 `/a2a` 调用本 Agent。

### 评估（阶段 7）

```bash
python evaluate.py --limit 5 --mode single
```

已装 `deepeval` 时用 AnswerRelevancy 等指标，未装则降级为关键词命中率。

## 四层护栏

| 层 | 实现 | 拦截内容 |
| --- | --- | --- |
| 输入 | `InputGuardrail` | 提示词注入、违禁词、超长输入 |
| 行为 | `BehaviorGuardrail` | 工具白名单、调用次数上限、重复调用死循环 |
| 输出 | `OutputGuardrail` | 标签越界、编造/不确定表述、拒答话术 |
| 运行时 | `RuntimeGuardrail` | Token 预算耗尽、请求超时 |

输出/行为护栏不通过时不改写答案，而是把失败原因抛回 ReAct 循环触发重试。

## 记忆（阶段 5）

- **短期**：当前会话最近 N 轮，由 LangGraph checkpointer 持久化
- **长期**：跨会话事实沉淀，`MEMORY_BACKEND=sqlite`（默认）或 `mem0`
- **共享**：多 Agent 共享黑板 `SharedMemory`

## 配置（agent/.env）

优先级：**环境变量 > .env > 代码默认值**。完整说明见 `agent/.env.example`，核心项：

```bash
# 可用模型接口列表：<接口地址>|<模型ID,...>[|<provider>]，多接口用分号分隔
MODEL_LIST=http://localhost:11434|llama3.1:8b,qwen2.5:7b,nomic-embed-text
# 默认使用的模型接口地址与模型 ID
DEFAULT_API_BASE=http://localhost:11434
DEFAULT_MODEL=llama3.1:8b
```

其余：`EMBEDDING_*`、`MAX_ATTEMPTS`、`USE_NATIVE_TOOLS`、`RERANK_*`、`MEMORY_*`、`AGENT_MODE`、`COUNCIL_ROUNDS`、`A2A_*`、`OBSERVABILITY_*`、`TOKEN_BUDGET_PER_SESSION`、`MAX_TOOL_CALLS`、`REQUEST_TIMEOUT_SECONDS`、`HTTP_HOST/PORT`。

## Docker 部署

```bash
docker compose up -d --build agent-api   # FastAPI 服务，监听 8000
docker compose up -d agent               # CLI 容器（容器内 git clone 后运行）
```

`agent-api` 使用 `agent/Dockerfile`（uvicorn + 健康检查），向量库/记忆库/埋点落在 `agent-data` 卷。

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request