使用 Bindu TypeScript SDK 将 OpenAI/OpenRouter Agent 快速发布为带 DID、A2A 与 OAuth 的微服务
使用 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)可还原出完整的六步流水线:
- 拉起 Bindu Python core:根据
coreAddress解析出 gRPC 端口,调用launchCore()以子进程方式启动 core(见下文);如果 core 已在运行,则跳过直接尝试连接。 - 启动 AgentHandler gRPC 服务:
startAgentHandlerServer(handler, callbackPort)在本地起一个 gRPC server(callbackPort=0表示自动分配端口),实现HandleMessages/GetCapabilities/HealthCheck三个服务方法,后续 core 就是通过这个回调把任务派发给你的 handler。 - 加载技能:
loadSkills()扫描skills配置中列出的路径,读取skill.yaml或SKILL.md,把内容内联进注册请求,这样 Python core 无需访问 SDK 项目的文件系统。 - 构造 core 配置:把
BinduConfig映射为与 Pythonbindufy一致的配置 JSON(author、name、description、version、deployment、kind、debug_mode、telemetry、num_history_sessions等),支持可选字段capabilities、execution_cost、extra_metadata。 - 注册 Agent:通过 gRPC 调用
RegisterAgent(见 client.ts),把配置、技能与回调地址提交给 core,返回agent_id、did、agent_url。 - 心跳保活:每 30 秒向 core 发送一次
Heartbeat,进程收到SIGINT时清理定时器并关闭 gRPC server。
也就是说,开发者只写一个函数调用,看到的是一个终端;DID 签发、A2A 协议、OAuth、x402、调度与存储全部发生在 Python core 内部(由 bindu serve --grpc 承载)。
Core 是如何被拉起的
core-launcher.ts 会按顺序尝试三种方式启动 Python core:
bindu serve --grpc --grpc-port <port>(pip 安装的 bindu CLI);uv run bindu serve --grpc --grpc-port <port>(uv 管理环境);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 |
进一步阅读
- TypeScript SDK 完整实现:sdks/typescript/src/index.ts、core-launcher.ts、client.ts、server.ts、types.ts
- gRPC 服务端与注册协议:bindu/grpc/server.py、bindu/grpc/registry.py、协议定义 proto/agent_handler.proto
- CLI 服务命令:bindu/cli/init.py(
bindu serve --grpc [--grpc-port N]) - 认证调用完整说明:docs/AUTH.md;gRPC 跨语言调用:docs/GRPC_LANGUAGE_AGNOSTIC.md、docs/grpc/sdk-typescript.md
- 更多语言示例:TypeScript LangChain Agent(examples/typescript-langchain-agent)、TypeScript Quiz Agent(examples/typescript-langchain-quiz-agent)