如何开发 AI 智能体平台

Cloud 平台、数据平台，现在是 agent 平台。

每家公司都想构建一个这样的平台，并运行一大批 agent。在之前构建过云、计算和数据平台之后，我希望我们能从过去的错误中吸取教训，第一次就把这件事做对。

数据时代是一个特别值得警惕的案例。我经历过那次伟大的“解绑”（unbundling），当时我们必须把多个工具拼接在一起：用于摄取（ingestion）、编排（orchestration）、转换（transformation），以及元数据、BI 和数据质量等服务。每个工具单独使用都很棒，但把它们组合在一起用就成了痛苦。80% 的工程时间都花在了把这些东西粘合在一起上。后来出现了“绑定”（bundling）。Snowflake、Databricks 和云提供商（尤其是 AWS）将整个栈整合起来，提供了统一的平台。

Agent 时代正以同样的方式开始：把功能当作独立产品出售，以及出现大量针对目前其实还不存在的问题的供应商。

如果你发现自己正在用 3 个不同的提供商来运行 agent 和数据，trace 散落在多个地方，而且没有自动改进循环，那么这篇文章就是为你准备的。

1、你需要一个 agent 平台

如果你把 agent 看作是“应用”（apps），那么很明显，它们需要一个像操作系统一样的系统来运行。

你的 agent 平台负责运行 agent、收集数据和指标、管理安全（防止未经授权的访问），以及阻止一个 agent 访问或污染另一个 agent 的数据。

2、我们正在构建什么

今天，我们将构建一个 agent 平台，你可以本地运行，也可以在 Railway 上以每月 20 美元的价格运行。

一旦它运行起来，你应该能够无需编写任何代码就能部署一个新的 agent（或 workflow）。因为平台已经处理好了一切，Claude Code 可以用很高的质量构建新 agent，然后通过实时查询它们来递归地改进它们。这就是拥有统一 agent 平台的最大优势。

我们还会设置一个用于重复性工作的调度器，用 evals 锁定行为，并将 agent 连接到 Slack 等界面。

最有趣的部分是看着 Claude Code 递归地改进你的 agent。

3、什么是 agent 平台

Agent 平台由五个部分组成：

• Runtime：运行 agent 的服务。这部分承担了大部分繁重工作。
• Storage：我们的数据所在的数据库：agent 会话、记忆、知识、trace 和 eval 历史。
• Connectors：agent 通过 MCP、API 或 CLI 连接外部系统的工具。把它们放在一个地方对安全有很大好处。
• Interfaces：Slack、Discord、Telegram、自定义 UI。在不同界面上解析身份的单一位置，这样同一个人无论是通过 Slack 联系你还是通过 Web 应用访问，都是同一个 user_id。
• Infrastructure：一切运行的地方。我们将使用 Docker 进行本地部署，使用 Railway 进行生产部署。

4、让我们开始吧

我将分享一个基础代码库，你可以在此基础上构建。

在我看来，这是 agent 平台的完美起点。

agent-platform
├── agents                       # agent code goes here
│   ├── code_search.py
│   └── web_search.py
├── app                          # server code goes here
│   ├── config.yaml
│   ├── main.py
│   └── settings.py
├── compose.yaml
├── db
│   ├── session.py
│   └── url.py
├── Dockerfile
├── docs                         # docs go here
│   ├── create-new-agent.md
│   ├── eval-and-improve.md
│   ├── improve-agent.md
│   └── review-and-improve.md
├── evals
│   └── cases.py                 # test cases
└── README.md

4.1 本地运行

首先让我们克隆、配置并运行我们的 agent 平台。

确保 Docker 已安装并正在运行。如果没有，请按照说明操作。

然后打开终端，逐一运行以下命令：

1) 克隆 agent-platform 模板

git clone https://github.com/agno-agi/agentos-railway-template.git agent-platform
cd agent-platform

2) 配置你的环境。复制示例 .env 文件，在你喜欢的代码编辑器中打开，并添加 OpenAI key。

cp example.env .env

3) 运行你的平台：1 个 FastAPI 服务器和 1 个 Postgres 数据库

docker compose up -d --build

这会启动两个容器：一个 FastAPI 服务器和一个 Postgres 数据库。在 http://localhost:8000/docs 确认 API 正在运行。

现在让我们给我们的平台一个 UI。

• 前往 os.agno.com 并登录。
• 将你的本地 OS 连接到 http://localhost:8000。

你应该会看到类似这样的界面：

4.2 创建你的第一个 agent

代码库附带了两个参考 agent 和一个 Claude Code 提示词，它可以为你构建新的 agent。

要创建一个新 agent，请打开 Claude Code 并运行：

Run docs/create-new-agent.md

Claude 会询问这个 agent 应该做什么、需要什么工具，然后生成 agent 文件，在 app/main.py 中注册它，重启容器，并运行冒烟测试。

对于一个简单的 agent，这通常需要 5-10 分钟。如果你正在构建带有自定义工具的定制化东西，则需要更长时间。

