# @adonis-agora/agent 中文文档

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

版本：0\.97\.7
npm 元数据更新时间：2026-11-05T22:16:53.789Z
中文译文更新时间：2026-11-05T19:34:05.977Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adonis-agora/agent
原文对照：https://npmcn.com/package/%40adonis-agora/agent/?lang=original
项目主页：https://davidecarvalho.github.io/agora/docs/agent
源码仓库：https://github.com/DavideCarvalho/adonis-agora-agent

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

- 包体积（解压后）：9.5 MB，1916 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：6 个
- peer 依赖：ai ^7\.0\.0，zod ^4\.0\.0，vite \>=5，katex ^0\.16\.45 \|\| ^0\.19\.0，react ^18\.0\.0 \|\| ^19\.0\.0，react-dom \>=18，remark-gfm ^4\.0\.1，streamdown ^2\.5\.0，typescript \>=5，remark-math ^6\.0\.0，react-native \>=0\.74，rehype-katex ^7\.0\.1，@ai-sdk/react ^4\.0\.0，@adonisjs/core ^7\.3\.0，react-markdown ^10\.1\.0，@adonisjs/lucid ^22\.4\.0，@adonisjs/redis ^9\.2\.0 \|\| ^10\.0\.0 \|\| ^11\.0\.0，@resvg/resvg-js ^2\.6\.0，node-sql-parser ^5\.3\.0，playwright-core \>=1\.48 \<2，rehype-sanitize ^6\.0\.0，@streamdown/code ^1\.1\.1，@streamdown/math ^1\.0\.2，unist-util-visit ^5\.1\.0，@json-render/react \>=0\.21\.0 \<1\.0\.0，@adonis-agora/authz \>=0\.4\.2 \<1\.0\.0，@adonis-agora/media \>=0\.18\.0 \<1\.0\.0，@adonisjs/assembler ^8\.4\.0，@streamdown/mermaid ^1\.0\.2，prism-react-renderer ^2\.4\.1，react-native-webview \>=13，@adonis-agora/durable \>=0\.43\.3 \<1\.0\.0，@qdrant/js-client-rest ^1\.11\.0，@adonis-agora/telescope \>=0\.4\.0 \<1\.0\.0，@adonis-agora/diagnostics \>=0\.1\.0 \<1\.0\.0
- 首次发布：2026-07-15T22:18:14.499Z
- 最新版本发布：2026-11-05T22:16:53.415Z
- 近 30 天下载量：35511（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：151（近 12 个月 151 个）

## 中文简介

为AdonisJS——Agora生态系统的一部分——提供治理,可持久支持的AI剂(聊天+工具调用+治理).

## 安装

```sh
npm install @adonis-agora/agent
```

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

## README

# @ adonis-agora/ 代理服务器

