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?
Section titled “Which files does Test or Live read?”| Space | Test reads | Live reads |
|---|---|---|
Reference (knowledge in the assistant tools) |
Saved draft files. | Reference content frozen at publication. |
Runtime (shared in the assistant tools) |
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
Section titled “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: agent and file tools take no workflowId. Find the agent by name with agent_list:
{ "search": "Support helper", "ownership": "mine" }Note the matching data.agents[].id. Later calls use it as <agentId>. Search for the file with agent_file_list before you add it:
{ "agentId": "<agentId>", "space": "knowledge", "search": "support-policy.md" }Inspect data.files. A page holds 50 files by default and 200 at most. If data.nextCursor is not null, call agent_file_list again with the same arguments and cursor set to it, repeating until the pages run out, before concluding the file is absent.
If absent, add it once with agent_knowledge_file_add, passing the policy text inline in content, then reread with agent_file_list:
{ "agentId": "<agentId>", "name": "support-policy.md", "type": "md", "content": "<policy text>" }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. The assistant tools also cap inline content at 2 MiB of UTF-8 data and 2,097,152 characters. The app rejects an empty Reference file. The assistant tools accept empty content.
Replace the policy and verify its answer
Section titled “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 assistant tools cannot replace or delete a Reference file. Calling agent_knowledge_file_add 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, agent_file_list with the arguments below returns Agent has no published version. After that, it shows the previous Reference snapshot until you publish again:
{ "agentId": "<agentId>", "space": "knowledge", "live": true }Keep the support handoff current
Section titled “Keep the support handoff current”Use this content for support-handoff.json:
{"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 with agent_workspace_file_add, passing the JSON text inline in content:
{ "agentId": "<agentId>", "name": "support-handoff.json", "type": "json", "space": "shared", "content": "<handoff JSON>" }Then list both Runtime inventories with agent_file_list, once with each environment:
{ "agentId": "<agentId>", "space": "shared", "environment": "live" }{ "agentId": "<agentId>", "space": "shared", "environment": "dev" }Inspect both inventories. Read the returned file at files/shared/<sandboxPath>, for example files/shared/support-handoff.json. The assistant tools 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
Section titled “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 assistant tools 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
Section titled “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.
The in-product builder can share a file of up to 25 MiB into the build chat. Check data.sharedInChat there, because storage alone does not prove the card was delivered.
An external assistant shares the handoff file with file_share, passing inline content:
{ "name": "support-handoff.json", "content": "<handoff JSON>" }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.