katanemo/plano · 上手攻略

仓库：katanemo/plano
链接：https://github.com/katanemo/plano
分类：ai
作者：Jay
更新：2026-07-13

这是什么

Plano 是一个构建在 Envoy 代理之上的 AI 原生数据平面（Data Plane）与代理服务器，专为 Agentic Application（智能体应用）设计。它的核心思路是：把 Agent 开发中反复出现的"管道工作"（路由、编排、安全过滤、可观测性）从业务代码中抽离出来，放到一个独立进程里处理，让你专注在 Agent 的核心业务逻辑上。

简单说：如果你的 AI 应用涉及多个 Agent、需要路由不同 LLM、需要安全过滤输入输出、需要观测链路——Plano 就是这些需求的统一基础设施层。

解决什么问题

自建 Agent 应用时，你会发现每个项目都要重复写：

路由逻辑：判断用户请求该分发给哪个 Agent
模型适配层：处理不同 Provider（OpenAI / Anthropic / 本地模型）的 API 差异
可观测性：为每个 Agent 调用植入 OTEL Trace / Metrics
安全过滤：Jailbreak 检测、内容审核、内存隔离
编排编排：多 Agent 协同时谁先谁后、结果如何汇总

Plano 用 YAML 声明式配置替代上述所有定制代码，并通过内置的 4B 参数路由模型实现智能分发。

快速安装

环境要求

Python ≥ 3.10
支持平台：Linux（x86_64 / aarch64）、macOS（Apple Silicon）
可选：Docker（v24+）用于容器模式

安装 CLI（推荐 uv）

# 安装 uv（如果你还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 用 uv 安装 planoai（v0.4.27）
uv tool install planoai==0.4.27

或用 pip 传统安装

python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate
pip install planoai==0.4.27

首次运行 planoai up 时会自动下载 Envoy、WASM 插件并缓存到 ~/.plano/ 目录。

Docker 模式（可选）

# 在任意 up/down 命令后加 --docker 即可
planoai up config.yaml --docker
planoai down --docker

核心用法

1. 作为 LLM 网关（最简单场景）

创建配置文件 plano_config.yaml：

version: v0.3.0

listeners:
  - type: model
    name: model_1
    address: 0.0.0.0
    port: 12000

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

启动服务：

planoai up plano_config.yaml

用 curl 测试：

curl --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user", "content": "What is the capital of France?"}], "model": "gpt-4o"}' \
  http://localhost:12000/v1/chat/completions

用 Python OpenAI 客户端调用（无需改动现有代码，只需改 base_url）：

from openai import OpenAI

client = OpenAI(
    api_key='--',                          # Plano 已接管认证
    base_url="http://127.0.0.1:12000/v1"  # 指向 Plano 网关
)

response = client.chat.completions.create(
    model="--",                            # 空字符串 → 使用配置的 default 模型
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)
print(response.choices[0].message.content)

2. 多 Agent 编排（核心场景）

这是 Plano 最亮眼的用法——用 YAML 声明 Agent 描述，让内置 4B 路由模型自动决定分发给哪个 Agent：

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    # 内置 4B 路由模型
    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    # 自动捕获 100% 链路追踪

你的 Agent 只需实现标准的 OpenAI 兼容 /v1/chat/completions 接口（任何语言/框架均可），然后注册到 Plano：

# weather_agent.py（FastAPI 示例）
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI

app = FastAPI()
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", [])
    # 取天气数据（业务逻辑）...
    weather_data = await get_weather_data(request, messages, days=7)

    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")

用户一个请求，Plano 自动路由到 weather_agent → flight_agent，返回完整旅行计划：

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?"}]
  }'

每条请求全程自动有 OpenTelemetry Trace，不需要在每个服务里手动插桩。

3. Filter Chain（安全过滤）

通过 Filter Chain 可以为所有请求统一添加 Moderation、Memory Hooks、Jailbreak 保护：

# 在 listeners 中加入 filter_chain 配置
filter_chain:
  - type: moderation
    provider: openai
  - type: jailbreak_check
  - type: memory_hook
    name: user_session_store

典型适用场景

场景	为什么用 Plano
多 Agent 产品（如旅行助手、客服机器人）	声明式 Agent 描述 + 内置路由，无需写 intent classifier
需要统一 LLM 网关的企业	一个入口管理所有 Provider，自动做 fallback 和负载路由
对输出内容有合规要求的产品	Filter Chain 统一注入 Moderation，不用每个 Agent 单独写
需要完整可观测性的 AI 应用	零代码自动 OTEL 追踪，排查链路问题
快速切换/测试不同 LLM	改一行配置换 Provider，不动业务代码

坑与注意

免费托管有限制：Plano 官方将 Plano-Orchestrator 模型免费托管在美国中部区域，仅供开发体验。生产环境需要自托管模型或联系官方获取 API Key（见 Discord）。
Agent 必须实现标准接口：你的 HTTP 服务必须暴露 /v1/chat/completions（OpenAI 兼容格式），Plano 才能正确路由。
Linux /tmp 是 tmpfs：某些 Linux 发行版上 /tmp 是独立文件系统，Docker 模式下可能出现跨设备链接错误。生产优先确认 tmpfs 挂载配置。
路由模型为 4B 参数：在低端设备上首次推理延迟可能偏高，这是基于模型做路由的代价。
config.yaml version 字段：文档示例使用 v0.3.0，CLI 版本为 0.4.27，两者有版本差，新功能请以 CLI 版本为准。

与同类对比

维度	Plano	LangChain / LangGraph	Portkey AI	LiteLLM
定位	数据平面 + Agent 编排	应用开发框架	LLM 网关 + 可观测性	LLM 统一调用
Agent 编排	内置声明式路由	代码驱动	不支持	不支持
Filter / Guardrail	Filter Chain 原生	需自行集成	有限	需自行集成
可观测性	Agentic Signals™ + OTEL	视框架而定	追踪丰富	有限
模型	任意 OpenAI 兼容	任意	任意	任意
学习曲线	中（YAML 配置）	高（Python 代码）	低	低

Plano 的独特价值在于它是一个独立进程，不依赖任何应用框架——你的 Python/Node/Go Agent 都可以接入，是真正的"管道层"而非"开发框架"。

一句话推荐结论

如果你在构建多 Agent 系统，受够了每次都要重写路由、追踪和过滤管道，Plano 用一行 YAML 声明把这些全部外包出去——专注写你的业务 Agent，基础设施全部交给它。