开发者指南

两种开发方式

Agent-Lab 既是一个可以作为库来使用的框架，也是一个可以直接在其中开发的仓库。两种方式都受支持：

• 作为库使用（推荐用于产品开发）。 将 btech-agent-lab 添加到你自己的项目中，通过继承基类来定义智能体，并使用 create_app() 组装应用。你通过框架的公共 API（继承、装饰器和配置）来扩展框架，而无需修改框架代码。可以从教程或快速开始入手，然后阅读扩展框架。如果想省去样板代码，可以使用 uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter 生成一个现成的使用方项目（参见 cookiecutter/README.md）。
• 在仓库内开发（面向贡献者和参考实现）。 克隆仓库，在 agent_lab/services/agent_types/ 下添加智能体，运行自带的参考应用，并使用 notebook 和集成测试。内置智能体正是以这种方式开发的。参见构建智能体工作流。

两种方式使用相同的构建模块，区别仅在于你的代码存放在哪里。请选择适合你项目的方式。

环境设置

安装

Agent-Lab 面向 Python 3.12+，并使用 uv 进行依赖管理。

将 Agent-Lab 作为库使用——将其安装到你自己的项目中：

pip install btech-agent-lab
# or
uv add btech-agent-lab

在仓库中开发——克隆仓库并同步环境：

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

请确保已安装并运行 Docker 或其他容器运行时——集成测试（通过 testcontainers）会用到它，自带的 Docker Compose 文件也依赖它来提供应用的各项依赖。

复制示例环境变量文件

cp .env.example .env

该文件包含 AI 供应商的 API 密钥，以及智能体模拟所使用的端点。每个变量都在配置参考中有说明。

参考实现

仓库附带一个完整的参考应用（agent_lab.main），它注册了所有内置智能体——RAG、浏览器自动化、语音备忘录、视觉以及多智能体 supervisor。它既是一个可部署的产品，也是使用本框架的标准示例：它不过是对内置智能体包调用一次 create_app() 而已。

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

在构建你自己的应用时，可以把它当作实时参考；它也是端到端体验 Agent-Lab 的最快方式。在开发或生产环境中为它预置基础设施（三个 PostgreSQL 数据库、Redis、Keycloak、Vault）的方法请参阅部署指南。下一节介绍如何在本地运行它。

运行应用

使用 Uvicorn 启动应用

在使用 IDE 进行开发和调试时，可以直接运行参考应用：

uvicorn agent_lab.main:app --reload

访问 http://localhost:8000/docs 查看交互式 OpenAPI 文档。

当你将 Agent-Lab 作为库使用时，也以同样的方式运行你自己的应用——让 uvicorn 指向调用 create_app() 的模块：

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

使用 Docker Compose 启动应用

两个预配置的 Docker Compose 文件会将参考应用与一套可观测性栈一起运行：

• compose-grafana.yml：应用，外加 Grafana、Prometheus、Tempo 和 Loki。
• compose-opensearch.yml：应用，外加 OpenSearch Dashboards。

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

应用启动后，可以通过 http://localhost:18000/docs 访问 API。可观测性仪表盘：

• Grafana：http://localhost:3000（默认凭据：admin/admin）。参见 Grafana 示例。
• OpenSearch Dashboards：http://localhost:5601。参见 OpenSearch 示例。

开发实践

依赖注入

应用使用 Dependency Injector 实现依赖注入，从而保持关注点分离，并让测试更加容易。

容器定义在 agent_lab/core/container.py 中。将 Agent-Lab 作为库使用时，继承 Container 来添加你自己的 provider，并将实例传给 create_app(container=...)。在仓库内开发时，可以直接在容器上注册额外的框架服务。

应用配置

配置通过 ConfigSource（参见 agent_lab/core/config.py）加载，并绑定到 DI 容器。框架为开发和测试提供了三个 YAML 配置源，会根据环境变量自动选择：

• config-dev.yml：开发环境，设置 DEVELOPING 时启用——用于 IDE 调试。
• config-test.yml：测试环境，设置 TESTING 时启用——由集成测试环境使用。
• config-docker.yml：Docker Compose 环境，设置 DOCKER 时启用。

这些文件定义了数据库连接、认证等设置，仅用于开发和测试。在生产环境中，请通过 VaultConfigSource 使用 Vault（未设置任何环境标志时的默认配置源）。如需从其他后端提供配置，请实现你自己的 ConfigSource，并将其传给 create_app(config_source=...)。所有配置键和环境变量都在配置参考中有说明。

实体领域模型

数据模型——应用中使用的实体及其关系——请参阅实体领域模型。

日志与可观测性

应用使用 OpenTelemetry 实现日志与可观测性；相关设置位于 agent_lab/infrastructure/metrics/tracer.py。FastAPI、HTTPX、LangChain、SQLAlchemy 和 OpenAI 调用开箱即被插桩，并为 Langfuse 和 LangWatch 提供了可插拔的后端。详情请参阅可观测性指南。

测试

项目使用 pytest，并侧重于集成测试（覆盖率门槛：90%），借助 Testcontainers 让测试在 Docker 容器中针对真实服务运行。另有一套独立的模拟测试套件，借助 LLM-as-judge 端到端地评估智能体行为。

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