4.3 测试你的新 agent

打开 os.agno.com 与你的 agent 聊天。用现实的提示运行它。检查 trace 和会话。尝试破坏它。尝试分布外（out-of-distribution）的问题、提示注入、边缘案例。这通常需要 5-20 分钟。

4.4 递归改进你的 agent

这是你的平台开始产生回报的地方。

在仓库中打开 Claude Code 并粘贴：

Run docs/improve-agent.md

Claude Code 可以直接通过 curl 访问你正在运行的 agent。然后迭代并改进你的 agent。

这就是为什么拥有整个栈如此值得。trace 数据、agent 代码、正在运行的平台以及迭代工具都生活在一个盒子里。Claude Code 可以看到所有这些，并根据需要进行改进。

5、用 evals 锁定行为

Evals 是你 agent 的回归测试。相同的提示、相同的 agent，按计划运行，当行为漂移时失败。

Evals 被定义为一组案例：

# evals/cases.py
Case(
    name="web_search_recent_anthropic_research",
    agent=web_search,
    input="What did Anthropic publish about agent research recently?",
    criteria=(
        "Answers the question by citing at least one real Anthropic URL "
        "(anthropic.com domain). The response is grounded in fetched content "
        "rather than refusing to answer."
    ),
    expected_tool_calls=(_WEB_SEARCH_TOOL,),
)

稍后用以下命令运行它们：

 python -m evals

结果会通过 eval_db 写入你的 Postgres，因此 eval 历史会出现在 os.agno.com 上，与会话和 trace 并列。

通过粘贴以下内容，将 Claude Code 连接到诊断循环：Run docs/eval-and-improve.md。它会诊断每个失败，并在范围内修复问题。

6、在 Railway 上运行

让我们把我们的平台上线，托管到某个地方。你公司可能有自己运行软件的方式。请遵循你们的那一套。

如果你正在寻找一个无需经历完整 DevOps 流程就能测试的地方，Railway 是我发现的最便宜、最快的 PaaS。每月 20 美元就能走得很远，而且代码库已经附带了 deploy-to-railway 脚本。

需要 Railway CLI 并执行 railway login。

6.1 配置生产环境

部署脚本会先读取 .env.production，然后回退到 .env。这让你可以为本地和生产环境保留不同的值：不同的 OpenAI key（不同预算）、仅生产环境的凭证、不同的 Slack 工作区等等。

cp .env .env.production
# Edit .env.production with production values

6.2 部署

代码库附带了一个脚本，它会配置一个 Postgres 数据库并在同一私有网络上部署应用。运行它：

./scripts/railway/up.sh

6.3 你的第一次部署会失败。这是预料之中的。

基于 Token 的授权默认是开启的。

没有 JWT_VERIFICATION_KEY，应用会拒绝提供服务。你的平台的职责是把你的数据挡在公共互联网之外。解决办法是生成一个 key 并把它放到你的生产环境变量中。

另一种做法是默认关闭 auth，然后指望人们以后自己加上——我们都知道这不会发生。人们会把服务器暴露在公共互联网上，被黑，然后怪我。

基于 Token 的认证给你三样东西：

• 无公共访问。没有有效 token 的请求会被服务器拒绝。
• 每个请求的身份。中间件解析 token，并将 user_id、session_id 和自定义 claims 注入你的端点。每个请求都绑定到用户和会话，从而防止数据泄露。
• 细粒度权限。用户级 token 可以运行 agent 并查看自己的会话。管理员 token 可以读取所有人的会话并测试任何 agent。你现在不需要了解或关心 RBAC，但当你开始思考安全问题时，你已经有了基础。

6.4 获取你的验证密钥

默认路径是让 os.agno.com 为你生成密钥对：

• 打开 os.agno.com，点击 Add OS → Live，输入你的 Railway 域名。
• 启用 Token Based Authorization，然后连接。
• 将公钥粘贴到 .env.production 中。

JWT_VERIFICATION_KEY=-----BEGIN PUBLIC KEY-----
MIIBIjANBgkq...
-----END PUBLIC KEY-----

实时连接到 AgentOS 需要专业订阅。使用优惠码 PLATFORM30 可获得 1 个月免费试用。如果你不想被收费，请记得在试用结束前取消。

FYI：你不必使用 os.agno.com。你可以自己生成 RSA 或 EC 密钥对，在自己的服务中使用私钥签名 token，并把匹配的公钥放到 JWT_VERIFICATION_KEY 中。平台不在乎密钥从哪里来，只要传入的 token 能验证通过即可。

6.5 同步环境变量并验证

在 .env.production 打开时，将集群内的调度器指向你的公共 Railway 域名，以便 cron 触发器可以访问 AgentOS：

# .env.production
AGENTOS_URL=https://<your-app>.up.railway.app

然后将变量推送到 Railway：

./scripts/railway/env-sync.sh

Railway 在环境变量更改时会自动部署。查看日志并确认平台正在提供服务：

