# 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.

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 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.

<CodePanel
  title="Upload files to session"
  snippets={[
    {
      language: 'bash',
      code: `curl -X POST https://api.vectara.io/v2/agents/{agent_key}/sessions/{session_key}/upload \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -F "file=@report.pdf" \\
  -F "file=@analysis.docx"`
    }
  ]}
  annotations={{
    bash: [
      { line: 1, text: 'Upload endpoint for session artifacts' },
      { line: 3, text: 'Attach first file' },
      { line: 4, text: 'Attach additional files in same request' }
    ]
  }}
  layout="stacked"
/>

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:

<CodePanel
  title="Artifact upload event"
  snippets={[
    {
      language: 'json',
      code: `{
  "id": "aev_upload_x8j2",
  "session_key": "ase_analysis_session",
  "type": "artifact_upload",
  "artifacts": [
    {
      "artifact_id": "art_report_a9k3",
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 1048576
    },
    {
      "artifact_id": "art_analysis_b2m5",
      "filename": "analysis.docx",
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size_bytes": 524288
    }
  ],
  "created_at": "2025-10-31T15:45:00Z"
}`
    }
  ]}
  annotations={{
    json: [
      { line: 4, text: 'Event type for artifact uploads' },
      { line: 5, text: 'Array of artifact references' },
      { line: 7, text: 'Unique identifier for referencing the artifact' },
      { line: 8, text: 'Original filename preserved' }
    ]
  }}
  layout="stacked"
/>

### 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.

<CodePanel
  title="Share an artifact with an input"
  snippets={[
    {
      language: 'bash',
      code: `curl -X POST https://api.vectara.io/v2/agents/{agent_key}/sessions/{session_key}/events \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "type": "input_message",
    "messages": [{"type": "text", "content": "Review the attached diff"}],
    "artifacts": [
      {
        "agent_key": "code_reviewer",
        "session_key": "ase_review_8a2f",
        "artifact_id": "art_diff_txt_91c3",
        "purpose": "The diff to review"
      }
    ]
  }'`
    }
  ]}
  annotations={{
    bash: [
      { line: 9, text: 'Agent and session that hold the artifact' },
      { line: 12, text: 'Why the artifact is shared; the agent sees it' }
    ]
  }}
  layout="stacked"
/>

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:

<CodePanel
  title="List artifacts in a session"
  snippets={[
    {
      language: 'curl',
      code: `curl -X GET "https://api.vectara.io/v2/agents/{agent_key}/sessions/{session_key}/artifacts"
       -H "Authorization: Bearer YOUR_API_KEY"`
    }
  ]}
  layout="stacked"
/>

## Retrieve content of an artifact

Download an artifact (including agent-generated ones).

<CodePanel
  title="List artifacts in a session"
  snippets={[
    {
      language: 'curl',
      code: `curl -X GET "https://api.vectara.io/v2/agents/{agent_key}/sessions/{session_key}/artifacts/{artifact_id}" 
       -H "Authorization: Bearer YOUR_API_KEY"`
    }
  ]}
  layout="stacked"
/>

### 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](/docs/agents/memory)
for the patterns this unlocks, including using a Vectara corpus as
cross-session memory.
