Scoping & Versioning

The filename you pass to saveArtifact controls two things: where the artifact is stored and how long it persists. Every call to saveArtifact appends a new version — old versions are never overwritten and can always be retrieved.

Scoping

Artifacts are either session-scoped or user-scoped, determined entirely by the filename prefix:

Session-scoped artifacts are tied to the current session and are no longer accessible once the session ends. Use them for temporary data — processing results, intermediate outputs, or anything that only makes sense in the context of one conversation.

User-scoped artifacts (user: prefix) persist across all sessions for a given user within the same app. Use them for data that should survive between conversations — user preferences, profile data, or long-lived files.

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

async function saveScopedArtifacts(ctx: CallbackContext) {
  // Session-scoped: discarded when the session ends
  await ctx.saveArtifact("summary.txt", { text: "session summary" });

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

When loading, use the same prefix you used when saving — no additional arguments needed:

const sessionData = await ctx.loadArtifact("summary.txt"); // session scope
const userSettings = await ctx.loadArtifact("user:settings.json"); // user scope

Versioning

Each call to saveArtifact creates a new version, starting at 0. Versions increment automatically — you cannot overwrite or delete a specific version. When you call loadArtifact without a version number, you always get the latest.

const v0 = await ctx.saveArtifact("report.txt", { text: "draft" }); // → 0
const v1 = await ctx.saveArtifact("report.txt", { text: "final" }); // → 1

const latest = await ctx.loadArtifact("report.txt"); // returns version 1
const draft = await ctx.loadArtifact("report.txt", 0); // returns version 0

Listing versions

To see which versions exist for a file, call listVersions directly on the service. This method is not on context objects because it requires the full session coordinates (appName, userId, sessionId) that contexts manage internally.

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

const artifactService = new InMemoryArtifactService();

const versions = await artifactService.listVersions({
  appName: "my_app",
  userId: "u1",
  sessionId: "s1",
  filename: "report.txt",
});
// → [0, 1]

Deletion

deleteArtifact removes all versions of a filename at once. Like listVersions, it lives on the service directly — not on context objects — because it's a destructive operation that requires explicit intent.

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

const artifactService = new InMemoryArtifactService();

await artifactService.deleteArtifact({
  appName: "my_app",
  userId: "u1",
  sessionId: "s1",
  filename: "summary.txt",
});

Next steps