利用 Cursor AI 规则与 Universal Registry 构建多智能体应用

1. 项目概述：用 Cursor AI 规则构建你的智能体连接中枢

如果你正在开发 AI 智能体，并且为如何让它找到其他智能体、进行有效交互而头疼，那么你很可能已经接触过 NANDA、MCP、A2A 这些听起来很酷但各自为战的协议。我最近在做一个需要跨协议调用不同 AI 能力的项目，就遇到了这个典型的“连接孤岛”问题。每个协议都有自己的 SDK、认证方式和 API 风格，光是集成测试就耗费了大量时间。直到我发现了 Hashgraph Online 的 Universal Agentic Registry 以及他们为 Cursor AI 准备的hol-cursorrules项目，它本质上是一个预配置的规则文件，能让你在 Cursor 这个 IDE 里，直接获得与一个覆盖了 59,000+ 个智能体的庞大网络进行交互的“超能力”。

简单来说，这个.cursorrules文件不是一个独立的软件，而是一套针对 Cursor AI 编辑器的开发环境配置和代码生成规则。它深度集成了@hashgraphonline/standards-sdk，将访问 Universal Registry 的复杂流程——包括密钥管理、协议适配、请求构造——封装成了你可以直接通过自然语言指令或代码补全调用的模板。这意味着，当你对 Cursor AI 说“帮我写一个搜索天气智能体的函数”时，它生成的不再是简单的骨架代码，而是包含完整认证、错误处理和符合 HOL SDK 最佳实践的、可直接运行的 TypeScript 代码。这极大地降低了开发者，尤其是那些希望快速构建具备网络发现能力 AI 应用的开发者，进入多智能体世界的门槛。无论你是想实验智能体间的自动协作，还是构建一个需要集成多种 AI 服务的复杂应用，这套工具都能为你提供一个坚实、标准的起点。

2. 核心思路拆解：为什么是 Cursor Rules + Universal Registry？

在深入代码之前，理解背后的设计哲学至关重要。这决定了你是否能灵活运用，而非仅仅照搬。整个方案的核心可以拆解为两个部分：统一的服务层（Universal Registry）和智能化的开发层（Cursor Rules）。

2.1 Universal Registry：解决“发现”与“连接”的根本问题

当前 AI 智能体生态的现状是碎片化的。Anthropic 的 MCP 服务器、Google 的 A2A 代理、各种链上验证的 ERC-8004 智能体，以及像 Virtuals 这样的代币化 AI 资产，它们各自生活在不同的网络和协议中。开发者要为每一个协议编写适配器，处理不同的身份验证（可能是 API Key、钱包签名或 OAuth），解析不同的数据格式。这不仅是重复劳动，更使得智能体间的“发现”变得异常困难——你无法在一个地方找到所有可用的服务。

Universal Agentic Registry 的定位就是成为这个“连接层”。它抽象了下游的各种协议（NANDA, MCP, A2A, Virtuals, ERC-8004, x402 Bazaar 等），向上提供了一个统一的、标准化的 RESTful API 和 SDK。你可以把它想象成一个“智能体的 DNS 系统”加“API 网关”。它的核心价值在于：

1. 标准化发现：通过一个search接口，你可以用自然语言（如“weather”、“code review”）或元数据过滤（如协议类型、费用模型）来查找智能体，结果会统一格式返回，无论底层智能体来自哪个协议。
2. 统一连接：通过一个chat接口，你可以与任何被注册的智能体开始对话。Registry 会帮你处理到目标协议的路由、消息格式转换和会话状态管理。
3. 身份与支付抽象：它集成了 Hedera 账户系统（HCS-10）和 x402 支付协议，为智能体交互提供了原生的身份验证和小额支付通道，简化了商业化智能体的调用流程。

2.2 Cursor Rules：将 SDK 能力注入开发工作流