railway logs --service agent-os

一旦看到成功的请求，AgentOS 就会通过你的 Railway 域名连接，你就上线了。

6.6 来自 GitHub 的自动部署

到目前为止，每次代码更新都需要运行 ./scripts/railway/redeploy.sh。

要在 push 到 main 时自动部署：

• 打开 Railway 仪表盘 → 你的项目 → agent-os 服务 → Settings。
• 在 Source 下，点击 Connect Repo 并选择你的仓库。
• 将部署分支设置为 main。

现在每次 push 到 main 都会触发构建和滚动部署。./scripts/railway/env-sync.sh 仍然是同步环境变量更改的方式。

选择退出 JWT（不推荐）

如果你必须在没有 auth 的情况下运行生产环境（例如，在另一个 auth 层后面的私有 VPC 内），请在 app/main.py 中设置 authorization=False 并重新部署。对于任何持有真实数据的部署，都请保持 authorization 开启。没有它，任何猜到你 Railway 域名的人都可以读取你的会话和 agent。

扩展

默认部署是两个副本，每个副本 4Gi 内存和 2 vCPU。这为你提供了零停机滚动部署和基本的容错能力。随着使用量增长，你可以在 railway.json 中增加或减少 numReplicas 和 limits。

7、超越 agent

经验法则：agent 用于开放式问题，team 用于路由，workflow 用于流程。你的大部分平台将是 agent。少数会是 team 或 workflow。你会知道什么时候需要哪一个。

多 agent 团队：当一个 agent 不够时，在一个专家团队中路由工作。Agno team 有三种模式：

• Coordinate：领导者规划工作、调用正确的专家并综合结果。
• Route：路由器选择一位专家来处理请求。
• Broadcast：每个专家并行运行，你进行聚合。
  当预先不知道正确的专家是谁时，请使用 team。team 概述会详细介绍每种模式。

Agentic 工作流：当一个流程需要每次都以相同方式运行时，编写一个 workflow。Workflow 给你确定性。用它们来处理平台中少数需要可重复的高杠杆流程。workflow 概述涵盖了这些模式。

关于 agent 本身的更多信息（指令、工具、记忆、模型配置），请参考 agents 概述。

8、计划任务

平台默认在 app/main.py 中启用了轻量级调度器：

agent_os = AgentOS(
    name="AgentOS",
    scheduler=True,
    ...
)

你可以按 cron 调度任何 agent 或 workflow。常见模式包括：

• 维护：清除 90 天前的会话，清理 Postgres 表，将 trace 数据旋转到冷存储。
• 主动运行：每个工作日早上，运行一个 agent 总结夜间新闻给你的投资组合公司，并发布到 Slack。
• 捕获回归：每周针对生产 agent 调度 python -m evals。在用户感受到之前，漂移就会出现在 eval 历史中。

请参阅 agno scheduler 文档了解 cron API。

9、连接到界面

你的 agent 应该出现在用户所在的地方：Slack 线程、Discord 频道、给现场团队的 Telegram，或者最重要的是：你产品内的自定义 UI。

对于 Slack、Discord、Telegram，模式类似。通过 interface 暴露 agent。参考 app/main.py 中的示例：

interfaces: list = []
if SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET:
    from agno.os.interfaces.slack import Slack

    interfaces.append(
        Slack(
            agent=code_search,
            streaming=True,
            token=SLACK_BOT_TOKEN,
            signing_secret=SLACK_SIGNING_SECRET,
            resolve_user_identity=True,
        )
    )

...

agent_os = AgentOS(
    ...
    interfaces=interfaces,
)

更多信息请阅读 interfaces 指南。

10、结束语

恭喜。如果你做到了这一步，你就拥有了一个在你自己的云中安全运行的统一 agent 平台。技术用户可以使用 Claude Code 创建和部署 agent。非技术用户可以使用无代码 UI。

会话、trace 和知识都存在于你的数据库中。你的基础设施被基于 JWT 的 RBAC 保护，API key 在一个地方管理。

11、为什么控制自己的数据很重要

在结束之前，谈谈数据主权。

与你的平台进行的每次交互都会产生数据。会话、记忆和 trace 都会流入你的 Postgres 数据库。这很重要有两个原因：

合规：把数据保留在你自己的数据库中，降低了泄露风险。一旦客户数据、专有代码或内部文档触碰到第三方 trace 工具或记忆服务，你的安全水平就变成了他们的安全水平。

自动改进：你的 trace 是 Claude Code（或你自己）闭环 agent 质量的方式。编码 agent 将成为构建和改进 agent 的主要方式。它们之所以能工作，是因为 trace 数据生活在迭代工具可以读取的地方。供应商拼接的栈把这个表面分散在三个 SaaS 产品上，循环永远无法闭合。

你今天部署的 agent 只是你所构建的最小部分。它们下面的平台，以及它所启用的迭代循环，才是真正重要的东西。

原文连接：How to Build an Agent Platform

汇智网翻译整理，转载请标明出处