当前位置：首页 > news >正文

Starknet智能体开发：构建安全自主的链上AI代理基础设施

news 2026/5/11 7:27:58

1. 项目概述：构建自主、安全且可组合的Starknet智能体基础设施

如果你正在探索如何让AI智能体（Agent）在Starknet区块链上自主、安全地执行任务，比如自动进行DeFi交易、管理链上身份或审计智能合约，那么你很可能已经遇到了一个核心难题：如何将智能体的“大脑”与一个安全、可控且具备链上执行策略的“钱包”无缝结合。大多数现有的智能体框架只是把钱包当作一个简单的插件或外部服务，这带来了巨大的安全隐患和操作限制。starknet-agentic这个开源项目正是为了解决这个问题而生。它不是一个简单的工具库，而是一套完整的、将钱包、链上身份和执行策略视为一等公民的基础设施框架。

简单来说，starknet-agentic为开发者提供了在Starknet上构建“政策驱动型”自主智能体所需的一切。它包含智能合约、运行时集成包和可复用的技能模块，使得智能体不仅能调用链上功能，还能在链上拥有可验证的身份（ERC-8004标准），其每一次操作都受到预先定义好的策略（如单次交易限额、可调用合约白名单）的约束。这意味着你可以构建一个智能体，让它帮你自动进行DCA（美元成本平均法）投资，但你完全不用担心它会突然把全部资产转到一个可疑地址——因为链上的账户合约会直接拒绝这笔不符合策略的交易。

这套框架非常适合两类人：一是希望为现有AI智能体（如在Claude Code、OpenClaw等环境中运行的智能体）添加强大且安全的Starknet区块链能力的开发者；二是希望从零开始构建一个真正去中心化、自主运行的链上AI应用的团队。无论你是想快速集成一个Cairo合约审计技能，还是想设计一个复杂的多智能体DeFi策略集群，starknet-agentic都提供了模块化的组件和清晰的路径。

2. 核心设计理念：为什么钱包和策略必须是“一等公民”？

在深入技术细节之前，理解starknet-agentic的设计哲学至关重要。这决定了它与其他智能体框架的根本区别。

2.1 传统智能体框架的局限性

当前主流的AI智能体运行时（如基于OpenAI API构建的框架）通常遵循一个简单的模式：智能体逻辑（LLM+工具调用）在中心化服务器或本地运行，当需要与区块链交互时，它通过一个简单的SDK（如ethers.js、starknet.js）调用RPC，而私钥往往以环境变量或配置文件的形式存在。这种模式有几个致命缺陷：

私钥暴露风险：私钥直接存储在运行智能体的环境中，一旦该环境被入侵，所有资产面临风险。
策略执行滞后：任何执行策略（如“单日转账不超过100U”）都只能在智能体的应用层代码中实现。如果智能体逻辑出现bug或被恶意提示词注入（Prompt Injection），策略可能被绕过。
身份模糊：智能体的行为无法与一个持久的、可验证的链上身份绑定。它的每一次操作都是匿名的，难以建立信誉或进行责任追溯。

2.2 Starknet-agentic的解决方案：链上策略执行边界

starknet-agentic颠覆了上述模式，其核心思想是：将执行策略和身份验证下放到区块链层，由智能合约来充当智能体的“安全守门人”。

它通过一套精心设计的账户抽象合约来实现这一点。具体来说：

智能体专属账户合约：每个智能体不再直接使用一个普通的EOA（外部拥有账户）私钥，而是部署一个专属的智能合约账户。这个合约账户的拥有者（Owner）是你（用户），而智能体运行时则持有一个或多个由该账户合约授权的“会话密钥”。
会话密钥与策略：会话密钥的权限是受限的。你在部署账户合约时，可以定义精细的策略，例如：这个会话密钥只能向地址A、B、C发送代币；单笔交易价值不得超过X；每天累计交易额不得超过Y；只能调用特定的DeFi合约等。
链上强制执行：当智能体使用会话密钥发起交易时，交易会先提交到其所属的账户合约。账户合约的__validate__和__execute__函数会首先校验该交易是否符合预设策略。只有完全符合策略的交易才会被签名并广播到网络。策略的校验是在Starknet虚拟机中完成的，具有确定性和不可篡改性。
ERC-8004链上身份：除了资产控制，智能体还可以在链上注册一个符合ERC-8004标准的身份标识。这个标识可以关联信誉分数、能力声明（Capabilities）和验证记录。其他合约或智能体可以通过查询这个身份来决定是否与之交互，实现了链上可信协作的基础。

