本文是 Agent SDK（智能体软件开发工具包）参考手册的入口，帮助您在动手写代码前先建立整体认知：SDK 由哪些能力组成、它们各自解决什么问题、代码在什么运行模型下执行，以及从哪里开始逐能力查阅。读完本文，您应能判断自己的需求对应哪几个模块，并顺着链接进入对应的参考文档。

背景信息 #

IGA Pages Agent 的 SDK 是一组 server-only（仅服务端） 的 Node 库，供您在 IGA Pages 的服务端环境（Functions 或全栈框架的服务端）中直接调用，把会话存储、工具、沙箱、对象存储等能力组合成 Agent 应用。它以核心包 @iga-pages/agent 为主，配合对象存储包 @iga-pages/blob。

SDK 的设计有四条贯穿始终的前提，理解它们能避免大多数接入误区：

• 只在服务端运行。 这两个包不能在浏览器代码中导入；SDK 会读取运行时环境与鉴权变量，只有服务端才具备这些条件。
• 运行时身份由平台注入，密钥不写进代码。 业务代码无需传入服务地址、项目 ID 或密钥。SDK 会使用当前应用的运行时身份访问对应项目中的资源；会话数据按当前项目身份隔离，不同项目彼此独立。
• 应用负责校验资源归属。 浏览器应通过应用自己的 API 访问 SDK 资源。会话 ID 和文件路径都不是访问凭证；写入 metadata.ownerId 也不会自动启用用户隔离。应用必须校验当前用户对会话、文件和沙箱的访问权限。
• 能力彼此独立，状态由应用显式管理。 Store 不会自动保存沙箱文件，Tools 不会自动记录执行历史，沙箱文件也不会自动写入 Blob。哪些状态需要持久化、用哪个能力保存，由应用明确决定。

能力全景与查阅入口 #

SDK 的各项能力按用途划分如下。请按需求定位到对应模块，再进入其参考文档查阅完整接口：

各模块的错误处理方式不同，没有统一的跨模块错误类型或返回格式：

• Store 和 Blob 的方法失败时会抛出各自的异常。
• Sandbox 的实例管理方法失败时会抛出异常；代码、命令、文件和浏览器等业务方法还可能返回 ok: false。
• Tools 的 execute() 通过顶层 status 区分成功与失败。

调用前，请查看所用模块的返回与错误处理说明，并按其约定读取结果或处理异常。具体字段与重试建议见对应参考文档。

此外，还有两份基础与专题文档配合使用：

• 环境准备、安装与登录关联项目的步骤，见安装与环境准备——这是调用上述任何能力的前置步骤。
• 多实例下的请求路由与会话亲和性（x-iga-pages-conversation-id），见运行时请求路由与会话亲和性——当应用依赖实例内运行态（事件流、可取消任务）时需要理解这条边界。

导入路径约定 #

核心能力从 @iga-pages/agent 的子路径按需导入，对象存储从 @iga-pages/blob 导入。只引入用到的子路径即可，无需引入全部内部包：

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";

Store 框架适配器属于核心包 @iga-pages/agent，请按所用框架从 @iga-pages/agent/store/openai、@iga-pages/agent/store/langgraph 或 @iga-pages/agent/store/claude 子路径导入，无需安装独立的适配器包。对应的第三方框架包需要另行安装，具体见框架适配。各模块的公开能力、示例和已确认边界见对应参考文档；需要完整类型信息时，以所安装版本的 TypeScript 类型定义为准。

会话 ID 的角色 #

应用可用同一个业务 conversationId 关联以下状态：

• Store 消息与 OpenAI Agents 会话。
• LangGraph／DeepAgents 执行状态，作为 thread_id。
• 按会话复用的沙箱。

除 store.createConversation() 外，这些入口都要求显式传入非空字符串，且最多 256 UTF-8 字节，不限定为 UUID。只有 store.createConversation() 可以省略 ID，并由 SDK 自动生成 UUID。通常在创建业务会话时确定一次，之后随请求保存并显式传递给 Store、Blob key 与 getConversationSandbox(conversationId)。

Claude Agent SDK 使用独立的 Claude session ID 恢复会话，应用需要自行维护它与业务 conversationId 的映射。

用 randomUUID() 生成一个符合约定的会话 ID 是常见做法：

import { randomUUID } from "node:crypto";

const conversationId = randomUUID();

需要强调的是：conversationId 只是资源标识，不是访问凭证。对外提供接口时，应用仍需自行校验当前用户是否有权访问该会话。会话亲和性请求头 x-iga-pages-conversation-id 同理，它是路由输入而非鉴权凭据，详见运行时请求路由与会话亲和性。