Skip to main content

Contexts and files

A Quick App works with files in several ways. Contexts give it fixed text, files, and folders. Users attach files to messages. Tools take files as parameters, and the agent can fetch URLs or work in its own DIAL folder. This page covers each of these, with its manifest fields. It is for platform engineers and app developers who configure Quick Apps. It assumes you know orchestration.

Contexts​

contexts is a required array; pass [] when the app has none. Each entry has a type:

typeFieldsWhat the agent gets
user-definedcontent (required)Inline text
fileurl (required), descriptionA DIAL file, such as files/<bucket>/<path>
folderurl (required, ends with /), description, max_depth (1–10, default 10)Every file and subfolder of a DIAL folder, up to max_depth levels
{
  "contexts": [
    { "type": "user-defined", "content": "Answer concisely and cite sources." },
    { "type": "file", "url": "files/<bucket>/handbook.pdf", "description": "Company policy handbook" },
    { "type": "folder", "url": "files/<bucket>/shared-docs/", "description": "Shared team docs", "max_depth": 5 }
  ]
}
  • How the agent learns about files. The internal_attachments_available_context tool lists the context files: title, URL, MIME type, description, and whether each is new, updated, or removed since the agent last saw the list. The backend adds this list to the conversation whenever it changes, so the model doesn't have to ask. The model can also call the tool itself.
  • Folders. A folder is expanded on every request, so files added later are found without editing the manifest.
  • Metadata only. The list has no file content. The agent reads a file through the attachment strategy or through a tool, such as RAG.

Attachments for the orchestrator​

By default, the orchestrator model receives only users' image attachments. Other attachments, and context files, reach it as metadata. To let it read them, set the lazy_on_demand strategy:

{
  "orchestrator": {
    "deployment": { "deployment_id": "<MODEL_ID>" },
    "attachment_strategy": { "type": "lazy_on_demand", "accepted_types": ["image/*", "application/pdf"] }
  }
}
  • The internal_attachments_get_content tool loads one file by its URL, for the model to read. Attachments on the latest user message are loaded at once.
  • A file loads only if the orchestrator's deployment accepts its MIME type, per its input_attachment_types in DIAL Core. accepted_types narrows that list further; it can't widen it.
  • An external http(s) URL is downloaded within the external URL fetch limits, and saved as a DIAL file the model can read.

File parameters​

Tools expect files in different forms: a data: URI, plain base64, text, or a URL. The agent writes a file parameter as file:<prefix>::<path or URL>, and the backend resolves it before the tool runs. This works for every tool type.

PrefixThe tool receivesUse for
datadata:<mime>;base64,<payload>Inline file content, such as images and PDFs. The default.
base64The file's bytes as base64Tools that need raw base64, or a retry when data fails
textThe file's UTF-8 textSource code, logs, Markdown, CSV. Binary files are rejected.
urlThe URL itselfTools that take a reference, not content
  • How the agent learns it. A built-in skill, tool-call-file-parameter-formatting, explains the convention. It is added at the start of every conversation.
  • Errors. A missing prefix, a binary file for text, or a blocked URL goes back to the model with the reason, so it can retry.
  • Limits. Only top-level string arguments are resolved. Files are loaded fully into memory. Each URL is loaded once per request.
  • DIAL files for MCP servers. When a dial-mcp tool parameter's schema has "dial_url": true, the backend gives the Toolset access to the DIAL file instead of sending its content. An external URL in such a parameter is rejected.

File size​

Every file the agent downloads, from DIAL or from an external URL, is limited to features.file_loading.size_limit bytes. When unset, the backend's DEFAULT_FILE_LOADING_SIZE_LIMIT applies, by default 10 MiB.

{ "features": { "file_loading": { "size_limit": 5242880 } } }

External URL fetch​

Fetching a non-DIAL URL, for a file parameter, an attachment, or web fetch, passes two tiers of control. The administrator's tier, in backend variables, is a hard cap. The app's tier, features.external_url_fetch, can only narrow it.