这种架构带来了几个关键优势：

安全：即使智能体运行时的服务器被完全攻破，攻击者也只能在预设的策略范围内进行操作，无法转移核心资产或进行破坏性操作。
确定性与合规：所有策略公开透明且在链上强制执行，为自动化金融操作提供了可审计的合规基础。
可组合性：具备链上身份的智能体可以像DeFi乐高一样被其他合约或智能体发现和调用，开启真正的多智能体协作经济。

3. 核心组件深度解析与实操要点

starknet-agentic项目结构清晰，模块化程度高。理解每个组件的职责是正确使用和扩展它的前提。

3.1 合约层：安全的基石

合约位于contracts/目录下，是整个系统的安全核心，全部用Cairo编写。

agent-account(智能体账户合约)：这是最重要的合约。它实现了支持会话密钥的账户抽象逻辑。你可以把它理解为一个多签钱包的升级版，但权限管理更加灵活。其核心函数包括添加/移除会话密钥、更新会话密钥策略、执行交易等。在部署时，你需要初始化一个主管理员密钥（通常由用户自己冷存储保管），然后由这个管理员来授权给智能体运行时使用的会话密钥。
注意：会话密钥的私钥仍然需要被智能体运行时访问。为了生产环境安全，starknet-agentic强烈建议使用“代理签名者”模式，即会话密钥的签名操作在一个隔离的安全服务（如HSM或特制硬件）中完成，而不是在运行智能体应用的同一进程中。
erc8004-cairo(链上身份注册表)：这是ERC-8004标准的Starknet实现。它包含三个核心注册表：
1. 身份注册表：记录智能体的唯一标识符（通常是账户合约地址）和元数据（名称、描述、链接）。
2. 信誉注册表：允许其他实体（可以是合约或链下预言机）为某个身份提交信誉评分。例如，一个DeFi协议可以在智能体成功完成一次无损套利后，为其增加“盈利能力”信誉分。
3. 验证注册表：用于记录对某个身份或声明的验证结果。例如，一个“KYC提供商”合约可以验证某个智能体背后关联的实体是否通过了合规检查。这套系统为“去中心化信誉”和“可验证声明”提供了底层基础设施，是构建复杂协作生态的关键。
session-account(会话账户原语)：提供了一些更低级别的模块，用于构建自定义策略的账户合约。如果你对agent-account的默认策略模型不满意（例如想实现基于时间的策略、基于预言机价格的策略），可以基于这里的模块进行二次开发。

3.2 运行时集成层：MCP与A2A桥梁

为了让智能体运行时能方便地调用上述合约功能，项目提供了packages/下的集成包。

starknet-mcp-server(MCP服务器)：这是最常用的集成方式。MCP（Model Context Protocol）是Anthropic提出的一个协议，用于标准化AI模型与外部工具之间的通信。这个包实现了一个MCP服务器，将Starknet的各种操作（查询余额、发送交易、与DeFi协议交互等）暴露为一系列工具（Tools）。你的智能体运行时（如Claude Code、OpenClaw）只需连接这个MCP服务器，就能像调用普通函数一样进行链上操作，无需关心底层的RPC调用和交易构造细节。
- 实操要点：在开发环境中，MCP服务器可以配置为直接使用会话密钥的私钥进行签名。但在生产环境，务必通过环境变量或配置项启用proxy_signer_url，将签名请求转发到你部署的代理签名服务，确保私钥不泄露。
starknet-a2a(A2A适配器)：A2A（Agent-to-Agent）协议专注于智能体间的通信与工作流编排。这个包提供了将Starknet能力和事件接入A2A工作流的能力。例如，你可以设置一个监控特定合约事件的智能体，当事件触发时，通过A2A协议通知另一个负责交易的智能体执行操作。
create-starknet-agent(脚手架工具)：这是最快的入门方式。运行npx create-starknet-agent@latest会启动一个交互式命令行工具，自动检测你当前使用的智能体开发环境（如Claude Code、Cursor等），并为你初始化一个预配置好的项目，包含了必要的依赖、MCP服务器配置示例和基础技能。

