Scoping & Versioning

Scoping

Artifacts can be scoped to the current session or to the user across sessions. Use the user: filename prefix to switch to user scope.

import type { CallbackContext } from '@iqai/adk';

export async function saveScopedArtifacts(ctx: CallbackContext) {
  const text = (s: string) => ({
    inlineData: { data: Buffer.from(s).toString('base64'), mimeType: 'text/plain' }
  });

  // Session-scoped: available only in this session
  await ctx.saveArtifact('summary.txt', text('session summary'));

  // User-scoped: available across all sessions for this user
  await ctx.saveArtifact('user:settings.json', {
    inlineData: {
      data: Buffer.from(JSON.stringify({ theme: 'dark' })).toString('base64'),
      mimeType: 'application/json'
    }
  });
}

Loading works the same way — the prefix determines where the service looks:

const latest = await ctx.loadArtifact('summary.txt'); // session scope
const userConfig = await ctx.loadArtifact('user:settings.json'); // user scope

Versioning

Each save creates a new version starting at 0. Loading without a version parameter returns the latest.

// v0
await ctx.saveArtifact('document.txt', {
  inlineData: { data: Buffer.from('A').toString('base64'), mimeType: 'text/plain' }
});

// v1
await ctx.saveArtifact('document.txt', {
  inlineData: { data: Buffer.from('B').toString('base64'), mimeType: 'text/plain' }
});

// Load specific version
const v0 = await ctx.loadArtifact('document.txt', 0);

// Load latest (v1)
const latestDoc = await ctx.loadArtifact('document.txt');

Listing Versions

The listVersions method (on the service, not context) can be used to find all existing version numbers for an artifact. Contexts do not expose version listing.

import { InMemoryArtifactService } from '@iqai/adk';

const artifactService = new InMemoryArtifactService();
// ... after saving some versions
const versions = await artifactService.listVersions({
  appName: 'my_app',
  userId: 'u1',
  sessionId: 's1',
  filename: 'document.txt'
});
// e.g., [0, 1, 2]

Deletion

Deletion removes all versions of a filename in the current scope. The deleteArtifact method permanently removes the artifact and all its versions.

Direct Service Access Required

The deleteArtifact method is not available through CallbackContext or ToolContext for safety reasons. You must access it directly through the artifact service instance.

Basic Deletion

import { InMemoryArtifactService } from '@iqai/adk';

const artifactService = new InMemoryArtifactService();

// Delete an artifact (removes all versions)
await artifactService.deleteArtifact({
  appName: 'my_app',
  userId: 'u1',
  sessionId: 's1',
  filename: 'document.txt'
});

Deletion Behavior

All Versions Removed: Deletion removes all versions of the artifact, not just the latest
Scope-Aware: Deletion respects the artifact's scope (session or user namespace)
Irreversible: Once deleted, artifacts cannot be recovered (unless you have backups)
No Context Access: Must be called directly on the artifact service, not through contexts