Conversations and files

A conversation is one thread with an agent: messages, tool calls, approvals, attachments, and its own files. This page covers conversations and the file model — the part of agents where naming precision pays off, because there are three distinct file surfaces with different lifecycles.

Conversations

• Test conversations run the mutable draft; Live conversations run the latest published version (versions and rails).
• The model is chosen per conversation — in the chat composer, or --model on cai agent conversation create / cai agent test. It is a runtime setting, never part of the agent.
• Conversations can be interrupted mid-turn and resumed by their next message. Users can attach files to messages; attachments are conversation-scoped.

cai agent conversation list <agentId>
cai agent conversation create <agentId> --message "..."
cai agent conversation history <conversationId> --last

The three file surfaces

Surface	App label	Lifecycle	Who writes it
Knowledge files	Reference tab	Belong to the agent; frozen into each published version. Live conversations read the published copies; Test reads the draft’s.	You / your coding agent, while building.
Runtime files	Runtime tab	Belong to the agent but live on a rail — dev or live. Not versioned by publish.	Workflows (via the agent-file nodes), the agent itself at runtime.
Conversation files	Conversation tab	Belong to one conversation.	The conversation: the agent, attachments, workflow tools running in it.

The rules that follow:

• Publishing freezes knowledge, not runtime. Editing a knowledge file changes the draft; live agents see it only after the next publish. Runtime files are the opposite — live immediately, on their rail, no publish involved.
• Workflows write runtime and conversation files only — on the rail the execution ran on. A workflow can never create or modify knowledge files.
• A conversation file can be promoted to the agent level when something produced in one conversation should become durable — that is the only bridge between the surfaces; nothing is promoted implicitly.
• Created-file types are limited to txt, csv, html, json, md, xml — and only txt and md support appending.

cai agent files <agentId>                 # list; filter by space
cai agent add-file <agentId> --file playbook.md --name "Playbook"   # knowledge (draft)

The pattern that makes this all useful

Have workflows write compact, structured context into runtime files instead of returning raw API payloads to the model: a daily pipeline summary, the current on-call roster, yesterday’s ticket digest. The agent reads a small, curated file instead of burning context on raw JSON — and the file updates on live rails without republishing anything.

Example prompts

Add a scheduled workflow that writes a daily "pipeline summary" runtime file for this agent, and update the instructions to read it before answering pipeline questions.

This conversation produced a great objection-handling doc. Promote it to the agent's knowledge files and publish so live users get it.