Artifacts

An artifact is a file a run produced. You ask for them with outputs in the agent config and read them off the result.

Declaring outputs#

outputs tells the agent which files to produce. A plain string is a path; the object form adds a display name and a MIME type.

TypeScript

import { createAgent } from '@coresourceai/sdk';

const agent = createAgent({
  type: 'saga',
  systemPrompt: 'Produce every declared output before finishing.',
  outputs: [
    'report.md',
    { path: 'data/summary.csv', name: 'summary.csv', mimeType: 'text/csv' }
  ]
});

const result = await agent.run('Compile the quarterly review.');
console.log(result.artifacts.map((artifact) => artifact.name));

await agent.close();

Declaring outputs is also a way of specifying the job. An agent asked for report.md and summary.csv knows it is not finished until both exist, and a run that produced only one comes back as partial_success rather than silently succeeding.

Reading artifacts back#

Each artifact carries metadata plus two accessors.

Member	Type	Notes
`id`	`string`	Stable identifier
`name`	`string \| undefined`	Usually the declared output name
`mimeType`	`string \| undefined`
`sizeBytes`	`number \| undefined`
`createdAt`	`string \| undefined`
`text(options?)`	`Promise<string>`	Whole body as a string
`download(options?)`	`Promise<Response>`	A `Response` you can stream

TypeScript

import { createAgent } from '@coresourceai/sdk';

const agent = createAgent({ type: 'agent', outputs: ['report.md'] });
const result = await agent.run('Write the report.');

const report = result.artifacts.find((artifact) => artifact.name === 'report.md');

if (report) {
  console.log(await report.text());
}

await agent.close();

name is optional, so find() on it can return nothing even when the run succeeded. Handle the miss rather than asserting.

Large artifacts#

text() buffers the whole body. For anything large, take the Response and stream it.

TypeScript

import { createWriteStream } from 'node:fs';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
import { createAgent } from '@coresourceai/sdk';

const agent = createAgent({ type: 'saga', outputs: ['dataset.parquet'] });
const result = await agent.run('Build the dataset.');

for (const artifact of result.artifacts) {
  const response = await artifact.download();

  if (!response.ok || !response.body) {
    throw new Error(`Could not download ${artifact.name ?? artifact.id}`);
  }

  await pipeline(
    Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0]),
    createWriteStream(`./out/${artifact.name ?? artifact.id}`)
  );
}

await agent.close();

maxOutputInlineBytes limits how much output content the runtime may project inline into the result. The complete artifact remains persisted. text() and download() both fetch the artifact content through the API, regardless of this setting.