> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 如何开发 AI 智能体平台
- URL: https://www.hubwiz.com/blog/how-to-build-an-ai-agent-platform/
- Published: 2026-05-07T22:47:25.000Z
- Updated: 2026-10-13T15:55:05.000Z
- Description: 每家公司都想构建一个这样的平台，并运行一大批 agent。在之前构建过云、计算和数据平台之后，我希望我们能从过去的错误中吸取教训，第一次就把这件事做对。
- Author: admin
- Tags: AGENT, #Import 2026-10-14 14:41

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](http://localhost:8000/docs?ref=hubwiz.com) 确认 API 正在运行。

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

- 前往 os.agno.com 并登录。
- 将你的本地 OS 连接到 [http://localhost:8000](http://localhost:8000/?ref=hubwiz.com)。

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

![](https://www.hubwiz.com/blog/content/images/2026/05/image-102.png)

### 4.2 创建你的第一个 agent

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

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

```
Run docs/create-new-agent.md
```

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

![](https://www.hubwiz.com/blog/content/images/2026/05/image-103.png)

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

### 4.3 测试你的新 agent

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

![](https://www.hubwiz.com/blog/content/images/2026/05/image-104.png)

### 4.4 递归改进你的 agent

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

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

```
Run docs/improve-agent.md
```

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

![](https://www.hubwiz.com/blog/content/images/2026/05/image-105.png)

这就是为什么拥有整个栈如此值得。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。它会诊断每个失败，并在范围内修复问题。

![](https://www.hubwiz.com/blog/content/images/2026/05/image-106.png)

## 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 中。

![](https://www.hubwiz.com/blog/content/images/2026/05/image-107.png)

```
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](https://x.com/ashpreetbedi/status/2052413981487427871?ref=hubwiz.com)

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

> **这是「Agent / MCP」专题的一部分。**完整地图见：[Agent / MCP / 自动化完全指南](https://www.hubwiz.com/blog/agent-stack/)