Artifacts

Artifacts give an agent access to files and documents without storing them in a corpus. You upload artifacts to a session for temporary use, and the agent can read, convert, or analyze these files during the conversation. Agents support multi-modal analysis through image artifacts, letting you work with documents and images on-the-fly without permanently indexing them into a corpus.

Working with artifacts in sessions

Sessions provide a workspace where agents can access and process files uploaded by users or generated by tools. These files are stored as artifacts that enable efficient file handling without bloating the agent's context.

To make files available to an agent, upload them to the session workspace using a multipart request. Files are stored as artifacts and can be referenced throughout the conversation.

After files are uploaded as artifacts, the agent can extract content from PDFs, Word documents, PowerPoint files, and images. Supported formats include PDF, DOCX, PPTX, and images (PNG, JPEG, GIF, WebP). Artifacts remain available throughout the session lifecycle, enabling multi-step workflows without re-uploading files.

Tip

Artifacts only stay attached to their specific session. If you want these artifacts in a corpus, use the index tool to add them.

Uploading files to a session

To make files available to an agent, upload them to the session workspace using a multipart request. Files are stored as artifacts and can be referenced throughout the conversation.

UPLOAD FILES TO SESSION

Code example with bash syntax.bash

1?

The response contains an ArtifactUploadEvent with references to all uploaded files. This event becomes part of the session history, making the agent aware of the available files:

ARTIFACT UPLOAD EVENT

Code example with json syntax.json

1

Sharing artifacts from another session

To give an agent a file that already exists in another session, list it in the artifacts field of an input message instead of uploading it again. The artifact keeps its identifier, and the session receives an ArtifactUploadEvent before the input, so the agent sees it like an uploaded file, along with the purpose you give.

SHARE AN ARTIFACT WITH AN INPUT

Code example with bash syntax.bash

1

To share an artifact, you need permission to read the artifacts of the agent it comes from, such as the agent_viewer role. If you lack it, the request fails with 403; if an artifact isn't in the session you name, it fails with 404. Either way nothing is shared and no input is recorded. Sub-agents receive the artifacts their parent agent passes them the same way.

List artifacts in a session.

View what is currently stored in a session's workspace:

LIST ARTIFACTS IN A SESSION

Code example with curl syntax.curl

1

Retrieve content of an artifact

Download an artifact (including agent-generated ones).

LIST ARTIFACTS IN A SESSION

Code example with curl syntax.curl

1

How agents use artifacts

After files are uploaded as artifacts, the agent can:

• Use document conversion tools to extract content from PDFs, Word documents, or PowerPoint files.
• View and analyze images visually to answer questions about charts, diagrams, screenshots, or photos.
• Extract text from images using OCR through the document conversion tool.
• Reference artifacts in analysis or question-answering workflows.
• Pass artifacts to indexing tools to add content to corpora.
• Create new artifacts as outputs of tool operations.

Artifacts remain available throughout the session lifecycle, enabling multi-step workflows without re-uploading files.

Agent-written artifacts

Artifacts aren't limited to files the user uploaded. An agent with artifact_create configured can write its own artifacts during a session — plans, notes, draft outputs, intermediate tool results — and read them back on later turns. See Memory for the patterns this unlocks, including using a Vectara corpus as cross-session memory.