你的第一个智能体

你将构建什么

一个完整、可运行的 Agent-Lab 应用：一个托管 echo 智能体的 FastAPI 服务，外加 MCP 服务器、PostgreSQL 持久化和 OpenTelemetry 插桩——全部由一条命令生成脚手架，无需任何手动装配。在此过程中，你将通过 REST 创建一个智能体实例、向它发送消息，并查看框架生成的追踪。

前提条件

• Python 3.12+ 和 uv（pip install uv）
• 正在运行的 Docker（或其他容器运行时）

本教程不需要任何 API 密钥——echo 智能体不会调用 LLM。基于 LLM 的智能体将在后续内容中介绍（参见下一步）。

1. 搭建项目脚手架

uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter

回答提示问题——使用默认值将得到一个名为 My Agent App 的项目：

cd my-agent-app

脚手架是框架的一个轻量使用方，而不是分支（fork）。btech-agent-lab 是 pyproject.toml 中的一个常规依赖；你的代码与它并存，并通过公共 API 对其进行扩展。

2. 了解生成的内容

my-agent-app/
├── my_agent_app/
│   ├── main.py              # the composition root — one create_app() call
│   ├── core/container.py    # your DI container — add providers here
│   ├── agents/echo/agent.py # your first agent (echo)
│   └── mcp/tools.py         # your first MCP tool
├── config-dev.yml / config-test.yml / config-docker.yml
├── tests/                   # unit tests (no infra) + optional testcontainers suite
├── compose.yml              # app + postgres (pgvector) + redis + vault
└── Makefile, docker/, .github/, pyproject.toml

打开 my_agent_app/main.py——这就是整个应用：

from agent_lab import create_app

from my_agent_app.core.container import Container

# An explicit scan_packages list replaces agent_lab's DEFAULT_SCAN_PACKAGES:
# only this project's agents, MCP tools, and prompts are discovered — none of
# the framework's built-in examples. Add "agent_lab.services.agent_types" or
# "agent_lab.interface.mcp" here if you want the built-ins back.
app = create_app(
    container=Container(),
    scan_packages=[
        "my_agent_app.agents",
        "my_agent_app.mcp",
    ],
)

再看 my_agent_app/agents/echo/agent.py——智能体本身：

from langchain_core.messages import AIMessage
from langgraph.graph import MessagesState

from agent_lab import AgentBase, AgentUtils, discoverable_agent
from agent_lab.interface.api.messages.schema import Message, MessageRequest
from agent_lab.services.tasks import TaskProgress


@discoverable_agent("my_agent_app_echo")
class EchoAgent(AgentBase):
    """Minimal agent: echoes the incoming message without calling an LLM."""

    def __init__(self, agent_utils: AgentUtils):
        super().__init__(agent_utils)

    def create_default_settings(self, agent_id: str, schema: str):
        pass

    def get_input_params(self, message_request: MessageRequest, schema: str) -> dict:
        return message_request.model_dump()

    def process_message(self, message_request: MessageRequest, schema: str) -> Message:
        message_content, response_data = self.format_response(
            MessagesState(
                messages=[AIMessage(content=f"Echo: {message_request.message_content}")]
            )
        )

        self.task_notification_service.publish_update(
            task_progress=TaskProgress(
                agent_id=message_request.agent_id,
                status="completed",
                message_content=message_content,
                response_data=response_data,
            )
        )

        return Message(
            message_role="assistant",
            message_content=message_content,
            response_data=response_data,
            agent_id=message_request.agent_id,
        )

有两点值得注意：

• @discoverable_agent("my_agent_app_echo")——这一个装饰器就会将该类注册到某个 agent_type 之下。无需编辑注册表，也无需修改 schema：REST API 会依据注册表动态校验 agent_type。
• AgentUtils 由 DI 容器通过构造函数注入。可以通过 extra_deps=("my_provider",) 声明更多依赖，并在 core/container.py 中添加对应的 provider（参见开发者指南）。

3. 先测试，再运行

脚手架的单元测试会在完全没有基础设施的情况下启动整个应用：

uv lock && uv sync --group dev --group test
make test_unit

你同样可以获得集成测试版本——make test_integration 会通过 testcontainers 启动真实的 Postgres、Redis 和 Vault 容器（需要 Docker）。

4. 运行应用

docker compose up --build -d
curl http://localhost:18000/status/liveness

这套技术栈包括：应用（端口 18000）、带 pgvector 的 PostgreSQL（三个数据库：关系型、向量、LangGraph 检查点）、用于发布/订阅状态更新的 Redis，以及用于管理密钥的 Vault。交互式 OpenAPI 文档位于 http://localhost:18000/docs。

脚手架中默认禁用认证（auth.enabled: false）。启用后，每个请求都需要携带 bearer 令牌——参见使用 Keycloak 进行认证。

5. 通过 REST 与智能体对话

智能体是某个实现的实例，通过 API 创建和配置。创建一个：

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-first-agent", "agent_type": "my_agent_app_echo"}' | jq

从响应中复制 id，然后向它发送一条消息：

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "<agent_id>",
        "message_role": "human",
        "message_content": "Hello, framework!"
      }' | jq

回复会同步返回：

{
  "message_role": "assistant",
  "message_content": "Echo: Hello, framework!",
  "agent_id": "<agent_id>",
  "id": "…"
}

这一来一回贯穿了整个技术栈：REST 请求 → 注册表查找 → DI 容器 → 你的智能体 → 消息持久化（回复同样会被存储——可以用 POST /messages/list 查看）。完整的端点目录请参阅 REST API 参考。

6. 查看追踪

Agent-Lab 的可观测性就是 OpenTelemetry。设置环境变量 OTEL_EXPORTER_OTLP_ENDPOINT 后，应用会导出 OTLP 追踪/指标/日志；未设置时，追踪就处于关闭状态——无论哪种情况都无需修改代码。

运行框架自带的 Grafana 技术栈（在框架仓库中），并让你的应用指向它的 Collector：

# In the agent-lab framework repo — collector on :4318, Grafana UI on :3000
docker compose -f compose-grafana.yml up --build

# Back in your project — restart the app with the endpoint set
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 docker compose up --build -d

再发送一条消息，然后打开 Grafana（http://localhost:3000，admin/admin），浏览 Agent-Lab 仪表盘：HTTP span、SQL 查询，以及——对于基于 LLM 的智能体——每一次模型调用及其 token 数量。更想使用托管的 LLM 可观测性平台？那就改为设置 LANGFUSE_HOST/LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY（或 LANGWATCH_ENDPOINT/LANGWATCH_API_KEY）——详情请参阅可观测性指南。

7. 在 MCP 客户端中使用它

脚手架已经附带了一个 MCP 工具（my_agent_app/mcp/tools.py），与框架的智能体发现、历史记录和消息工具一起暴露在 /mcp 上。使用 MCP Inspector 试一试：

npx @modelcontextprotocol/inspector

连接到 http://localhost:18000/mcp（Streamable HTTP），列出工具，然后调用 my_agent_app_hello_tool。同一个服务器也可以与 Claude Desktop 及任何 MCP 客户端配合使用——参见 MCP 服务器指南。

下一步