本文介绍 Agent SDK 的用途、核心能力和使用边界，帮助您判断开发 Agent 应用时需要接入哪些模块，并找到对应的参考文档。

背景信息 #

什么是 Agent #

Agent（智能体）是一类以大语言模型为核心，能够理解用户目标、调用工具并分步完成任务的应用。

例如，用户上传一份数据并提出分析需求后，Agent 可以读取文件、执行代码、分析结果，并生成报告。要构建这样的应用，除了调用模型和编排任务，通常还需要保存对话、提供工具执行环境，以及持久化用户文件和生成结果。

Agent SDK 如何支持开发 Agent 应用 #

IGA Pages 支持部署和运行 Agent 应用。您可以通过 Functions 或全栈框架的服务端实现 Agent 逻辑，并结合前端界面，为用户提供对话、文件上传和结果展示等交互。

Agent SDK 为您开发 Agent 应用提供会话存储、沙箱执行、工具调用和文件存储等基础能力。您可以按需组合这些能力，也可以通过适配接口将它们接入 OpenAI Agents SDK、LangGraph、DeepAgents 或 Claude Agent SDK。

开发过程中，各组成部分的职责如下：

核心能力 #

会话存储 Store #

保存会话与消息，为多轮对话提供持久化支持。您可以直接使用 Store 接口，也可以通过框架适配器接入所用 Agent 框架。

对于 LangGraph 和 DeepAgents，还可以使用检查点能力保存执行状态。接口和示例请参见会话存储 Store。

沙箱 Sandbox #

提供受控的执行环境，用于运行代码、执行 Shell 命令、操作文件和完成浏览器任务。

您可以创建独立沙箱，也可以按业务会话获取和复用沙箱，让同一会话中的后续任务继续使用已有的执行环境。接口和示例请参见沙箱 Sandbox。

工具 Tools #

将沙箱能力封装成 Agent 可以调用的工具，方便接入 Agent 框架。

当 Agent 判断需要执行代码时，可以调用相应工具，由工具在沙箱中完成执行并返回结果。Sandbox 提供执行环境，Tools 提供面向 Agent 的调用接口。接口和示例请参见工具 Tools。

对象存储 Blob #

持久保存用户上传的文件、分析报告和其他生成结果。

需要长期保留的沙箱文件，应由应用显式写入 Blob。沙箱中的文件不会自动转存。接口和示例请参见对象存储 Blob。

这些能力如何配合 #

以“上传数据并生成分析报告”为例，应用可以按以下流程组合 SDK 能力：

1. 接收文件：通过应用接口接收用户上传的数据，按需存入 Blob。
2. 保存对话：使用 Store 保存用户请求和会话消息。
3. 执行分析：Agent 通过 Tools 调用 Sandbox，在沙箱中读取数据并运行分析代码。
4. 保存结果：将生成的报告写入 Blob，并在会话中记录结果文件的关联信息。
5. 展示结果：由应用前端展示 Agent 回复和报告入口。

各项能力可以独立使用。例如，仅需要持久化对话的应用可以只接入 Store；需要执行代码时，再接入 Sandbox 和 Tools。

安装与使用 #

Agent SDK 是仅供服务端使用的 Node.js 库，主要包含以下软件包：

核心能力通过子路径按需导入：

import { store } from "@iga-pages/agent/store";
import { getConversationSandbox } from "@iga-pages/agent/sandbox";
import { getTools } from "@iga-pages/agent/tools";
import { blob } from "@iga-pages/blob";

框架适配器包含在核心包中，无需安装独立的适配器包。您仍需另行安装所使用的第三方 Agent 框架。

首次接入时，建议按以下顺序阅读：

1. 安装与环境准备：完成安装、登录和项目关联。
2. 框架适配：了解如何接入所使用的 Agent 框架。
3. 根据需求查阅会话存储 Store、沙箱 Sandbox、工具 Tools和对象存储 Blob的接口与示例。

使用前需要了解的边界 #

SDK 仅在服务端运行 #

请在 Functions 或全栈框架的服务端代码中调用 SDK，不要在浏览器代码中导入。

平台会注入运行时身份。SDK 使用该身份访问当前项目中的资源，业务代码无需显式传入服务地址、项目 ID 或密钥。

应用负责用户访问权限 #

SDK 的会话数据按项目隔离。同一项目内，不同用户之间的资源访问权限由应用负责校验。

会话 ID 和文件路径都不是访问凭证。浏览器应通过应用自己的 API 访问资源，由服务端验证当前用户是否有权操作对应的会话、文件或沙箱。

应用显式管理需要保存的状态 #

各模块之间不会自动同步数据：

• Store 不会自动保存沙箱文件。
• Tools 不会自动记录工具执行历史。
• Sandbox 不会自动将文件写入 Blob。

请根据业务需要，明确哪些消息、执行记录和文件需要持久化，并调用对应接口保存。

使用业务会话 ID 关联资源 #

应用可以为每次对话分配一个统一的 conversationId，并在保存消息、获取沙箱等操作中传入该 ID，以关联同一次对话的资源。各模块不会自动建立关联，具体用法请参见对应的能力参考文档。

如果应用依赖实例内的事件流或可取消任务，还需阅读运行时请求路由与会话亲和性，了解多实例部署下的请求路由方式。