有了强大的服务层，下一步就是降低开发者的使用门槛。这就是hol-cursorrules的用武之地。Cursor AI 是一个集成了大语言模型的 IDE，它不仅能补全代码，更能理解项目上下文，根据规则生成复杂的代码块。.cursorrules文件正是用来“教导” Cursor AI 如何在我们这个特定项目（使用 HOL SDK 的项目）中工作的说明书。

这个文件做了以下几件关键事情：

1. 环境与工具链预设：它定义了项目使用 TypeScript 严格模式、Node.js 20+、pnpm 包管理器、Jest 配合 SWC 进行测试。这确保了 Cursor 生成的代码和推荐的操作（如安装依赖、运行测试）与项目的最佳实践保持一致。
2. HOL SDK 上下文注入：这是最核心的部分。它通过示例代码和规则，让 Cursor AI 深刻理解RegistryBrokerClient这个核心类，包括如何初始化（需要哪些环境变量）、各个方法（search,chat.start,resolveUaid）的调用方式、参数结构以及返回类型。当你让 Cursor “写一个搜索函数”时，它参考的是这些真实、有效的示例，而不是凭空想象。
3. 代码质量约束：它制定了代码规范，比如禁止使用any类型、文件命名采用 kebab-case、单个文件不超过 500 行。这保证了 AI 生成的代码不仅能用，而且整洁、可维护，符合团队协作标准。
4. 工作流引导：它提倡 TDD（测试驱动开发）流程。当你创建一个新功能时，Cursor 可能会优先提示你“是否需要先创建一个测试文件？”，这有助于培养良好的开发习惯。

两者的结合创造了一个高效的开发闭环：Registry 提供强大、统一的后端服务，而 Cursor Rules 则将调用这些服务的最佳实践“编码”到了你的 IDE 中，让你能以接近自然语言的方式，快速生成生产级别的集成代码。这比反复查阅文档、复制粘贴示例要快得多，也准确得多。

3. 从零开始：环境配置与首次集成实操

理论讲完了，我们动手把它用起来。假设你正在启动一个新的 Node.js 项目，目标是构建一个能查询并调用翻译智能体的简单服务。

3.1 项目初始化与基础依赖安装

首先，创建一个新目录并初始化项目。按照.cursorrules的约定，我们使用 pnpm 和 TypeScript。

mkdir my-agent-orchestrator cd my-agent-orchestrator pnpm init

接下来，安装核心依赖。@hashgraphonline/standards-sdk是必须的，同时我们需要 TypeScript 和相关的类型定义。

pnpm add @hashgraphonline/standards-sdk pnpm add -D typescript @types/node ts-node

初始化 TypeScript 配置。为了与规则保持一致，我们生成一个严格的tsconfig.json。

npx tsc --init --strict --esModuleInterop --skipLibCheck

现在，将关键的.cursorrules文件引入项目。这是激活 Cursor AI 特殊能力的一步。

curl -O https://raw.githubusercontent.com/hashgraph-online/hol-cursorrules/main/.cursorrules

完成这一步后，当你用 Cursor IDE 打开这个项目文件夹，它就会自动识别这个规则文件，并加载其中定义的上下文和偏好。你会注意到，它的代码补全建议和聊天回答，开始偏向于 HOL SDK 的模式。

3.2 配置环境变量与客户端初始化

几乎所有与 Registry 的交互都需要身份验证。通常，这涉及 Hedera 测试网的账户 ID 和私钥。我们创建一个.env文件来安全地管理这些敏感信息。

# .env HEDERA_OPERATOR_ID=0.0.1234567 HEDERA_OPERATOR_KEY=302e020100300506032b657004220420... HOL_API_KEY=your_hol_api_key_optional # 如果访问需要API密钥的端点

重要安全提示：永远不要将.env文件提交到版本控制系统（如 Git）。确保它在.gitignore文件中。对于私钥，上述格式是一个示例，实际应使用你从 Hedera Portal 或钱包导出的完整 ED25519 私钥。在生产环境中，应考虑使用密钥管理服务（KMS）或环境变量注入。

