Docs
Contents

Scenarios SDK

Purpose and use cases

Scenarios organize business terminology into names, definitions and ordered category paths. A customer support team can maintain refund, delivery and account recovery scenarios before building a knowledge graph. Operations teams can import a reviewed business catalog instead of recreating definitions in every application. Scenarios are persistent business resources, rather than a cache of model extracted graph entities. Creating or editing one does not rebuild an existing graph. Category knowledge bindings connect the business catalog with a knowledge base and document tag path so that GraphRAG construction and Wiki organization can use the same structure. Start a separate index operation after changing relevant definitions and verify its terminal result before expecting the graph to change.

Prerequisites

Install exactly agentbase-node-sdk@2.12.0 and configure a project API key. Reading needs scenarios.read; creation, editing, importing, deletion and knowledge binding need scenarios.write. Bindings also obey the constraints of the selected knowledge base. Store the key in server environment variables and never send it to the browser. Administrative UI automation can use the matching Console SDK with a valid Console identity and target project context. A server method appearing in generated code does not establish that a browser user can invoke it with the same authorization.

Workflow

  1. Initialize the project Client and Scenarios service. Read categories and locate the full target path before writing.

  2. Create a category and scenario. Save returned identifiers and revisions, then read back the name, definition and ordered path.

  3. Read the current revision before editing. After saving, read the result again instead of treating a stale list row as the current resource.

  4. For bulk import, parse the file, inspect the conflict preview and explicitly select a conflict policy before committing. Commit is atomic; correct validation failures before resubmitting, and check created/updated/skipped counts after success.

  5. Before deleting a category, fetch the impact preview and confirmation token. Inspect affected resources and confirm deletion. Individual scenario deletion requires its current revision.

Parameters and results

Parameter / methodContract
categoriesOrdered array of strings containing the full directory path; a single Support/Refunds string does not represent two path segments
name / definitionBusiness name and description; name is required on creation, while definition defaults to an empty string
scenarioIdOptional on creation and defaults to unique(); retain a custom ID so uncertain submissions can be checked before retrying
revisionCurrent version for scenario updates/deletion, category renaming and knowledge binding; protects concurrent edits
limit / offsetList pagination; search matches names and includeDescendants controls descendant inclusion
createCategoryReceives the complete categories path; save the returned category ID and revision
updateKnowledgeBindingReceives categoryId, revision and the selected knowledge base/tag path or binding collection
parseImport / previewImport / importSeparate parsing, preview and commit phases; a successful preview does not save records
getCategoryDeletionImpact / deleteCategoryRead impact and token before confirming deletion; repeat the preview if it expires or affected state changes

A Scenario returns an ID, revision, name, definition and category path. ScenarioList contains scenario entries and list statistics. Preview responses contain per item decisions. Commit is atomic; verify created/updated/skipped counts against your intent. Categories and scenarios are separate resource types. Inspect affected descendants and existing bindings before renaming or removing a category. Keep business definitions short enough for reviewers to check, but do not replace a complete path with a display label when saving it.

Errors and retry boundaries

For 400/422, inspect the category array, field lengths, file mapping and conflict policy. For 401/403, verify project identity and scopes rather than widening a key without understanding the denied operation. A 404 can indicate deletion or the wrong project. On 409, read the latest revision and content before deciding how to edit again. Refresh an expired deletion impact token instead of bypassing confirmation. After a network failure, check the saved ID or category path before creating another resource. Do not retry a destructive operation in a loop. Read every result page: the first visible page and its row count are not the entire catalog. Parsing a file can succeed while commit validation fails. Correct the reported conflicts before resubmitting; do not assume a successful parse has saved any scenarios.

SDK categories

Examples use the Node Server SDK object argument signatures. The Console SDK is for administrative identities with a target project context. Java, Python and Go use their own generated names and argument conventions; this page does not guess translations of Node object calls. Browser access must follow the actual endpoint authentication contract. See the Scenarios API for HTTP parameters, statuses and method mappings. The shared workflow is independent of the programming language, while the exact constructor, enum and error types belong to each SDK distribution.

Language examples

The examples below use Node.js and share the initialized scenarios object. Read operations can be run independently; run writes in a dedicated demonstration project.

Initialize and read categories

import { Client, Scenarios } from 'agentbase-node-sdk';
const client = new Client().setEndpoint(process.env.AGENTBASE_ENDPOINT)
 .setProject(process.env.AGENTBASE_PROJECT_ID).setKey(process.env.AGENTBASE_API_KEY);
const scenarios = new Scenarios(client);
const categories = await scenarios.listCategories({ limit: 25, offset: 0 });
console.log(categories);

Create and read back

await scenarios.createCategory({ categories: ['Customer support', 'Refunds'] });
const created = await scenarios.create({ categories: ['Customer support', 'Refunds'],
 name: 'Refund eligibility', definition: 'Determine whether a delivered order is eligible for refund.' });
const current = await scenarios.get({ scenarioId: created.$id });
console.log(current.name, current.revision);

Update and read a page

const saved = await scenarios.update({ scenarioId: current.$id,
 revision: current.revision, definition: 'Check delivery date, return window and payment status.' });
const page = await scenarios.list({ limit: 25, offset: 0,
 categories: ['Customer support'], includeDescendants: true });
console.log(saved.revision, page);

Parse an import file

import { InputFile } from 'agentbase-node-sdk/file';
const parsed = await scenarios.parseImport({ file: InputFile.fromPath(process.env.AGENTBASE_SCENARIO_FILE) });
console.log(parsed);

Preview category deletion

const impact = await scenarios.getCategoryDeletionImpact({ categoryId: process.env.AGENTBASE_SCENARIO_CATEGORY_ID });
console.log(impact);

Preview and commit an import

import { ConflictPolicy } from 'agentbase-node-sdk';
if (parsed.sheets.some(sheet => sheet.errors.length)) throw new Error('Correct invalid rows first');
const entries = parsed.sheets.flatMap(sheet => sheet.entries);
const preview = await scenarios.previewImport({ entries, conflictPolicy: ConflictPolicy.Skip });
console.log(preview);

Inspect the preview created/updated/skipped counts before running the commit separately.

const imported = await scenarios.import({ entries, conflictPolicy: ConflictPolicy.Skip });
console.log(imported.created, imported.updated, imported.skipped);

Confirm deletion

const categoryId = process.env.AGENTBASE_SCENARIO_CATEGORY_ID;
const reviewed = await scenarios.getCategoryDeletionImpact({ categoryId });
console.log(reviewed.categories, reviewed.scenarios);

Run deletion only after reviewing impact; refresh the preview if state changes.

await scenarios.deleteCategory({ categoryId, token: reviewed.token });

Further examples

Installation · Node initialization · JavaScript examples