# @gaia-agent/sdk 中文文档

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

版本：0\.1\.26
npm 元数据更新时间：2026-04-07T01:20:56.454Z
中文译文更新时间：2026-11-15T21:02:36.146Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：354 kB，123 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：22 个
- 首次发布：2025-11-11T10:53:11.659Z
- 最新版本发布：2026-04-07T01:20:56.122Z
- 近 30 天下载量：4006（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 17 个）

## 中文简介

使用 AI SDK v6 ToolLoop Agent 与可互换的提供者为 GAIA 基准制作准备的 AI 代理库

## 安装

```sh
npm install @gaia-agent/sdk
```

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

## README

![GAIA Agent Logo](https://npmcn.com/package/%40gaia-agent/sdk/docs/logo.svg)

# GAIA 超级特工SDK

### 在数秒内,而不是数周内建立GAIA-Benchmark-ready超级AI代理公司

**配有18+工具和可互换供应商的生产准备超级AI代理商**  
建于 AI SDK v6 ToolLooopAgent & ToolSDK.ai 上 **动作推理**

[![npm version](https://img.shields.io/npm/v/@gaia-agent/sdk.svg?style=flat-square)](https://www.npmjs.com/package/@gaia-agent/sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](https://npmcn.com/package/%40gaia-agent/sdk/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg?style=flat-square)](https://www.typescriptlang.org/) [![AI SDK](https://img.shields.io/badge/AI_SDK-v6-purple.svg?style=flat-square)](https://sdk.vercel.ai/)

[快速启动](https://npmcn.com/package/%40gaia-agent/sdk/#readme--quick-start) • 妇女 [特征](https://npmcn.com/package/%40gaia-agent/sdk/#readme--features) • 妇女 [GAIA 基准](https://npmcn.com/package/%40gaia-agent/sdk/#readme--gaia-benchmark) • 妇女 [文档](https://npmcn.com/package/%40gaia-agent/sdk/#readme--documentation)

* * *

## \* 特性

<table><tbody><tr><td><h3 id="readme-zero-configuration">QQ 零配置</h3><p>预配置的代理设备已准备好,可以从盒子中取出GAIA基准</p><h3 id="readme-react-reasoning-pattern">*</h3><p>构建理性+结构化思维的代理框架</p><h3 id="readme-planning-verification">规划和核查</h3><p>多步骤规划+复杂任务的答案核查</p><h3 id="readme-18-built-in-tools">++ 18+ 内置工具</h3><p>按官方SDK分类(塔维利,Exa,E2B,浏览器使用,钢铁)</p><h3 id="readme-swappable-providers">🔄可移动供应商</h3><p>方便供应商切换沙盒、浏览器、搜索和内存</p><h3 id="readme-ai-powered-search">AI授权搜索</h3><p>Tavily 和 Exa 智能网络搜索集成</p></td><td><h3 id="readme-secure-sandbox">安全沙盒</h3><p>E2B 有代码执行+文件系统操作的云沙盒</p><h3 id="readme-browser-automation">QQ 浏览器自动化</h3><p>Steel, 浏览器 Use 或 AWS Agent Core 用于网络交互</p><h3 id="readme-agent-memory">XQ 代理内存</h3><p>Mem0 或 AWS 代理内存</p><h3 id="readme-tree-shaking-friendly">* * * 树摇动友好</h3><p>颗粒出口无害环境管理, 第一种类型Script</p></td></tr></tbody></table>

* * *

## 为什么是GAIA探员?

### 我们的使命

**授权开发人员在几分钟内,而不是几个月内建立世界一流的"超级AI代理".**

无论是为您的产品创建生产准备的AI助手,还是在GAIA基准中竞争,GAIA Agent提供您需要的企业级基础.

<table><tbody><tr><td><h3 id="readme-traditional-approach">传统方法</h3><ul><li>设置 API 的天数/周数</li><li>手动写入工具包</li><li>每个服务处理出错</li><li>找出要使用的供应商</li><li>综合测试头痛</li></ul></td><td><h3 id="readme-with-gaia-agent">与GAIA代理人</h3><ul><li><strong>3行代码</strong> 要开始</li><li><strong>备妥16个工具</strong> 带有正式 SDKs</li><li><strong>GAIA 基准已就绪</strong> 马上</li><li><strong>交换提供者</strong> 带一行</li><li><strong>生产测试</strong> 执行情况</li></ul></td></tr></tbody></table>

**节省时间:** 从基础设施设置数周起 —— 三行代码

**结果 :** 一个世界一流的,生产准备的超级特工 对抗顶级AI系统

### GAIA基准是什么?

这个 [GAIA 基准](https://huggingface.co/datasets/gaia-benchmark/GAIA) 是一个综合性的评价套件,旨在测试AI代理在包括推理,搜索,代码执行,和浏览器自动化等一系列广泛任务中的能力.

📖 **[更多信息:GAIA](https://arxiv.org/abs/2311.12983)**

* * *

## QQ 快速启动

### 安装

```bash
npm install @gaia-agent/sdk ai @ai-sdk/openai zod
```

### 基本用途

```typescript
import { createGaiaAgent } from '@gaia-agent/sdk';

// Create the agent - reads from environment variables
const agent = createGaiaAgent();

const result = await agent.generate({
  prompt: 'Calculate 15 * 23 and search for the latest AI papers',
});

console.log(result.text);
```

### 环境设置

创建一个 `.env` 文件 :

```bash
# Required
OPENAI_API_KEY=sk-...

# Default providers (at least one required)
TAVILY_API_KEY=tvly-...      # Search
E2B_API_KEY=...              # Sandbox
STEEL_API_KEY=steel_live_... # Browser
```

📖 **[完整的环境变量指南](https://npmcn.com/package/%40gaia-agent/sdk/docs/environment-variables.md)**

* * *

## QQ 内置工具

| 类别 | 工具 | 供应商 |
| --- | --- | --- |
| 🧮 **核心** | 计算器, httprequest | 内建 |
| � **规划** | 规划员、核查员 | 内建 |
| 🔍 **搜索** | tavilySearch, exaSearch, exaGet Contents (英语) | Tavily( 默认), Exa |
| 🛡️ **沙盒** | e2b 沙盒、 沙盒执行 | E2B (默认), Sandock |
| 🖥️ **浏览器** | 钢浏览器、浏览器使用工具、aws浏览器 | Steel (默认), 浏览器 Use, AWS |
| 🧠 **内存** | 记起,记起,记起,记起 | Mem0 (默认), AWS 代理Core |

📖 **[完整工具文档 –](https://npmcn.com/package/%40gaia-agent/sdk/docs/tools-reference.md)**  
📖 **[供应商比较](https://npmcn.com/package/%40gaia-agent/sdk/docs/providers.md)**  
📖 **[动作 + 规划指南](https://npmcn.com/package/%40gaia-agent/sdk/docs/react-planning.md)** 新来

* * *

## 交换提供者

用一行切换提供者 :

```typescript
import { createGaiaAgent } from '@gaia-agent/sdk';

const agent = createGaiaAgent({
  providers: {
    search: 'exa',              // Use Exa instead of Tavily
    sandbox: 'sandock',         // Use Sandock instead of E2B
    browser: 'browseruse',      // Use BrowserUse instead of Steel
  },
});
```

或通过环境变量设定 :

```bash
GAIA_AGENT_SEARCH_PROVIDER=exa
GAIA_AGENT_SANDBOX_PROVIDER=sandock
GAIA_AGENT_BROWSER_PROVIDER=browseruse
```

* * *

## GAIA 基准

运行正式的GAIA基准,加强成果跟踪:

```bash
# Basic benchmark
pnpm benchmark                  # Run validation set
pnpm benchmark --limit 10       # Test with 10 tasks

# Resume interrupted runs
pnpm benchmark --resume         # Continue from checkpoint

# Filter by capability
pnpm benchmark:files            # Tasks with file attachments
pnpm benchmark:code             # Code execution tasks
pnpm benchmark:search           # Web search tasks
pnpm benchmark:browser          # Browser automation tasks

# Stream mode (real-time thinking)
pnpm benchmark:random --stream  # Watch agent think in real-time

# Wrong answers collection
pnpm benchmark:wrong            # Retry only failed tasks
```

### QQ 错误的回答收藏

自动跟踪和重试失败的任务 :

```bash
# 1. Run benchmark (auto-creates wrong-answers.json)
pnpm benchmark --limit 20

# 2. View wrong answers
cat benchmark-results/wrong-answers.json

# 3. Retry only failed tasks
pnpm benchmark:wrong --verbose

# 4. Keep retrying until all pass
pnpm benchmark:wrong
# → "🎉 No wrong answers! All previous tasks passed."
```

📖 **[错误的答案指南](https://npmcn.com/package/%40gaia-agent/sdk/docs/wrong-answers.md)**  
📖 **[恢复特性指南](https://npmcn.com/package/%40gaia-agent/sdk/docs/resume-feature.md)**  
📖 **[基准模块](https://npmcn.com/package/%40gaia-agent/sdk/docs/benchmark.md)**  
📖 **[GAIA 设置指南 −](https://npmcn.com/package/%40gaia-agent/sdk/docs/gaia-benchmark.md)**

* * *

## 增强基准结果

基准结果现在包括全部任务细节:

```json
{
  "taskId": "abc123",
  "question": "What year was X founded?",
  "level": 2,
  "files": ["image.png"],
  "answer": "1927",
  "expectedAnswer": "1927",
  "correct": true,
  "durationMs": 5234,
  "steps": 3,
  "toolsUsed": ["search", "browser"],
  "summary": {
    "totalToolCalls": 5,
    "uniqueTools": ["search", "browser", "calculator"],
    "hadError": false
  },
  "stepDetails": [ /* ... */ ]
}
```

容易分析和调试

* * *

## 基准结果

不同任务类别的最新基准业绩:

| 基准命令 | 时间戳 | 结果 | 准确性 | 型号 | 供应商 | 细节 |
| --- | --- | --- | --- | --- | --- | --- |
| `pnpm benchmark` | 2025-11-26 08:33 | 第22/53号来文 | 41.51% | gpt-4o (英语) | 搜索:tavily,沙盒:e2b,浏览器:钢 | [查看细节](https://npmcn.com/package/%40gaia-agent/sdk/docs/benchmark-results.md#validation) |
| `pnpm benchmark:level1` | 2025-11-27 10:38 (中文(简体) ) | 第16/53号来文 | 30.19% | gpt-4o (英语) | 搜索:Openai, Sandbox:e2b, 浏览器:钢铁, 记忆: mem0 | \- 说吧 |
| `pnpm benchmark:level1` | 2025-12-03 04:12 (英语) | 第21/53号来文 | 39.62% | 克劳德·索内 4.5 | 搜索:Openai, Sandbox:e2b, 浏览器:钢铁, 记忆: mem0 | [查看细节](https://npmcn.com/package/%40gaia-agent/sdk/docs/benchmark-results.md#level-1) |

📖 **[见逐项任务的详细结果](https://npmcn.com/package/%40gaia-agent/sdk/docs/benchmark-results.md)**

**说明:** 基准结果在每个基准运行后自动更新.

* * *

## 测试

使用 Vitest 运行单元测试 :

```bash
pnpm test                # Run all tests
pnpm test:watch          # Watch mode
pnpm test:coverage       # Coverage report
```

📖 **[测试指南 –](https://npmcn.com/package/%40gaia-agent/sdk/docs/testing.md)**

* * *

## 高级用途

### 自定义工具

```typescript
import { createGaiaAgent, getDefaultTools } from '@gaia-agent/sdk';
import { tool } from 'ai';
import { z } from 'zod';

const agent = createGaiaAgent({
  tools: {
    ...getDefaultTools(),
    weatherTool: tool({
      description: 'Get weather',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ temp: 72, condition: 'sunny' }),
    }),
  },
});
```

### 工具SDK 集成

将数千项工具从 [工具SDK.ai](https://toolsdk.ai/) 生态系统:

```typescript
import { createGaiaAgent, getDefaultTools } from '@gaia-agent/sdk';
import { ToolSDKApiClient } from 'toolsdk/api'; // npm install toolsdk

// Initialize ToolSDK client
const toolSDK = new ToolSDKApiClient({ apiKey: process.env.TOOLSDK_AI_API_KEY });

// Load tools from ToolSDK packages
const emailTool = await toolSDK.package('@toolsdk.ai/mcp-send-email', {
  RESEND_API_KEY: process.env.RESEND_API_KEY,
}).getAISDKTool("send-email");

const agent = createGaiaAgent({
  tools: {
    ...getDefaultTools(),
    emailTool
  },
});

const result = await agent.generate({
  prompt: 'Help me search for the latest AI news and send it to john@example.com',
});
```

📖 **[工具SDK 包件 −](https://toolsdk.ai/)**

### 扩展 GAIA 代理类

```typescript
import { GAIAAgent } from '@gaia-agent/sdk';

class ResearchAgent extends GAIAAgent {
  constructor() {
    super({
      instructions: 'Research assistant specialized in AI papers',
      additionalTools: { /* custom tools */ },
    });
  }
}
```

📖 **[高级使用指南](https://npmcn.com/package/%40gaia-agent/sdk/docs/advanced-usage.md)**  
📖 **[API 参考](https://npmcn.com/package/%40gaia-agent/sdk/docs/api-reference.md)**

* * *

## 页:1

<table><tbody><tr><td><h3 id="readme-guides">指南</h3><ul><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/quick-start.md" rel="nofollow noopener noreferrer">快速启动指南</a></strong> - 五分钟后开始</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/react-planning.md" rel="nofollow noopener noreferrer">重新行动+规划指南</a></strong> NEW - 加强推理和规划</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/reflection-guide.md" rel="nofollow noopener noreferrer">反思指南</a></strong> QQ NEW - 分步思考(可选)</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/environment-variables.md" rel="nofollow noopener noreferrer">环境变量</a></strong> - 完整的配置指南</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/gaia-benchmark.md" rel="nofollow noopener noreferrer">GAIA 基准</a></strong> - 要求、设置、提示</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/improving-gaia-scores.md" rel="nofollow noopener noreferrer">改进GAIA分数</a></strong> - 提高业绩和自我发展的战略</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/wrong-answers.md" rel="nofollow noopener noreferrer">错误的回答收藏</a></strong> - 跟踪和重试出错</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/providers.md" rel="nofollow noopener noreferrer">提供者比较</a></strong> - 详细供应商比较</li></ul></td><td><h3 id="readme-reference">参考文献</h3><ul><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/api-reference.md" rel="nofollow noopener noreferrer">API 参考</a></strong> - 完成API文档</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/tools-reference.md" rel="nofollow noopener noreferrer">工具参考</a></strong> - 所有可用的工具</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/advanced-usage.md" rel="nofollow noopener noreferrer">高级使用</a></strong> - 扩展示例、模式</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/benchmark.md" rel="nofollow noopener noreferrer">基准模块</a></strong> - 模块建筑</li><li><strong><a href="https://npmcn.com/package/%40gaia-agent/sdk/docs/testing.md" rel="nofollow noopener noreferrer">测试指南</a></strong> - 与Vitest进行单位测试</li></ul></td></tr></tbody></table>

* * *

## 捐款

这个项目使用国家防范机制自动出版。 当更改合并为 `main`数字 :

1.  QQ 测试自动运行
2.  版本出错到下个补丁(如:0.1.0-0.1.1)
3.  QQ 更改日志创建于 `changelog/`
4.  向国家预防机制公布
5.  已创建 Git 标签

手动版本的出错(小/主要)见 [文档/NPM PUBLISH SETUP.md](https://npmcn.com/package/%40gaia-agent/sdk/docs/NPM_PUBLISH_SETUP.md)。 。 。 .

* * *

## 许可证

Apache 许可证 2.0

* * *

与 QQ 为AI 社区制作

## 常见问题

### @gaia-agent/sdk 是什么？

使用 AI SDK v6 ToolLoop Agent 与可互换的提供者为 GAIA 基准制作准备的 AI 代理库

### 如何安装 @gaia-agent/sdk？

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

### @gaia-agent/sdk 支持 TypeScript 吗？

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

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

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

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

@gaia-agent/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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