接下来，创建项目的入口文件，例如src/index.ts。在这里，我们将初始化RegistryBrokerClient。根据.cursorrules中的示例和 SDK 文档，初始化时需要配置网络端点（默认为主网）和认证信息。

// src/index.ts import { RegistryBrokerClient, Network } from '@hashgraphonline/standards-sdk'; import * as dotenv from 'dotenv'; // 加载环境变量 dotenv.config(); // 初始化客户端 const client = new RegistryBrokerClient({ // 对于开发和测试，强烈建议使用测试网 network: Network.TESTNET, // 或 Network.MAINNET // 认证信息通常从环境变量读取，客户端会在需要时自动使用它们 // 对于某些操作（如chat），需要在调用时显式传递 auth 参数 }); // 简单的健康检查：获取Registry统计信息 async function bootstrap() { try { const stats = await client.getStats(); console.log(`✅ Registry 连接成功！`); console.log(` 总智能体数: ${stats.totalAgents}`); console.log(` 支持协议: ${stats.supportedProtocols.join(', ')}`); } catch (error) { console.error('❌ 无法连接至 Registry:', error); process.exit(1); } } bootstrap();

运行这个脚本，确保一切配置正确。

npx ts-node src/index.ts

如果看到成功的连接信息，恭喜你，你的开发环境已经成功与 Universal Agentic Registry 对接上了。此时，你的 Cursor AI 已经“知晓”了client对象的所有可用方法，你可以尝试在代码中输入client.，看看它给出的智能补全建议，应该包含了search,resolveUaid,chat等方法及其完整的参数提示。

4. 核心功能深度实现与代码解析

环境搭好了，我们来深入实现两个最核心的场景：搜索智能体和与智能体对话。我会给出比官方示例更详细、更健壮的代码，并解释每一步的考量。

4.1 智能体发现：实现一个健壮的搜索模块

搜索是发现的起点。SDK 的client.search()方法非常强大，支持关键词、协议过滤、分页等。我们来实现一个可复用的搜索函数，并处理好错误和结果解析。

// src/agentDiscovery.ts import { RegistryBrokerClient, type AgentSearchParams, type AgentSearchResult, type AgentHit } from '@hashgraphonline/standards-sdk'; export interface SearchOptions { query: string; protocol?: string; // 例如：'mcp', 'a2a', 'virtuals' limit?: number; offset?: number; } /** * 在 Universal Registry 中搜索智能体 * @param client 已初始化的 RegistryBrokerClient 实例 * @param options 搜索选项 * @returns 格式化后的搜索结果列表 */ export async function searchAgents( client: RegistryBrokerClient, options: SearchOptions ): Promise<{ agents: AgentHit[]; total: number; hasMore: boolean }> { const params: AgentSearchParams = { q: options.query, limit: options.limit || 10, offset: options.offset || 0, }; // 如果指定了协议，添加到过滤条件 if (options.protocol) { // 注意：根据实际API，过滤字段名可能是 `registry` 或 `protocol` // 需要查阅最新SDK文档或OpenAPI Spec确认。这里假设为 `registry`。 params.registry = options.protocol; } try { const result: AgentSearchResult = await client.search(params); // 结果处理 const formattedAgents = result.hits.map((hit: AgentHit) => ({ name: hit.name, description: hit.description, uaid: hit.uaid, // Universal Agent ID，用于唯一标识和后续调用 protocol: hit.registry, // 来源协议 // 可能还有其他元数据，如评分、费用等 score: hit._score, })); return { agents: formattedAgents, total: result.total, hasMore: result.offset + result.hits.length < result.total, }; } catch (error) { console.error(`搜索智能体失败 (查询: "${options.query}")：`, error); // 根据错误类型进行更精细的处理，例如网络错误、认证错误、参数错误等 if (error instanceof Error && error.message.includes('auth')) { throw new Error('认证失败，请检查 HEDERA_OPERATOR_ID 和 HEDERA_OPERATOR_KEY 配置。'); } throw error; // 重新抛出，让调用方决定如何处理 } } // 示例用法 async function exampleSearch() { const client = new RegistryBrokerClient({ network: Network.TESTNET }); const translationResults = await searchAgents(client, { query: 'translation english chinese', protocol: 'mcp', // 只搜索 MCP 协议的智能体 limit: 5, }); console.log(`找到 ${translationResults.total} 个翻译相关智能体:`); translationResults.agents.forEach((agent, index) => { console.log(` ${index + 1}. ${agent.name} (${agent.protocol})`); console.log(` 描述: ${agent.description}`); console.log(` UAID: ${agent.uaid}`); }); }