[![npm version](https://img.shields.io/npm/v/@adonis-agora/agent)](https://www.npmjs.com/package/@adonis-agora/agent) [![npm downloads](https://img.shields.io/npm/dm/@adonis-agora/agent)](https://www.npmjs.com/package/@adonis-agora/agent) [![CI](https://github.com/DavideCarvalho/adonis-agora-agent/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/DavideCarvalho/adonis-agora-agent/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@adonis-agora/agent)](https://www.npmjs.com/package/@adonis-agora/agent)

治理、持久支持的AI代理(聊天+工具调用+治理) **阿多尼斯·贾克** 部分 [阿戈拉语Name](https://github.com/DavideCarvalho) 生态系统.

包裹是两样东西 彼此上分层:

-   A 类 **框架不可知代理循环** —— 说 `runAgentLoop(deps, input, hooks)` 驱动一个模型 工具 模型对照一套SPI(模型/存储/定额/角色/沉入/跑道/治理). 这个 `hooks` 接缝( 接缝)`step` 编号 : `awaitApproval` 编号 : `openSink` 编号 : `runAgent`)让同样的循环体运行 正在处理或作为可重复播放的持久工作流程(通过) `@adonis-agora/durable`,可选对等点).
-   一个 **AdonisJS 整合外壳** - 服务提供者, `defineConfig`,HTTP线路(`/agent/*`, (中文(简体) ), `/agent/governance/*`, (中文(简体) ), `/agent/attachments`),路西德后置商店,工具发现来自 `app/agent_tools`,RAG( pgvector 或 Qdrant 检索器, 加上 PageIndex 类树导航 long 文档),一个被规范的只读 SQL 工具,以及一个回放聊天钩.

`read` 工具自动执行, `action` 人类批准工具门(HITL),以及 `agent` 工具代表 给另一个有名的特工.

## 组成部分登记册和服务器渲染

工具支持 a `present` 钩在功能上和装饰上都有. 在每个应用程序中注册自定义组件,在网络屏幕和静态导出之间共享React渲染器,并为您自己的送出适配器生成已加成的PNG/PDF表格和图表.

见 [组件渲染指南](https://npmcn.com/package/%40adonis-agora/agent/docs/authoring/component-rendering.mdx) 用于完整的示例、图案、文本倒置和抓取配置.

### React 本地化的 Generative UI 沙盒

`@adonis-agora/agent/react-native/genui` 绘制沙盒组件( e)`ui__sandbox`在一个坚硬的 `react-native-webview` - 网络iframe的文档和CSP, 相同的检查 `agent.send` 桥 - 并再出口 " React " 本地安全基因供应商和部件(从这里进口) 应用程序,不是来自 `/react/genui`) (中文(简体) ). 安装 `react-native-webview` (可选对等),然后:

```tsx
import { createNativeSandboxRenderer, GenuiProvider } from '@adonis-agora/agent/react-native/genui'

const Sandbox = createNativeSandboxRenderer({ theme: { vars: tokens }, baseUrl: 'https://api.example.com/agent' })
<GenuiProvider registry={{ Sandbox }} onAction={chat.sendUiAction}>…</GenuiProvider>
```

见 [本地反应中的沙盒](https://npmcn.com/package/%40adonis-agora/agent/docs/genui-sandbox-react-native.mdx)。 。 。 .

## 安装

```sh
pnpm add @adonis-agora/agent
node ace configure @adonis-agora/agent
```

`configure` 注册提供者,电线 ASSEMBLER `init` 生成已键入的钩子 `app/agent_tools` 枪管( 如不到位, 倒回运行时扫描) , 发布 `config/agent.ts`,以及 发布迁移情况——基干表、平面图 RAG-chunk表和树导航 表格(删除您不使用的任何表格,例如,如果您通过 Qdrant 检索到的 pgvector 迁移, 或树移,如果您不导航长文档; 运行 `node ace migration:run` 其余部分).

仅 `ai` (或手卷出) `ModelProvider`),并严格要求有模范工厂. 所有东西 换句话说 **选项对等点**,仅在配置时懒惰地导入 :

| 端点 | 需要时间 |
| --- | --- |
| `ai` (单位:千美元)`^7.0.0`(中文(简体) ) | `aiSdkModel` ——Vercel AI SDK v7适配器(`@adonis-agora/agent/ai-sdk`(中文(简体) ) |
| `@adonisjs/lucid` (单位:千美元)`^22.4.0`(中文(简体) ) | `stores.lucid()`,定价,治理读取模型,数据工具的 `db` |
| `@adonisjs/redis` (单位:千美元)`^9.2.0`(中文(简体) ) | `tokenSinks.redis()` ——多replica SSE 令牌流出 |
| `@adonis-agora/durable` (单位:千美元)`^0.8.0`(中文(简体) ) | `durable: true` ——再玩安全耐用跑道(`@adonis-agora/agent/durable`(中文(简体) ) |
| `@adonis-agora/authz` (单位:千美元)`^0.4.0`(中文(简体) ) | `AuthzActorResolver` 编号 : `AuthzToolAuthorizer` (单位:千美元)`@adonis-agora/agent/authz`(中文(简体) ) |
| `@adonis-agora/telescope` (单位:千美元)`^0.4.0`(中文(简体) ) | 望远镜监视器扩展( U)`@adonis-agora/agent/telescope`(中文(简体) ) |
| `@qdrant/js-client-rest` (单位:千美元)`^1.11.0`(中文(简体) ) | `retrievers.qdrant({...})` |
| `node-sql-parser` (单位:千美元)`^5.3.0`(中文(简体) ) | 被监管者 `dataTool` (单位:千美元)`@adonis-agora/agent/data`(中文(简体) ) |
| `react` (单位:千美元)`^18` 编号 : `^19`, (中文(简体) ), `@ai-sdk/react` 财务报告和审定财务报表 `ai` | `AgentProvider` 编号 : `useAgentChat` (单位:千美元)`@adonis-agora/agent/react`(中文(简体) ) |

## 配置

仅 `model` 需要——选取 `store` 按名称(内存、单进程商店的缩写):

```ts
// config/agent.ts
import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
import { aiSdkModel } from '@adonis-agora/agent/ai-sdk'
import { openai } from '@ai-sdk/openai'

export default defineConfig({
  model: () => aiSdkModel(openai('gpt-4o-mini')), // any Vercel AI SDK v7 `LanguageModel`
  store: 'lucid',
  stores: { lucid: stores.lucid(), memory: stores.memory() },
  actorResolver: new AuthActorResolver(), // defaults to one that THROWS — an identity is never fabricated
})
```

定价(`costUsd` 和每个转弯 `/agent/governance/*` 读取两个默认的路由到镜像 `store` 当它 `stores.lucid()` (相同的连接,表格自动创建) – 覆盖到 `pricingStore` 编号 : `governanceQueries`,或 `false` 以禁用. `sink` 默认为进程内符号 下沉; 通过 `tokenSinks.redis({...})` 所以任何舱都可以服务 任何运行的SSE流.

## 使用

### 聊天——供应商为您挂载 HTTP API

没有可以写入的控制器: 一旦配置, 提供者本身会挂载 `POST /agent/chat` (开始) a run and SSE -- protect the sorder stream),并接通了符号流, `GET /agent/chat/:runId/stream` (重接),线 CRUD, 高ITL核准/拒绝 `action` 工具、配额和——何时 `governanceQueries` 设置了—— `/agent/governance/*` 读取路线。 每个路线都解决了演员本身的问题(失败时401);a `threadId` 转至 `chat` 必须属于打电话者.

从反应中驱动它 `@adonis-agora/agent/react` 整个无头层(历史、恢复、a) 消息队列、 批准、 附件、 线索等, 带有会话 cookie 和 屏蔽 CSRF 标志 已连接 :

```tsx
// npm i @ai-sdk/react ai
import { AgentProvider, useAgentChat } from '@adonis-agora/agent/react'

export default function ChatPage() {
  return (
    <AgentProvider>
      <Chat />
    </AgentProvider>
  )
}

function Chat() {
  const { transcript, composer, queue } = useAgentChat()
  return (
    <form onSubmit={(e) => (e.preventDefault(), void composer.submit())}>
      {transcript.items.map((item) => (
        <p key={item.id}>{item.role}: {item.text}</p>
      ))}
      {queue.items.map((m) => <p key={m.id}>(waiting) {m.text}</p>)}
      <input value={composer.text} onChange={(e) => composer.setText(e.target.value)} />
      <button disabled={!composer.canSend}>Send</button>
    </form>
  )
}
```

钩子船在阿戈拉。 其协议仍然与Aviary兼容,但安装和 释放是独立的。 没有反应, 请使用无框架流客户端 :

```ts
import { createAgentChatClient } from '@adonis-agora/agent/client'

const client = createAgentChatClient({ basePath: '/agent' })
const { parts } = await client.send({ body: { message: 'hi' }, onParts: (parts) => render(parts) })
```

### 写入一个规范的工具

工具是自动发现的 `app/agent_tools`。 。 。 . `ReadTool` 自动执行; `ActionTool` 需求 运行前的人类批准:

```ts
// app/agent_tools/allocation_queue.ts
import { z } from 'zod'
import { ReadTool } from '@adonis-agora/agent'
import type { AiToolCtx } from '@adonis-agora/agent'

export default class AllocationQueue extends ReadTool<{}, Row[]> {
  static tool = {
    name: 'allocation_queue',
    description: 'Lists pending allocation requests for the current tenant.',
    input: z.object({}),
    ability: 'agent.coordinator.queue.read',
  }
  async execute(_input: {}, ctx: AiToolCtx): Promise<Row[]> {
    return db.from('allocations').where('tenant_ref', ctx.actor.tenantRef)
  }
}
```

一个 `ActionTool` 写在某处 写在书上和检查点上 记录着两篇: 他们之间死亡的工人重新运行了恢复工具. `ctx.idempotencyKey` (单位:千美元)`<runId>:<toolCallId>`)每一次执行一次呼叫,都一样——传递到下游 一能钥匙(供应商的) `Idempotency-Key`,一个独特的列 `id` 工作流程中的工具 因此,第二次尝试降落在第一次.

### 管理只读 SQL

`@adonis-agora/agent/data` 船舶 `dataTool` ——一个已失效的SQL工具:它需要一个明确的, 基于角色的表格允许列表,在可选的每行租户范围重写(从调用演员的 `tenantRef`),注入行数 `LIMIT`在他们撞到模型前 切入过大的结果 上下文。 登记为静态工具 `config/agent.ts` (单位:千美元)`defineConfig({ tools: [dataTool({...})] })`(中文(简体) ) 或从一个 `app/agent_tools/` 模块 :

```ts
import { dataTool } from '@adonis-agora/agent/data'
import db from '@adonisjs/lucid/services/db'

export const executeSql = dataTool({
  db,
  tableAccess: {
    roleGroups: { ADMIN: ['billing'] },
    tablesByGroup: { billing: ['orders', 'invoices'] },
  },
  tenant: { tenantColumn: 'tenant_ref', scopedTables: ['orders', 'invoices'] },
  maxRows: 200,
})
```

### 护栏-PII、秘密、即时注射、工具中毒

`@adonis-agora/agent/guardrails` 把探测器和规则引擎 安装在循环的处理器接合器上, 哪个 `config/agent.ts` 现在当作 `inputProcessors` 编号 : `outputProcessors`数字 :

```ts
// config/agent.ts
import { createGuardrails } from '@adonis-agora/agent/guardrails'

const guardrails = createGuardrails({
  pii: 'redact',                 // reversible: the model sees [EMAIL_1], the reader the address
  secrets: 'block',
  injection: { threshold: 0.6 }, // the prompt and every tool result; default action: block
  toolPoisoning: true,           // guardrails.screenTool, for `mcpServers[].screen`
  rules: (ctx) => rulesForTenant(ctx.actor?.tenantRef), // more rules, resolved per scan
  onEvent: (event) => audit(event),                     // hits carry fingerprints, never values
})

export default defineConfig({
  model: () => aiSdkModel(openai('gpt-4o-mini')),
  inputProcessors: [guardrails.input],
  outputProcessors: [guardrails.output],
  mcpServers: [{ name: 'docs', transport: { type: 'http', url }, screen: (t) => guardrails.screenTool(t) }],
})
```

被屏蔽的提示失败运行( E)`ProcessorFailedError` 由一 `GuardrailBlockedError`页:1 被屏蔽的工具结果被扣留并打开; 被屏蔽的答案或工具呼叫是 `OutputRejectedError`。 。 。 . `guardrails.wrapTool(name, handler)` 将占位符恢复到工具的 参数和运行 `tool_args` 规则他们。 输出处理器声明 `incremental`,所以请 答案持续流出。 探测器`detectPii` 与Luhn/CPF/CNPJ/IBAN核对, `detectSecrets`, (中文(简体) ), `scoreInjection`, (中文(简体) ), `scoreToolText`和 `scan` 独立工作。 在阿戈拉当地的护卫舰执行船;它不需要一个Aviary核心包.

### 框架不可知核心(无AdonisJS)

`runAgentLoop(deps, input, hooks)` 是一个共享的转会机构, 既包括进程(`InlineAgentRunner`(中文(简体) ) 和能耐的跑道 `hooks` 说明它装的是哪个 直接锻炼(例如: a test),与内相相双从 `@adonis-agora/agent/testing`数字 :

```ts
import { runAgentLoop, ToolRegistry, DefaultRolesPolicy } from '@adonis-agora/agent'
import {
  FakeModelProvider,
  echoScript,
  InMemoryAgentStore,
  InMemoryTokenStreamSink,
} from '@adonis-agora/agent/testing'

const sink = new InMemoryTokenStreamSink()
const { text } = await runAgentLoop(
  {
    model: new FakeModelProvider(echoScript('hi there')),
    store: new InMemoryAgentStore(),
    registry: new ToolRegistry(),
    rolesPolicy: new DefaultRolesPolicy(),
    day: '2026-07-21',
    systemPrompt: 'You are a helpful assistant.',
  },
  { threadId: 'thread-1', actor: { id: 'user-1', roles: ['USER'] }, userText: 'hi' },
  {
    runId: crypto.randomUUID(),
    openSink: () => sink.open('run-1'),
    awaitApproval: async () => 'approve',
    step: (_name, fn) => fn(),
  },
)
```

## 盘子

`node ace configure @adonis-agora/agent` 还登记嵌入式治理控制台—— `@adonis-agora/agent-dashboard` 反应 SPA, 直接捆入 `@adonis-agora/agent`属于自己的 `dist/` 在建设时间. **没有单独的安装,没有单独的提供者注册.** 它会上升 `<path>/dashboard` (默认) `/agent/dashboard`一次) `governanceAuthorize` 已配置——每个面板 但配额读取交叉角色 `/agent/governance/*` 没有那道门,那道路就不存在了 因此控制台拒绝上载(并附有靴子警告说明原因)而不是装载和404 每个面板上 :

```ts
// config/agent.ts
export default defineConfig({
  // ...
  governanceAuthorize: (actor) => actor.roles?.includes('ADMIN') ?? false,
  // dashboard: { enabled: true, path: '/agent/dashboard', authorize: (actor) => actor.roles?.includes('ADMIN') ?? false },
})
```

两者 `governanceAuthorize` 财务报告和审定财务报表 `dashboard.authorize` 返回一个 `AuthorizeResult` —— 说 `boolean | { allowed: boolean; reason?: 'unauthenticated' | 'forbidden' }` (从 `@adonis-agora/agent` 财务报告和审定财务报表 `@adonis-agora/agent/dashboard`) (中文(简体) ). `true`编号 :`{ allowed: true }` 允许; `{ allowed: false, reason: 'unauthenticated' }` 答题 `401`· ; `false`, (中文(简体) ), `{ allowed: false }`, (中文(简体) ), `reason: 'forbidden'` 或掷出答案 `403`。控制台用其拒绝访问的页面,即 与 JSON 的治理路径; 重定向的钩子本身被保存 .

见 [治理仪表板](https://npmcn.com/package/%40adonis-agora/agent/docs/governance/dashboard.mdx) 对于完整的配置形状.

独立安装( 仍然支持)

`@adonis-agora/agent-dashboard` 船舶作为自己的可安装包 装自有供应商,用于 需要其独立发布cadence或在嵌入式提供者之前配置的应用程序 已存在 :

```sh
pnpm add @adonis-agora/agent-dashboard
node ace add @adonis-agora/agent-dashboard
```

它读取相同的 `config('agent').dashboard` 块。 仅登记两个供应商中的一个——安装 两者在同一路径中都将AdonisJS的"重复路线"出错投出出后靴.

## 诊断

运行时事件流经 `@adonis-agora/agent/telescope`监视器 [`@adonis-agora/telescope`](https://github.com/DavideCarvalho/adonis-telescope) 已安装,同时 框架不可知性 `diagnostics` 从根切入点导出的事件类型.

## 测试

`@adonis-agora/agent/testing` 船舶 `FakeModelProvider` 和内膜双倍的商店,水槽, 配额和治理 SPI,因此,代理循环可以决定性地进行,没有DB,Redis, 或者一个真正的模型提供者.

## 链接

-   重现 : [https://github.com/Davide Carvalho/ados-agent 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/DavideCarvalho/adonis-agent)
-   更改日志 : [https://github.com/DavideCarvalho/adonis-agent/blob/master/packages/adonis/CHANGELOG.md 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/DavideCarvalho/adonis-agent/blob/master/packages/adonis/CHANGELOG.md)
-   配套软件包( 也自动嵌入, 参见 [盘子](https://npmcn.com/package/%40adonis-agora/agent/#readme-dashboard) 上文: [`@adonis-agora/agent-dashboard`](https://github.com/DavideCarvalho/adonis-agent/tree/master/packages/dashboard)

## 许可证

麻省理工学院

## 常见问题

### @adonis-agora/agent 是什么？

为AdonisJS——Agora生态系统的一部分——提供治理,可持久支持的AI剂\(聊天\+工具调用\+治理\)\.

### 如何安装 @adonis-agora/agent？

在项目目录运行 npm install @adonis-agora/agent，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 poppy-agent，可以用 npx poppy-agent 直接运行。

### @adonis-agora/agent 支持 TypeScript 吗？

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

### @adonis-agora/agent 支持 ESM 还是 CommonJS？

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

### @adonis-agora/agent 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @adonis-agora/agent 可以商用吗？

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

### @adonis-agora/agent 的下载量有多少？

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

### @adonis-agora/agent 还在维护吗？

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