Work with Studio and recover changes

Use Studio to inspect or edit an agent visually and the SDK to keep its behavior in source. Both work on the same canonical graph. Revision checks stop an old SDK plan from overwriting a newer Studio edit.

Keep three things distinct: the mutable draft you are editing, an immutable publication you can test, and the current head selected for ordinary runs. Phone-number assignments and already running calls have their own state.

Preview, apply and publish

The authoring library separates review from mutation:

For a first preview, import your compiled tutorial project and select its integration:

import { Cumulus } from '@cumulus/sdk';
import { authoring } from '@cumulus/sdk/agent';
import { agent, bindings, integration } from './dist/project.js';

const baseUrl = process.env.CUMULUS_API_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error('Set API origin and key');
const client = new Cumulus({ baseUrl, apiKey });
const plan = await authoring.preview(client, agent, bindings, {
  projectKey: 'service_guide', integration,
});
console.log({ tenant: plan.tenantId, revision: plan.baseRevision, changes: plan.changes });

For later previews, pass the previous receipt as well. It identifies the managed agent and the baseline you last applied. Review the tenant and every proposed change, then preserve the plan you approved.

Applying requires expectedRevision: plan.baseRevision. Supply an awaited onCheckpoint callback that durably saves the receipt before and after each batch. Publishing takes the same callback so a lost response can be reconciled. The CLI already stores plans and checkpoints; use it if you do not need a custom deployment process.

A successful apply changes the draft, not the publication. Publication defaults to test-only; use live: true when you intend to advance the ordinary head. Test that exact version before assigning numbers. Runtime helpers show pinned calls and result retrieval.

Backport a Studio change

Suppose you applied revision 8, then a teammate edits a prompt in Studio and creates revision 9. Your next preview should stop with DraftConflict. That gives you a chance to bring their change into source:

1. Run cumulus export to save studio-backport.json.
2. Compare the exported graph with your TypeScript and backport the intended change.
3. Rebuild and validate the source locally.
4. Preview with --adopt-reviewed-revision 9, using the actual revision you reviewed.
5. Review the fresh diff, then apply. A later edit still causes a conflict.

With the library, authoring.exportDraft(client, agentId) reads the draft, and preview's acceptRemoteRevision selects the reviewed baseline. These are explicit reconciliation steps, not a force overwrite.

The export is canonical graph data; it does not reconstruct TypeScript. Protected fields can be redacted, so do not send the export back as a full-document replacement. The planner removes resources it previously managed and preserves unknown Studio resources and protected credentials. Changing a resource key may change its identity.

Recover an interrupted apply or publication

An apply can span several edit batches. The receipt records each batch before sending it and checkpoints the returned revision afterward. Preserve that receipt when a request fails.

Do not recreate the agent or mint another publication to escape an unknown outcome. A partially edited draft is still a draft; it has not changed the running publication. SDK errors explains the error fields and recovery evidence.

Receipts include project/agent/tenant identity, draft ID and revision, desired-definition hashes, head version and publication reference. They may contain prompts, URLs and configuration references. Save them privately and atomically. Call effectiveTenant(client) before choosing a stored receipt; an operator's home tenant can differ from the effective target.

Promote and roll back deliberately

authoring.promote(client, receipt) selects the publication saved in that receipt as head. To select an older publication, deliberately choose its historical receipt or use the native publication operation. A test-only publication remains test-only after promotion.

Before changing phone routing, record the old assignments. Restore the intended head and number assignments explicitly, then inspect every returned pin. Number assignment follows the current head and multiple updates are not atomic.

Already admitted calls retain their publication. Keep older customer endpoint contracts working while those calls finish. Restoring an older graph does not undo external bookings, database changes or a deployment of your application server.

Editing components with protected fields

Root nodes use focused edits; components normally use replacement. For components containing transfers, SDK 0.3.4 can add scoped nodes and change edges while preserving existing node configuration. It refuses configuration, removal or metadata changes that could overwrite redacted transfer credentials. Use credential-aware native edits for those cases.