Bindu TypeScript SDK 实战指南:用 bindufy() 把任意 TS Agent 变成一个带身份、认证与支付的微服务

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

Bindu TypeScript SDK 实战指南:用 bindufy() 把任意 TS Agent 变成一个带身份、认证与支付的微服务

导读

本指南围绕 Bindu 的 TypeScript SDK(@bindu/sdk)展开:它提供与 Python 侧同名的 bindufy() 函数,让你用 OpenAI SDK、LangChain.js 或原生 fetch 写出的 TypeScript Agent,在不重写任何基础设施的前提下,直接获得 DID 身份、OAuth2 认证、x402 支付、任务调度、存储与 A2A 协议能力。读完本文你将掌握 SDK 的安装方式、bindufy() 从启动 Python 核心到注册 Agent 的完整执行链路、五种 Handler 编写模式、全部配置项与类型定义、Skill 加载机制,以及 gRPC 桥接层(GrpcAgentClient)的底层原理与当前限制。

核心思想:一次函数调用,一个完整微服务

Bindu 是 AI Agent 的身份、通信与支付层。它的 TypeScript SDK 解决的核心问题是:你已经有 TypeScript Agent,不想用 Python 重写基础设施。

import { bindufy } from "@bindu/sdk";

bindufy({
  author: "dev@example.com",
  name: "my-agent",
  deployment: { url: "http://localhost:3773", expose: true },
}, async (messages) => {
  // Your agent logic — any framework, any LLM
  return "Hello from TypeScript!";
});

一次函数调用,一个终端,就是一个完整微服务。SDK 的入口实现位于 sdks/typescript/src/index.ts,其文档注释明确写道:开发者只看到 bindufy(),所有 gRPC 管道细节都被内部消化。

关键在于:TypeScript 侧通过 gRPC 适配器拿到了与 Python Agent 完全相同的微服务能力——DID 身份、A2A 协议、x402 支付、OAuth2 认证、Redis 调度、PostgreSQL 存储,全部无需重新实现。Python 版本是 bindufy(config, handler)(handler 在同进程内运行),TypeScript 版本是 bindufy(config, handler)(handler 在 TS 进程运行,基础设施在 Python 核心中运行)。同名函数、同构配置、同样的结果,只是语言不同。

安装:npm 包 + Python 核心

SDK 本身通过 npm 安装:

npm install @bindu/sdk

同时,机器上必须安装 Bindu Python 核心(SDK 依赖它承担全部基础设施职责):

pip install bindu
# 或使用 uv:
uv pip install bindu

