Manage Agent Files

Use Reference for material published with your agent, Runtime for shared information that changes independently, and Conversation for one chat’s attachments and outputs. For Support helper, put support-policy.md in Reference, the current handoff in Runtime, and a customer’s document in its conversation.

Which files does Test or Live read?

Space	Test reads	Live reads
Reference (knowledge in CLI/MCP)	Saved draft files.	Reference content frozen at publication.
Runtime (shared in CLI/MCP)	Live files overlaid by development files at the same path; development wins.	Current live Runtime files, independently of publication.
Conversation	That Test conversation’s files.	That Live conversation’s files.

Reference supports txt, md, json, csv, html, and xml. Use files/knowledge/<sandboxPath> for Reference and files/shared/<sandboxPath> for Runtime. The returned sandboxPath omits those folders.

Add the support policy

Save this example as a local UTF-8 support-policy.md. Substitute your own policy before sharing it:

Support policy

Reply with the relevant policy and identify its section. Before escalation, ask for a missing ticket ID. Escalate account-specific requests with the ticket ID and a short issue summary. Do not promise an exception before review.

In the app: open Agents → Support helper → Edit → Reference files → Add files. Select the file, confirm its Unsaved row, then Save changes to open Test.

Finish active Test turns and resolve or deny requests before saving. A save that changes the draft stops active Test runtimes. It also expires pending approvals and approvals granted but not yet run. History remains, and the next message uses the saved draft. One save allows 100 file operations and 100 MiB of added content. A failed batch commits nothing, and the app keeps your edits for correction.

With an assistant: these agent and file commands need no workflow context, and no workflow is pinned. Find the agent by name:

cai agent list --search "Support helper" --ownership mine --json

Note the matching data.agents[].id. Later commands use it as <agentId>. Search for the file before you add it:

cai agent files <agentId> --space knowledge --search "support-policy.md" --json

For MCP, use agent_file_list with agentId, space: "knowledge", and search: "support-policy.md".

Inspect data.files. A page holds 50 files by default and 200 at most. If data.nextCursor is not null, use it as <cursor> and repeat until the pages run out, before concluding the file is absent:

cai agent files <agentId> --space knowledge --search "support-policy.md" --cursor <cursor> --json

If absent, add once and reread:

cai agent add-file <agentId> --file support-policy.md --name support-policy.md --type md --space knowledge --json
cai agent files <agentId> --space knowledge --search "support-policy.md" --json

MCP uses agent_knowledge_file_add with agentId, name, type: "md", and inline policy text in content instead of a local path. Tell the agent to read files/knowledge/support-policy.md.

Reference and Runtime text files have a backend limit of 25 MiB of UTF-8 data, and CLI additions count against it. MCP also caps inline content at 2 MiB of UTF-8 data and 2,097,152 characters. The app rejects an empty Reference file. The CLI and MCP accept empty content.

Replace the policy and verify its answer

In Edit, remove the old row and add the revised file. Confirm the replacement shows as Unsaved before Save changes. An invalid selection leaves only the removal staged. With both staged, one transaction removes the old file first, then adds the replacement under the original name. If the server fails, both changes roll back.

The CLI and MCP cannot replace or delete a Reference file. Running add-file again creates support-policy-2.md, and the original stays available. Ask the owner to replace it in Edit.

Ask Test a question whose answer changed, and compare the reply with the revised policy. Before the first publish, the command below returns Agent has no published version. After that, it shows the previous Reference snapshot until you publish again:

cai agent files <agentId> --space knowledge --live --json

MCP uses agent_file_list with agentId, space: "knowledge", and live: true.

Keep the support handoff current

Save support-handoff.json locally:

{"ticket_id":"T-104","status":"awaiting_review","summary":"Customer requests an account-specific policy review."}

Adding Runtime content updates the live store without another publish. An enabled, published agent reads it on its next turn. A paused agent reads it once you enable it. An unpublished agent has no Live conversation. Add the file, then list both Runtime inventories:

cai agent add-file <agentId> --file support-handoff.json --name support-handoff.json --type json --space shared --json
cai agent files <agentId> --space shared --environment live --json
cai agent files <agentId> --space shared --environment dev --json

MCP uses agent_workspace_file_add with agentId, name, type: "json", space: "shared", and JSON text in content. Inspect both inventories. Read the returned file at files/shared/<sandboxPath>, for example files/shared/support-handoff.json. The CLI and MCP add new Runtime paths, but cannot replace existing ones.

In the app: Files → Runtime is for inspection, and offers no Runtime upload control. Test lists development rows only, so it hides live files that Test also reads. Inspect Live separately. Reset Test files deletes development rows, and deletes only the matching rows while you are searching. Reference and live Runtime files remain. Deleting a development override makes the live file effective in Test again.

A workflow writes Runtime files in its own execution environment. Updating a live file in development creates or updates a development copy at the same path. Publishing does not promote that copy. Run the writing workflow on Live after publishing both resources. In Create agent file, Replace existing file is off by default, so a collision produces -2, -3, and later copies. Turn replacement on for a stable path, or use Update agent file, whose default is Replace. Append supports only txt and md.

The in-product builder can add Reference files. Its credentials cannot add Runtime files directly, so use an external assistant or a file-writing workflow.

Attach a document to one conversation

Open a Test or Live conversation, select Attach files, choose the document, and send its task. Conversation uploads accept the text formats above, plus PDF, DOC/DOCX, XLS/XLSX, ZIP, PNG, JPEG, GIF, and WebP. Each request allows 10 nonempty files, each at most 25 MiB and each with an allowed MIME type. One invalid file rejects the whole request before anything is stored. The public CLI and MCP cannot upload conversation attachments, so ask the person to attach them.

A workflow’s file value carries metadata such as name, size, and URL. It does not parse CSV. Extract typed values before passing rows to a workflow.

Deliver a file someone can open

Ask Support helper to create the result and call built-in share_file with its workspace-relative path (the file may be up to 25 MiB). Download the file from Files → Conversation, and check T-104 and its status.

In the in-product builder, share the handoff file into the build chat:

cai file share support-handoff.json --name support-handoff.json --json

This CLI command requires builder credentials and allows 25 MiB. Check data.sharedInChat, because storage alone does not prove the card was delivered. External MCP assistants use file_share with name and inline content. Its decoded limit is 2 MiB, encoding defaults to utf8, and an omitted mimeType is inferred. Relay the returned url, and download it before expiresAt.