Files and inputs

Data reaches a run three ways: uploaded files, structured input, and references to artifacts an earlier run produced. Files and artifact references can be placed at relative paths you choose; structured input remains JSON. Storage locations and the runtime's filesystem roots are not part of the public API.

Sending files in#

files accepts a local path or an in-memory file object, mixed freely.

TypeScript

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

const agent = createAgent({ type: 'agent', outputs: ['findings.md'] });

const result = await agent.run({
  prompt: 'Analyse the supplied invoices against the policy and write findings.md.',
  files: [
    // A path on your machine. Uploaded under its basename.
    './invoices.csv',

    // In-memory content, placed at an explicit destination.
    {
      name: 'policy.txt',
      path: 'references/policy.txt',
      data: 'Escalate invoices above EUR 50,000.',
      mimeType: 'text/plain'
    }
  ],
  input: { country: 'DE', currency: 'EUR' }
});

await agent.close();

Field	Type	Notes
`name`	`string`	Required. The file's name
`data`	`Blob \| Uint8Array \| ArrayBuffer \| string`	Required. The content
`path`	`string`	Destination relative to the run's input directory. Defaults to `name`
`mimeType`	`string`	Helps the agent choose how to read it

path is what lets you build a directory layout the agent can navigate:

TypeScript

import type { AgentFile } from '@coresourceai/sdk';

const files: AgentFile[] = [
  { name: 'q1.csv', path: 'quarters/q1.csv', data: 'month,total\n' },
  { name: 'q2.csv', path: 'quarters/q2.csv', data: 'month,total\n' },
  { name: 'README.md', path: 'README.md', data: '# Quarterly exports' }
];

Structured input#

input is a JSON object handed to the run alongside the prompt. Use it for structured parameters rather than interpolating them into prose. It remains separate from the prompt in the request and is made available to the run.

TypeScript

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

const agent = createAgent({ type: 'agent' });

const result = await agent.run({
  prompt: 'Produce the regional breakdown described in the input.',
  input: {
    regions: ['DACH', 'Nordics'],
    currency: 'EUR',
    thresholds: { escalate: 50_000, review: 10_000 }
  }
});

await agent.close();

Passing artifacts between runs#

A run's artifacts can be fed into a later run by reference.

TypeScript

import { createAgent, type AgentInput } from '@coresourceai/sdk';

const researcher = createAgent({ type: 'saga', outputs: ['research.md'] });
const writer = createAgent({ type: 'agent', outputs: ['brief.md'] });

const research = await researcher.run('Research invoice automation.');

const inputs: AgentInput[] = research.artifacts.map((artifact) => ({
  type: 'artifact',
  runId: research.id,
  artifactId: artifact.id,
  path: `upstream/${artifact.name ?? artifact.id}`
}));

const brief = await writer.run({
  prompt: 'Write an executive brief from the upstream research.',
  inputs
});

await Promise.all([researcher.close(), writer.close()]);

inputs (as distinct from files) references content that already lives on the platform. On the native hosted path, the reference stays server-side. If the downstream createAgent() uses custom tools, runtime tools, a local skill bundle, or a locally registered MCP server, the SDK provisions its bridge and downloads the artifact before uploading it to that runtime. This is also the mechanism composeAgents uses for its default handoff.

An AgentInput is either an uploaded file or a prior artifact:

TypeScript

import type { AgentInput } from '@coresourceai/sdk';

const fromUpload: AgentInput = {
  type: 'file',
  fileId: 'file_01J8Z5',
  path: 'inputs/ledger.csv'
};

const fromPriorRun: AgentInput = {
  type: 'artifact',
  runId: 'run_01J8Z5',
  artifactId: 'art_01J8Z6',
  path: 'upstream/report.md'
};