# @21st-sdk/agent 中文文档

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

版本：0\.0\.18
npm 元数据更新时间：2026-04-28T18:00:22.684Z
中文译文更新时间：2026-11-06T12:09:58.663Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4021st-sdk/agent
原文对照：https://npmcn.com/package/%4021st-sdk/agent/?lang=original
项目主页：https://21st.dev/agents

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

- 包体积（解压后）：61.6 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：zod \>=3\.24
- 首次发布：2026-03-06T02:33:43.828Z
- 最新版本发布：2026-04-28T18:00:22.524Z
- 近 30 天下载量：3264（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

定义 AI 代理和工具,对 21 代理 机构进行全面类型推断

## 安装

```sh
npm install @21st-sdk/agent
```

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

## README

# @ 21st- sdk/ 代理服务器

定义全类型推断的AI代理. 配置层 [21号特工](https://21st.dev/agents)。 。 。 .

## 安装

```bash
npm install @21st-sdk/agent zod
```

## 快速启动

创建 `src/agent.ts`数字 :

```ts
import { agent, tool } from "@21st-sdk/agent"
import { z } from "zod"

export default agent({
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful coding assistant.",
  tools: {
    greet: tool({
      description: "Greet a user by name",
      inputSchema: z.object({ name: z.string() }),
      execute: async ({ name }) => ({
        content: [{ type: "text", text: `Hello, ${name}!` }],
      }),
    }),
  },
})
```

然后部署与 [第21个SDK CLI](https://www.npmjs.com/package/@21st-sdk/cli)数字 :

```bash
npx @21st-sdk/cli login
npx @21st-sdk/cli deploy
```

## API 密码

### `agent(config)`

创建代理配置。 返回配置为 a `_type: "agent"` 运行时间标记 .

```ts
export default agent({
  // Model to use (default: "claude-sonnet-4-6")
  model: "claude-sonnet-4-6",

  // For "claude-code" runtime, string prompts are appended
  // to Claude Code's preset system prompt by default.
  systemPrompt: "You are a PR reviewer...",

  // Custom tools the agent can use
  tools: {
    lint: tool({ ... }),
    test: tool({ ... }),
  },

  // Runtime: "claude-code" (default) or "codex"
  runtime: "claude-code",

  // Permission mode: "default", "acceptEdits", or "bypassPermissions"
  permissionMode: "default",

  // Max turns before stopping (default: 50)
  maxTurns: 50,

  // Max budget in USD
  maxBudgetUsd: 5,

  // Lifecycle hooks
  onStart: async () => { ... },
  onToolCall: async ({ toolName, input }) => { ... },
  onToolResult: async ({ toolName, input, output }) => { ... },
  onStepFinish: async ({ step }) => { ... },
  onFinish: async ({ result }) => { ... },
  onError: async ({ error }) => { ... },
})
```

### `tool(definition)`

用 Zod schema 验证创建工具定义 .

```ts
import { tool } from "@21st-sdk/agent"
import { z } from "zod"

const myTool = tool({
  description: "What this tool does",
  inputSchema: z.object({
    path: z.string(),
    verbose: z.boolean().optional(),
  }),
  execute: async (args) => {
    // args is fully typed from the schema
    return {
      content: [{ type: "text", text: "result" }],
    }
  },
})
```

### 钩子

#### `onToolCall`

在工具执行前运行 。 返回时 `false` 挡住它.

```ts
onToolCall: async ({ toolName, input }) => {
  if (toolName === "Bash" && input.command?.includes("rm -rf")) {
    return false // blocked
  }
}
```

#### `onFinish`

代理成功完成后运行 .

```ts
onFinish: async ({ result }) => {
  await fetch("https://my-api.com/webhook", {
    method: "POST",
    body: JSON.stringify({ done: true }),
  })
}
```

## 如何运作

`agent()` 财务报告和审定财务报表 `tool()` 是身份功能 —— 它们完全返回您传递的东西, 并添加了类型的推论。 实际处决发生在使用克洛德特工SDK的第21代理运行时间(E2B sandbox).

您的代码运行在一个安全的云沙盒中, 完全可以访问 Node.js, git, 和系统工具.

对于 `runtime: "claude-code"`,省略 `systemPrompt` 使用 Claude Code 的默认预设系统快取. 如果您通过一个字符串, 它会自动附在预设上 。 您也可以直接通过预设对象 :

```ts
systemPrompt: {
  type: "preset",
  preset: "claude_code",
  append: "Your extra instructions here",
}
```

## 许可证

麻省理工学院

## 常见问题

### @21st-sdk/agent 是什么？

定义 AI 代理和工具,对 21 代理 机构进行全面类型推断

### 如何安装 @21st-sdk/agent？

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

### @21st-sdk/agent 支持 TypeScript 吗？

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

@21st-sdk/agent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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