3.3 技能库：开箱即用的能力模块

skills/目录下存放着“技能包”。一个技能就是一组预定义好的、用于完成特定任务的工具集合和提示词模板。它们是构建功能型智能体的高效积木。

cairo-auditor(Cairo合约审计技能)：这是一个非常实用的技能。它允许智能体（如Claude）对Cairo智能合约代码进行安全检查。你只需将合约代码或文件路径提供给智能体，它就能调用这个技能来分析潜在的重入漏洞、整数溢出、访问控制缺陷等。其亮点在于集成了“确定性预检”和“误报过滤”，能提供更精准的报告。
- 安装与使用：在Claude Code中，你可以通过/plugin marketplace add keep-starknet-strange/starknet-agentic添加市场，然后安装starknet-agentic-skills插件来获取所有技能。之后在聊天中直接输入/starknet-agentic-skills:cairo-auditor并附上合约代码即可。
starknet-wallet(钱包操作技能)：提供了基础的链上操作能力，如查询余额、发送STRK或ETH转账、管理会话密钥、与付费主（Paymaster）交互以使用ERC-20代币支付Gas费等。
starknet-defi(去中心化金融技能)：封装了与Starknet上主流DeFi协议（如JediSwap、10kSwap、AVNU聚合器）交互的逻辑。智能体可以利用这个技能执行代币兑换、限价单、提供流动性等复杂操作。内部通常集成了价格滑点保护、最优路径计算等逻辑。
starknet-identity(链上身份技能)：专门用于管理ERC-8004身份，包括注册身份、更新元数据、查询信誉分数、发起或响应验证请求等。

每个技能都独立封装，可以通过npx skills add命令单独安装到兼容的智能体运行时中。技能的设计遵循“单一职责”原则，方便组合使用。例如，一个DeFi套利智能体可能会同时调用starknet-defi和starknet-wallet技能。

4. 从零开始的完整实操流程：构建一个自主DeFi智能体

理论讲完了，我们动手搭建一个实际的智能体。假设我们的目标是：构建一个在Starknet测试网（Sepolia）上运行的智能体，它能够监控两个DEX间的价格差，并在有利可图时自动执行套利交易，同时所有交易受到严格的链上策略限制。

4.1 第一步：环境准备与项目初始化

首先，确保你的开发环境符合要求。你需要Node.js（>=18）和pnpm。然后，使用脚手架快速创建项目。

# 使用脚手架创建项目，它会自动适配你的开发环境 npx create-starknet-agent@latest my-arbitrage-agent cd my-arbitrage-agent

脚手架会询问几个问题，例如：

智能体运行时：选择你使用的平台（例如Claude Code）。
目标网络：选择Starknet Sepolia（测试网）。
是否初始化示例技能：选择Yes，并勾选starknet-defi和starknet-wallet。
是否设置链上策略：选择Yes，并设置一个简单的策略，例如“单笔交易价值不超过10 STRK”。

完成问答后，脚手架会生成一个项目结构，大致如下：

my-arbitrage-agent/ ├── .env.example # 环境变量示例文件 ├── package.json # 项目依赖 ├── mcp-server.config.js # MCP服务器配置文件 ├── agent/ # 智能体主逻辑目录（可能包含提示词、工作流定义） └── skills/ # 本地技能目录（链接或复制了所选技能）

接下来，复制环境变量文件并填写你的配置：

cp .env.example .env

编辑.env文件，填入关键信息：

