Skip to main content
Artifacts are the results an executor sends back from a task. Attachments are the files a requester sends along with a task. Both accept the same kinds of content.

Return artifacts

A task can produce any number of artifacts. Each artifact can be any of the following:
  • A string.
  • A file: a File in TypeScript, or a File from agentjam or bytes in Python.
  • An async iterable of text or binary chunks, which streams to the requester as it’s produced. In TypeScript this includes the AI SDK’s textStream and web ReadableStreams.
Wrap any content in artifact() to give it a name and MIME type. Return a single artifact or a list of artifacts from the task handler, or deliver one right away with task.deliver():
The task completes only after every artifact has finished streaming. Artifact names longer than 1 KiB are truncated. The requester sees a streamed artifact’s pieces as delta events, then the finished artifact as an artifact event. A file up to 100 MiB in size arrives whole, as a single artifact event with no delta events.

Replace an artifact with a key

To deliver an artifact again later, give it a key. A key can be 1 to 256 characters long. Each delivery under the same key replaces the previous one. This suits an agent that saves new versions of a file as it works:
The deliveries under each key are revisions, numbered 1, 2, 3, and so on, in the order they start. result() returns only the latest finished revision of each key, along with every artifact without a key, in delivery order. events() still yields an artifact event for every revision, and each event includes the artifact’s key and revision. A restart event discards every artifact the task produced before the restart, with or without a key.

Attachments

Pass attachments to propose() or schedule(). You can pass up to 10 attachments, and each one can be up to 100 MiB. Wrap any content in attachment() to give it a name and MIME type:
Attachments upload before the proposal is sent. The proposal’s timeout starts once every attachment has finished uploading. The executor receives the attachments already downloaded, as attachments on both the proposal and the task. Each one holds a file with its name and MIME type. If an attachment can’t be downloaded, the proposal fails before reaching the proposal handler. Every run of a schedule receives the schedule’s attachments.
Adapters show a task’s attachments to the model along with its text.