关键点解析：

• 错误处理：搜索可能因网络、认证、查询语法等问题失败。我们使用try-catch包裹，并将认证错误提取出来给出明确提示，这对调试非常友好。
• 结果格式化：原始返回的AgentHit对象可能包含很多字段。我们提取最关键的几个（名称、描述、UAID、协议）组成一个新对象，使调用方更容易使用。UAID 是后续与智能体交互的关键。
• 分页支持：通过offset和limit参数，以及返回的hasMore标志，可以轻松实现“加载更多”的功能。

4.2 与智能体交互：构建一个可管理的对话会话

找到智能体后，下一步就是与它对话。client.chat接口提供了会话管理。这里我们实现一个简单的对话循环，并考虑会话状态的持久化。

// src/agentChat.ts import { RegistryBrokerClient, Network, type ChatConversation, type ChatMessage } from '@hashgraphonline/standards-sdk'; export class AgentChatSession { private conversation: ChatConversation | null = null; private messageHistory: Array<{ role: 'user' | 'agent'; content: string }> = []; constructor( private client: RegistryBrokerClient, private agentUaid: string, private auth: { accountId: string; privateKey: string } ) {} /** * 初始化或重新开始一个对话会话 */ async start(): Promise<void> { try { this.conversation = await this.client.chat.start({ uaid: this.agentUaid, auth: this.auth, }); this.messageHistory = []; // 开始新会话时清空历史 console.log(`✅ 已连接到智能体: ${this.agentUaid}`); } catch (error) { console.error(`❌ 无法启动与智能体 ${this.agentUaid} 的对话:`, error); throw error; } } /** * 向智能体发送消息并获取回复 * @param userMessage 用户输入 * @returns 智能体的回复内容 */ async sendMessage(userMessage: string): Promise<string> { if (!this.conversation) { throw new Error('会话未初始化，请先调用 start() 方法。'); } this.messageHistory.push({ role: 'user', content: userMessage }); try { const response = await this.conversation.sendMessage({ content: userMessage, // 可以附加上下文或元数据，例如： // metadata: { userId: '123', sessionId: 'abc' } }); const agentReply = response.content; // 假设回复是文本，实际可能是复杂对象 this.messageHistory.push({ role: 'agent', content: agentReply }); return agentReply; } catch (error) { console.error(`发送消息失败:`, error); // 可能因为会话过期、费用不足等原因失败，这里可以加入重试或刷新会话的逻辑 throw error; } } /** * 获取当前会话的历史记录 */ getHistory(): Array<{ role: string; content: string }> { return [...this.messageHistory]; } /** * 结束当前会话（如果SDK支持） */ async end(): Promise<void> { // 注意：当前SDK的ChatConversation接口可能没有显式的`end`方法。 // 会话可能由服务器超时管理。这里是一个预留的清理接口。 this.conversation = null; console.log('会话已结束。'); } } // 示例用法：与一个翻译智能体对话 async function exampleChat() { const client = new RegistryBrokerClient({ network: Network.TESTNET }); const auth = { accountId: process.env.HEDERA_OPERATOR_ID!, privateKey: process.env.HEDERA_OPERATOR_KEY!, }; // 假设我们通过搜索找到了一个翻译智能体的 UAID const translatorUaid = 'hcs10://0.0.987654/translator-mcp-agent'; const session = new AgentChatSession(client, translatorUaid, auth); await session.start(); const reply1 = await session.sendMessage('请将“Hello, world!”翻译成中文。'); console.log(`智能体回复: ${reply1}`); const reply2 = await session.sendMessage('再翻译成法语。'); console.log(`智能体回复: ${reply2}`); console.log('对话历史:'); console.log(session.getHistory()); await session.end(); }

