Poppyseed · 适用于 Next.js 的 Personal Agent Protocol

来源：https://www.withpoppyseed.dev/

让个人 AI 代理使用你的网站。

Poppyseed 在 Next.js 中实现了 Personal Agent Protocol（https://personalagentprotocol.org/），简称 Poppy。安装一个包，添加一个路由，AI 代理就能找到你的网站、帮助用户登录，并在购买前征得用户同意。

npm install poppyseed zod

可直接粘贴到 Claude Code、Cursor 或 Codex 中，也可以先阅读下面的说明：

为这个使用 Next.js App Router 的应用添加 Personal Agent Protocol（简称 Poppy；规范：https://personalagentprotocol.org/docs/spec）支持，使用 poppyseed 包，让人们个人的 AI 代理能够使用这个应用。

1. 运行：
   npm install poppyseed zod

   然后：
   echo "POPPYSEED_SECRET=$(openssl rand -base64 48)" >> .env.local

2. 在项目根目录创建 poppyseed.config.ts。基于应用现有的数据和函数，挑选 2-4 个有用的只读工具：

   import { definePoppyseed, memoryStore, tool, ToolError } from "poppyseed";
   import { z } from "zod";

   const dev = process.env.NODE_ENV === "development";

   export const poppyseed = definePoppyseed({
     // domain 必须与代理访问的 host 一致：开发环境用 localhost
     organization: {
       name: "",
       domain: dev ? "localhost" : "",
     },
     secret: process.env.POPPYSEED_SECRET!,
     store: memoryStore(),
     ...(dev && {
       baseUrl: "http://localhost:3000",
       dev: { allowInsecureClients: true },
     }),
     // 使用开发服务器的真实端口
     tools: {
       example: tool({
         description: "面向代理的功能描述",
         scope: null, // 公开，无需登录
         input: z.object({ /* 输入 */ }),
         run: async (input) => ({ /* JSON 结果 */ }),
         // 抛出 new ToolError("...") 用于代理应看到的错误
       }),
     },
   });

3. 创建 app/api/poppyseed/[...path]/route.ts（不要导出其他内容）：

   import { toNextHandlers } from "poppyseed/next";
   import { poppyseed } from "@/poppyseed.config";

   export const { GET, POST, DELETE } = toNextHandlers(poppyseed);

4. 在 next.config.ts 中，保留所有现有选项，并包装导出：
   import { withPoppyseed } from "poppyseed/next/config"，
   然后 export default withPoppyseed(nextConfig)。

5. 验证：启动开发服务器，然后对每个工具运行
   npx poppyseed agent http://localhost:3000 <tool-name>。
   只有发现（discovery）和工具调用都成功时才会以退出码 0 结束；
   如有问题请修复，直到成功。然后运行 npm run build。

请提醒我在部署前在托管商的环境变量中设置 POPPYSEED_SECRET。

如果需要访问用户账户的工具、用户批准的购买操作、客服代理，或无服务器托管（postgresStore），请参阅
https://withpoppyseed.dev/docs/guides 和
https://withpoppyseed.dev/docs/deployment。

更喜欢手动操作？请按照快速上手指南（https://www.withpoppyseed.dev/docs/quickstart）操作。

poppyseed.config.ts

import { definePoppyseed, memoryStore, tool } from "poppyseed";
import { z } from "zod";

const dev = process.env.NODE_ENV === "development";

export const poppyseed = definePoppyseed({
  organization: {
    name: "Seed Café",
    domain: dev ? "localhost" : "seed.cafe",
  },
  secret: process.env.POPPYSEED_SECRET!,
  store: memoryStore(),
  ...(dev && {
    baseUrl: "http://localhost:3000",
    dev: { allowInsecureClients: true },
  }),
  tools: {
    menu: tool({
      description: "今日菜单上的饮品",
      scope: null, // 任何人，无论是否已登录
      input: z.object({ size: z.enum(["small", "large"]) }),
      run: ({ size }) => ({ drinks: menu(size) }),
    }),
  },
});

app/api/poppyseed/[...path]/route.ts

import { toNextHandlers } from "poppyseed/next";
import { poppyseed } from "@/poppyseed.config";

export const { GET, POST, DELETE } = toNextHandlers(poppyseed);

next.config.ts

import { withPoppyseed } from "poppyseed/next/config";

// 只有 /.well-known/poppy.json、/oauth/*、/mcp 和 /poppy/*
// 路由到 Poppyseed。其余 URL 仍然属于你。
export default withPoppyseed(nextConfig);

npx poppyseed agent http://localhost:3000 menu

1. 在 /.well-known/poppy.json 中发现了 Seed Café
2. 启动了一个会话，使用自己的密钥签名
3. 通过 MCP 和 OpenAPI 列出了 1 个工具
4. 调用了 menu

{
  "drinks": [
    { "name": "Flat white", "price": 4.2 }
  ]
}

按需开启更多功能

poppyseed.config.ts

export const poppyseed = definePoppyseed({
  organization: {
    name: "Poppy Travel",
    domain: "poppy.travel",
  },
  secret: process.env.POPPYSEED_SECRET!,
  store: postgresStore(pool),
  accounts: {
    current: yourLogin,
    signInUrl: (to) => `/login?return_to=${to}`,
  },
  signIn: {
    device: {
      scopes: ["poppy:read", "poppy:write"],
    },
  },
  conversations: {
    agent: claudeAgent({
      instructions: "帮助旅行者。",
    }),
  },
  tools: {
    search_flights: tool({
      description: "搜索单程航班",
      scope: null,
      input: z.object({
        from: z.string(),
        to: z.string(),
        date: z.iso.date(),
      }),
      run: (input) => ({ offers: searchFlights(input) }),
    }),
    my_trips: tool({
      description: "你的即将出发的行程",
      scope: "poppy:read",
      input: z.object({}),
      run: (_, ctx) => ({ trips: tripsOf(ctx.account.id) }),
    }),
    book_flight: tool({
      description: "预订航班报价",
      scope: "poppy:write",
      input: z.object({ offer_id: z.string() }),
      operation: {
        propose: ({ offer_id }) => quote(offer_id),
        // { summary, terms }
        perform: ({ id, terms }, ctx) => book(ctx.account.id, terms, id),
      },
    }),
  },
});

37 秒看清全部效果

已通过规范校验

98 项一致性检查全部通过，在真实 Next.js 服务器上通过 HTTP 进行验证，覆盖了 Personal Agent Protocol（https://personalagentprotocol.org/docs/spec）中的 147 条规则。每一项检查都通过故意违反对应规则并观察其失败来加以验证。

对你的网站运行同样的检查：

npx poppyseed check https://your.site