# @agentionai/agents 中文文档

规范地址：https://npmcn.com/package/%40agentionai/agents/

版本：1\.18\.2
npm 元数据更新时间：2026-10-12T09:08:38.690Z
中文译文更新时间：2026-11-08T10:32:30.640Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40agentionai/agents
原文对照：https://npmcn.com/package/%40agentionai/agents/?lang=original
项目主页：https://docs.agention.ai/
源码仓库：https://gitlab.com/agentionai-group/agention-lib

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

- 包体积（解压后）：1 MB，186 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：ollama ^0\.5\.18，openai ^7\.13\.0，voyageai ^0\.0\.3，apache-arrow ^18\.0\.0，@openrouter/sdk ^1\.2\.106，@lancedb/lancedb ^0\.23\.0，@typesafe-ai/sdk ^0\.6\.0，@anthropic-ai/sdk ^0\.71\.2，@mistralai/mistralai ^1\.13\.0，@google/generative-ai ^0\.24\.1，@modelcontextprotocol/sdk ^1\.26\.0
- 首次发布：2026-01-26T23:33:48.486Z
- 最新版本发布：2026-10-12T09:08:38.334Z
- 近 30 天下载量：1799（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

代理库

## 安装

```sh
npm install @agentionai/agents
```

也可以使用：`pnpm add @agentionai/agents`、`yarn add @agentionai/agents`、`bun add @agentionai/agents`

## README

# 代理

> AI 无魔法特工