关键点解析：

• 会话封装：我们将ChatConversation对象封装在AgentChatSession类中，管理其生命周期和历史记录。这比每次调用都重新创建会话更清晰，也更容易维护状态。
• 错误与状态管理：在sendMessage中检查会话是否存在。在实际生产中，你还需要处理网络中断、智能体无响应、账户余额不足等异常情况，可能需要加入重试机制或回退方案。
• 历史记录：在本地维护一个messageHistory数组非常有用，可以用于在前端展示对话、提供上下文给后续提示，或者实现“回到上一步”的功能。
• 认证传递：注意auth参数在chat.start时传递。这通常是你 Hedera 账户的私钥签名，用于支付智能体调用的微交易（如果该智能体需要付费）。确保私钥的安全存储至关重要。

5. 进阶应用与架构模式

掌握了基础调用后，我们可以探索更复杂的应用模式。这些模式能帮助你构建真正强大、可扩展的多智能体应用。

5.1 智能体路由与负载均衡

当有多个智能体提供相同或类似功能时（例如，多个不同的天气查询服务），一个简单的路由策略可以提升系统的鲁棒性和性能。

// src/agentRouter.ts import { RegistryBrokerClient, type AgentHit } from '@hashgraphonline/standards-sdk'; interface RoutedAgent { uaid: string; weight: number; // 用于加权随机选择 lastResponseTime?: number; // 用于基于性能的路由 failureCount: number; } export class SimpleAgentRouter { private agentPool: Map<string, RoutedAgent[]> = new Map(); // key: 服务类型， value: 智能体列表 constructor(private client: RegistryBrokerClient) {} /** * 为特定服务类型发现并初始化候选智能体池 * @param serviceType 服务类型，如 'weather', 'translation.chinese' */ async discoverAgentsForService(serviceType: string): Promise<void> { const results = await this.client.search({ q: serviceType, limit: 20, // 发现较多候选 }); const agents: RoutedAgent[] = results.hits.map(hit => ({ uaid: hit.uaid, weight: 1, // 初始权重相同 failureCount: 0, })); this.agentPool.set(serviceType, agents); console.log(`为服务 "${serviceType}" 发现了 ${agents.length} 个候选智能体。`); } /** * 根据策略选择一个智能体 * @param serviceType 服务类型 * @param strategy 选择策略：'random' | 'weighted' | 'fastest' */ selectAgent(serviceType: string, strategy: 'random' | 'weighted' = 'weighted'): string | null { const pool = this.agentPool.get(serviceType); if (!pool || pool.length === 0) { return null; } if (strategy === 'random') { const idx = Math.floor(Math.random() * pool.length); return pool[idx].uaid; } // 加权随机（权重越高，被选中的概率越大） if (strategy === 'weighted') { const totalWeight = pool.reduce((sum, agent) => sum + agent.weight, 0); let random = Math.random() * totalWeight; for (const agent of pool) { random -= agent.weight; if (random <= 0) { return agent.uaid; } } } return pool[0].uaid; // fallback } /** * 更新智能体的路由权重（基于成功或失败） * @param serviceType 服务类型 * @param uaid 智能体UAID * @param success 是否成功 */ updateAgentWeight(serviceType: string, uaid: string, success: boolean): void { const pool = this.agentPool.get(serviceType); if (!pool) return; const agent = pool.find(a => a.uaid === uaid); if (agent) { if (success) { agent.weight = Math.min(agent.weight * 1.1, 10); // 成功则小幅增加权重，上限10 agent.failureCount = 0; } else { agent.failureCount++; agent.weight = Math.max(agent.weight * 0.5, 0.1); // 失败则大幅降低权重，下限0.1 // 如果连续失败多次，可以考虑从池中暂时移除 if (agent.failureCount > 3) { console.warn(`智能体 ${uaid} 多次失败，考虑将其从 ${serviceType} 池中排除。`); } } } } }

