Attachments

Agents work with files, not just text. A run can start with uploaded files, generate new files mid-workflow (an image from a prompt_call, a report from a sub-agent), and deliver files at the end (email an attachment, write to S3, render in the UI). This page is the high-level guide to how files move through an agent and how you wire them between steps. For the exhaustive field-by-field reference, see Attachments references field.

The two channels: binary and text

Every attachment travels through the agent in two parallel channels:

1. Native binary — capable LLMs (Claude, Gemini, Nova, GPT-4o-class) receive the raw bytes as a media content block, so the model truly "sees" the image / hears the audio / reads the PDF natively.
2. Extracted text — every file is also OCR'd or transcribed. That text is what a text-only model sees, and what the prompt scanner and governance evaluators inspect.

You don't choose between them — the runtime picks the right channel per step based on the model's capabilities (see multi-modal routing). The thing you control is which files reach which step. That is what attachment references do.

Where attachments come from

There are exactly two origins for an attachment inside a run:

The file that lands on a step's input (from whichever upstream step fed it) is also reachable with the bare {{attachments[…]}} form.

What does not produce attachments

• Web Fetch returns text (markdown / HTML / plain text) by default. The page content flows as {{step.<id>.output}} — feed it to a prompt_call as text. Exception: when its media_types field selects images, video, audio, or documents, Web Fetch can produce attachments (a multi-asset manifest) — but only when at least one asset is actually downloaded. If none are found, or every asset is skipped (over a size cap, failed fetch), the output stays text-only, so don't assume {{step.<id>.attachments}} exists just because media_types was set; see Web Fetch. Web Search always returns text, not binary files.
• text, merge, extract_content, extract_data, regex_replace, gates, and other transforms operate on text and pass attachments through untouched if their input carried any; they never create new ones.

If you need a remote file as a real binary attachment, fetch it inside a prompt_call using the web tools, or upload it as agent input.

The reference grammar

An attachment reference is a {{…}} expression that selects zero or more files from one source. The same grammar works everywhere — inside a text field or in a step's dedicated Attachments list.

Multiple references union their matches in list order and dedupe (first-seen wins). A reference that matches nothing is a no-op (logged at INFO), never an error.

Implicit vs explicit visibility

A step only "sees" an attachment when its template declares the dependency — this keeps uploads from silently leaking into intermediate steps that don't want them.

• Implicit — referencing {{input}}, {{agent.input}}, or {{step.<id>.input|output}} pulls in all attachments carried on that source. Existing templates keep working unchanged.
• Explicit — any {{attachments[…]}} selector narrows the set. As soon as one explicit selector targets a source, it replaces the implicit "all" for that source.

Two ways to use a reference

1. Inline, in a text field — drop the placeholder into a prompt_call prompt, an email HTML body, an S3 object key, or a webhook payload. The file is routed to that exact spot. This is how LLM-call steps (prompt_call, evaluate_step, extract_data) receive files — there is no separate field; the placeholder is the trigger.

   Summarize {{attachments[0]}} in three bullet points.
   

2. The per-step Attachments field — manifest-consuming steps (send_email, write_aws_s3_object, webhook_call, call_agent, publish_content, write_content_attachment, for_each, display_result, streaming_result) expose a dedicated Attachments list of references that selects which files the step ingests. The editor builds it row-by-row with a live match-count preview.

   ["{{attachments[*.pdf]}}", "{{step.report.attachments[0]}}"]
   

   Leaving the list empty defaults to "every attachment on the step's input" — except the result steps (display_result / streaming_result), where the default is text only (attach nothing unless a reference is set).

Worked examples

1. Summarize an uploaded PDF

A dynamic_input trigger accepts one PDF; a prompt_call reads it inline.

Trigger: dynamic_input
  → Prompt Call:
      prompt_template: "Summarize {{attachments[0]}} in 200 words."
      → Streaming Result

The bare {{attachments[0]}} resolves to the first file on the prompt step's input — the uploaded PDF. No Attachments field needed; the inline placeholder routes the binary.

2. Analyze each uploaded image

Fan out over every uploaded file, one iteration each, with a for_each in iterate_attachments mode. This is the right shape for "do X to each attached image / file" — and it works as the first step, drawing directly from the trigger uploads.

Trigger: dynamic_input
  → For Each (id: image-loop, iterate_attachments: true)   # omit input_template; omit the attachments filter to take ALL uploads
      body:
        → Prompt Call (id: describe):
            prompt_template: "Describe {{step.image-loop.item.attachment}} and list any text you can read."
      child_steps:                                          # run ONCE, after every iteration finishes
        → Prompt Call (id: digest):
            prompt_template: |
              Combine these per-image descriptions into one summary, grouping similar images:
              {{step.image-loop.output}}
        → Display Result

Each iteration's item carries the current file's metadata (storage_key, mime, name); {{step.<for_each_id>.item.attachment}} hands the real file to the body prompt. Inside the body, the bare {{attachments[0]}} resolves to the same current file. Add an attachments filter (e.g. ["{{agent.attachments[*.pdf]}}"]) only when the user explicitly restricts the set — never narrow "image" to a single extension.

Collecting the results. When every iteration has finished, the loop's own output is the aggregated array of its body outputs, addressable as {{step.<for_each_id>.output}} — for a single-step body it's a JSON array of strings (one per image); for a multi-step body it's an array of objects keyed by body-step id. Put the steps that consume it in the for_each's child_steps (the post-loop continuation that runs once): here a digest Prompt Call folds the per-image descriptions into one summary, which a Display Result then surfaces. Swap in Send Email or Write to S3 to deliver the digest instead. See the For Each step reference.

