# @auth/agent 中文文档

规范地址：https://npmcn.com/package/%40auth/agent/

版本：0\.6\.2
npm 元数据更新时间：2026-06-12T01:17:54.342Z
中文译文更新时间：2026-11-07T05:44:37.626Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40auth/agent
原文对照：https://npmcn.com/package/%40auth/agent/?lang=original
项目主页：https://github.com/better-auth/agent-auth#readme
源码仓库：https://github.com/better-auth/agent-auth

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

- 包体积（解压后）：145 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：ai \>=3\.0\.0
- 首次发布：2026-03-17T17:01:26.035Z
- 最新版本发布：2026-06-12T01:17:54.010Z
- 近 30 天下载量：16668（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

Auth代理协议客户SDK——代理身份、登记和能力授权

## 安装

```sh
npm install @auth/agent
```

也可以使用：`pnpm add @auth/agent`、`yarn add @auth/agent`、`bun add @auth/agent`

## README

# @auth/代理服务器

客户端 SDK 用于 [Auth 代理协议](https://github.com/better-auth/agent-auth-protocol) 代理人身份、登记和能力授权.

## 安装

```bash
npm install @auth/agent
```

## 快速启动

```ts
import { AgentAuthClient } from "@auth/agent";

const client = new AgentAuthClient({
  directoryUrl: "https://directory.example.com",
});

// Discover a provider
const config = await client.discoverProvider("https://api.example.com");

// Connect an agent with constrained capabilities
const agent = await client.connectAgent({
  provider: "https://api.example.com",
  capabilities: ["read_data", { name: "transfer_money", constraints: { amount: { max: 1000 } } }],
  name: "my-assistant",
});

// Execute a capability
const result = await client.executeCapability({
  agentId: agent.agentId,
  capability: "read_data",
  arguments: { id: "user-123" },
});
```

## AI 框架整合

### 维塞尔 AI SDK

`toAISDKTools` 自动进口 `jsonSchema` 从 `ai` 软件包。 如果喜欢的话,明确通过:

```ts
import { generateText } from "ai";
import { AgentAuthClient, getAgentAuthTools, toAISDKTools } from "@auth/agent";

const client = new AgentAuthClient();
const tools = await toAISDKTools(getAgentAuthTools(client));

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools,
  prompt: "Transfer $50 to Alice",
});
```

通过 `jsonSchema` 明确( 避免动态导入) :

```ts
import { generateText, jsonSchema } from "ai";
import { AgentAuthClient, getAgentAuthTools, toAISDKTools } from "@auth/agent";

const client = new AgentAuthClient();
const tools = await toAISDKTools(getAgentAuthTools(client), { jsonSchema });
```

### OpenAI 函数调用

```ts
import { AgentAuthClient, getAgentAuthTools, toOpenAITools } from "@auth/agent";

const client = new AgentAuthClient();
const { definitions, execute } = toOpenAITools(getAgentAuthTools(client), {
  strict: true, // structured outputs — prevents hallucinated arguments
});

const res = await openai.chat.completions.create({
  model: "gpt-4o",
  tools: definitions,
  messages,
});

for (const call of res.choices[0].message.tool_calls ?? []) {
  const result = await execute(call.function.name, JSON.parse(call.function.arguments));
}
```

### 雅典克劳德

```ts
import { AgentAuthClient, getAgentAuthTools, toAnthropicTools } from "@auth/agent";

const client = new AgentAuthClient();
const { definitions, processToolUse } = toAnthropicTools(getAgentAuthTools(client));

const res = await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  tools: definitions,
  messages,
});

const toolUseBlocks = res.content.filter((b) => b.type === "tool_use");
if (toolUseBlocks.length > 0) {
  const results = await processToolUse(toolUseBlocks);
  messages.push({ role: "assistant", content: res.content }, { role: "user", content: results });
}
```

### 处理错误

所有适配器按结构将工具执行错误包裹 `{ error, code }` 对象而不是投掷。 这让模特们能优雅地恢复:

```json
{ "error": "Capability not granted", "code": "capability_not_granted" }
```

## SDK 工具

SDK曝光了映射到代理生命周期的协议工具:

| 工具 | 说明 |
| --- | --- |
| `list_providers` | 已发现/ 已配置的提供者列表 |
| `search_providers` | 有意查询登记册 |
| `discover_provider` | 通过 URL 查找提供者 |
| `list_capabilities` | 名单提供者能力 |
| `describe_capability` | 获得全部能力定义 |
| `connect_agent` | 登记代理人(有可选限制) |
| `execute_capability` | 执行授予的能力 |
| `request_capability` | 请求增加能力 |
| `agent_status` | 检查代理地位和赠款 |
| `sign_jwt` | 手动签名代理 JWT |
| `disconnect_agent` | 撤销代理 |
| `reactivate_agent` | 重新激活过期的代理 |
| `rotate_agent_key` | 旋转代理键盘 |
| `rotate_host_key` | 旋转主机密钥pair |
| `enroll_host` | 使用入学标志输入主机 |

## 过滤工具

使用 `filterTools` 只暴露您的代理工具:

```ts
import { getAgentAuthTools, filterTools } from "@auth/agent";

const allTools = getAgentAuthTools(client);

const minimal = filterTools(allTools, { only: ["execute_capability", "agent_status"] });
const safe = filterTools(allTools, { exclude: ["sign_jwt", "rotate_host_key"] });
```

## 子路径导入

对于只需要工具+适配器(没有客户端、加密或存储)的更轻的导入:

```ts
import { getAgentAuthTools, toOpenAITools, filterTools } from "@auth/agent/tools";
```

## 制约因素(第2.13节)

连接或请求限制参数值的能力时通过限制 :

```ts
await client.connectAgent({
  provider: "https://api.example.com",
  capabilities: [
    "read_data",
    {
      name: "transfer_money",
      constraints: {
        amount: { max: 1000, min: 1 },
        currency: { in: ["USD", "EUR"] },
      },
    },
  ],
});
```

受约束的赠款退还 `capabilityGrants[].constraints`。 。 。 .

## 存储

SDK使用可插件存储,用于持续的主机身份和代理连接:

```ts
import { AgentAuthClient } from "@auth/agent";

const client = new AgentAuthClient({
  storage: myCustomStorage, // implements Storage interface
});
```

内建: `MemoryStorage` (默认,非持久性). 对于长期运行的应用程序,执行 `Storage` 与您首选的后端( 数据库、 文件系统、 KV 存储等) 接口 :

| 方法组 | 说明 |
| --- | --- |
| `getHostIdentity` 编号 : `setHostIdentity` 编号 : `deleteHostIdentity` | 主机键盘和身份 |
| `getAgentConnection` 编号 : `setAgentConnection` 编号 : `deleteAgentConnection` | 代理连接状态 |
| `getProviderConfig` 编号 : `setProviderConfig` 编号 : `listProviderConfigs` | 缓存提供者发现文件 |

> CLI 软件包 (`@auth/agent-cli`)包括基于文件的文件 `FileStorage` 执行,休息时可选择加密——见 [`packages/cli/src/storage.ts`](https://npmcn.com/package/%40auth/cli/src/storage.ts) 参考执行.

## 许可证

麻省理工学院

## 常见问题

### @auth/agent 是什么？

Auth代理协议客户SDK——代理身份、登记和能力授权

### 如何安装 @auth/agent？

在项目目录运行 npm install @auth/agent，或使用 pnpm add / yarn add / bun add。

### @auth/agent 支持 TypeScript 吗？

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

### @auth/agent 支持 ESM 还是 CommonJS？

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

### @auth/agent 可以商用吗？

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

### @auth/agent 的下载量有多少？

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

### @auth/agent 还在维护吗？

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