使用 Bindu TypeScript SDK 将 OpenAI/OpenRouter Agent 快速发布为带 DID、A2A 与 OAuth 的微服务

原创2026-09-24 13:11:521,641 阅读
文章标签:人工智能AI Agent多智能体后端RPC框架认证鉴权微服务可观测性Web3示例工程

使用 Bindu TypeScript SDK 将 OpenAI/OpenRouter Agent 快速发布为带 DID、A2A 与 OAuth 的微服务

本文基于仓库中的 TypeScript OpenAI Agent 示例(examples/typescript-openai-agent),讲解如何用 TypeScript 编写一个基于 OpenAI SDK 的对话 Agent,并通过 Bindu 的 TypeScript SDK 的 bindufy(config, handler) 一键将其发布为完整的 Agent 微服务——自动获得 DID 身份、A2A 协议端点与 OAuth 认证,与 Python Agent 享有同等能力。读完本文,你将掌握 Bindu TS SDK 的运行原理、配置文件逐项含义、OpenRouter 接入方式,以及开启认证后调用 Agent 的完整姿势。

示例概览:TypeScript 世界里的 "Bindufied" Agent

examples/typescript-openai-agent 是一个最小可运行的完整示例:代码只有 index.ts 一个文件,外加一份技能声明(skills/question-answering/skill.yaml)和依赖清单(package.json)。它演示的核心思路是:

用 TypeScript 写 Agent 逻辑(调用 OpenAI SDK 完成对话),再用 Bindu 把这段逻辑包装成网络服务——Bindu 负责 DID、A2A 端点、OAuth、调度、存储等一切基础设施。