首次执行需要下载 Docker 镜像和嵌入模型，可能耗时几分钟。完整内容请参阅测试指南。

初始化 pre-commit

如果你打算为代码库做贡献，或在 Agent-Lab 之上构建新的智能体，请安装 pre-commit 钩子：

pre-commit install

这可以确保你的代码在提交之前符合项目的编码规范。

构建智能体工作流

Agent-Lab 构建于 LangGraph 之上，它为使用 LLM 构建智能体工作流提供了强大的方式。得益于模块化架构和智能体基类，构建工作流的过程非常直接。

定义新的智能体实现

智能体（Agent） 是 Agent-Lab 中的核心概念，代表一个能够执行任务、做出决策，并与其他智能体或外部系统交互的自主实体。智能体是某个基类的具体实现：

继承 WorkflowAgentBase 的类需要定义：

• 一个表示智能体行为的工作流——包括任务、决策，以及与其他智能体或外部系统的交互。
• 初始化参数，例如提示词（Jinja2 模板）和其他用于定制智能体行为的设置（向量存储集合、temperature 等）。

下面是一个执行语音转录与分析的智能体在创建并存入数据库之后，其已持久化的初始化参数示例：

可以通过 REST API 创建并完善由同一实现支撑的多个智能体。

使用 @discoverable_agent 注册智能体

使用 @discoverable_agent("<agent_type>") 装饰你的 AgentBase 子类。智能体所需的注册工作仅此一个装饰器——它会让智能体：

• 可被智能体注册表（agent_lab/services/agent_types/registry.py）发现，
• 可通过 DI 容器解析：容器会延迟实例化它，并注入所声明的 extra_deps，
• 在 API 层面有效：因为创建智能体的 schema 会依据注册表动态校验 agent_type。

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

注意（迁移）：早期版本需要手动将每个智能体接入 container.py、将其添加到 registry.py，并扩展 agents/schema.py 中的 Pydantic schema。这些步骤现已废弃——@discoverable_agent 会处理所有这些工作。你声明的任何 extra_deps 都会在实例化时按名称从（可能被继承过的）容器中解析。

如果智能体需要 AgentUtils 之外的协作对象，请将它们作为 provider 暴露在容器上（作为库使用时继承 Container），并在 extra_deps 中列出它们的名称。

让智能体可被发现

框架只会导入被告知的智能体模块，从而触发装饰器：

• 在仓库内： 将智能体放在 agent_lab/services/agent_types/ 下——参考应用会将该包作为 DEFAULT_SCAN_PACKAGES 的一部分进行扫描（create_app()）。

• 作为库使用： 将你的包传给 create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"])——显式列表会替换默认值（这也是排除内置能力的方式）；或者通过 agent_lab.agents 入口点组从已安装的包中发布它，使使用方能够自动加载：

  # pyproject.toml of the package that ships the agents
  [project.entry-points."agent_lab.agents"]
  my_agents = "my_agents"

试验智能体实现

参见 notebooks，其中包含使用 Jupyter 以交互方式测试智能体的示例，所用的依赖注入机制与应用相同。这是在受控环境中进行原型开发和行为验证的便捷方式——参见研究者指南。

REST API 智能体接口

智能体注册后，即可通过 REST API 创建和管理它的实例——你可以运行同一实现的多个已配置实例，每个实例都有自己的提示词和设置。端点目录和请求示例请参阅 REST API 参考。

测试智能体

• 集成测试（tests/integration/）借助 pytest 和 testcontainers，针对真实基础设施验证智能体。
• 模拟（tests/simulation/）借助 LLM-as-judge 端到端地评估行为。参见测试指南。

MCP 服务器

如需将你的智能体（以及额外的工具）暴露给 Claude Desktop 等 MCP 客户端，以实现智能体发现、对话历史和智能体之间的通信，请参阅 MCP 服务器指南。

扩展框架

将 Agent-Lab 作为库使用时，你完全通过 create_app() 以及顶层 agent_lab 包导出的公共 API 来塑造应用——无需修改框架代码：

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

以上所有内容都从 agent_lab 导出（参见 agent_lab/__init__.py）；这些选项所使用的完整配置键列表请参阅配置参考。

参与贡献

我们非常感谢社区的支持。如果你遇到任何问题或有改进建议，请在我们的 GitHub Issues 页面创建 issue 进行反馈。

如需为项目做贡献，请按以下步骤操作：

1. Fork 本仓库。
2. 为你的新功能或缺陷修复创建一个新分支。
3. 运行 pre-commit install 启用 pre-commit 钩子，进行修改，并使用清晰简洁的提交信息提交。
4. 确保你的修改能通过 pre-commit 钩子以及 90% 的覆盖率门槛（make test）。
5. 将修改推送到你 fork 的仓库。
6. 向原仓库的 main 分支创建 Pull Request（PR）。

我们会审查你的 PR 并给出反馈。感谢你的贡献与支持！

生产部署

如需使用自带的 Helm chart 和 Terraform 脚本在生产环境中部署参考应用，请参阅部署指南。