@byteplus-iga-pages/agent

Server-side SDK for BytePlus IGA Pages agents: persist conversations, run Sandbox tools, and connect to agent frameworks.

Official BytePlus IGA Pages documentation

Quick start

Requires Node.js 20+ and an BytePlus IGA Pages server runtime.

npm install @byteplus-iga-pages/agent
npm install -g @byteplus-iga-pages/cli
bp-iga login
bp-iga pages link
bp-iga pages dev

Pages supplies the project identity locally and after deployment. No IGA endpoint or credential is needed in application code.

Store

import { store } from "@byteplus-iga-pages/agent/store";

const { conversationId } = await store.createConversation({
  metadata: { title: "New conversation" },
});
await store.appendMessage({
  conversationId,
  role: "user",
  payload: { text: "Hello" },
});
const page = await store.listMessages({ conversationId, limit: 20 });

Store preserves your JSON payload. page.nextCursor continues pagination. Your application must authorize access to each conversation ID.

Tools and Sandbox

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

const sandbox = getConversationSandbox(conversationId);
const result = await getTools(sandbox).code_run.execute({
  language: "python",
  code: "print(1 + 1)",
});
if (result.status === "error") throw new Error(result.error.message);

// Direct Sandbox API, when you need more control:
await sandbox.code.executeCode({ language: "python", code: "print(1 + 1)" });

getTools(sandbox) provides nine tools: files_read, files_write, files_list, files_search, files_find, shell_exec, code_run, browser_fetch, and browser_screenshot. Calls return { status: "success", data } or { status: "error", error }.

The direct Sandbox API exposes:

| Module | Methods | | --- | --- | | sandbox.code | executeCode | | sandbox.shell | execCommand, view, waitForProcess, killProcess | | sandbox.file | readFile, writeFile, replaceInFile, searchInFile, findFiles, grepFiles, listPath | | sandbox.browserPage | Navigation, interaction, screenshots, and page content; see the exported Sandbox type for all methods |

Use getConversationSandbox(conversationId) for a conversation-bound instance. For a standalone instance, use const sandbox = await createSandbox(), save sandbox.sandboxId, and reconnect with connectSandbox(sandboxId). Instances also support getInfo(), extendTimeout(minutes), and destroy().

Imports

There is no package-root import. Use these subpaths:

| Path after @byteplus-iga-pages/agent/ | API | | --- | --- | | store | store, StoreError | | store/openai, store/langgraph, store/claude | createSession, createCheckpointer, createSessionStore | | tools | Portable getTools | | tools/openai, tools/openai-agents, tools/claude, tools/langchain | Framework-specific getTools | | sandbox | getConversationSandbox, createSandbox, connectSandbox |

Install the corresponding framework SDK when using an adapter. See package.json for optional peer dependencies.

License

See LICENSE for terms of use.