为什么?

编码代理人(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)

特征

快速启动

1. 安装

npm install @bunny-agent/sdk ai

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

// 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

"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. 运行

export ANTHROPIC_API_KEY=sk-ant-xxx
npm run dev

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

本地对云沙盒

本地模式( Desktop apps并调试)

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

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在盒子里工作.

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桌面应用,本地开发,调试.

云模式-桑多克(建议)

山多克 沙发 为基于多克的云沙盒提供持续体积.

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

npm install @bunny-agent/sandbox-sandock

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() });

其他云沙盒

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

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

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

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

请求范围 服务器

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

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数字 :

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 沙盒运输(云/本地文件系统)

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

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 发现附加运行时间的能力 开始转弯前:

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

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

见 检索引用合同 页:1 能力计划、AI SDK要求和引用元数据字段.

出口

环境变量

文档

完整文档 : 兔子代理人.dev/docs

• 快速启动指南
• 沙盒配置
• 代理模板
• API 参考

许可证

阿帕奇 - 2.0