ADK-TSArtifacts
Store and retrieve named, versioned files — images, CSVs, JSON blobs, or any binary data — across agent callbacks and tools in ADK-TS.
Artifacts are named, versioned blobs your agent can save and retrieve at any point during execution — from callbacks, tools, or directly on the service. Use them when you need to pass files between steps, persist user uploads, or cache generated content.
How it works
Artifacts are Part objects from @google/genai — either { text }, { inlineData }, or { fileData }. Filenames without a prefix are session-scoped; prefix with user: to persist across sessions.
Quick start
import {
AgentBuilder,
CallbackContext,
InMemoryArtifactService,
} from "@iqai/adk";
const { runner } = await AgentBuilder.create("my_agent")
.withModel("gemini-2.5-flash")
.withArtifactService(new InMemoryArtifactService())
.withBeforeAgentCallback(async (ctx: CallbackContext) => {
const version = await ctx.saveArtifact("notes.txt", {
text: "Agent started.",
});
console.log(`Saved at version ${version}`); // 0
const artifact = await ctx.loadArtifact("notes.txt");
if (artifact?.text) console.log(artifact.text);
return undefined;
})
.build();Switch to GcsArtifactService for durable, production storage. Both services
implement the same interface — no other code changes needed.
Next steps
⚙️ Runner Configuration
Wire up a service and enable auto-save for user uploads
🔌 Context Integration
Save and load via CallbackContext and ToolContext
🗂️ Scoping & Versioning
Session vs user namespaces and how versions work
💾 Service Implementations
In-memory for dev, GCS for production, custom backends
🍳 Recipes
Upload → process → save, media generation, result caching
✅ Best Practices
Caching, batching, validation, and cleanup