AI Agents

The ai-agents and ai-agent commands mirror the /ai-agents page and its per-agent detail view. From the terminal you can run the full agent lifecycle (create / update / delete), flip the default agent, and manage each agent’s knowledge base.

Backed by /api/v1/app/ai-agents/*. Every call uses your stored oc_live_ token.

Quick start


# 1. Create a support agent
splashify ai-agent create \
  --name "Support bot" \
  --agent-type support \
  --channel whatsapp \
  --industry retail \
  --role "Customer support agent for our online store" \
  --goal "Resolve order, shipping and return queries on the first reply" \
  --instructions "Always confirm order ID before quoting status. Escalate to a human if frustrated."
 
# 2. Make it the default agent
splashify ai-agent set-default <agent_id>
 
# 3. Upload knowledge (PDF / DOCX / MD / TXT — max 15MB)
splashify ai-agent knowledge <agent_id> upload ./returns-policy.pdf
 
# 4. Tune it
splashify ai-agent update <agent_id> \
  --temperature 0.3 \
  --processing-msg true \
  --processing-msg-text "Looking that up for you…"

Command tree


ai-agents                           list all agents
ai-agent <agent_id>                 show one
ai-agent create                     POST a new agent
ai-agent update <agent_id>          sparse PUT (only flags you pass)
ai-agent delete <agent_id>          DELETE
ai-agent set-default <agent_id>     promote to default
ai-agent unset-default <agent_id>   demote
ai-agent knowledge <agent_id>
  ├── list                          (default — list knowledge files)
  ├── upload <file>                 multipart upload
  └── delete <file_id>              remove

Channel types

Agents can run on one of two channels:

`--channel`	What it drives	Extra gates
`whatsapp` (default)	Replies on WhatsApp conversations	None — works on any active plan
`instagram`	Replies on Instagram DMs	Plan must have `instagram_automation_enabled` AND the account must have an IG connected via `splashify instagram connect`. The backend returns 403 with code `ig_bot_blocked` otherwise.

Creating an agent


splashify ai-agent create \
  --name "Sales qualifier" \
  --agent-type sales \
  --channel whatsapp \
  --industry "B2B SaaS" \
  --use-case lead_qualification \
  --role "Qualify inbound leads via 3 short questions" \
  --goal "Capture company name, team size, and use-case in under 6 messages" \
  --instructions "Be concise. If unclear, ask one clarifying question, then summarise and hand off."

Backed by	`POST /api/v1/app/ai-agents`

Flag	Required	Notes
`--name`	yes	Display name
`--agent-type`	yes	Free-form tag, e.g. `support`, `sales`, `lead_qualification`
`--channel`	no	`whatsapp` (default) \| `instagram`
`--industry`	no	Industry tag for routing/analytics
`--use-case`	no	Specific use-case tag
`--role`	no	Single-paragraph role description
`--goal`	no	One-sentence goal
`--instructions`	no	System-prompt body (any length)

Updating an agent

update is a sparse PUT — only fields you pass are sent, the rest are preserved. This is intentionally different from canned/waba/attribute updates (which use the load-modify-write pattern); the agents endpoint accepts pointers for every editable field.


# Change the goal
splashify ai-agent update <id> --goal "New goal here"
 
# Tune the LLM
splashify ai-agent update <id> \
  --ai-provider anthropic \
  --ai-model claude-sonnet-4-6 \
  --temperature 0.3
 
# Enable inbound-image OCR and a processing-message bubble
splashify ai-agent update <id> \
  --image-recognition true \
  --processing-msg true \
  --processing-msg-text "On it — give me a moment…"
 
# Pause an agent
splashify ai-agent update <id> --status paused

Flag	Notes
`--name`	New display name
`--role`	role_description
`--goal`	goal
`--instructions`	system-prompt body
`--status`	typically `active` or `paused`
`--tone`	tone tag, e.g. `friendly`, `formal`
`--assign-to`	`team_member_id` to escalate handoffs to
`--ai-provider`	`anthropic` \| `openai` \| `gemini`
`--ai-model`	provider-specific model id
`--temperature`	float 0.0–1.0
`--processing-msg`	`true` \| `false`
`--processing-msg-text`	text shown while the agent is thinking
`--image-recognition`	`true` \| `false`

Default agent

Only one agent at a time can be the default — the one that takes incoming conversations when no other routing rule fires.


splashify ai-agent set-default <agent_id>
splashify ai-agent unset-default <agent_id>     # clears it; nothing replaces it automatically

Knowledge base

Each agent has its own knowledge base — files the agent can cite when answering. Accepted formats: .pdf, .docx, .md, .txt. Max file size: 15MB (enforced server-side).


# List files
splashify ai-agent knowledge <agent_id>
splashify ai-agent knowledge <agent_id> list
 
# Upload
splashify ai-agent knowledge <agent_id> upload ./returns-policy.pdf
splashify ai-agent knowledge <agent_id> upload ./faqs.md
 
# Delete
splashify ai-agent knowledge <agent_id> delete <file_id>

Backed by	`GET /api/v1/app/ai-agents/:agent_id/knowledge`
	`POST /api/v1/app/ai-agents/:agent_id/knowledge` (multipart, field `file`)
	`DELETE /api/v1/app/ai-agents/:agent_id/knowledge/:file_id`

Common workflows

Bulk-import a folder of knowledge files


AGENT=<agent_id>
for f in ./kb/*.{pdf,docx,md,txt}; do
  [ -f "$f" ] || continue
  splashify ai-agent knowledge "$AGENT" upload "$f"
done

Snapshot an agent’s full config to JSON (for backup or cloning)


splashify ai-agent <agent_id> > agent-backup.json
splashify ai-agent <agent_id> knowledge > agent-backup.kb.json

Pause every agent


splashify ai-agents | \
  jq -r '.agents[] | .agent_id' | \
  xargs -I{} splashify ai-agent update {} --status paused

Find which agent is current default


splashify ai-agents | \
  jq '.agents[] | select(.is_default) | {agent_id, name, channel_type, status}'

Wipe and re-upload the knowledge base


AGENT=<agent_id>
splashify ai-agent knowledge "$AGENT" | jq -r '.files[].file_id' | \
  xargs -I{} splashify ai-agent knowledge "$AGENT" delete {}
 
for f in ./kb-v2/*; do
  splashify ai-agent knowledge "$AGENT" upload "$f"
done

Troubleshooting

HTTP 403 ig_bot_blocked on Instagram channel — plan doesn’t include instagram_automation_enabled or no IG account is connected. Run splashify subscription and splashify instagram to confirm.

Knowledge upload returns 400 “unsupported format” — only .pdf, .docx, .md, .txt are accepted. The CLI validates this client-side before the round-trip, but if you bypass with splashify api, the backend returns the same 400.

temperature flag clamped — the backend clamps to [0.0, 1.0]. The CLI sends whatever you pass; values outside the range are silently clamped server-side, no error.

Agent stopped replying after set-default — there can only be one default at a time. Setting a new default automatically unsets the previous one. The previous agent isn’t deleted, just demoted — splashify ai-agent update <previous_id> --status active keeps it available for explicit routing rules.