研究者指南

本指南的目标读者

本指南面向希望在 Agent-Lab 中探索、复现和扩展实验的 AI 研究人员和开发者。如果你会写 Python、使用 Jupyter，并习惯以实验、智能体和流水线的方式思考问题，你会感到得心应手。熟悉 LLM、RAG 和容器基础知识会有所帮助，但并非必需。

Agent-Lab 提供可复用的组件（智能体类型、工具、集成），以及一系列包含分步示例的 Jupyter notebook，帮助你快速上手。

快速开始——运行示例

要求：Python 3.12+、可用的 Jupyter 环境（JupyterLab 或 Notebook），以及可选的本地 Docker（用于端到端集成）。在仓库的克隆副本中操作：

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

打开 notebooks/，从 01_… 开始，然后依次学习你感兴趣的 notebook。

说明：

• Notebook 基本都是自包含的；每个 notebook 的开头都会说明所需的环境变量和外部服务（API 密钥、端点）。
• 所需的密钥位于 .env 中——复制 .env.example 并填写（参见配置参考）。
• 如果想在你自己的项目中（而不是在本仓库中）基于 Agent-Lab 做实验，可执行 pip install btech-agent-lab，并通过 create_app() 组装应用——参见开发者指南中的扩展框架。

项目结构——快速导览

• notebooks/——智能体类型、评估和集成的交互式示例。从这里开始。
• agent_lab/——框架包：
  • app_factory.py——组合根：create_app()。
  • core/——配置源、DI 容器、extra_deps 解析。
  • domain/——模型、仓储接口、异常（即实体领域模型）。
  • services/——业务逻辑以及 agent_types/ 中的各个实现。
  • interface/——api/（HTTP 路由）和 mcp/（MCP 服务器）。
  • infrastructure/——数据库、认证、指标/追踪适配器。
• tests/——unit/、integration/、template/ 和 simulation/ 测试套件（参见测试与模拟）。
• doc/——你正在阅读的文档。

理解这些分层，你就知道各种行为位于何处：示例在 notebooks 中，核心契约在 core/ 和 domain/ 中，适配器在 infrastructure/ 中。

Notebook——主要学习路径

典型的学习顺序：

每个 notebook 都包含：实验目标的简要说明、所需的环境变量和密钥、辅助函数，以及用于检查智能体决策和指标的打印/可视化输出。

小贴士：按顺序运行 notebook，可以获得循序渐进的学习曲线。迭代过程中请使用较小的数据集和样本量，以保持运行速度。

核心概念

• Agent——位于 agent_lab/services/agent_types/ 下的已注册实现（@discoverable_agent）。注册表通过 DI 容器延迟解析它，并注入其声明的 extra_deps。
• Tools——智能体可以调用的独立能力（搜索、浏览、TTS/ASR），以适配器的形式实现在 agent_lab/infrastructure/ 或 agent_lab/interface/ 中。
• Container——DI 组合对象（agent_lab/core/container.py）；继承它即可为你的实验添加 provider。
• Repositories——位于 agent_lab/domain/repositories/ 中的数据访问接口。
• ConfigSource——配置的来源；实验中使用 YAML 配置源，生产环境中使用 Vault。

当你想修改行为时，先判断这项改动属于哪一类：实验性（仅限 notebook）、架构层面（core/domain/services），还是集成层面（infrastructure 中的适配器）。优先进行小而可测试的改动——并添加或更新一个 notebook 来展示新行为。

运行实验并记录结果

Notebook 会打印中间步骤；如需更稳健的实验：

• 在随机性有影响的地方使用确定性的随机种子。

• 记录与你的问题相关的指标——延迟、token 用量、工具调用次数、评审分数。可观测性层会以 OpenTelemetry 格式导出所有数据（参见可观测性）；模拟测试工具会将评审分数记录到 Langfuse/LangWatch（参见测试与模拟）。

• 如需可重复运行，可将 notebook 单元格导出为脚本，并在 CI 或计算节点上运行：

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• docker/app/Dockerfile 会构建一个版本固定的运行时镜像，以实现可复现的执行。

新行为的原型开发

1. 添加新的智能体类型：在 agent_lab/services/agent_types/ 下创建类，使用 @discoverable_agent("your_type") 装饰它，并添加一个 notebook，通过 DI 容器挂载它并用一个小场景进行验证。完整演练请参阅构建智能体工作流。
2. 替换嵌入服务提供商：在 agent_lab/infrastructure/ 下实现一个兼容的适配器，并用 notebook 01 进行验证。
3. 添加检索存储或向量数据库：在 agent_lab/domain/repositories/ 中实现仓储方法，并在 agent_lab/infrastructure/database/ 中实现适配器；用一个小型加载 notebook 写入初始数据，并在查询 notebook 中演示检索。

设计建议：保持适配器接口精简，并通过小型单元测试对其进行隔离测试。

测试与评估

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

当你修改核心行为时，请添加一个单元测试和一个演示该改动的简短 notebook——正是这种组合让本项目中的研究具备可复现性。完整的测试工具、评审配置和评估平台请参阅测试与模拟。

可复现性检查清单

• 固定你的环境版本（uv + pyproject.toml / uv.lock）。
• 记录随机种子和配置文件（config-dev.yml、config-test.yml）。
• 将 notebook 检查点及所有输出产物（CSV/JSON）与实验一同保存。
• 记下你导出数据所用的追踪端点——追踪就是你的实验日志。