Skip to main content
ai.search-files: Investigate a ZIP archive with a question and return an answer plus file citations. Read-only: the step opens files in the archive and never writes back. ZIP is the only accepted format in this version. Optionally scope the search to a folder prefix and cap how many files and investigation turns may run. Use ai.search-files when a run already has a ZIP bundle and you need a cited answer from the files inside it — for example “which contracts mention assignment?” or “is there a signed amendment in this packet?”. The step is an investigation primitive, not an extractor: it does not return structured fields from a schema, and it does not modify the archive. Point archive at a workflow file input ({ "$fileId": "file_..." }) or a previous step’s file output. Nested ZIP members stay opaque until you extract them and pass the extract output into another search or list step. Encrypted ZIP entries are rejected. See Upload files for hosted multipart, on-prem, headless, and Agent sandbox limits. Git-backed Agents do not run this step. ZIP attachments in a sandbox are inspected with filesystem tools, not ai.search-files.

​
Citations and grounding

Treat the three outputs as different kinds of evidence:
  • Inspected-path guarantee. citations[].path is always a file the step actually opened. It is taken from filesInspected. The step never cites a path it did not read.
  • Excerpts are copies. When citations[].excerpt is present, it is a contiguous substring copied from the inspected file text. Invented or paraphrased excerpts are dropped; the citation then keeps the path only.
  • The answer is LLM-generated. Citations constrain which files and excerpts may be returned. They do not prove every sentence in answer.
The step may return an answer with no citations only when it did not open any files and the answer comes from archive listing metadata (paths and sizes). After any successful file read, the step requires at least one citation to an inspected file. ZIP-only. Encrypted entries are rejected. At most 10,000 central-directory entries. Reads share the same per-entry (64 MiB), per-reader (512 MiB), and process-wide concurrent inflation (512 MiB) budgets as archive extract. Nested ZIP members stay opaque until you extract them and pass that file into another search. Hosted vs headless vs Agent sandbox: Upload files. Downstream steps can read:

​
Configuration

Configuration goes inside the step’s with: block.
​
string
required
Template expression or file reference for the ZIP archive to inspect. ZIP is the only accepted format in this version.
​
string
required
Natural-language question to answer from files inside the archive.
​
string
Optional folder prefix inside the archive. When set, only files under this path are in scope.
​
string
Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted.
​
string
Model override (advanced).
​
"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
Reasoning effort for models that support it. Omit to use the selected model’s default.
​
integer
default:"12"
Maximum investigation turns. Default 12, capped at 50.
​
integer
default:"50"
Maximum files the step may open. Default 50, capped at 200.

​
Output

The investigation answer. Citations point at inspected files; the answer text itself is model-generated.
Citations to files the step inspected. Excerpts, when present, are copied from inspected text.
Archive-relative paths of files the step opened during investigation.