概述

构建代理型演示项目很容易。但要以安全、可靠且可重复的方式将代理型应用顺利上线却并不简单。在快速完成一个原型之后，你往往会发现自己不得不开发“隐藏的中间件”来支撑生产环境：用于将请求路由到正确代理的逻辑、用于安全与内容审核的护栏钩子、用于持续学习的评估与可观ility集成，以及分散在不同框架和应用代码中的模型与提供商特有处理逻辑。

Plano通过将核心交付相关功能整合到统一的进程外数据平面中，有效解决了这一问题。

• 🚦 编排： 代理之间的低延迟编排；无需修改应用代码即可添加新代理。
• 🔗 模型敏捷性： 可按[模型名称、别名（语义化名称）]路由，或根据偏好自动路由](#use-plano-as-a-llm-router)。
• 🕵 Agentic Signals™： 无需编写代码即可捕获信号，同时为每个代理生成OTEL追踪与指标。
• 🛡️ 内容审核与记忆钩子： 通过过滤链一致地构建防越狱机制、添加内容审核策略并管理记忆。

Plano将这些基础架构工作从你的框架中剥离出来，让你能够专注于最重要的事情：代理型应用的核心业务逻辑。Plano背后有行业领先的LLM研究，其核心贡献者基于Envoy构建了关键基础设施，可大规模支持现代工作负载。

高层网络序列图：

立即前往我们的文档，了解如何利用Plano提升代理型应用的速度、安全性及可观ility。

[!重要提示] Plano及其Arch系列LLM（如Plano-Orchestrator-4B、Arch-Router等）在美国中部地区免费托管，旨在为你提供出色的首次开发体验。若需扩展规模并在生产环境中运行，你可以选择在本地运行这些LLM，或通过Discord联系我们获取API密钥。

---

使用Plano构建代理型应用

Plano将编排、模型管理和可观ility作为模块化的构建块——让你只需配置所需的部分（用于代理编排和护栏的边缘代理，或从你的服务中进行LLM路由，或者两者结合），从而无缝融入现有架构。下面是一个使用Plano构建的简单多代理旅行助手示例，展示了这三项核心能力。

📁 完整可运行代码： 请参阅demos/agent_orchestration/travel_agents/，其中包含可在本地运行的天气和航班代理完整代码。

1. 在YAML中定义你的代理

# config.yaml
version: v0.3.0

# 你需要声明的内容：代理URL和自然语言描述
# 你无需编写的部分：意图分类器、路由逻辑、模型回退、提供商适配器或追踪埋点

agents:
  - id: weather_agent
    url: http://localhost:10510
  - id: flight_agent
    url: http://localhost:10520

model_providers:
  - model: openai/gpt-4o
    access_key: $OPENAI_API_KEY
    default: true
  - model: anthropic/claude-3-5-sonnet
    access_key: $ANTHROPIC_API_KEY

listeners:
  - type: agent
    name: travel_assistant
    port: 8001
    router: plano_orchestrator_v1  # 由我们的4B参数路由模型驱动。你可以更换为其他模型
    agents:
      - id: weather_agent
        description: |
          提供全球任意城市的实时天气和预报信息。
          处理诸如“巴黎现在天气如何？”、“东京会下雨吗？”等问题。

      - id: flight_agent
        description: |
          搜索机场之间的航班信息，包括实时状态和时刻表。
          处理诸如“从纽约飞往洛杉矶的航班有哪些？”、“给我看看飞往西雅图的航班”之类的请求。

tracing:
  random_sampling: 100  # 自动捕获追踪数据以便评估

2. 编写简单的代理代码

你的代理只是实现了OpenAI兼容聊天补全接口的HTTP服务器。你可以使用任何语言或框架：

# weather_agent.py
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI

app = FastAPI()

# 指向Plano的LLM网关——它会为你处理模型路由
llm = AsyncOpenAI(base_url="http://localhost:12001/v1", api_key="EMPTY")

@app.post("/v1/chat/completions")
async def chat(request: Request):
    body = await request.json()
    messages = body.get("messages", [])
    days = 7

    # 你的代理逻辑：获取数据、调用API、执行工具
    # 完整实现请参阅demos/agent_orchestration/travel_agents/
    weather_data = await get_weather_data(request, messages, days)

    # 将响应流式返回至Plano
    async def generate():
        stream = await llm.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "system", "content": f"天气：{weather_data}"}, *messages],
            stream=True
        )
        async for chunk in stream:
            yield f"data: {chunk.model_dump_json()}\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