SDK 会自动探测并启动 Python 核心,不需要手动启动它。如果核心缺失或启动失败,控制台会输出提示 Make sure Bindu is installed: pip install bindu<a href="https://link.gitcode.com/i/00c79da4f489b6c3649b70094b69ae8e" target="_blank">grpc](见 [core-launcher.ts)。

调用 bindufy() 时究竟发生了什么

bindufy() 的执行流程共 9 步,在 sdks/typescript/src/index.ts 中可逐行对应:

  1. SDK 读取磁盘上的 Skill 文件(yaml/markdown),把内容随注册请求一并发给核心;
  2. SDK 在随机端口启动一个 gRPC 服务器——这是核心回调你的 handler 的入口(AgentHandler 服务,见 server.ts);
  3. SDK 以子进程方式启动 bindu serve --grpc 作为核心;
  4. SDK 等待核心的 gRPC 服务在 :3774 就绪;
  5. SDK 调用 RegisterAgent,携带你的 config、skills 和回调地址;
  6. 核心运行完整的 bindufy 管道——DID、认证、x402、manifest、HTTP 服务器;
  7. SDK 收到 agent ID、DID 和 A2A URL;
  8. SDK 启动心跳循环(每 30 秒一次);
  9. 终端显示 "Waiting for messages..."。

当客户端通过 A2A HTTP 发来消息时,核心调用你的 handler(经 gRPC),你处理后返回字符串,核心再用 DID 签名把响应回传给客户端。按 Ctrl+C 时,SDK 会终止 Python 核心并退出。

核心启动的三级回退策略

从源码 core-launcher.ts 看,启动核心按以下顺序尝试:

优先级 命令 适用场景
1 bindu serve --grpc --grpc-port <port> 已通过 pip 安装 bindu CLI
2 uv run bindu serve --grpc --grpc-port <port> uv 托管的 Python 环境
3 python3 -m bindu.cli serve --grpc --grpc-port <port> 纯 Python 模块回退

启动后,SDK 通过 waitForPort() 以 500ms 间隔轮询端口连通性,最长等待 30 秒;超时会报错 Bindu core did not start within 30s on port ...。核心的 stdout/stderr 会统一加上 [bindu-core] 前缀打印到你的终端,方便排查。核心作为子进程随父进程退出而被清理(SIGINT/SIGTERM/exit 均会触发 child.kill("SIGTERM"))。

注册与心跳的 gRPC 调用

注册逻辑在 sdks/typescript/src/client.ts:

  • registerAgent(coreAddress, configJson, skills, callbackAddress):连接核心 :3774 的 BinduService,发送 RegisterAgent 请求(config 以 JSON 字符串传递,skills 以 proto 结构传递),成功后解出 agent_id、did、agent_url;
  • sendHeartbeat(coreAddress, agentId):每 30 秒向核心发送一次 Heartbeat 请求,表明 SDK 进程仍存活。心跳失败会被静默忽略,不影响主流程。

端口架构:三个端口,各司其职

:3773  HTTP   — A2A 协议(客户端连接这里)
:3774  gRPC   — Agent 注册(SDK 连接这里)
:XXXXX gRPC   — Handler 执行(核心回调 SDK,动态端口)
  • :3773 是核心启动的 A2A HTTP 服务器,客户端、Agent Card、支付协商都走这里;
  • :3774 是核心的 gRPC 注册服务(BinduService),SDK 在这里完成注册与心跳;
  • 动态端口是 SDK 侧 AgentHandler gRPC 服务器,callbackPort: 0 表示由系统自动分配。

gRPC 协议层:两个服务、六个 RPC

仓库根目录的 proto/agent_handler.proto 定义了 SDK 与核心的全部契约,核心注释点明设计意图:config 以 JSON 字符串传输,使 proto 与 Python 配置 schema 解耦,新增配置字段无需改动 proto。

  • BinduService(运行在核心,:3774):RegisterAgent、Heartbeat、UnregisterAgent;
  • AgentHandler(运行在 SDK 侧,动态端口):HandleMessages(一元调用,核心发消息、SDK 执行 handler 返回结果)、HandleMessagesStream(服务端流式,已定义但 SDK 侧未启用)、GetCapabilities、HealthCheck。

HandleResponse 中的 state 字段支持 ""、"input-required"、"auth-required" 三种取值,与核心侧 ResponseDetector.determine_task_state() 一一对应。SDK 侧 server.ts 的 HandleMessages 实现正是这一契约的具体落地:handler 返回字符串时封装为 {content, state: "", is_final: true};返回对象时透传 state、prompt、metadata;handler 抛错则回传 grpc.status.INTERNAL 错误。

Handler 编写模式

MessageHandler 的签名是 (messages: ChatMessage[]) => Promise<string | HandlerResponse>。以下五种模式覆盖了绝大多数实战场景。

简单响应

async (messages) => {
  return "The answer is 42.";
}

任务立即以该响应完成。

OpenAI SDK

import OpenAI from "openai";
const openai = new OpenAI();

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

仓库中的完整可运行示例见 examples/typescript-openai-agent/index.ts——它通过 OpenRouter 兼容端点调用模型(baseURL: "https://openrouter.ai/api/v1",模型默认 openai/gpt-4o-mini),并额外演示了 coreAddress: "localhost:4774" 覆盖默认端口、cors_origins 配置等进阶用法。

LangChain.js

import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({ model: "gpt-4o" });

async (messages) => {
  const response = await llm.invoke(
    messages.map(m => ({ role: m.role, content: m.content }))
  );
  return typeof response.content === "string"
    ? response.content
    : JSON.stringify(response.content);
}

LangChain 的 invoke 结果可能是复合对象,因此需要做类型收窄。完整示例见 examples/typescript-langchain-agent/(一个带 research Skill 的 LangChain.js 调研助手)。

多轮对话(状态转移)

有时 Agent 需要更多信息才能回答。返回一个状态转移对象即可:

async (messages) => {
  if (messages.length === 1) {
    // First message — ask for clarification
    return {
      state: "input-required",
      prompt: "Could you be more specific about what you're looking for?"
    };
  }

  // Second message — now answer
  const lastMessage = messages[messages.length - 1].content;
  return `Based on your clarification: here's the detailed answer about "${lastMessage}"...`;
}

input-required 状态下任务保持开启,用户发送后续消息后,核心会携带完整对话历史再次调用你的 handler。这一机制在核心侧由 ResponseDetector 根据 state 字段判定任务状态,最终落到 input-required 状态。

错误处理

如果 handler 抛出异常,SDK 会捕获并返回 gRPC 错误,核心的 ManifestWorker 将任务标记为失败,用户收到错误响应。

async (messages) => {
  try {
    return await myLlmCall(messages);
  } catch (err) {
    // Option A: Let it throw — task fails with error message
    throw err;

    // Option B: Return a graceful message
    return "Sorry, I'm having trouble processing your request right now.";
  }
}

需要区分的是:handler 内的 try/catch 只能拦截同步与 await 的异常;未捕获异常由 server.ts 统一转为 grpc.status.INTERNAL,核心侧 GrpcAgentClient 收到后由 ManifestWorker 既有的错误处理机制接管,将任务标记为失败——这正是"gRPC 层对上下游透明"的体现。

配置项详解

BinduConfig 的完整类型定义在 sdks/typescript/src/types.ts,以下是带注释的完整配置示例:

bindufy({
  // Required
  author: "dev@example.com",        // 用于 DID 生成(必填)
  name: "my-agent",                  // Agent 名称(必填)
  deployment: {
    url: "http://localhost:3773",    // A2A HTTP 服务器地址(必填)
    expose: true,                    // 是否暴露给 CORS 来源(默认 false)
    cors_origins: ["http://localhost:5173"],  // 允许的 CORS 来源
    protocol_version: "v1",          // A2A 协议版本(可选)
  },

  // Optional
  description: "What my agent does",
  version: "1.0.0",                  // 默认 "1.0.0"
  skills: ["skills/question-answering"],   // 文件路径或内联定义
  execution_cost: {                  // x402 支付配置
    amount: "1000000",               // 原子单位金额(字符串)
    token: "USDC",                   // 代币类型(默认 "USDC")
    network: "base-sepolia",         // 网络(默认 "base-sepolia")
    pay_to_address: "0x...",         // 收款地址(可选)
  },
  capabilities: {
    streaming: false,                // 是否支持流式
    push_notifications: false,       // 是否支持推送通知
    state_transition_history: false, // 是否记录状态转移历史
  },

  // Advanced
  coreAddress: "localhost:3774",     // 覆盖核心 gRPC 地址(默认 "localhost:3774")
  callbackPort: 0,                   // 0 = 自动分配
  kind: "agent",                     // "agent" | "team" | "workflow",默认 "agent"
  extra_metadata: {},                // 附加元数据
  debug_mode: false,
  telemetry: true,                   // 默认 true
  num_history_sessions: 10,          // 保留的历史会话数,默认 10
}, handler);

各字段在 index.ts 中被组装为发给核心的 config JSON:debug_mode 默认 false、telemetry 默认 true、num_history_sessions 默认 10;capabilities、execution_cost、extra_metadata 仅在显式配置时才加入。核心侧会以与 Python bindufy() 完全相同的 ConfigValidator 校验这份 JSON——这也是 proto 保持与配置 schema 解耦的原因。

x402 支付配置

设置 execution_cost 后,Agent 将进入 x402 支付管道:客户端需要先完成支付(如 USDC / base-sepolia 网络)才能调用你的 handler。amount 是字符串形式的原子单位金额。支付流程的完整说明见 docs/PAYMENT.md 与 docs/grpc/README.md。

Skills:定义 Agent 的能力

SDK 支持两种 Skill 定义方式,加载逻辑见 index.ts 的 loadSkills()。

文件式(推荐)

创建 skills/my-skill/skill.yaml 或 skills/my-skill/SKILL.md:

bindufy({
  skills: ["skills/question-answering", "skills/code-review"],
}, handler);

loadSkills() 会以 process.cwd() 为基准解析路径:优先读取 skill.yaml(并尝试从 YAML 中解析 name、description),否则读取 SKILL.md(格式标记为 markdown),随后把 raw_content 连同名称、标签、输入/输出模式封装成 proto 的 SkillDefinition 发送给核心。这样核心无需访问 SDK 项目的文件系统——所有 Skill 内容都在注册时随请求传输(见 proto/agent_handler.proto 中 SkillDefinition.raw_content 的注释)。

内联式

bindufy({
  skills: [{
    name: "question-answering",
    description: "Answer questions using GPT-4o",
    tags: ["qa", "assistant"],
    input_modes: ["text/plain"],
    output_modes: ["text/plain"],
    version: "1.0.0",
    author: "dev@example.com",
  }],
}, handler);

仓库中大量真实示例的 Skill 文件可以参考 examples/typescript-langchain-agent/skills/research/,以及文档 docs/SKILLS.md 中关于 Skill 清单与格式的说明。

类型系统

SDK 导出的类型定义在 sdks/typescript/src/types.ts,开发者只接触这些类型,永远不需要接触 gRPC 或 proto 类型:

interface ChatMessage {
  role: string;     // "user", "assistant", or "system"
  content: string;
}

// Your handler signature
type MessageHandler = (messages: ChatMessage[]) => Promise<string | HandlerResponse>;

interface HandlerResponse {
  content?: string;
  state?: "input-required" | "auth-required";
  prompt?: string;
  metadata?: Record<string, string>;
}

// Returned by bindufy()
interface RegistrationResult {
  agentId: string;
  did: string;
  agentUrl: string;
}

注意 BinduConfig 中的 deployment 为必填项,且 author 与 name 缺失会导致核心侧校验失败(报 "Registration failed")。RegistrationResult.did 形如 did:bindu:...,是核心在注册管道中生成的 W3C 去中心化标识符。

底层原理:GrpcAgentClient 这座桥

TypeScript SDK 之所以"零基础设施心智负担",核心秘诀在 Python 侧的 GrpcAgentClient(详见 docs/grpc/client.md)——它是一个长得像函数的类:调用它传入消息,返回字符串或 dict,但内部实际执行了一次到远端进程的 gRPC 调用。调用方对此完全无感。

这解决了一个关键工程问题:核心的 ManifestWorker 有一行 raw_results = self.manifest.run(message_history or [])。对 Python Agent,manifest.run 是对开发者 handler 的包装;对 TypeScript/Kotlin Agent,这同一行调用需要走网络——但 ManifestWorker 负责任务状态转移、错误处理、追踪和支付结算,改动它风险极高。方案就是:让 GrpcAgentClient 成为"长得像 handler 的可调用对象"。

注册时,BinduServiceImpl.RegisterAgent 创建 GrpcAgentClient(request.grpc_callback_address),并在 create_manifest() 中执行 manifest.run = grpc_client——从此该 Agent 的每个任务都流经这个客户端。其内部三步走:

# 1. 把 Python dict 转成 protobuf
proto_msgs = [ChatMessage(role=m["role"], content=m["content"]) for m in messages]
request = HandleRequest(messages=proto_msgs)

# 2. 通过 gRPC 调用 SDK 的 AgentHandler
response = self._stub.HandleMessages(request, timeout=self._timeout)

# 3. 转回 ManifestWorker 期望的类型
if response.state:
    return {"state": response.state, "prompt": response.prompt}
else:
    return response.content

转换、调用、转换回去,三步就是整座桥。GrpcAgentClient 是唯一知道 gRPC 存在的组件,它之上(ManifestWorker、ResultProcessor、ResponseDetector、ArtifactBuilder)与之下(DID 签名、支付结算)的代码对 gRPC 完全无感知。由于采用惰性连接(首次调用时才建立 channel),注册瞬间 SDK 的 gRPC 服务器尚未就绪也不会报错。SDK 崩溃后,下一次 HandleMessages 会以 grpc.StatusCode.UNAVAILABLE 失败,ManifestWorker 既有错误处理会将其标记为任务失败。

一次完整问答的调用链如下:

ManifestWorker calls manifest.run(messages)
  → GrpcAgentClient.__call__([{"role": "user", "content": "..."}])
    → 转 protobuf: ChatMessage(role="user", content="...")
    → gRPC: AgentHandler.HandleMessages(HandleRequest{messages: [...]})
    → TypeScript SDK 收到调用
    → 开发者 handler 运行: await openai.chat.completions.create(...)
    → SDK 返回: HandleResponse{content: "...", state: ""}
  → GrpcAgentClient 看到 state 为空,返回字符串
→ ManifestWorker 收到结果(与本地 handler 完全一致)
→ ResultProcessor 归一化 → ResponseDetector 判定 "completed"
→ ArtifactBuilder 创建 DID 签名产物
→ 用户收到响应

调试与手动测试

查看核心日志:Python 核心输出统一带 [bindu-core] 前缀打印在终端:

[bindu-core] INFO  gRPC server started on 0.0.0.0:3774
[bindu-core] INFO  Agent registered: openai-assistant-agent
[bindu-core] INFO  HTTP server started on 0.0.0.0:3773

手动测试 Agent:

# A2A 服务器是否在运行?
curl http://localhost:3773/health

# Agent Card 长什么样?
curl http://localhost:3773/.well-known/agent.json | python3 -m json.tool

# 发送一条测试消息
curl -X POST http://localhost:3773 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"Hello"}],"messageId":"test-1","contextId":"test-2","taskId":"test-3","kind":"message"}},"id":"1"}'

端口冲突:清理占用 3773/3774 端口的进程:

lsof -ti:3773 -ti:3774 | xargs kill 2>/dev/null

常见故障(来自 sdks/typescript/README.md 的 Troubleshooting 章节):

  • "Bindu core did not start within 30s":核心启动失败。执行 pip show bindu 确认安装,用 bindu serve --grpc --help 或 uv run bindu serve --grpc --help 验证 CLI 可用;
  • "Registration failed":核心已启动但拒绝了配置。查看终端的 [bindu-core] 日志,常见原因是缺少 author 或 name、端口被占用;
  • "Handler error":handler 抛出了异常。常见原因是 .env 缺 API Key、调用 LLM 网络错误、响应格式非法。

当前限制与特性对比

  • 无流式输出:handler 必须返回完整响应,无法逐块产出(HandleMessagesStream 在 proto 中已定义,但 GrpcAgentClient 未调用,见 docs/grpc/limitations.md)。对 2 秒内的短回答无感知差异,对长回答(分析、代码生成、研究)体验差距明显;
  • 依赖 Python:必须安装 Bindu 核心(pip install bindu);
  • 每端口单 Agent:每次 bindufy() 调用使用 :3773 作为 HTTP 端口。

gRPC Agent 与 Python Agent 的完整特性对比:

特性 Python Agent gRPC Agent
一元响应 可用 可用
流式响应 可用 未实现
DID 身份 可用 可用
x402 支付 可用 可用
Skills 可用 可用
状态转移(input-required) 可用 可用
健康检查 可用 可用
多语言 仅 Python 任意语言
延迟开销 0ms 1-5ms
TLS 不适用(进程内) 未实现
自动重连 不适用(进程内) 未实现

结论是:gRPC Agent 在核心功能(DID、认证、支付、Skills、A2A 协议)上与 Python Agent 完全对齐,差距集中在流式、安全与韧性三方面,均属后续规划范畴。此外,gRPC 连接目前使用 grpc.insecure_channel(明文),仅建议在 localhost 或可信网络运行;SDK 进程崩溃后不会自动重连,需要重新 RegisterAgent;尚无 gRPC 专属指标与多实例负载均衡(可用 Envoy 等反向代理前置 SDK 实例并将代理地址注册为回调)。

运行示例

在仓库中可以找到两个可直接运行的参考实现:

其余语言 SDK 与协议细节可继续阅读 docs/grpc/README.md(架构总览)、docs/grpc/api-reference.md(gRPC 方法级参考)与 docs/grpc/sdk-development.md(为 Rust、Go、Swift 等语言构建新 SDK)。gRPC 相关的 E2E 测试位于 tests/integration/grpc/test_grpc_e2e.py,可作为协议行为的可执行文档。

登录后查看全文
Bindu