3. Generate an image and deliver it

A prompt_call on an image-generation model produces a file; downstream steps reference it via {{step.<id>.attachments[…]}}.

Prompt Call (id: gen, image-generation model):
  prompt_template: "A watercolor fox in a snowy forest."
  → Send Email:
      html_body: '<p>Here is your image:</p><img src="{{step.gen.attachments[0]}}" />'

In an email HTML body the placeholder is CID-embedded so it renders inline (see inline images). To store it instead, point a Write to S3 step at the same reference:

  → Write to S3:
      object_key: "fox-{{index}}-{{name}}"
      attachments: ["{{step.gen.attachments}}"]

Because image generation can emit several files, include a per-attachment placeholder ({{name}} / {{index}} / {{ext}}) in object_key so each file writes to a distinct object. To surface the generated image in the UI, give a Display Result step the reference ["{{step.gen.attachments}}"] (result steps attach nothing by default).

4. Forward uploads to a sub-agent

call_agent is a manifest consumer — its Attachments field chooses which files to forward to the sub-agent, which receives them as if they were its own dynamic_input uploads.

Trigger: dynamic_input
  → Call Agent (target: "invoice-parser"):
      attachments: ["{{agent.attachments[*.pdf]}}"]

Only the PDFs among the uploads are propagated to the sub-agent's first prompt step. See the Call Agent step.

5. Route one specific file

References compose, so you can pick exactly one file out of a mixed batch and send it somewhere specific — e.g. email just the contract PDF while archiving everything to S3:

Prompt Call → (manifest flows downstream)
  → Send Email:
      attachments: ["{{attachments[contract.pdf]}}"]
  → Write to S3:
      object_key: "archive/{{index}}-{{name}}"
      attachments: ["{{attachments}}"]

6. Chatbot that iterates on a generated image

A conversational agent that generates an image and lets the user refine it turn by turn ("make the moon bigger", "warmer palette"). Each turn is one run; conversation memory carries the running thread, and the Add Chat Turn step returns it as a messages array that a use_step_input_as_messages Prompt Call feeds straight to the model. The key is the attachments field on the assistant turn — it persists the generated image with that turn so it replays into the next turn as a native media block the model can actually see.

Trigger: chat (conversational)
  → Add Chat Turn (conversation, key: "{{metadata.user_id}}", speaker: "user", content: "{{agent.input}}")
      → Prompt Call (id: gen, image-generation model, use_step_input_as_messages: true)
          → Display Result (attachments: ["{{step.gen.attachments}}"])
          → Add Chat Turn (conversation, key: "{{metadata.user_id}}", speaker: "assistant",
                           content: "Here's the image.", attachments: ["{{step.gen.attachments}}"])

On turn 2, the loaded history is replayed into the Prompt Call as a messages array in which the assistant turn carries the image as a media block. The model sees the picture it drew, so "make the moon bigger" now refers to something concrete — it can iterate instead of regenerating blind.

How memory carries attachments. When an Add Chat Turn step has an attachments reference, each matched file is copied into memory-owned storage (so it outlives the run) and recorded with the turn. On replay — a prompt_call with use_step_input_as_messages: true reading that history — turns that carried files are rendered as multi-block messages (text + native media), exactly as if the file had been uploaded on that turn. Notes: only conversation memory (Add Chat Turn) persists attachments — not general memory (Add Memory); a turn keeps up to 10 attachments of 20 MB each (oversized files are skipped); the model must support image input natively, and remembered images add to each turn's token cost, so persist deliberately (typically just the latest generated image). Leave attachments empty for a text-only turn.

Per-step cheat sheet

Validation, uploads, and limits

Saved agents carry a static attachment-reference contract derived from every step's templates, which drives three safety gates:

• Editor save rejects a reference on a step type that can't route binaries, or a {{step.<id>.attachments}} against a step that doesn't produce a manifest.
• Upload time rejects files when the agent declares no attachment references at all (nothing would consume them).
• Run time requires the uploaded batch to satisfy the references: every exact filename must be present, the highest declared index must be in range, and every glob must match at least one file.

Uploaded files are also prompt-scanned in parallel — an unsafe attachment (e.g. a jailbreak embedded in a PDF) fails the run's input scan closed. Per-file limits: 200 MB per uploaded file; 25 MB total per email (SES); 5 MB for base64 webhook payloads. See File Attachments on the Agents page for the full upload / API / MCP flow and the contract-introspection endpoints.

Input file retention

An uploaded input binary is part of the run's trace, so it is kept only as long as the run trace itself — i.e. your account's agent-trace retention (the free default is 7 days; set the retention on the system-managed agent-traces source connection, or keep traces forever). After that window the binary is swept and only its extracted text remains. Practically: replaying a run (the "run again with the same files" affordance) re-attaches the original uploads while they're still present — and each replay refreshes the retention clock on the files it reuses, so a file stays available as long as it keeps getting replayed (a blob is only swept once no run has referenced it within the retention window). Replay a run whose files have already been swept and any lost image falls back to its extracted text (documents stay readable as text; raw images are dropped). The replayed files are re-resolved server-side from the original run, so this is automatic and safe — there's nothing to re-upload. Replay is available from the UI, the API, and MCP.

Further reading

• Attachments references field — the complete reference table and per-consumer behaviour.
• File Attachments (Agent Steps) — selector syntax and multi-modal routing internals.
• File Attachments (Agents) — uploading files to a run, the attachment contract, and downloading run outputs.
• For Each step — iterating over attachments.