3. 启动Plano并查询你的代理

先决条件： 请按照先决条件指南安装Plano并设置好环境。

# 启动Plano
planoai up config.yaml
...

# 查询 - Plano 在一次对话中智能地将用户路由到两位客服
curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "我下周想从纽约飞往巴黎旅行。那里的天气怎么样？你能帮我找一些航班吗？"}
    ]
  }'
# → Plano 将请求路由至 weather_agent 获取巴黎的天气信息 ✓
# → 随后路由至 flight_agent 查询纽约 → 巴黎的航班信息 ✓
# → 返回包含天气信息和航班选项的完整旅行计划

4. 免费获得可观测性和模型敏捷性

每个请求都通过 OpenTelemetry 进行端到端追踪——无需任何额外的埋点代码。

您无需构建的内容

基础设施相关事项	不使用 Plano	使用 Plano
代理编排	编写意图分类器 + 路由逻辑	在 YAML 中声明代理描述
模型管理	处理各提供商 API 的特殊性	统一的 LLM API 并附带状态管理
丰富追踪	为每个服务手动埋点 OTEL	自动化的端到端追踪与日志
学习信号	构建管道以捕获/导出追踪数据	无需代码即可获取代理行为信号
添加代理	更新路由代码、测试并重新部署	直接添加到配置文件，重启即可

为何高效： Plano 使用专门构建的轻量级 LLM（例如我们自己的 40 亿参数调度器）来完成路由任务，而非依赖重量级框架或 GPT-4——这样既能提供生产级别的路由能力，又大幅降低了成本和延迟。

---

联系我们

如需联系我们，请加入我们的 Discord 服务器。我们会在那里积极回复并提供支持。

开始使用

准备好试用 Plano 了吗？请查看我们的完整文档：

• 快速入门指南 —— 几分钟内即可上手
• LLM 路由 —— 可按模型名称、别名或智能偏好进行路由
• 代理编排 —— 构建多代理工作流
• 过滤链 —— 添加安全约束、内容审核及记忆钩子
• 提示目标 —— 将提示转化为确定性的 API 调用
• 可观测性 —— 追踪数据、指标和日志

贡献

我们非常欢迎对 路线图 的反馈，并诚挚邀请您为 Plano 贡献力量！无论是修复 bug、新增功能、改进文档，还是制作教程，您的帮助都将不胜感激。更多详情请参阅我们的 贡献指南。

如果您觉得 Plano 很有用，请给本仓库点个 star ⭐️ —— 我们的最新发布和更新都会首先在这里公布。

Plano 快速上手指南

Plano 是一个面向智能体（Agentic）应用的 AI 原生代理服务器和数据平面。它通过将路由、编排、安全过滤和可观测性等通用基础设施从应用代码中剥离，帮助开发者更安全、可靠地将智能体应用交付到生产环境。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux (推荐), macOS, 或 Windows (WSL2)。
• 运行时依赖：
  • Docker：Plano 核心基于 Envoy 构建，推荐使用 Docker 运行。
  • Python 3.8+：用于编写智能体业务逻辑（也支持其他语言，只要实现 OpenAI 兼容接口）。
  • pip：用于安装 Plano CLI 工具。
• API Keys：准备好您的 LLM 提供商密钥（如 OPENAI_API_KEY, ANTHROPIC_API_KEY 等）。

