企业级 AI 对话 Agent

一个内部助手：支持多轮对话，外加由真实 MCP 服务器提供的文件系统工具——该服务器仅在真正涉及文件时才被连接。

• 架构与设计理由 → WRITEUP.md

• 约定、护栏、决策日志 → CLAUDE.md

• 用于构建它的逐字提示 → PROMPTS.md

需要安装什么，以及安装顺序

项目可以独立运行。Traces 和行为评估是两个独立的可选层级，每个都有各自的前提条件——两者都不是查看 agent 工作所必需的。选择一个层级，到此为止即可。

第 2 层和第 3 层相互独立——你可以做两者都做、两个都做，或都不做。如果缺少 Docker 或 Node，第 1 层不会受到任何影响。

Related MCP server: Files MCP Server

第 1 层 — Core（必需）

版本要求

确切版本在 requirements.txt 中；范围在 pyproject.toml 中。

为什么 mcp 被限制在 2.0.0 以下： MCP Python SDK v2 将 FastMCP 重命名为 MCPServer，并移除了 mcp.server.fastmcp 模块。langchain-mcp-adapters 0.3.2 声明了相同的上限，因此两者不能在其之上同时安装。这个固定将隐式约束显式化；这不是降级。

运行

# 0. clone
git clone https://github.com/Semmargl/enterprise-ai-chat-agent.git
cd enterprise-ai-chat-agent

# 1. environment
python3 -m venv .venv                 # or: uv venv --python 3.14
source .venv/bin/activate             # Windows: .venv\Scripts\activate
pip install -r requirements.txt       # or: uv pip install -r requirements.txt

# 2. secrets
cp .env.example .env
# then open .env and put your OpenRouter key in OPENROUTER_API_KEY

# 3. sample files to play with (the working folder starts empty)
mkdir -p workspace && cp samples/* workspace/

# 4. check the wiring before spending a token
pytest -q                             # expect: 44 passed, <1s, no network needed

# 5. start
python -m src.main

检查点： agent 会根据一天中的时间问候你，并回答一个问题。如果第 4 步打印了 44 passed，则沙箱、记忆窗口和工具可见性都已验证，无需任何一次 API 调用。

agent 会进行正常对话，并在你第一次要求文件时连接到文件服务。

python -m src.main --thread report   # a separate, named conversation

用 exit 退出。用相同的 --thread 再次启动，对话会继续：状态被检查点到 SQLite，而不是保存在内存中。

运行 MCP 服务器的两种方式

注意两个"默认值"：当变量未设置时，代码回退到 0，而 .env.example 提供 MCP_AUTOSTART=1，这样干净的克隆无需第二个终端即可运行。复制模板即可获得自动启动；在没有 .env 的情况下部署则得到生产形态。

无论哪种方式，在你要求文件之前，都不会连接任何东西。

值得尝试的事情

日志中应该关注什么

日志是 JSON 格式，每个事件一行，输出到 stderr。correlation_id（一次用户轮次）和 thread_id（一次对话）这两个键将它们关联起来。

var/audit.jsonl 是审计跟踪：每个工具调用一行，包含结果和持续时间。它记录路径、大小和哈希——绝不记录文件内容，绝不记录机密。

它有意放在 var/ 而不是 workspace/ 中：agent 自己的文件工具可以访问沙箱根目录下的所有路径，因此放在那里的审计跟踪可能会被记录它的进程修改。检查点数据库（var/checkpoints.sqlite）也出于同样的原因放在外面——它是 agent 的记忆，而不是它的工作区。启动时会拒绝将两者中的任何一个放回沙箱内的配置。

第 2 层 — Phoenix 中的 Traces（可选）

前提：Docker。 如果没有 Docker，请跳过整个部分——agent 不需要它。默认是 OTEL_EXPORTER=none，因此干净的克隆可以在完全没有收集器的情况下运行。

插桩是采用 OpenInference 语义的 OpenTelemetry，因此 span 描述的是 LLM 和工具调用，而不是通用的 HTTP 工作。导出器是一个环境变量，而不是代码路径——将 Phoenix 换成任何其他 OTLP 后端只需一个变量，而不是重构。

# 1. start Phoenix (first run pulls the image, ~1-2 min)
docker run -d --name phoenix -p 6006:6006 -p 4317:4317 arizephoenix/phoenix

# 2. wait for it, then confirm it answers
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6006    # expect: 200

# 3. run the agent pointed at it — two turns, one plain and one about a file
OTEL_EXPORTER=otlp OTEL_ENDPOINT=http://127.0.0.1:6006/v1/traces \
  python -m src.main --thread traces

检查点： 打开 http://localhost:6006。两轮对话产生 两个 trace。打开文件那个——工具调用嵌套在 create_agent 循环内，位于模型调用之下。那个嵌套正是关键：它是 agent 的控制流，而不是扁平的 HTTP 请求列表。

# when finished
docker stop phoenix && docker rm phoenix

不要将 OTEL_EXPORTER=console 用于本地调试以外的任何用途： 这些 span 会打印整个提示和每个工具结果——也就是文件内容——而审计跟踪有意从不存储这些内容。

第 3 层 — 行为评估（可选）

前提：Node 18+。 如果没有就跳过；pytest 已经覆盖了所有确定性内容。

pytest 覆盖了无需网络即可检查的内容：路径限制、窗口算术、工具可见性。它无法覆盖的是，系统在与真实模型进行真实九轮对话后是否仍然表现正常。这三个用例位于 promptfooconfig.yaml 中，并通过 scripts/promptfoo_provider.py 针对真正的 agent 运行——而不是针对裸模型。

# 1. install
npm i -g promptfoo@latest

# 2. the venv must be active and .env filled in — the provider spawns the real agent
source .venv/bin/activate

# 3. run
NODE_NO_WARNINGS=1 PROMPTFOO_DISABLE_TELEMETRY=1 PROMPTFOO_DISABLE_UPDATE=1 \
  promptfoo eval -o results.json; echo "EXIT=$?"

# 4. browse the results (optional)
promptfoo view

检查点： EXIT=0，且 results.json 包含 "successes": 3, "failures": 0, "errors": 0。完整运行需要 40–60 秒——这是九轮真实对话加上两轮单轮对话。

两件看起来像失败但并非失败的事情。 进度条可能看起来卡在 0% | 0/3：Node 将警告写入同一终端行并覆盖它。以 EXIT 和 JSON 为准，而不是进度条。重复运行时 assertions.cached > 0 是 评分器 缓存自己的调用——agent 对话本身从不被缓存。添加 --no-cache 可进行完全冷运行。

这会消耗 tokens。 三个用例，共十一轮对话，外加一个评分断言的 LLM 评分器——全部使用你 .env 中的同一个 OPENROUTER_API_KEY。

配置

每个设置都在 .env.example 中有文档。对行为影响最大的有：MCP_AUTOSTART、SANDBOX_ROOT、MAX_FILE_BYTES、HISTORY_WINDOW_MESSAGES、SUMMARIZATION_TRIGGER_MESSAGES、OTEL_EXPORTER。

.env 从第一次提交起就在 .gitignore 中，从未被提交过：

git log --all --full-history -- .env    # returns nothing