[![npm version](https://img.shields.io/npm/v/@agentionai/agents.svg)](https://www.npmjs.com/package/@agentionai/agents)

一个综合性的TypeScript工具包,用于用RAG来构建LLM动力的代理,以及多代理工作流程. 没有隐藏的状态机器,没有强制抽象——只是打字的代理,可相容的图表,和一个完整的工具包中的完全控制.

**[文档](https://docs.agention.ai/)** 二. 支助 **[实例](https://docs.agention.ai/guide/examples)** 二. 支助 **[吉特拉布语Name](https://gitlab.com/agentionai-group/agention-lib)** 二. 支助 **[无](https://www.npmjs.com/package/@agentionai/agents)**

## 快速启动

### 1\. 安装

仅安装您需要的选择性导入 :

```bash
# Install core library + Claude SDK
npm install @agentionai/agents @anthropic-ai/sdk
```

### 2\. 获取 API 密钥

从选中的提供者获取 API 密钥 :

-   **克劳德**数字 : [control.harmanic.com (中文(简体) )](https://console.anthropic.com/)
-   **开放AI**数字 : [互联网档案馆的存檔,存档日期2013-12-02. openai.com](https://platform.openai.com/api-keys)
-   **双子座**数字 : [aistudio.google.com (中文(中国大陆) )](https://aistudio.google.com/app/apikey)
-   **迷雾**数字 : [控制台. mistral.ai](https://console.mistral.ai/)
-   **打开路透社**数字 : [开口/钥匙](https://openrouter.ai/keys) - 一个钥匙,几十个上游供应商
-   **奥拉玛** 编号 : **拉玛.cpp**: 不需要 API 密钥——在当地运行模型(参见 [代理指南](https://docs.agention.ai/guide/agents)(中文(简体) )

设定为环境变量:

```bash
export ANTHROPIC_API_KEY=your-key-here
```

### 3\. 创建您的第一代理

```typescript
// Import only Claude - no other agent SDKs required!
import { ClaudeAgent } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'assistant',
  name: 'Assistant',
  description: 'You are a helpful assistant.',
  model: 'claude-sonnet-4-5',
});

const response = await agent.execute('What can you help me with?');
console.log(response);
```

### 选择性导入

只导入所需的代理 :

```typescript
import { ClaudeAgent } from '@agentionai/agents/claude';     // Requires @anthropic-ai/sdk
import { OpenAiAgent } from '@agentionai/agents/openai';     // Requires openai
import { GeminiAgent } from '@agentionai/agents/gemini';     // Requires @google/generative-ai
import { MistralAgent } from '@agentionai/agents/mistral';   // Requires @mistralai/mistralai
import { OpenRouterAgent } from '@agentionai/agents/openrouter'; // Requires @openrouter/sdk
import { OllamaAgent } from '@agentionai/agents/ollama';     // Requires ollama (local, no API key)
import { LlamaCppAgent } from '@agentionai/agents/llamacpp'; // Requires openai (local, no API key)
```

或导入一切( 需要全部 SDK ):

```typescript
import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
```

## 特征

-   **多服务, 无锁定** - Claude、OpenAI、双子座、Mistral、OpenRouter(一个钥匙,几十个上游供应商),加上通过Ollama和lama.cpp的本地模型-相同的接口。 用一行切换模型. `listModels()` 问任何提供者它目前提供什么, 一个共享的形状.
-   **可编译上下文管理** - 工具结果遮掩(无损失、免费)+滚动总和(自动起火)+副代理授权(按结构进行隔离).
-   **流线** - 说吧 `executeStream()` 克劳德,OpenAI,OpenRouter, 和所有OpenAI兼容的代理。 也门 `{ type: "text" | "reasoning" }` 块; 工具呼叫处理透明 .
-   **内建工具** - 使用自定义的服务器侧工具(例如Anthropic的网页搜索、bash、文本编辑器),同时使用自己的工具.
-   **可编曲的,非魔法** - 特工就是目标 管道为阵列. 没有隐藏的状态 没有惊喜.
-   **多式联运/愿景** - 以统一文本同时发送图像 `MessageContent[]` 所有供应商的API.
-   **完全可观察性** ——逐个计票,执行时间,管线结构可视化.
-   **类型脚本- Native** - 严格打字、接口和通用软件.
-   **RAG 准备** - LanceDB向量商店, 信号意识分解, 摄取管道出盒子.

### 有工具的代理

```typescript
import { GeminiAgent, Tool } from '@agentionai/agents/gemini';

const weatherTool = new Tool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'City name' },
    },
    required: ['location'],
  },
  execute: async ({ location }) => {
    // In production, call a weather API
    return JSON.stringify({
      location,
      temperature: 22,
      conditions: 'Sunny',
    });
  },
});

const agent = new GeminiAgent({
  apiKey: process.env.GEMINI_API_KEY,
  id: 'weather-agent',
  name: 'Weather Agent',
  description: 'You are a weather assistant.',
  model: 'gemini-flash-lite-latest',
  tools: [weatherTool],
});

const response = await agent.execute("What's the weather in Paris?");
```

### 内容管理

每一次代理谈话都不断增长——工具结果堆积而成,转弯而成堆积而成活物复合. Agention的历史插件使上下文窗口自动倾斜,不进行人工记账.

```typescript
import { toolResultMaskingPlugin, compressionPlugin } from '@agentionai/agents/history/plugins';
import { History } from '@agentionai/agents/history';

// Mask old tool results at read time — sync, free, lossless
const maskingPlugin = toolResultMaskingPlugin({ keepRecentResults: 2 });

// Compress old turns into a rolling summary — auto-fires past a token budget
const history = new History([], { maxTokens: 50000 })
  .use(maskingPlugin)
  .use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 8000 } }));

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'Research topics thoroughly.',
  model: 'claude-sonnet-4-6',
  tools: [searchTool, maskingPlugin.retrieveTool],
}, history);
```

| 战略 | 费用 | 数据损失 | 触发 |
| --- | --- | --- | --- |
| `toolResultMaskingPlugin` | 0 —同步, 没有 LLM 调用 | 无——全部内容总是可以检索的 | 每个 `getEntries()` 调用 |
| `compressionPlugin` | LLM 令牌( 使用廉价模型) | 是 -- -- 细节交易简洁 | `autoReduceWhen` 阈值或手动 `history.reduce()` |
| `Tool.fromAgent()` | 无——结构选择 | 主要上下文无一(子代理历史是独立的) | 自动——只是将代理件包成工具 |

[内容管理指南](https://docs.agention.ai/guide/context-management) • 妇女 [API 历史 ~](https://docs.agention.ai/guide/history)

### 本地模型( Ollama / lama.cpp / OpenAI 兼容服务器)

在自己的机器上运行模型——不需要API密钥. 与其他提供者相同的代理接口 :

```typescript
import { OllamaAgent } from '@agentionai/agents/ollama';
import { LlamaCppAgent } from '@agentionai/agents/llamacpp';

// Ollama (https://ollama.com) — pull a model first: `ollama pull qwen2.5`
const ollama = new OllamaAgent({
  id: 'local-ollama',
  name: 'Local Assistant',
  description: 'You are a helpful assistant.',
  model: 'qwen2.5',
  apiKey: '',
});

// llama.cpp server (`llama-server -m model.gguf`) — OpenAI-compatible API
const llamaCpp = new LlamaCppAgent({
  id: 'local-llamacpp',
  name: 'Local Assistant',
  description: 'You are a helpful assistant.',
  apiKey: '',
  baseURL: 'http://localhost:8080/v1',
});

const response = await ollama.execute('What can you run locally?');

// Discover which models are available on the server
const models = await ollama.listModels();
```

**自定义 OpenAI 兼容服务器** (vLLM, LM Studio, College AI, Groq,.):扩展 `OpenAICompatibleAgent` 直接 :

```typescript
import { OpenAICompatibleAgent, OpenAICompatibleConfig } from '@agentionai/agents/llamacpp';

class VLLMAgent extends OpenAICompatibleAgent {
  constructor(config: Omit<OpenAICompatibleConfig, 'vendor'>) {
    super({ ...config, vendor: 'llamacpp', baseURL: config.baseURL ?? 'http://localhost:8000/v1' });
  }
  protected getVendorName() { return 'vLLM'; }
}
```

[完整指南 –](https://docs.agention.ai/guide/agents#custom-openai-compatible-agents)

### 内建工具

使用服务商自己的服务器侧工具( 由服务商执行, 而非本地) 与您的自定义工具 :

```typescript
import { ClaudeAgent, webSearchTool } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'You are a helpful research assistant with web access.',
  model: 'claude-sonnet-4-6',
  builtInTools: [webSearchTool({ maxUses: 5 })],
});

const response = await agent.execute('What happened in the news today?');
```

### 流线

所有三个主要供应商都通过下列途径支持流动: `executeStream()`返回一个 `AsyncGenerator<StreamChunk>`每个块是 `{ type: "text" | "reasoning"; content: string }` ——可见输出的文本,内部思维符号的推理(DeepSeek R1,克洛德扩展思维,OpenAI o-series).

```typescript
import { ClaudeAgent } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'assistant',
  name: 'Assistant',
  description: 'You are a helpful assistant.',
});

for await (const chunk of agent.executeStream('Tell me a story')) {
  if (chunk.type === 'text') process.stdout.write(chunk.content);
}
```

工具呼叫以透明方式处理——每次往返后发电机继续流出. 同样的API工作跨越 `ClaudeAgent`, (中文(简体) ), `OpenAiAgent`,以及 `LlamaCppAgent` / 任意 `OpenAICompatibleAgent` 子类.

### 多剂管道

链剂与不同的供应商和模型:

```typescript
import { ClaudeAgent } from '@agentionai/agents/claude';
import { OpenAiAgent } from '@agentionai/agents/openai';
import { Pipeline } from '@agentionai/agents/core';

const researcher = new OpenAiAgent({
  apiKey: process.env.OPENAI_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'Research the given topic and provide key facts.',
  model: 'gpt-4o',
  tools: [searchTool],
});

const writer = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'writer',
  name: 'Writer',
  description: 'Write a blog post based on the research provided.',
  model: 'claude-sonnet-4-5',
});

const pipeline = new Pipeline([researcher, writer]);
const result = await pipeline.execute('Renewable energy trends in 2024');
```

### 代理代表团

使用代理作为分级工作流程的工具:

```typescript
import { ClaudeAgent } from '@agentionai/agents/claude';
import { OpenAiAgent } from '@agentionai/agents/openai';

// Research assistant (cheaper model for data gathering)
const researchAssistant = new OpenAiAgent({
  apiKey: process.env.OPENAI_API_KEY,
  id: 'research-assistant',
  name: 'Research Assistant',
  description: 'Search and summarize information on topics.',
  model: 'gpt-4o-mini',
  tools: [searchTool],
});

// Lead researcher delegates to assistant, synthesizes findings
const researcher = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Lead Researcher',
  description: 'Research topics thoroughly using your assistant.',
  model: 'claude-sonnet-4-5',
  agents: [researchAssistant],  // Assistant available as a tool
});

const result = await researcher.execute('Latest developments in quantum computing');
```

### 多式联运/愿景

使用文本同时发送图像 `imageUrl()` 或者说 `imageBase64()`。同样的 `MessageContent[]` 接口在所有提供者之间工作 :

```typescript
import { ClaudeAgent } from '@agentionai/agents/claude';
import { imageUrl, imageBase64 } from '@agentionai/agents/core';
import * as fs from 'fs';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'vision-agent',
  name: 'VisionAgent',
  description: 'You analyze images.',
  model: 'claude-opus-4-6',
});

// Remote image by URL
const response = await agent.execute([
  imageUrl('https://example.com/chart.png'),
  { type: 'text', text: 'Summarize this chart in one sentence.' },
]);

// Local image as base64
const data = fs.readFileSync('./photo.jpg').toString('base64');
const response2 = await agent.execute([
  imageBase64(data, 'image/jpeg'),
  { type: 'text', text: 'What plant is this?' },
]);
```

| 提供者 | 網址 | 基础64 |
| --- | --- | --- |
| 克劳德 | ✅ | ✅ |
| 开放AI | ✅ | ✅ |
| 双子座 | ✅ | ✅ |
| 迷雾 | ✅ | ❌ |

## 核心概念

### 探员

Claude,OpenAI,双子座,Mistral通过Ollama和lama.cpp实现统一接口,并实现本地模式. 工具、历史和信使追踪系统.

[学习更多](https://docs.agention.ai/guide/agents)

### 工具

JSON Schema + 处理器图案. 独特的能力:将任何代理人包起来作为代表团等级的工具。 同时支持运行服务器侧面的自定义内置工具(例如Anthropic的网页搜索,bash,文本编辑器).

[学习更多](https://docs.agention.ai/guide/tools)

### 内容管理

工具结果遮掩(无损失,免费)+滚动相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相 可编译插件使上下文窗口自动倾斜.

[学习更多](https://docs.agention.ai/guide/context-management) • 妇女 [API 历史 ~](https://docs.agention.ai/guide/history)

### 多式联运/愿景

统一 `MessageContent[]` 用于所有提供者图像的界面。 URL和 Base64 图像,将文本和图像自由混合在一个呼叫中.

[学习更多](https://docs.agention.ai/guide/multimodal)

### 图表管道

编成相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相相接相接相接相 混合模型和提供者自由.

[学习更多](https://docs.agention.ai/guide/graph-pipelines)

### RAG 矢量存储器

LanceDB 向量存储, 信号意识分解, 摄取管道, 以及取出工具.

[学习更多](https://docs.agention.ai/guide/vector-stores)

### 观察性

随叫随到和按节点计数、期限指标、全面执行的能见度.

[学习更多](https://docs.agention.ai/guide/graph-pipelines#metrics--observability)

## 文档

-   **[开始](https://docs.agention.ai/guide/getting-started)** - 安装和第一代理
-   **[内容管理](https://docs.agention.ai/guide/context-management)** - 预算、蒙面和压缩
-   **[探员](https://docs.agention.ai/guide/agents)** - 代理配置和提供者
-   **[工具](https://docs.agention.ai/guide/tools)** - 增加能力和代理授权
-   **[多式联运/愿景](https://docs.agention.ai/guide/multimodal)** - 向所有提供者发送图像
-   **[历史](https://docs.agention.ai/guide/history)** - 对话持续和插件
-   **[图表管道](https://docs.agention.ai/guide/graph-pipelines)** - 多代理人工作流程
-   **[矢量存储器](https://docs.agention.ai/guide/vector-stores)** - RAG和语义搜索
-   **[实例](https://docs.agention.ai/guide/examples)** - 现实世界的执行情况
-   **[API 参考](https://docs.agention.ai/api)** - 全面的API文档

## 为什么是特工?

|  | 原始 SDKs | 重型框架 | 代理 |
| --- | --- | --- | --- |
| **控制权** | 满 | 有限 | 满 |
| **沸腾** | 高级 | 低级 | 低级 |
| **透明度** | 满 | 有限 | 满 |
| **多供应商** | 手动 | 变数 | 内建 |
| **类型脚本** | 变数 | 经常为部分 | 土著 |

-   **飞快一点** 停止为每个项目重建代理基础设施
-   **保持灵活** ——交换提供者,混合模型,自定义一切
-   **继续控制** - 看清楚每一步都发生了什么
-   **自信地缩放** - 内置的计量标准、信使跟踪和可观察性

## 实例

看看这个 [实例](https://gitlab.com/agentionai-group/agention-lib/-/tree/master/examples) 完整工作示例目录 :

-   有不同提供者的基本代理人
-   定制工具和代理人授权
-   顺序、平行和表决管道
-   带有向量搜索的 RAG 应用程序
-   文档摄取和分解

## 由代理设计

-   **[马歇尔](https://marshall.agention.ai/)** 开口重量的编码代理。 运行一个完全通过ella.cpp或Ollama在本地硬件上的规划员/编码员/审查员环路,不需要API密钥,账户,或云——有批准权的文件写作和 shell命令,并支持将本地模式和付费模式混合到角色之间.

## 捐款

欢迎捐款! 请打开一个问题或提交拉动请求.

## 链接

-   **[文档](https://docs.agention.ai/)**
-   **[吉特拉布语Name](https://gitlab.com/agentionai-group/agention-lib)**
-   **[无](https://www.npmjs.com/package/@agentionai/agents)**
-   **[问题](https://gitlab.com/agentionai-group/agention-lib/-/issues)**

## 常见问题

### @agentionai/agents 是什么？

代理库

### 如何安装 @agentionai/agents？

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

### @agentionai/agents 支持 TypeScript 吗？

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

### @agentionai/agents 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @agentionai/agents 可以商用吗？

@agentionai/agents 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @agentionai/agents 的下载量有多少？

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

### @agentionai/agents 还在维护吗？

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