Artifacts

client.artifacts gives you the files your agents publish from their workspaces, such as a report or a generated image. List them by agent or session, then hand your user a short-lived download link. To learn how an agent publishes a file, read Artifacts.

const { data } = await client.artifacts.list({ sessionId });
for (const artifact of data) {
  const { url } = await client.artifacts.createDownloadUrl({ artifactId: artifact.artifactId });
  console.log(artifact.filename, url);
}

Every method takes one input object and accepts an optional abortSignal. A published artifact never changes, even if the agent later edits the file in its workspace.

Available operations

Methods

list()

Lists your artifacts, newest first, 50 per page.

Signature: list(input?: ArtifactsListOptions): Promise<ArtifactsListResponse>

const page = await client.artifacts.list({ agentId, sessionId });

Returns ArtifactsListResponse. Errors: validation_failed, invalid_cursor.

get()

Reads one artifact's details without downloading it.

Signature: get(input: { artifactId: string } & ResourceRequestOptions): Promise<ArtifactListItem>

const artifact = await client.artifacts.get({ artifactId });
console.log(artifact.filename, artifact.sizeBytes);

Returns ArtifactListItem. Errors: validation_failed, not_found.

createDownloadUrl()

Creates a link that downloads the file directly for five minutes.

Signature: createDownloadUrl(input: { artifactId: string } & ResourceRequestOptions): Promise<ArtifactDownloadUrlResponse>

const { url, expiresAt } = await client.artifacts.createDownloadUrl({ artifactId });

Anyone with the link can download the file until expiresAt, so check that the user may see the artifact before you hand it out, and keep it out of logs. Create a new link each time you need one. Returns ArtifactDownloadUrlResponse. Errors: validation_failed, not_found, service_unavailable.

delete()

Deletes an artifact for good. The file in the workspace stays.

Signature: delete(input: { artifactId: string } & ResourceRequestOptions): Promise<void>

await client.artifacts.delete({ artifactId });

Deleting it again fails with not_found. Errors: validation_failed, not_found.

Response types

ArtifactListItem

agentId and sessionId stay on the artifact even after you delete that agent or session with its artifacts kept.

ArtifactsListResponse

interface ArtifactsListResponse {
  data: ArtifactListItem[];
  nextCursor: string | null;
}

ArtifactDownloadUrlResponse

interface ArtifactDownloadUrlResponse {
  url: string;
  expiresAt: string;
}

Next

• Artifacts
• Sessions reference