使用 TypeScript + LangChain.js + Bindu 构建 10 题 MCQ 测验 Agent：从 bindufy 配置到 JSON-RPC 调用完整实战

【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址https://gitcode.com/gh_mirrors/bin/Bindu点击查看免费下载本文以 Bindu 仓库中的 typescript-langchain-quiz-agent 示例 为线索完整讲解如何把一个普通的 TypeScript LangChain.js 程序通过bindu/sdk的bindufy()一键改造成具备 A2AAgent-to-Agent协议能力、DID 身份、技能声明与可选认证的 AI Agent 微服务。读完你将掌握示例工程的安装与运行、bindufy()配置项的完整语义、底层Python 核心 gRPC 回调的启动原理、技能文件skill.yaml/SKILL.md的声明方式以及无认证与开启 DID 签名认证两种场景下通过 JSON-RPC 与 Agent 对话的完整方法。示例概览输入一段文本返回一份 10 题测验typescript-langchain-quiz-agent是一个极简但完整的 Agent 示例把一段源文本交给它它会基于 LangChain.js OpenRouter模型为openai/gpt-oss-120b在一条严格约束的系统提示词下生成一份10 道单选题MCQ的测验——每道题 4 个选项A/B/C/D、只有一个正确答案、附一句解析。这个 Agent 被bindufy()包装后注册进 Bindu 核心对外暴露一个符合 A2A 协议的 HTTP 端点外部客户端通过 JSON-RPCmessage/send即可调用。示例的核心价值在于两点语言无关性Agent 的逻辑生成测验与 Bindu 的身份/通信/支付层完全解耦开发者只写业务 handler其余DID、认证、调度、存储、HTTP 网关全部由 Bindu 核心接管零成本上手bindufy()会在本地自动拉起 Bindu Python 核心DID、x402、A2A 协议、调度与存储均在其中开发者看到的是一个函数调用、一个终端。快速开始安装与运行示例的安装与运行步骤见 示例 README整理如下export OPENROUTER_API_KEY在 openrouter.ai/keys 获取的 API Key cd examples/typescript-langchain-quiz-agent npm install然后运行npx tsx quiz-agent.ts # Agent 对外地址http://localhost:3773两点必须注意的细节入口文件是quiz-agent.ts不是index.ts。package.json的scripts.start也明确写为npx tsx quiz-agent.ts见 package.jsontsx直接执行 TypeScript 文件无需先编译。端口占用问题。SDK 会以子进程方式启动 Bindu Python 核心命令形如uv run bindu serve --grpc --grpc-port 4774。示例的bindufy()配置中coreAddress为localhost:4774如果 4774 被占用请修改quiz-agent.ts中的coreAddress字段。依赖方面package.json查看完整清单声明了bindu/sdk以file:../../sdks/typescript方式指向仓库内 SDK、langchain/openai、dotenv、yaml开发依赖为tsx与typescript。其中bindu/sdk是仓库内本地包说明该示例依赖的是仓库自带的 TypeScript SDK 实现sdks/typescript而不是 npm 上的独立发布包。核心代码解剖quiz-agent.ts完整源码见 quiz-agent.ts它由四个部分组成LLM 初始化、系统提示词、bindufy()配置与业务 handler。1. LangChain LLM 初始化OpenRouter 的 baseURL 覆盖写法const llm new ChatOpenAI({ model: openai/gpt-oss-120b, // 与 Python 版本一致 temperature: 0.3, configuration: { baseURL: https://openrouter.ai/api/v1, apiKey: process.env.OPENROUTER_API_KEY, }, });关键点是 OpenRouter 通过baseURL覆盖工作LangChain 的ChatOpenAI默认指向 OpenAI 官方端点此处改为https://openrouter.ai/api/v1模型名带openai/前缀API Key 使用 OpenRouter 的 Key。temperature: 0.3偏保守适合需要稳定输出格式的测验生成任务。2. 系统提示词把输出格式焊死SYSTEM_PROMPTquiz-agent.ts#L27-L55是整个 Agent 行为约束的核心值得完整阅读。它规定恰好生成 10 道多选题每道题 4 个选项 A/B/C/D每题仅一个正确答案每个正确答案附带一句解析语言清晰、学术化。同时给出标准输出模板标题# Quiz: Knowledge Check每题以### Question N开头、**Correct Answer:**与**Explanation:**结尾。这条提示词与技能声明文件SKILL.md中的输出格式模板SKILL.md#L52-L70完全一致保证技能声明的能力与实际行为对齐。3. bindufy()把 Agent 包装成微服务bindufy( { author: your.emailexample.com, name: quiz-generator-agent, description: Educational assessment expert for MCQ generation, version: 1.0.0, deployment: { url: http://localhost:3773, expose: true, cors_origins: [http://localhost:5173], }, skills: [skills/quiz-generation], coreAddress: localhost:4774, capabilities: { streaming: false, push_notifications: false, }, }, async (messages: ChatMessage[]) { ... } );各配置项含义可对照 sdks/typescript/src/types.ts 中的BinduConfig理解配置项示例值说明以源码注释与实现为准authoryour.emailexample.comAgent 作者邮箱必填用于生成 DID 身份的一部分namequiz-generator-agentAgent 名称必填description一句话描述参与 Agent 卡片与能力协商version1.0.0默认1.0.0deployment.urlhttp://localhost:3773Agent 对外 A2A HTTP 地址deployment.exposetrue是否对外暴露deployment.cors_origins[http://localhost:5173]CORS 白名单示例为配合前端开发端口skills[skills/quiz-generation]技能文件路径SDK 会读取目录下skill.yaml或SKILL.md并随注册请求上送核心coreAddresslocalhost:4774Bindu 核心 gRPC 地址默认localhost:3774capabilities{streaming: false, push_notifications: false}能力声明关闭流式与推送kind未填默认agent可选agent/team/workflowcallbackPort未填默认 0SDK 本地 AgentHandler gRPC 端口0 表示自动分配execution_cost可选x402 支付相关的执行成本声明debug_mode/telemetry/num_history_sessions默认false/true/10调试、遥测与历史会话数4. 业务 handler接收消息调用 LLM返回结果async (messages: ChatMessage[]) { if (!messages || messages.length 0) { return Error: No input provided.; } // 只取最后一条用户消息避免盲目传递完整历史 const userInput messages[messages.length - 1].content; const langchainMessages [ { role: system, content: SYSTEM_PROMPT }, { role: user, content: userInput }, ]; const response await llm.invoke(langchainMessages); return typeof response.content string ? response.content : JSON.stringify(response.content); }handler 的签名是(messages: ChatMessage[]) Promisestring | HandlerResponse其中ChatMessage仅含role与content两个字段见 types.ts#L9-L12。这里有两个实现要点一是取messages[messages.length - 1]只提取最新输入而非把全部历史交给 LLM二是对response.content做字符串/对象分支处理兼容 LangChain 的不同返回形态。错误会被捕获并转成Error: ...文本返回不会让调用方看到未处理的异常。bindufy() 底层做了什么一次调用四步装配从 sdks/typescript/src/index.ts 的bindufy()实现 可以完整看到一次函数调用背后的装配过程拉起 Bindu Python 核心launchCore(grpcPort, httpPort)以子进程方式启动核心。gRPC 端口从coreAddress解析示例中 4774 即由此而来HTTP 端口从deployment.url解析示例中 3773。启动 AgentHandler gRPC 服务startAgentHandlerServer(handler, callbackPort)在本地开启一个实现AgentHandler.HandleMessages的 gRPC 服务server.ts#L39-L60核心收到任务后回调它它再调用你的业务 handler。端口为 0 时自动分配。加载技能并注册loadSkills(config.skills, callerDir)读取技能目录下的skill.yaml或SKILL.md内容拼装成注册请求中的skills数组index.ts#L52-L107随后通过registerAgent()调用 gRPCRegisterAgentclient.ts#L40-L78把配置 JSON、技能与回调地址上送核心返回agentId、did、agentUrl。心跳保活每 30 秒调用一次sendHeartbeat(coreAddress, agentId)并在SIGINT时清理资源退出。核心启动本身也有三级降级策略core-launcher.ts#L94-L111优先bindu serve --grpcpip 安装的 CLI其次uv run bindu serve --grpc最后python3 -m bindu.cli serve --grpc。启动后会轮询探测 gRPC 端口是否就绪waitForPort超时 30 秒。也就是说README 中提到的SDK 会 spawnuv run bindu serve --grpc --grpc-port 4774是uv可用、且未安装独立 CLI 时的典型路径。技能声明让 Agent 的能力可被发现、可被协商示例把生成测验的能力声明为一个技能位于 skills/quiz-generation由skill.yaml与SKILL.md双文件构成。skill.yaml完整内容声明了技能的元数据id: quiz-generation-v1、name: quiz-generation、version: 1.0.0、标签education、mcq-creation、assessment 等、输入输出模式text/plain与application/json、示例查询Generate a quiz from this chapter about photosynthesis 等。其中assessment 部分专门服务于技能协商机制keywordsquiz、test、assessment、mcq、multiple-choice、generate、knowledge、check 等用于匹配用户请求specializations对educationconfidence_boost 0.4、assessment0.3、quiz-generation0.5领域给出置信度加成anti_patterns明确声明该技能不处理实时数据、图片/视频、音频、数据库查询、文件上传、代码执行等请求防止被错误路由complexity_indicators按 simple/medium/complex 三档关键词区分请求复杂度。SKILL.md完整内容则是人类与 Agent 可读的能力说明包含输出格式模板、示例查询、性能参考如每份测验恰好 10 题、上下文窗口 128k tokens以及 Integration 代码片段。注意skill.yaml中的avg_processing_time_ms: 5000、context_window_tokens: 128000等是技能元数据中声明的参考值实际表现取决于所选模型与网络状况不应视为性能承诺。另外SDK 的loadSkills逻辑index.ts#L70-L92优先读取skill.yaml解析成功则取其name与description若 YAML 解析失败或文件不存在则回退读取SKILL.md并将格式标记为markdown。因此技能目录中两个文件至少保留一个SDK 即可正常工作。与 Agent 对话无认证模式JSON-RPC 调用以AUTH__ENABLEDfalse启动时直接用 curl 发送 JSON-RPC 请求即可。以下是示例 README 提供的完整请求见 README.md#L24-L30curl -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:Generate a quiz from this text: The mitochondrion is the powerhouse of the cell.}],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 格式jsonrpc: 2.0、id、method: message/send、paramsparams.message中parts数组承载具体内容kind: text的文本并配套messageId、contextId、taskId三个 UUIDparams.configuration.acceptedOutputModes: [application/json]声明可接受的输出模式。发送后通过tasks/get拉取任务结果——产物是一份 markdown 格式的 10 题测验含答案键answer key与每题解析。也就是说完整链路是发送消息 → 核心调度 → 回调你的 handler → LLM 生成 → 产物落库 → 客户端取回。开启认证DID 签名与四个 Header 四道闸门当AUTH__ENABLEDtrue时每次调用必须同时满足两个条件携带 Hydra 签发的短时 bearer token证明你有权限并用 Agent 的 DID 私钥对请求体签名证明请求确实是你发出的。任一缺失Agent 都会以 JSON-RPC-32009拒绝。完整流程见 docs/AUTH.md核心要点如下。每个请求携带的四个 HeaderAuthorization: Bearer access_token ← 来自 Hydra约 1 小时过期 X-DID: did:bindu:author:name:id ← 你的身份 X-DID-Timestamp: unix-seconds ← 与服务器时钟相差须在 300 秒内 X-DID-Signature: base58 Ed25519 sig ← 对 {body, did, timestamp} 的签名服务端四道校验闸门闸门校验内容失败表现1bearer token 存在且在 Hydra 中有效HTTP 401 JSON-RPC-32009 Authentication is required...2X-DID与 token 的client_id一致HTTP 403 {error:Invalid DID signature,details:{reason:did_mismatch}}3该 DID 的公钥已在 Hydra 客户端元数据中注册HTTP 403 details.reason public_key_unavailable4时间戳在 300 秒内且签名验证通过HTTP 403 details.reason invalid_signature时钟偏差与坏签名被合并处理四道闸门按序执行第一处失败即停止全部通过后你的 handler 才会运行。每次请求的四个步骤铸 token向 Hydra 的/oauth2/token以client_credentials换取access_tokenexpires_in约 3599 秒在内存中缓存、到期前约 60 秒刷新构造 JSON-RPC body序列化一次并保持字节不变——签名用的字节必须等于发送的字节签名对第二个 JSON 对象{body: body字符串, did: did, timestamp: ts}做sort_keysTrue的序列化再用 Ed25519 私钥签名并 base58 编码发送带上上述四个 Header。跨语言头号坑JavaScript 的JSON.stringify在冒号和逗号后不加空格而 Python 的json.dumps默认带空格。签名载荷必须采用同一形态否则签名无法验证、报invalid_signature。仓库提供了 canonical fixturedocs/AUTH.md#L230-L253用于跨语言校验种子为 32 个零字节、DID 为did:bindu:test、body 为{test: value}、时间戳为1000签名载荷为{body: {\test\: \value\}, did: did:bindu:test, timestamp: 1000}期望的 base58 签名为3SfU4VPTHLbzZzCn17ZqU6y2tnzHQbdo2nnXQr6XZXk34XgyzwSKRrCYEWRmmGXrV39mdkyhTsy5oasfTpNuqyM2。若结果不一致通常是缺了空格、键未排序或 base58 字母表错误Bindu 使用 Bitcoin 字母表。若不想手写签名逻辑仓库提供了现成实现供参考gateway/src/bindu/identity/local.tsTypeScript 参考实现、docs/postman-did-signing.jsPostman 预请求脚本、docs/AUTHENTICATION.mdbearer token 侧完整讲解与 docs/DID.md签名侧完整讲解。常见问题速查现象最可能原因修复HTTP 401 -32009token 缺失/失效重新铸 token以Authorization: Bearer …携带HTTP 403did_mismatchX-DID与 token 的client_id不一致用与X-DID相同的 DID 铸 tokenHTTP 403public_key_unavailableHydra 客户端元数据缺public_key用GET /admin/clients/did检查注册HTTP 403invalid_signature时钟偏差 300s、重放、body 字节漂移、排序/空格不一致、用了错误的种子每次请求重新签名对要发送的精确字节签名对照 canonical fixture 校验HTTP 400-32700body 结构错误如缺params.configuration发生在认证之前先修 body可先对未认证的 peer 验证继续深入相关仓库资源示例本体examples/typescript-langchain-quiz-agentREADME、源码、技能、package.json、tsconfig.jsonSDK 实现sdks/typescript/src/index.ts、sdks/typescript/src/core-launcher.ts、sdks/typescript/src/client.ts、sdks/typescript/src/server.ts、sdks/typescript/src/types.ts认证文档docs/AUTH.md、docs/AUTHENTICATION.md、docs/DID.md协议定义proto/agent_handler.proto同类示例对照Python 版 LangChain 示例见 examples/beginner、TypeScript OpenAI 直连版见 examples/typescript-openai-agent、TypeScript LangChain 研究 Agent 见 examples/typescript-langchain-agent从一份简单的文本 → 测验业务逻辑出发本示例完整展示了 Bindu 的 Agent 化范式bindufy()负责装配skills/负责能力声明A2A JSON-RPC 负责对外通信DID Hydra 负责身份与认证。你可以把它当作模板替换 handler 与技能声明即可快速产出自己的 TypeScript Agent。赞分享【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址https://gitcode.com/gh_mirrors/bin/Bindu点击查看免费下载相关推荐bindu/sdk TypeScript SDK 实战指南用 bindufy() 一键将任意 TypeScript Agent 升级为 A2A 微服务bindu/sdk TypeScript SDK 实战指南用 bindufy 一键将任意 TypeScript Agent 升级为 A2A 微服务 bin为 Bindu 构建新语言 SDK从 proto 契约到 bindufy() 的完整实现指南为 Bindu 构建新语言 SDK从 proto 契约到 bindufy 的完整实现指南 Bindu 通过 gRPC 实现了语言无关的 Agent 微服务化使用 Bindu TypeScript SDK 将 LangChain.js 研究 Agent 一键封装为带 DID 认证的 A2A 微服务使用 Bindu TypeScript SDK 将 LangChain.js 研究 Agent 一键封装为带 DID 认证的 A2A 微服务 本篇技术指南以仓库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考