ControlAdministratorAppResult
On or offEXTERNAL_URL_FETCH_ENABLED, default falseenabled: null follows the administrator, false opts outOff unless the administrator turns it on
HostsEXTERNAL_URL_FETCH_HOST_ALLOWLISThost_allowlist: null follows the administrator, a list narrows it, [] blocks every hostA host must pass both lists
{ "features": { "external_url_fetch": { "host_allowlist": ["example.com"] } } }
  • Host patterns. example.com matches that host only. *.example.com matches any subdomain, but not example.com itself. IP addresses never match.
  • Safety. Requests carry no DIAL credentials. Each hop of a redirect is checked against the allowlist and against private and loopback addresses. Redirects are capped by EXTERNAL_URL_FETCH_MAX_REDIRECTS.
  • Deployments that fetch URLs themselves. When a DIAL deployment advertises features.url_attachments, an external URL is passed to it as a reference. The backend fetches nothing, so these controls don't apply.

Web fetch​

features.web_fetch adds the internal_web_fetch tool. It fetches an external http(s) resource, such as a README or a documentation page. The text comes back inline, cut at max_inline_size bytes. With a save_path, the resource is saved to the agent's DIAL folder instead; binary content must be saved.

{ "features": { "web_fetch": { "enabled": true } } }
  • max_inline_size defaults to the backend's TOOL_CALL_RESULT_OFFLOAD__SIZE_THRESHOLD, 40000.
  • Web fetch follows the external URL fetch controls. If they block external URLs, the app shows a failed Initialization issues stage until you allow them or remove web_fetch.

DIAL files tools​

features.dial_files gives the agent tools to work with files in DIAL storage. From Quick Apps 0.14.0, every tool is on by default: an app with no dial_files block, or with "dial_files": null, gets all of them, including the tools that change files. To keep the agent from changing files, set enabled_tools to "read_only". Before 0.14.0, the tools are off by default and {} turns on every tool.

FieldDefaultDescription
enabled_tools"all""all", "read_only" (list, read_lines, read_chars, search, find), or a list of any of list, read_lines, read_chars, search, find, write, edit, delete, copy, move. "read_only" and read_chars need Quick Apps 0.14.0 or later.
agent_home_dir""A subfolder of the app's data folder that relative paths start from. It ends with /; no files/, leading /, or ...
max_files_scanned50The most files a folder search reads in one call
tool_call_result_offloadBackend defaultsSee Tool-call result offload

The tools are internal_file_list, internal_file_read_lines, internal_file_read_chars, internal_file_search, internal_file_find, internal_file_write, internal_file_edit, internal_file_delete, internal_file_copy, and internal_file_move. Writes and moves accept relative paths only, inside the agent's folder. A delete can't be undone.

{ "features": { "dial_files": { "enabled_tools": ["list", "read_lines", "search"], "agent_home_dir": "workspace/" } } }

Tool-call result offload​

Preview. It needs ENABLE_PREVIEW_FEATURES=true.

A tool response larger than the threshold is saved to a DIAL file, and the model reads it back in parts with read_lines and search. Both tools must be in enabled_tools.

FieldDefaultDescription
enabledTOOL_CALL_RESULT_OFFLOAD__ENABLED_BY_DEFAULT, trueWhether large responses are offloaded
size_thresholdTOOL_CALL_RESULT_OFFLOAD__SIZE_THRESHOLD, 40000The size, in bytes, above which a response is offloaded
excluded_toolsTOOL_CALL_RESULT_OFFLOAD__EXCLUDED_TOOLS, []More tools that are never offloaded. internal_file_read_lines, internal_file_search, and read_skill never are.

Files in the answer​

  • Add an attachment. features.representation_tooling adds the internal_representation_add_attachment tool, on by default once the section is set. It attaches any URL to the answer, so the user can open or download it. The tool takes a url, and an optional title and MIME type, which it infers from the URL or title when it can. Each call shows an Add attachment stage at the info level.
  • Tool attachments. Each tool's attachment settings decide which attachment types it accepts, and which of its result attachments appear in the answer. A REST API tool can also turn its HTTP response into an attachment. See Attachments.
{ "features": { "representation_tooling": { "add_attachment": true } } }

Further reading​