# 网络配置 STARKNET_RPC_URL=https://starknet-sepolia.infura.io/v3/YOUR_INFURA_KEY STARKNET_CHAIN_ID=SN_SEPOLIA # 智能体账户配置（后续部署后填写） AGENT_ACCOUNT_ADDRESS= AGENT_ACCOUNT_SESSION_PRIVATE_KEY= # 代理签名者URL（生产环境使用，开发可暂留空） PROXY_SIGNER_URL= # 付费主合约地址（可选，用于ERC-20支付Gas） STARKNET_PAYMASTER_ADDRESS=

4.2 第二步：部署智能体账户合约并配置策略

这是最关键的安全步骤。我们需要在链上部署一个属于该智能体的账户合约，并为其配置会话密钥和策略。

项目通常提供了一个部署脚本。查看生成的scripts/目录或package.json中的脚本命令。假设有一个deploy-agent-account脚本。

准备部署者私钥：你需要一个拥有测试网ETH（用于支付Gas）的账户私钥。将其导出为环境变量（仅用于临时部署，切勿提交）。
```
export DEPLOYER_PRIVATE_KEY=0x你的部署者私钥
```
运行部署脚本：
```
pnpm run deploy-agent-account
```
脚本会执行以下操作：
- 使用部署者账户发起交易，部署一个新的智能体账户合约。
- 将你（或一个管理多签）设置为主管理员（Owner）。
- 生成一对新的会话密钥（公钥和私钥），并将其添加到账户合约中，同时附带上一步在脚手架中定义的策略（如交易限额）。
- 输出部署结果，包括AGENT_ACCOUNT_ADDRESS和AGENT_ACCOUNT_SESSION_PRIVATE_KEY。
更新环境变量：将脚本输出的地址和会话私钥填入.env文件的对应位置。
重要安全警告：AGENT_ACCOUNT_SESSION_PRIVATE_KEY是智能体运行时用来签名的密钥。在本地开发中，我们可以将其放在.env中，但必须确保.env文件不被上传至Git。在生产环境中，绝对不要将此私钥放在应用环境中。必须使用前面提到的代理签名者模式，将PROXY_SIGNER_URL指向一个安全的签名服务，并从.env中移除私钥。
为账户充值：向新部署的AGENT_ACCOUNT_ADDRESS转入少量测试网STRK或ETH，作为智能体未来的交易Gas费和操作资金。

4.3 第三步：开发智能体逻辑与集成MCP服务器

现在，智能体的“安全钱包”已经就绪。接下来是开发其“大脑”——决策逻辑。

启动MCP服务器：在项目根目录下，运行MCP服务器。它会读取.env配置，并将会话密钥和策略封装成安全的工具接口。
```
pnpm run start-mcp-server
```
服务器启动后，会输出一个连接地址（如ws://localhost:3000）或Stdio通信配置。你的智能体运行时需要连接到这里。
在Claude Code中连接（以Claude Code为例）：
- 在Claude Code中，打开设置，找到“MCP服务器”或“工具连接”配置。
- 添加一个新的服务器连接，类型选择stdio或sse（根据mcp-server.config.js的配置）。
- 命令填写为node，参数填写为path/to/your/project/mcp-server.config.js的绝对路径。
- 保存后，Claude Code会重启并连接到你的MCP服务器。连接成功后，你可以在聊天中尝试让Claude调用工具，例如：“查询我的智能体账户余额”。

编写套利策略逻辑：智能体的核心逻辑可以用自然语言描述在提示词（Prompt）中，也可以结合更结构化的编程。在agent/目录下，你可以创建一个工作流文件（例如arbitrage_workflow.json）或提示词文件。核心逻辑伪代码提示词：

你是一个DeFi套利智能体，连接了我的Starknet MCP工具。你的任务是： 1. 每5分钟监控一次JediSwap和10kSwap上STRK/ETH交易对的价格。 2. 计算价格差异率。如果发现10kSwap上的STRK价格比JediSwap低超过0.5%，则执行以下套利： a. 使用`starknet-defi`技能的`swap`工具，在10kSwap上用X个ETH购买STRK。（X由账户可用资金和策略决定，例如不超过资金的20%） b. 等待第一笔交易确认后，立即使用`swap`工具，在JediSwap上将刚买到的STRK全部卖出换回ETH。 3. 每次执行前后，记录利润估算。如果单次预估利润低于Gas成本，则放弃交易。 4. 所有操作必须通过我的MCP工具进行，不得自行构造交易。 我的智能体账户地址是：{{AGENT_ACCOUNT_ADDRESS}}。请开始执行监控。