这个简单的路由器实现了服务发现、加权随机选择以及基于反馈的动态权重调整。在实际生产中，你还可以集成健康检查、延迟测量等更复杂的策略。

5.2 构建一个链式调用（智能体工作流）

多智能体系统的强大之处在于协作。你可以让一个智能体的输出作为另一个智能体的输入，形成工作流。

// src/agentWorkflow.ts import { AgentChatSession } from './agentChat'; import { RegistryBrokerClient, Network } from '@hashgraphonline/standards-sdk'; /** * 一个简单的两阶段工作流：先总结文章，再将总结翻译成目标语言。 */ async function summarizeAndTranslateWorkflow( client: RegistryBrokerClient, articleText: string, targetLanguage: string ): Promise<string> { const auth = { accountId: process.env.HEDERA_OPERATOR_ID!, privateKey: process.env.HEDERA_OPERATOR_KEY!, }; // 阶段 1: 寻找并使用总结智能体 const summarizerUaid = 'hcs10://0.0.111111/summarizer-agent'; // 假设已知 const summarizerSession = new AgentChatSession(client, summarizerUaid, auth); await summarizerSession.start(); const summary = await summarizerSession.sendMessage(`请用一段话总结以下文章：\n${articleText}`); await summarizerSession.end(); console.log(`📝 总结完成: ${summary.substring(0, 100)}...`); // 阶段 2: 寻找并使用翻译智能体 // 这里演示动态搜索。实践中，可以预先发现并缓存。 const searchResults = await client.search({ q: `translation to ${targetLanguage}`, limit: 3 }); if (searchResults.hits.length === 0) { throw new Error(`未找到翻译成 ${targetLanguage} 的智能体`); } const translatorUaid = searchResults.hits[0].uaid; const translatorSession = new AgentChatSession(client, translatorUaid, auth); await translatorSession.start(); const translatedSummary = await translatorSession.sendMessage(`请将以下内容翻译成${targetLanguage}：\n${summary}`); await translatorSession.end(); console.log(`🌐 翻译完成: ${translatedSummary.substring(0, 100)}...`); return translatedSummary; } // 使用示例 async function runWorkflow() { const client = new RegistryBrokerClient({ network: Network.TESTNET }); const longArticle = `...`; // 你的长篇文章内容 try { const finalResult = await summarizeAndTranslateWorkflow(client, longArticle, 'spanish'); console.log('最终结果:', finalResult); } catch (error) { console.error('工作流执行失败:', error); } }

这个例子展示了如何将两个独立的智能体调用串联起来，构建一个复杂的功能。你可以将其扩展为更复杂的 DAG（有向无环图）工作流，其中包含条件分支、并行执行等。

6. 开发、测试与部署实战经验

在实际项目中使用这套工具，有一些经验和陷阱值得分享。

6.1 测试策略：模拟与集成测试

为使用 HOL SDK 的代码编写测试至关重要。由于涉及网络调用和可能的费用，我们需要分层测试。

单元测试（使用 Jest 和模拟）： 对于像AgentChatSession这样的业务逻辑类，我们应该模拟RegistryBrokerClient。

// __tests__/agentChat.test.ts import { AgentChatSession } from '../src/agentChat'; import { RegistryBrokerClient, type ChatConversation } from '@hashgraphonline/standards-sdk'; jest.mock('@hashgraphonline/standards-sdk'); describe('AgentChatSession', () => { let mockClient: jest.Mocked<RegistryBrokerClient>; let mockConversation: jest.Mocked<ChatConversation>; beforeEach(() => { mockConversation = { sendMessage: jest.fn(), } as any; mockClient = { chat: { start: jest.fn().mockResolvedValue(mockConversation), }, } as any; }); it('应该成功发送消息并记录历史', async () => { const session = new AgentChatSession(mockClient, 'test-uaid', { accountId: '0.0.1', privateKey: 'key' }); mockConversation.sendMessage.mockResolvedValueOnce({ content: 'Mocked reply' }); await session.start(); const reply = await session.sendMessage('Hello'); expect(mockClient.chat.start).toHaveBeenCalledWith({ uaid: 'test-uaid', auth: { accountId: '0.0.1', privateKey: 'key' }, }); expect(mockConversation.sendMessage).toHaveBeenCalledWith({ content: 'Hello' }); expect(reply).toBe('Mocked reply'); expect(session.getHistory()).toEqual([ { role: 'user', content: 'Hello' }, { role: 'agent', content: 'Mocked reply' }, ]); }); });

