# @bunny-agent/sdk 中文文档

规范地址：https://npmcn.com/package/%40bunny-agent/sdk/

版本：0\.10\.3-beta1
npm 元数据更新时间：2026-11-07T00:49:39.979Z
中文译文更新时间：2026-11-08T19:57:38.193Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bunny-agent/sdk
原文对照：https://npmcn.com/package/%40bunny-agent/sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：298 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：ai ^6\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-04-14T06:43:58.097Z
- 最新版本发布：2026-11-07T00:49:39.792Z
- 近 30 天下载量：7219（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：115（近 12 个月 115 个）

## 中文简介

Bunny Agent SDK - 用于构建AI代理的 AI 提供者和反应钩

## 安装

```sh
npm install @bunny-agent/sdk
```

也可以使用：`pnpm add @bunny-agent/sdk`、`yarn add @bunny-agent/sdk`、`bun add @bunny-agent/sdk`

## README

# @bunny-agent/sdk (英语)

**将编码代理超能力插入你的产品——一个下午.**

转弯 [克劳德代码](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), (中文(简体) ), [麻醉剂SDK](https://docs.anthropic.com/en/docs/agents-and-tools/agent-sdk), (中文(简体) ), [代码 CLI](https://github.com/openai/codex), (中文(简体) ), [打开代码](https://github.com/nicepkg/opencode), (中文(简体) ), 和其他编码代理 **AI SDK 兼容型号** 您可以从任何后端流出并在任何 React UI 中渲染.

[![npm](https://img.shields.io/npm/v/@bunny-agent/sdk?style=flat-square)](https://www.npmjs.com/package/@bunny-agent/sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](https://npmcn.com/package/%40bunny-agent/sdk/LICENSE) [![AI SDK](https://img.shields.io/badge/AI_SDK-v6-purple.svg?style=flat-square)](https://sdk.vercel.ai/)

* * *

## 为什么?

编码代理人(Claude Code, Codex CLI, 双子座 CLI, OpenCode.)已经有:

-   高级内存和上下文管理
-   \* 战斗测试工具的使用(bash、文件 I/O、网页搜索)
-   MCP服务器生态系统
-   \* 改进了数百万次互动的提示

**@bunny-agent/sdk让你在自己的产品中掌握所有的东西** ——作为标准AI SDK型号,采用零即时工程.

```
Your App  →  @bunny-agent/sdk  →  Coding Agent (Claude / Codex / …)
                                      ↕
                              Sandbox (Local or Cloud)
```

## 特征

| 特性 | 说明 |
| --- | --- |
| 🔌 **AI SDK 提供者** | `createBunnyAgent()` 返回您通过的模式 `streamText` 编号 : `generateText` |
| ⚛️ **反应钩** | `useBunnyAgentChat`, (中文(简体) ), `useArtifacts`, (中文(简体) ), `useWriteTool`, (中文(简体) ), `useAskUserQuestion` |
| 🖥️ **本地模式** | 内建 `LocalMachine` (无隔离)和 `SrtSandbox` (OS级隔离) – 运行在您的机器上用于桌面应用程序调试( D) |
| ☁️ **云沙盒** | 插进 [山多克 沙发](https://sandock.ai/),E2B,或代顿纳用于孤立的云处决 |
| 🎨 **代理模板** | 基于 Markdown 的模板将通用代理变成域专家 |
| 🔄 **多回合会议** | 以完整文件系统的连续性恢复对话 |

* * *

## 快速启动

### 1\. 安装

```bash
npm install @bunny-agent/sdk ai
```

### 2.后端——创建API路由(Next.js)

```typescript
// app/api/ai/route.ts
import { createBunnyAgent, LocalMachine } from "@bunny-agent/sdk";
import {
  convertToModelMessages,
  createUIMessageStream,
  createUIMessageStreamResponse,
  streamText,
} from "ai";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const sandbox = new LocalMachine({
    workdir: process.cwd(),
    templatesPath: process.cwd(),
    runnerCommand: ["npx", "-y", "@bunny-agent/runner-cli@latest", "run"],
    env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  });

  const bunnyAgent = createBunnyAgent({
    sandbox,
    cwd: sandbox.getWorkdir(),
  });

  const stream = createUIMessageStream({
    execute: async ({ writer }) => {
      const result = streamText({
        model: bunnyAgent("sonnet"),
        messages: await convertToModelMessages(messages),
        abortSignal: request.signal,
      });
      writer.merge(result.toUIMessageStream());
    },
  });

  return createUIMessageStreamResponse({ stream });
}
```

### 3\. 前端——聊天UI

```tsx
"use client";
import { useBunnyAgentChat } from "@bunny-agent/sdk/react";

export default function Chat() {
  const { messages, isLoading, sendMessage } = useBunnyAgentChat({
    apiEndpoint: "/api/ai",
  });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          {m.parts.map((p, i) => p.type === "text" && <span key={i}>{p.text}</span>)}
        </div>
      ))}
      <form onSubmit={(e) => { e.preventDefault(); sendMessage(e.currentTarget.input.value); }}>
        <input name="input" placeholder="Ask anything…" />
        <button disabled={isLoading}>Send</button>
      </form>
    </div>
  );
}
```

### 4\. 运行

```bash
export ANTHROPIC_API_KEY=sk-ant-xxx
npm run dev
```

就是这样,你现在有一个完整的编码代理 流入你的应用.

* * *

## 本地对云沙盒

### 本地模式( Desktop apps并调试)

`LocalMachine` 是内置的,不需要额外的软件包。 该代理直接运行在您的机器文件系统中,并有您的用户权限和 **无隔离** (它以前被命名为 `LocalSandbox`;这个别名仍然有效,但已贬值)。 当你想要本地机器上实际OS级隔离时,请使用 `SrtSandbox` 相反——相同的API,但每个命令都用 [Anthropic 的沙盒运行时间](https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime) (bulble wrap on Linux, Seatbelt on macOS):写作仅限于工作目录,网络访问被屏蔽,除非您允许列表域.

```typescript
import { createBunnyAgent, SrtSandbox } from "@bunny-agent/sdk";

const sandbox = new SrtSandbox({
  workdir: "/path/to/project",
  isolation: {
    allowedDomains: ["api.anthropic.com", "*.npmjs.org"],
    denyRead: ["~/.ssh", "~/.aws"],
    allowWrite: ["~/.npm"], // runners that write to the home dir need this
  },
});
```

Linux 需要吗 `bubblewrap` + 键 `socat` 已安装(并安装在 Ubuntu 24.04+ 上,一个 AppArmor 配置文件,用于授予 `userns` 以图表示。 macOS在盒子里工作.

```typescript
import { createBunnyAgent, LocalMachine } from "@bunny-agent/sdk";

const sandbox = new LocalMachine({
  workdir: "/path/to/project",
  templatesPath: "./my-agent-template",
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const bunnyAgent = createBunnyAgent({ sandbox, cwd: sandbox.getWorkdir() });
```

最佳用途: Electron/Tauri桌面应用,本地开发,调试.

### 云模式-桑多克(建议)

[山多克 沙发](https://sandock.ai/) 为基于多克的云沙盒提供持续体积.

> **为什么是桑多克?** 编码代理依赖于文件系统 `append` 其他POSIX语义学. 山多克是唯一一个有云沙盒的 **100% POSIX 兼容文件系统**,确保代理运行 没有金融服务失败。 音量为 **持久性和可分享性** 穿过沙盒.

```bash
npm install @bunny-agent/sandbox-sandock
```

```typescript
import { createBunnyAgent } from "@bunny-agent/sdk";
import { SandockSandbox } from "@bunny-agent/sandbox-sandock";

const sandbox = new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,   // Get yours at https://sandock.ai
  image: "ghcr.io/vikadata/bunny-agent:latest",     // Pre-built image (fast startup)
  skipBootstrap: true,
  workdir: "/workspace",
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  // Optional: persistent volumes
  volumes: [
    { volumeName: "my-workspace", volumeMountPath: "/workspace" },
  ],
});

const bunnyAgent = createBunnyAgent({ sandbox, cwd: sandbox.getWorkdir() });
```

| 桑多克选项 | 说明 |
| --- | --- |
| `apiKey` | 您的 Sandock API 密钥 ([沙发克.ai](https://sandock.ai/)(中文(简体) ) |
| `image` | Docker 图像 - 使用 `ghcr.io/vikadata/bunny-agent:latest` 用于预建,或 `sandockai/sandock-code:latest` |
| `skipBootstrap` | `true` 当使用预建的图像时( 在沙盒内安装 skips npm) |
| `volumes` | 已命名持续工作空间会话存储的卷( C) |
| `keep` | `true` (默认) 执行后将沙盒活到~30分 |
| `memoryLimitMb` | MB 内存限制 |

### 其他云沙盒

```bash
npm install @bunny-agent/sandbox-e2b      # E2B cloud sandbox
npm install @bunny-agent/sandbox-daytona   # Daytona workspace
```

```typescript
import { E2BSandbox } from "@bunny-agent/sandbox-e2b";
const sandbox = new E2BSandbox({ apiKey: process.env.E2B_API_KEY });

import { DaytonaSandbox } from "@bunny-agent/sandbox-daytona";
const sandbox = new DaytonaSandbox({ apiKey: process.env.DAYTONA_API_KEY });
```

* * *

## 代理模板

模板自定义代理所知道的以及它的行为——纯粹的Markdown,没有代码.

```
my-agent/
├── CLAUDE.md              # System instructions
├── skills/
│   └── sql-expert/
│       └── SKILL.md       # Modular capability
└── .claude/
    └── mcp.json           # MCP server integrations
```

```typescript
const sandbox = new LocalMachine({
  workdir: process.cwd(),
  templatesPath: "./templates/analyst",  // Point to your template
});
```

内建模板 : `default`, (中文(简体) ), `coder`, (中文(简体) ), `analyst`, (中文(简体) ), `researcher`, (中文(简体) ), `seo-agent`。 。 。 .

* * *

## 请求范围 服务器

Pi跑者接受每个模型请求的MCP配置. 配置 穿越守护者JSON或一发跑者CLI有效载荷,从不 写入工作空间 :

```typescript
const bunnyAgent = createBunnyAgent({
  sandbox,
  runnerType: "pi",
  allowedTools: ["read", "bash", "mcp"],
  mcpConfig: {
    mcpServers: {
      analytics: {
        url: "https://mcp.example.com/rpc",
        headers: {
          "X-API-Key": process.env.ANALYTICS_MCP_KEY!,
        },
        auth: false,
        lifecycle: "lazy",
        directTools: false,
      },
    },
    settings: {
      hostConfigDiscovery: "off",
      outputGuard: true,
    },
  },
});
```

信任的 SDK 调用器也可以配置 stdio 服务器 `command`, (中文(简体) ), `args`, (中文(简体) ), `env`,以及 `cwd`;这些命令在所选沙盒内执行。 一个 明确 `allowedTools` 列表必须包含 `mcp`。 。 。 .

配置已请求范围 。 新的配置适用于下一个 消息,包括恢复对话,而活动回合则保留 开始的配置 。 OAuth 和活转热置换不是 由本API提供.

公共网络路由不应直接接受此可信任的形状. 转换 a 严格 HTTPS 仅输入 `McpConfig`,拒绝本地主机/私人目标 在沙盒边界执行网络入侵政策.

* * *

## 反应钩

所有钩子都可以从 `@bunny-agent/sdk/react`数字 :

```typescript
import {
  useBunnyAgentChat,     // Full chat with streaming
  useArtifacts,         // Display agent-generated files (reports, charts)
  useWriteTool,         // Handle file write tool calls
  useAskUserQuestion,   // Handle interactive questions from the agent
} from "@bunny-agent/sdk/react";
```

* * *

## API 参考

### 提供者

#### `createBunnyAgent` 沙盒运输(云/本地文件系统)

```typescript
import { createBunnyAgent, LocalMachine } from "@bunny-agent/sdk";

const bunnyAgent = createBunnyAgent({
  sandbox: SandboxAdapter,       // LocalMachine, SrtSandbox, SandockSandbox, E2BSandbox, etc.
  cwd?: string,                  // Working directory inside sandbox
  env?: Record<string, string>,  // Environment variables
  template?: string,             // Template name
  resume?: string,               // Session ID for multi-turn
  verbose?: boolean,             // Debug logging
});

const model = bunnyAgent("claude-sonnet-4-20250514");
```

#### 守护进程 HTTP 传输( 相同的提供者)

**任何沙盒适配器** (E2B,桑多克, `LocalMachine`等):通过 **`sandbox` + 键 `daemonUrl`**URL 解决 **内部** 沙盒( 沙盒) `vikadata/bunny-agent` 图像开始 `bunny-agent-daemon` 在港口3080。 SDK流经 `streamCodingRunFromSandbox` (单位:千美元)`curl -N` 在沙盒中,包括 `LocalMachine`(没有) `fetch` 从您的服务器。 它没有叫 `/healthz` 除非您选择 Pi 搜索合同 `"auto"`参见下文。 使用 `isBunnyAgentDaemonHealthy` 从 `@bunny-agent/sdk` 在设定前进行明确的准备状态探测 `daemonUrl` (如倒回CLI跑道).

```typescript
import { createBunnyAgent, DEFAULT_BUNNY_AGENT_DAEMON_URL } from "@bunny-agent/sdk";

const bunnyAgent = createBunnyAgent({
  sandbox: mySandboxAdapter,
  daemonUrl: DEFAULT_BUNNY_AGENT_DAEMON_URL, // http://127.0.0.1:3080 inside the container
  runnerType: "claude",
  cwd: "/workspace",
});
```

奥米 `daemonUrl` 用于使用 **CLI 跑者** 在一个沙盒里. `createBunnyAgent` 总是需要一个 `sandbox` 适配器.

#### 结构化网络搜索和回答引用

对于 Pi 守护进程执行, 请选择 `searchContractVersion: "auto"` 关于提供者 或个人模型。 SDK 发现附加运行时间的能力 开始转弯前:

```typescript
const bunnyAgent = createBunnyAgent({
  sandbox: mySandboxAdapter,
  daemonUrl: DEFAULT_BUNNY_AGENT_DAEMON_URL,
  runnerType: "pi",
  searchContractVersion: "auto",
});
```

-   一个有能力的守护进程使用 v1 结构化的搜索和回答说明,并带有 需要流确认。 一个健康的更年长的守护进程使用遗产搜索.
-   发现发送只读 `/healthz` 穿过同一个沙箱运输. 回合执行一次; 永远不会重放来谈判支持 。 失败或 畸形的发现在被执行前拒绝,而不是默默地降级.
-   健康结果被缓存30秒 每个附着的手柄,沙盒ID, 和守护进程 URL 。 现场运行时间重启需要那么长的时间才能发现.
-   选择保留遗产行为而不被发现。 明确 `1` 保持严格的承认要求而不被发现。 CLI 执行 并且其他跑者在 `"auto"` 已选定.

见 [检索引用合同](https://npmcn.com/package/docs/search-citation-contract.md) 页:1 能力计划、AI SDK要求和引用元数据字段.

### 出口

| 入口 | 出口 |
| --- | --- |
| `@bunny-agent/sdk` | `createBunnyAgent`, (中文(简体) ), `BunnyAgentLanguageModel`, (中文(简体) ), `submitAnswer`, (中文(简体) ), `DEFAULT_BUNNY_AGENT_DAEMON_URL`;再出口 `LocalMachine` (从) `@bunny-agent/sandbox-local`和 `SrtSandbox` (从) `@bunny-agent/sandbox-srt`(中文(简体) ) |
| `@bunny-agent/sdk/react` | `useBunnyAgentChat`, (中文(简体) ), `useArtifacts`, (中文(简体) ), `useWriteTool`, (中文(简体) ), `useAskUserQuestion`, (中文(简体) ), `DEFAULT_BUNNY_AGENT_DAEMON_URL` (从 `@bunny-agent/manager`(中文(简体) ) |

* * *

## 环境变量

| 变量 | 需求 | 说明 |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | 对 | Anthropic API 键 |
| `SANDOCK_API_KEY` | 为桑多克 | [沙发克.ai](https://sandock.ai/) API 密钥 |
| `E2B_API_KEY` | 用于E2B | E2B API 密钥 |
| `DAYTONA_API_KEY` | 代托纳 | 代托纳 API 密钥 |

* * *

## 文档

完整文档 : [兔子代理人.dev/docs](https://bunny-agent.dev/docs)

-   [快速启动指南](https://bunny-agent.dev/docs/quick-start)
-   [沙盒配置](https://bunny-agent.dev/docs/sandboxes)
-   [代理模板](https://bunny-agent.dev/docs/templates)
-   [API 参考](https://bunny-agent.dev/docs/api)

* * *

## 许可证

阿帕奇 - 2.0

## 常见问题

### @bunny-agent/sdk 是什么？

Bunny Agent SDK - 用于构建AI代理的 AI 提供者和反应钩

### 如何安装 @bunny-agent/sdk？

在项目目录运行 npm install @bunny-agent/sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^6\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bunny-agent/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bunny-agent/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bunny-agent/sdk 可以商用吗？

@bunny-agent/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bunny-agent/sdk 的下载量有多少？

根据 npm 官方下载统计，@bunny-agent/sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 7,219 次，日均约 241 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bunny-agent/sdk 还在维护吗？

最新版本 0\.10\.3-beta1 发布于 2026/11/07（1 天前）；至今共发布 115 个版本，其中过去 12 个月发布了 115 个；首次发布于 2026/04/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。