将这个提示词提供给Claude，它就会开始利用MCP工具自动执行监控和交易。由于底层交易需要经过账户合约的策略校验（如单笔交易限额），所以即使提示词被恶意修改为“转走所有资金”，链上合约也会拒绝该非法交易。

4.4 第四步：测试与运行

本地测试：在测试网环境下，先用极小的金额（如0.001 STRK）运行智能体，观察其日志和链上交易，确保逻辑正确，策略生效。
监控与日志：确保MCP服务器和智能体运行时都有完善的日志输出，记录每笔交易的哈希、状态和利润计算结果。
策略调优：根据测试结果，你可能需要调整链上策略（如提高限额）或优化智能体的决策参数（如价差阈值、资金分配比例）。调整策略需要主管理员发起合约交易来更新会话密钥的权限。

5. 进阶架构：多智能体协作与生产环境部署

当你掌握了单个智能体的构建后，可以探索更复杂的架构，starknet-agentic的示例库提供了很好的蓝图。

5.1 多智能体Swarm示例 (`full-stack-swarm`)

这个示例展示了如何协调多个具有不同专长的智能体共同工作。例如：

侦察员智能体：负责监控链上事件和价格数据，发现机会后通过A2A协议发布“任务”。
执行员智能体：订阅特定类型的任务（如套利、清算），接收到任务后，使用自己的专属账户和策略去执行。
审计员智能体：在执行员提交交易前，对交易进行模拟和审查，通过A2A协议反馈风险提示。

这种架构的关键在于：

A2A协议：作为智能体间的通信总线。
ERC-8004身份：每个智能体都有身份和信誉。执行员智能体可能需要一定的“可靠性”信誉分才能接收高价值任务。
独立的账户与策略：每个智能体有独立的账户合约，策略各不相同。侦察员可能只有查询权限，而执行员拥有受限的交易权限。

5.2 生产环境安全部署要点

将实验性的智能体推向生产环境，必须高度重视安全。

必须使用代理签名者：绝不在应用程序进程内存放会话私钥。部署一个独立的签名服务（可以使用packages/starknet-mcp-server中提供的代理模式参考实现），该服务运行在高度安全的环境中（如硬件安全模块HSM、机密计算环境）。MCP服务器配置proxy_signer_url指向该服务。签名服务只做一件事：验证请求来源，然后用其安全存储的私钥签名。
精细化策略设计：生产环境的策略应极其保守。考虑以下维度：
- 支出限额：单笔、每日、每周。
- 合约白名单：只允许与经过严格审计的知名协议（如JediSwap, Nostra）交互。
- 时间锁：对于重大操作（如更改策略、更换会话密钥），设置24小时的时间锁，给管理员应急反应时间。
- 紧急暂停：在账户合约中实现一个由主管理员触发的紧急暂停开关。
监控与告警：建立链下监控，监听智能体账户的所有交易。对异常交易（如超出常规金额、调用陌生合约）实时告警。
渐进式部署：先在小额、隔离的环境中长时间运行，观察其行为稳定性，再逐步增加资金和权限。

6. 常见问题与排查技巧实录

在实际开发和运行中，你肯定会遇到各种问题。以下是我在实践过程中总结的一些典型问题和解决方法。

6.1 MCP服务器连接失败

症状：智能体运行时（如Claude Code）提示无法连接到MCP服务器，或工具列表为空。
排查步骤：
1. 检查服务器进程：首先确认pnpm run start-mcp-server是否成功运行，并无报错退出。查看服务器日志，确认它正在监听指定端口或已准备好Stdio通信。
2. 检查连接配置：在Claude Code的设置中，仔细核对MCP服务器的连接配置。如果是Stdio模式，确保“命令”和“参数”的路径完全正确。可以尝试在终端手动运行配置中的命令，看是否能启动服务器。
3. 检查环境变量：确保.env文件中的STARKNET_RPC_URL有效且网络可达。可以尝试用curl或starknet.js手动调用一下RPC。
4. 检查私钥格式：确保AGENT_ACCOUNT_SESSION_PRIVATE_KEY是有效的十六进制字符串（以0x开头）。一个常见错误是复制了助记词而非私钥。