示例将 OpenAI SDK 指向 OpenRouter(baseURL: https://openrouter.ai/api/v1),这样整个示例舰队共享同一把 API Key,便于在同一个测试环境里跑多个 Agent。示例默认模型为 openai/gpt-4o-mini,也可通过 OPENAI_MODEL 环境变量覆盖。

值得注意的是,你写的虽然只是 TS 代码,但 Agent 上线后与 Python Agent 完全相同:拥有 DID、A2A 端点、OAuth——因为 TS SDK 会在后台通过 gRPC 拉起 Python 版的 Bindu core,身份、协议、支付层的能力全部由 core 承载。

环境准备与启动

安装依赖

示例依赖声明在 package.json 中:

依赖 版本要求 作用
@bindu/sdk file:../../sdks/typescript Bindu TypeScript SDK(本地路径安装,即仓库内 sdks/typescript)
openai ^4.0.0 OpenAI/OpenRouter 官方 SDK
dotenv ^16.4.0 读取 .env 环境变量
tsx(dev) ^4.7.0 直接运行 TypeScript,无需先编译
typescript(dev) ^5.4.0 TS 编译器

安装与启动步骤如下:

export OPENROUTER_API_KEY=<get one at https://openrouter.ai/keys>
cd examples/typescript-openai-agent
npm install

dotenv 已在代码中启用(index.ts),所以也可以把 OPENROUTER_API_KEY(以及可选的 OPENAI_MODEL)写入 .env 文件,而不必每次 export。

注意:示例通过 file:../../sdks/typescript 以本地路径引用 SDK。从源码结构看,这意味着开发/调试时直接使用仓库内 SDK 源码;若要在项目外使用,需单独发布并安装 @bindu/sdk 包。

启动 Agent

npx tsx index.ts
# http://localhost:3773

启动成功后,Agent 的 A2A 端点监听在 http://localhost:3773。这背后发生了一次完整的进程编排,详见下一节。

bindufy 一次调用,发生了什么

从 SDK 入口 sdks/typescript/src/index.ts 可以看到,bindufy() 是一个异步函数,接收 BinduConfig 和 MessageHandler,返回 RegistrationResult(包含 agentId、did、agentUrl)。SDK 注释里把整个过程概括为四步:拉起 Python core、启动 gRPC 回调服务、通过 RegisterAgent 注册、保持进程存活处理任务。

结合源码(index.ts)可还原出完整的六步流水线:

  1. 拉起 Bindu Python core:根据 coreAddress 解析出 gRPC 端口,调用 launchCore() 以子进程方式启动 core(见下文);如果 core 已在运行,则跳过直接尝试连接。
  2. 启动 AgentHandler gRPC 服务:startAgentHandlerServer(handler, callbackPort) 在本地起一个 gRPC server(callbackPort=0 表示自动分配端口),实现 HandleMessages / GetCapabilities / HealthCheck 三个服务方法,后续 core 就是通过这个回调把任务派发给你的 handler。
  3. 加载技能:loadSkills() 扫描 skills 配置中列出的路径,读取 skill.yaml 或 SKILL.md,把内容内联进注册请求,这样 Python core 无需访问 SDK 项目的文件系统。
  4. 构造 core 配置:把 BinduConfig 映射为与 Python bindufy 一致的配置 JSON(author、name、description、version、deployment、kind、debug_mode、telemetry、num_history_sessions 等),支持可选字段 capabilities、execution_cost、extra_metadata。
  5. 注册 Agent:通过 gRPC 调用 RegisterAgent(见 client.ts),把配置、技能与回调地址提交给 core,返回 agent_id、did、agent_url。
  6. 心跳保活:每 30 秒向 core 发送一次 Heartbeat,进程收到 SIGINT 时清理定时器并关闭 gRPC server。

也就是说,开发者只写一个函数调用,看到的是一个终端;DID 签发、A2A 协议、OAuth、x402、调度与存储全部发生在 Python core 内部(由 bindu serve --grpc 承载)。

Core 是如何被拉起的

core-launcher.ts 会按顺序尝试三种方式启动 Python core:

  1. bindu serve --grpc --grpc-port <port>(pip 安装的 bindu CLI);
  2. uv run bindu serve --grpc --grpc-port <port>(uv 管理环境);
  3. python3 -m bindu.cli serve --grpc --grpc-port <port>(源码运行兜底)。

启动后它会轮询 gRPC 端口(默认 30 秒超时),端口可连接即视为 core 就绪,并把 core 的输出以 [bindu-core] 前缀转发到当前终端。若 bindu 命令不存在,会提示先安装 pip install bindu[grpc]。

端口约定与冲突处理

示例默认配置 coreAddress: "localhost:4774",而 SDK 内置默认值是 localhost:3774(见 types.ts)。gRPC 端口与 HTTP 端口的换算关系在 index.ts:gRPC 端口取自 coreAddress,HTTP 端口取自 deployment.url(默认 3773)。

示例 README 特别提醒:如果 4774 端口被占用(开发环境下 gateway 的 dev server 常驻于此),请修改 bindufy 配置里的 coreAddress 指向空闲端口。同理,3773 端口被占用时也应调整 deployment.url。

对应地,Python 侧 CLI 也支持 bindu serve --grpc <a href="https://link.gitcode.com/i/4aa40231bdc49c1fcb661862e75eaba7" target="_blank">--grpc-port N],默认 gRPC 端口 3774,定义见 [bindu/cli/init.py。

逐行拆解 index.ts:配置文件与 handler

完整配置清单

示例中的 bindufy 配置(index.ts)覆盖了 SDK 中最常用的字段:

字段 示例值 类型 说明
author opnai-sample-ts@getbindu.com string(必填) Agent 作者,参与 DID 身份组成
name openai-assistant-agent string(必填) Agent 名称,用于注册与 A2A 卡片
description "An assistant built with the OpenAI SDK and Bindu..." string(可选) Agent 描述
version "1.0.0" string(可选,默认 "1.0.0") 版本号
deployment.url "http://localhost:3773" string(必填) Agent 对外 A2A 端点
deployment.expose true boolean 是否对外暴露
deployment.cors_origins ["http://localhost:5173"] string[] 允许的跨域来源(示例中为前端 inbox 开发服务器端口)
skills ["skills/question-answering"] SkillConfig[] 技能路径或内联定义
coreAddress "localhost:4774" string(默认 "localhost:3774") Python core 的 gRPC 地址

SDK 类型定义(types.ts)中还提供了更多可选字段:kind("agent" | "team" | "workflow",默认 "agent")、capabilities(streaming、push_notifications、state_transition_history)、execution_cost(x402 支付所需的金额/代币/网络/收款地址)、extra_metadata、debug_mode、telemetry(默认 true)、num_history_sessions(默认 10)、callbackPort(AgentHandler 回调端口,默认自动分配)。

Handler:你的 Agent 逻辑

bindufy 的第二个参数是消息处理函数(类型 MessageHandler,见 types.ts):

async (messages: ChatMessage[]) => {
  const response = await openai.chat.completions.create({
    model: process.env.OPENAI_MODEL || "openai/gpt-4o-mini",
    messages: messages.map((m) => ({
      role: m.role as "user" | "assistant" | "system",
      content: m.content,
    })),
  });
  return response.choices[0].message.content || "";
}

要点:

  • messages 是 Bindu 传入的对话历史(ChatMessage[],每项含 role 与 content),直接映射为 OpenAI SDK 的 messages 数组;
  • 模型默认 openai/gpt-4o-mini,可用 OPENAI_MODEL 环境变量覆盖;
  • handler 返回纯字符串即可;SDK 的 server.ts 在 HandleMessages 中会把字符串封装为 {content, state:"", is_final:true} 的 gRPC 响应回传给 core。若返回 HandlerResponse 对象,则 state、prompt、metadata 会被一并透传,用于表达 input-required、auth-required 等状态转换。

与 Agent 对话:认证关闭与开启两种姿势

AUTH__ENABLED=false:直接 JSON-RPC 调用

未开启认证时,可用 curl 直接调用 A2A 端点(示例 README 原文命令):

curl -sS http://localhost:3773/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"message/send","id":"00000000-0000-0000-0000-000000000004","params":{"message":{"role":"user","parts":[{"kind":"text","text":"Reply with one plain-text sentence: capital of France?"}],"kind":"message","messageId":"00000000-0000-0000-0000-000000000001","contextId":"00000000-0000-0000-0000-000000000002","taskId":"00000000-0000-0000-0000-000000000003"},"configuration":{"acceptedOutputModes":["application/json"]}}}'

请求体是标准 JSON-RPC 2.0,method 为 message/send,params.message 携带角色、文本 part 以及 messageId/contextId/taskId 等标识。

常见坑:模型返回 input-required 并不是 bug。 示例 README 特别说明:如果你提的是含糊的开放式问题,openai/gpt-4o-mini 有时会以 JSON 形式回复 {"state":"input-required","prompt":"..."}——这是模型在索要澄清,bindu 的响应检测器会把它解析成合法的 input-required 任务状态。把提示词写明确,才能得到 completed 状态。

AUTH__ENABLED=true:四头签名调用

开启认证后(AUTH__ENABLED=true),每次调用需要同时完成授权证明与身份证明两件事,缺一不可(详见 docs/AUTH.md):

请求头 示例 作用
Authorization Bearer <access_token> 来自 Hydra OAuth 服务器的短时 token(约 1 小时过期)
X-DID did:bindu:<author>:<name>:<id> 调用者身份
X-DID-Timestamp Unix 秒 与服务器时钟相差须在 300 秒内
X-DID-Signature base58 Ed25519 签名 对 {body, did, timestamp} 签名

core 的中间件按四道闸门依次校验(见 AUTH.md):token 有效性 → X-DID 与 token 的 client_id 一致 → DID 公钥已注册 → 时间戳与签名有效;任一失败即拒绝(典型错误码 -32009)。示例 README 建议直接参考 docs/AUTH.md 实现签名调用。

技能声明:Agent 能力如何被协商

示例挂载了 skills/question-answering/skill.yaml,它是一份完整的 Bindu 技能清单,包含:

  • 元数据:id: question-answering-v1、name、version、author;
  • 描述:由 OpenRouter 统一 API 提供 300+ 模型(GPT-4o、Claude、Llama、Gemini、Mistral 等)的通用问答能力;
  • 模式:input_modes/output_modes 均为 text/plain 与 application/json;
  • 示例查询:examples 提供 6 条典型提问,帮助协商与路由;
  • 能力明细:capabilities_detail 声明对话问答、代码辅助(typescript/python/rust/kotlin/go/java)、分析推理、创意写作;
  • 需求:requirements 列出 @openrouter/sdk 依赖、联网要求与 OPENROUTER_API_KEY;
  • 评估字段:assessment 提供 keywords、specializations(带 confidence_boost)、anti_patterns 与 complexity_indicators,供能力协商/技能匹配使用。

从 SDK 实现看,skills 配置既可以传文件路径(SDK 读取 skill.yaml 或 SKILL.md 并内联进注册请求),也可以直接传内联对象(name、description、tags、input_modes、output_modes、version、author),两种形式见 index.ts。

常见问题速查

症状 原因与对策
npx tsx index.ts 后 Agent 无法上线 core 拉取失败:确认本机可执行 bindu CLI(pip install bindu[grpc]),或存在 uv 环境可执行 uv run bindu
4774 端口冲突 gateway dev server 占用时,把 coreAddress 改为空闲端口(如 localhost:4775)
3773 端口冲突 修改 deployment.url 中的端口,保持与 gRPC 端口分离
含糊提问返回 input-required 属正常状态转换,非 bug;明确提示词可获得 completed 状态
开启认证后调用被拒(-32009) 检查四个请求头是否齐全、DID 签名是否正确、时间戳是否在 300 秒窗口内,详见 docs/AUTH.md

进一步阅读

登录后查看全文
Bindu