box ai agent

box-ai-agent

Create, update, or invoke a persistent Box AI Studio agent. The "memory librarian" persona has locked instructions ("answer only from indexed memory, cite file IDs, never speculate"). Audit-friendly for regulated environments.

Tier: Enterprise Advanced only — AI Studio is gated to that tier. The skill auto-checks via box-tier-detect and surfaces a clean message otherwise.

Usage

/box-ai-agent <create|update|invoke|delete|status> [args]

Subcommands:

• create [--name=<n>] — create the memory-librarian agent
• update [--name=<n>] — update config (instructions, model, etc.)
• invoke --question="..." — ask the agent
• delete --name=<n> — remove the agent
• status [--name=<n>] — show current config + live drift detection

Default agent config

name: box-memory-librarian-<workspace_name>
type: ai_agent_ask
ask:
  model: <from settings.ai_model or default GPT-5 mini>
  system_message: |
    You are the memory librarian for the <workspace_name> agent-memory workspace.
    Your role: answer questions strictly from the indexed memory files.
    Cite the source memory ID and title for every fact in your answer.
    If you cannot find an answer in the indexed memories, say so explicitly —
    do not speculate, do not generalize, do not invent. Refuse to discuss
    content outside this workspace.
  prompt_template: "{user_question}"
  temperature: 0.2
  include_citations: true
access_state: enabled

Locked instructions are the whole point — behavior is consistent across users and audit-friendly.

Live config drift detection

status subcommand compares workspace-cached config against Box AI's live config. If an admin changed the agent in Box's UI but the plugin's cached copy is stale, surfaces the drift and offers to re-sync.

When to use

• Regulated workflow needing consistent agent behavior across users
• Multiple users querying the same workspace need locked guardrails
• Org compliance requires AI access controls (locked model, locked prompt, locked scope)

When NOT to use

• Tier below Enterprise Advanced — use box-ai-recall instead (Business+)
• One-off ad-hoc Q&A — box-ai-recall is simpler
• You want varied prompts — AI Studio's strength is locking

AI Unit cost

Each invocation consumes AI Units like /ai/ask. Enterprise Advanced gets 20,000 units/month default — see Box AI Units.

Don't

• Don't create without locked guardrails — defeats the purpose
• Don't delete an agent other teams might use without confirming
• Don't weaken the "cite or refuse" system prompt
• Don't invoke a disabled agent (access_state: disabled) silently — surface

See also

• Box AI Integration — broader context
• Box AI Units — cost model
• box-ai-recall — per-call alternative
• Source: skills/box-ai-agent/SKILL.md