Building an agent

An agent is a conversational operator: it holds context, reasons about requests, and calls the tools you attach — nothing else. You control the guardrails; the agent controls the judgment. This page covers assembling one; publishing and sharing have their own pages.

What an agent is made of

Part	What it does
Instructions	The standing brief: role, tone, rules, when to use which tool.
Tools	Integration actions and workflow tools, each with its own approval policy.
Knowledge files	Reference documents the agent can read — playbooks, policies, product docs. Frozen into each published version. In the app they live on the agent’s files under the Reference tab.
Conversations	Test conversations (run the draft) and Live conversations (run the latest published version), each with its own files and history.

Plus housekeeping: an enabled state, visibility (private or organization), and labels for organizing the agents list.

One thing an agent deliberately does not contain: a model. The model is a per-conversation runtime choice made in the chat composer (or --model on cai agent test / conversation create) — it is not agent configuration and is not part of a published version.

The build loop

cai agent create --name "Customer follow-up"
cai agent update <agentId> --instructions-file instructions.md
cai agent add-action <agentId> --integration hubspot --action create-note ...
cai agent add-workflow <agentId> --workflow <workflowId> --flow <flowId> ...
cai agent add-file <agentId> --file playbook.md --name "Playbook"
cai agent test <agentId> --message "..."      # a Test conversation against the draft

Everything above edits the draft — private, mutable, invisible to your organization. Test conversations use the draft, the current knowledge files, and attached workflows’ development heads — and they read and write the workflows’ development data stores. Nothing reaches teammates or live users until you publish.

Inspecting results: a direct integration action produces an action run inside the conversation; a workflow tool additionally produces a workflow execution with full node-level detail (cai exec tree).

Writing instructions that work

• Name the tools and when each applies — the agent routes better when instructions describe the same boundaries the tools enforce.
• Put policy in instructions, facts in knowledge files. Instructions say “always check the refund policy first”; the policy document is a knowledge file.
• Keep tool descriptions specific (capped at 280 characters): “Create a follow-up note on the contact after a call” beats “CRM tool”.
• Don’t restate what the platform enforces. Approval gates, connection scoping, and version rails hold whether or not the instructions mention them.

Agents and workflows, both directions

Agents call workflows as tools — and workflows can drive agents: native nodes exist to create an agent conversation, send a message into one, send Slack as the agent, and create or update agent files. That closes useful loops: a scheduled workflow can push a daily brief into an agent’s runtime files, or open a conversation when something needs judgment. Workflow-authored files land in the agent’s Runtime files on the rail the execution ran on — a workflow can never write knowledge files.

Example prompts

Create a private support-triage agent: one action to create CRM notes (approval on), our escalation policy as a knowledge file, and instructions that route billing issues to escalation. Test it with three realistic tickets. Don't publish.

Review this agent's instructions against its attached tools and flag anything the instructions promise that no tool can do.