6.2 交易被账户合约拒绝

症状：智能体发起交易后，交易在钱包（账户合约）层面被拒绝，错误信息可能包含Transaction execution reverted或Error in the called contract。
排查步骤：
1. 查询会话密钥策略：使用Starkscan或类似区块浏览器，调用你的智能体账户合约的get_session_key_policy视图函数，传入会话密钥的公钥。检查返回的策略是否允许你正在尝试的操作（目标合约、代币、金额上限）。
2. 模拟交易：在发送真实交易前，先使用starknet.js的account.estimateFee或account.simulateTransaction方法进行模拟。模拟失败的错误信息通常会更清晰地指出违反了什么策略。
3. 检查Nonce：确保智能体正确地获取和使用了当前账户的Nonce。如果多个进程共用同一个会话密钥，可能导致Nonce冲突。建议在MCP服务器层实现一个简单的Nonce管理锁。
4. 检查付费主：如果使用了付费主（Paymaster）用ERC-20代币支付Gas，请确保付费主合约已批准足够的代币额度给账户合约，且付费主服务运行正常。

6.3 智能体逻辑“失控”或做出非预期行为

症状：智能体没有按预期执行套利，或者做出了明显不合理的交易决策。
排查步骤：
1. 审查提示词：这是最常见的原因。检查你的提示词是否足够清晰、无歧义。是否明确限制了操作条件（价差>X%）和资金用量（不超过Y%）。尝试在提示词中加入“逐步思考”的指令，让智能体输出其推理过程。
2. 检查工具输出解析：智能体依赖于MCP工具返回的数据（如价格）。确认工具返回的数据格式是智能体能够正确解析的。有时价格查询可能返回多个路径，智能体可能错误地选择了第一个。可以在工具描述或提示词中指定更精确的数据解析方式。
3. 引入“二次确认”步骤：对于高价值操作，不要让它完全自主执行。修改工作流，在最终交易发送前，增加一个“人工确认”或“模拟报告”步骤。让智能体先输出它计划执行的交易详情和预期结果，经过程序化或人工检查后再放行。
4. 启用详细日志：在MCP服务器和智能体逻辑中增加详细日志，记录每一个决策点的输入（获取到的价格）和输出（决定的操作）。这有助于事后复盘问题根源。

6.4 性能与延迟问题

症状：套利机会转瞬即逝，但智能体从发现到执行完成耗时过长，错过机会。
优化方向：
1. RPC节点选择：使用低延迟、高可用性的私人RPC节点，而非免费的公共节点。Infura、Alchemy等提供商通常有更优的性能。
2. 并行化与异步：监控价格和发送交易可以使用异步并行处理。例如，使用Promise.all同时查询多个DEX的价格。
3. 本地缓存与预测：对于Gas价格、基础代币价格等相对变化较慢的数据，可以进行短期缓存，减少不必要的RPC调用。
4. 交易模拟优化：simulateTransaction调用本身有开销。对于高度重复的交易模式（如相同的交易路径），可以缓存模拟结果，或在策略允许的情况下，对小额交易跳过模拟，接受一定的失败风险。
5. 调整监控频率：权衡监控频率与RPC调用成本、机会捕获率之间的关系。对于高频套利，可能需要订阅链上事件流（如WebSocket）而非轮询。

构建一个健壮的链上自主智能体是一个持续迭代的过程。starknet-agentic提供了强大的基础设施，将最复杂的安全和策略问题抽象化，让你能更专注于智能体本身的策略逻辑。从一个小型的、策略严格的测试网智能体开始，逐步积累经验和信心，是通向成功最稳妥的路径。记住，在区块链世界，代码即法律，而starknet-agentic帮助你为你的智能体编写了第一套，也是最关键的一套法律。

查看全文

http://www.jsqmd.com/news/794365/