Skip to main content

​
Overview

The BaseArtifactService interface provides methods for managing artifacts - files, images, and other data generated during agent interactions. Artifacts are versioned and scoped to sessions.

​
Available Implementations

  • InMemoryArtifactService - Simple in-memory storage for development
  • GcsArtifactService - Google Cloud Storage backed artifacts

​
Interface Methods

​
saveArtifact

Saves an artifact to storage and returns the version number.
​
args
object
required
Arguments for saving an artifact.
​
returns
Promise<number>
The version number of the saved artifact (starts at 1).
import { InMemoryArtifactService } from '@iqai/adk';

const artifactService = new InMemoryArtifactService();

// Save a text artifact
const version = await artifactService.saveArtifact({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt',
  artifact: {
    text: 'Generated content'
  }
});

console.log('Saved as version:', version);

​
loadArtifact

Loads an artifact from storage.
​
args
object
required
Arguments for loading an artifact.
​
returns
Promise<Part | null>
The artifact data as a Part object, or null if not found.
// Load latest version
const artifact = await artifactService.loadArtifact({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt'
});

if (artifact?.text) {
  console.log('Content:', artifact.text);
}

// Load specific version
const oldVersion = await artifactService.loadArtifact({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt',
  version: 1
});

​
listArtifactKeys

Lists all artifact filenames for a session.
​
args
object
required
Arguments for listing artifacts.
​
returns
Promise<string[]>
Array of artifact filenames.
const filenames = await artifactService.listArtifactKeys({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456'
});

console.log('Artifacts:', filenames);
// Output: ['output.txt', 'image.png', 'data.json']

​
deleteArtifact

Deletes all versions of an artifact.
​
args
object
required
Arguments for deleting an artifact.
​
returns
Promise<void>
Resolves when the artifact is deleted.
await artifactService.deleteArtifact({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt'
});

​
listVersions

Lists all version numbers for an artifact.
​
args
object
required
Arguments for listing versions.
​
returns
Promise<number[]>
Array of version numbers (e.g., [1, 2, 3]).
const versions = await artifactService.listVersions({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt'
});

console.log('Available versions:', versions);
// Output: [1, 2, 3, 4]

​
Artifact URIs

Artifacts can be referenced using URIs: 
import { getArtifactUri, parseArtifactUri } from '@iqai/adk';

// Create a URI
const uri = getArtifactUri({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt',
  version: 2
});
// Returns: artifact://my-app/user-123/session-456/output.txt?version=2

// Parse a URI
const parsed = parseArtifactUri(uri);
console.log(parsed);
/*
{
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.txt',
  version: 2
}
*/

​
Usage with Agents

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

const artifactService = new InMemoryArtifactService();

const agent = new AgentBuilder()
  .withModel('gpt-4')
  .withSessionConfig({
    appName: 'my-app',
    userId: 'user-123',
    artifactService: artifactService
  })
  .buildLlm();

// Agents can save artifacts through tools
const response = await agent.ask('Generate a Python script');

// List what was generated
if (agent.session) {
  const artifacts = await artifactService.listArtifactKeys({
    appName: agent.session.appName,
    userId: agent.session.userId,
    sessionId: agent.session.id
  });
  console.log('Generated artifacts:', artifacts);
}

​
Common Use Cases

​
Saving Code Files

await artifactService.saveArtifact({
  appName: 'code-assistant',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'script.py',
  artifact: {
    text: 'def hello():\n    print("Hello, World!")'
  }
});

​
Saving Images

await artifactService.saveArtifact({
  appName: 'image-gen',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'output.png',
  artifact: {
    inlineData: {
      mimeType: 'image/png',
      data: base64EncodedImageData
    }
  }
});

​
Version History

// Save multiple versions
for (let i = 0; i < 3; i++) {
  await artifactService.saveArtifact({
    appName: 'my-app',
    userId: 'user-123',
    sessionId: 'session-456',
    filename: 'document.txt',
    artifact: { text: `Version ${i + 1} content` }
  });
}

// List all versions
const versions = await artifactService.listVersions({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'document.txt'
});
// Returns: [1, 2, 3]

// Load specific version
const v1 = await artifactService.loadArtifact({
  appName: 'my-app',
  userId: 'user-123',
  sessionId: 'session-456',
  filename: 'document.txt',
  version: 1
});

Build docs developers (and LLMs) love

Get started for freeTalk to us