集成测试（有限使用）： 对于真正的端到端测试，可以创建一个专用的 Hedera 测试网账户，并使用一些已知的、免费的测试智能体。务必设置较长的超时时间，并注意测试成本。

// __tests__/integration/registrySearch.integration.ts import { RegistryBrokerClient, Network } from '@hashgraphonline/standards-sdk'; describe('Registry Search Integration', () => { let client: RegistryBrokerClient; jest.setTimeout(30000); // 网络请求可能需要时间 beforeAll(() => { // 仅在配置了测试密钥时才运行 if (!process.env.HEDERA_TESTNET_OPERATOR_ID) { console.warn('未设置测试网密钥，跳过集成测试。'); return; } client = new RegistryBrokerClient({ network: Network.TESTNET, }); }); it('应该能搜索到公开的智能体', async () => { // 假设存在一些公开的测试智能体 const result = await client.search({ q: 'test', limit: 5 }); expect(result.hits).toBeInstanceOf(Array); // 不假设一定有结果，但响应结构应该正确 expect(result).toHaveProperty('total'); expect(result).toHaveProperty('hits'); }); });

6.2 性能优化与缓存策略

频繁调用 Registry 搜索或重复初始化客户端会影响性能。

• 客户端复用：确保在你的应用（如 Express 服务器）中，RegistryBrokerClient实例是单例的，并在整个生命周期内复用。
• 智能体元数据缓存：搜索到的智能体信息（名称、描述、UAID）在一定时间内是稳定的。可以使用内存缓存（如node-cache）或 Redis 来缓存搜索结果，键可以是搜索查询的哈希。设置一个合理的 TTL（例如 5-10 分钟）。
• 连接池与超时：检查 SDK 是否支持 HTTP 客户端配置（如 axios 实例）。可以配置连接池、超时和重试策略来提升网络请求的稳定性。

6.3 部署注意事项

• 环境变量管理：生产环境务必使用安全的秘密管理服务（如 AWS Secrets Manager, HashiCorp Vault）来注入HEDERA_OPERATOR_KEY，绝不要硬编码或提交到代码仓库。
• 网络选择：开发测试阶段务必使用Network.TESTNET。切换到Network.MAINNET前，请充分测试并了解主网交易会产生真实费用。
• 错误监控与告警：集成像 Sentry 或 Datadog 这样的应用监控工具，捕获并告警智能体调用失败、认证错误、余额不足等情况。
• 费用预算：与智能体的交互可能产生微支付。你需要监控 Hedera 账户的余额，并设置预算或警报，防止意外消耗。

7. 常见问题与排查指南

在实际开发中，你肯定会遇到一些问题。以下是我遇到的一些典型情况及其解决方法。

一个实用的调试技巧：在开发初期，大量使用console.log输出关键对象的完整结构，比如search返回的完整结果、chat.start返回的会话对象。这能帮助你快速理解 API 的实际数据格式，比反复查阅文档更高效。另外，充分利用提供的 Postman Collection 直接测试 API，可以隔离 SDK 可能存在的问题，确认是后端服务问题还是前端集成问题。

最后，别忘了这个项目是开源的，并且鼓励贡献。如果你改进了.cursorrules文件，添加了更有用的示例，或者修复了文档中的错误，都可以提交 Pull Request 来获取 HOL Points。这种社区驱动的迭代，正是让工具生态保持活力的关键。