Working with Artifacts (Beta)

Beta / preview API. The artifacts() middleware comes from @genkit-ai/middleware; the Artifact type from genkit/beta. Read agents.md first.

Artifacts are named, content-bearing deliverables an agent produces during a session — files, reports, code, etc. They live in the session (deduplicated by name) and are returned in res.artifacts / tracked on the client's chat.artifacts.

Give the model artifact tools

The artifacts() middleware (see using middleware) adds write_artifact and read_artifact tools and injects an <artifacts> listing into the system prompt each turn (names + sizes, not full content). No custom tool code needed.

import { artifacts } from '@genkit-ai/middleware';
import { ai } from './genkit.js';

export const workspaceAgent = ai.defineAgent({
  name: 'workspaceAgent',
  system: `You are a code generation assistant. Use write_artifact to create
files (pass the filename as "name" and the full content as "content"). Use
read_artifact to review or modify a previously created file.`,
  use: [artifacts()],
});

Run it; artifacts are produced via the tool and returned in the response:

const chat = workspaceAgent.chat();
const res = await chat.send('Write poem.txt with a poem about Genkit');
console.log(res.artifacts); // Artifact[]

Options:

• readonly (default false): when true, only read_artifact is provided — the model can read but not create/update artifacts. Useful on an orchestrator that should review (but not produce) sub-agent artifacts.

The Artifact shape

import type { Artifact } from 'genkit/beta';

// An artifact's content lives in `parts` (text parts). `metadata` is optional.
const artifact: Artifact = {
  name: 'poem.txt',
  parts: [{ text: 'Roses are red…' }],
  metadata: { source: 'workspaceAgent' }, // optional
};

Writing the same name again replaces the artifact (dedup by name).

Programmatic access (inside tools / custom agents)

Use the active session. ai.currentSession() throws when there's no active session, so only call it inside an agent turn.

const session = ai.currentSession();

// Read all artifacts:
const all = session.getArtifacts(); // Artifact[]
const found = all.find((a) => a.name === 'poem.txt');

// Create / replace artifacts:
session.addArtifacts([{ name: 'notes.md', parts: [{ text: '# Notes' }] }]);

Reading artifacts on the client

The remoteAgent client tracks artifacts on chat.artifacts (and each response exposes res.artifacts):

import { remoteAgent } from 'genkit/beta/client';

const agent = remoteAgent({ url: '/api/workspaceAgent' });
const chat = agent.chat();
const res = await chat.send('Create index.html and styles.css');
console.log(res.artifacts); // Artifact[] produced this turn
console.log(chat.artifacts); // all artifacts tracked for the session

Sharing artifacts across agents

In multi-agent orchestration, set the agents() middleware's artifactStrategy: 'session' so sub-agent artifacts are merged into the parent session (namespaced by invocation ID), and add artifacts({ readonly: true }) to the orchestrator so it can read_artifact them:

use: [
  agents({ agents: ['researcher', 'coder'], artifactStrategy: 'session' }),
  artifacts({ readonly: true }),
];