注意：Plano 的默认编排模型（如 plano_orchestrator_v1）在美国中部区域免费提供用于开发测试。若需在生产环境大规模使用或本地部署，请参考官方文档或联系团队获取支持。

安装步骤

1. 安装 Plano CLI

使用 pip 安装 Plano 命令行工具：

pip install planoai

2. 配置环境变量

导出您的 LLM 提供商 API 密钥，以便 Plano 读取：

export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

3. 验证安装

检查版本以确保安装成功：

planoai --version

基本使用

以下示例展示如何快速构建一个包含“天气查询”和“航班搜索”的多智能体旅行助手。

第一步：定义智能体配置 (config.yaml)

创建 config.yaml 文件。在此文件中，您只需声明智能体的 URL 和自然语言描述，无需编写复杂的路由逻辑或意图分类器。

# config.yaml
version: v0.3.0

agents:
  - id: weather_agent
    url: http://localhost:10510
  - id: flight_agent
    url: http://localhost:10520

model_providers:
  - model: openai/gpt-4o
    access_key: $OPENAI_API_KEY
    default: true
  - model: anthropic/claude-3-5-sonnet
    access_key: $ANTHROPIC_API_KEY

listeners:
  - type: agent
    name: travel_assistant
    port: 8001
    router: plano_orchestrator_v1  # 使用轻量级专用模型进行路由
    agents:
      - id: weather_agent
        description: |
          Gets real-time weather and forecasts for any city worldwide.
          Handles: "What's the weather in Paris?", "Will it rain in Tokyo?"

      - id: flight_agent
        description: |
          Searches flights between airports with live status and schedules.
          Handles: "Flights from NYC to LA", "Show me flights to Seattle"

tracing:
  random_sampling: 100  # 自动捕获 traces 用于评估

第二步：编写智能体业务代码

您的智能体只需是实现了 OpenAI 兼容接口的 HTTP 服务。以下以 Python FastAPI 为例编写一个简单的天气智能体 (weather_agent.py)：

# weather_agent.py
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI

app = FastAPI()

# 指向 Plano 的 LLM 网关，由 Plano 处理模型路由
llm = AsyncOpenAI(base_url="http://localhost:12001/v1", api_key="EMPTY")

@app.post("/v1/chat/completions")
async def chat(request: Request):
    body = await request.json()
    messages = body.get("messages", [])
    days = 7

    # 此处为您的业务逻辑：获取数据、调用外部 API 等
    # 模拟获取天气数据
    weather_data = f"Sunny, 25°C in the requested location (simulated)"

    # 通过 Plano 流式返回响应
    async def generate():
        stream = await llm.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "system", "content": f"Weather: {weather_data}"}, *messages],
            stream=True
        )
        async for chunk in stream:
            yield f"data: {chunk.model_dump_json()}\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

注：请在终端启动此服务并监听端口 10510 (对应 config 中的 weather_agent url)。同理需启动 flight_agent 监听 10520。

第三步：启动 Plano 并测试

1. 启动 Plano 服务： 在终端运行以下命令加载配置：

   planoai up config.yaml
   

2. 发送请求测试编排能力： 使用 curl 向 Plano 发送请求。Plano 会自动识别用户意图，依次调用天气智能体和航班智能体，并整合结果。

   curl http://localhost:8001/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{
       "model": "gpt-4o",
       "messages": [
         {"role": "user", "content": "I want to travel from NYC to Paris next week. What is the weather like there, and can you find me some flights?"}
       ]
     }'
   

   预期结果：

   • Plano 自动将天气相关问题路由给 weather_agent。
   • Plano 自动将航班查询问题路由给 flight_agent。
   • 返回包含天气信息和航班选项的完整旅行计划。

第四步：查看可观测性数据

Plano 默认集成 OpenTelemetry。所有请求的端到端追踪（Traces）、指标和日志将自动捕获，无需在代码中添加任何埋点 instrumentation。您可以结合 Jaeger 或 Prometheus 等工具查看详细的智能体交互链路。