# Autonomous AI Agents

_AI Features_

Define an AI agent in plain English ("every morning, find leads not contacted in 48h and create a follow-up task"). Distinct from the chat-widget AI Agent — this one acts on your CRM, not your visitors.

## Steps
1. Sidebar > Tools > AI Intelligence > AI Agents. Click "✨ New Agent".
2. Modal step 1: name the agent (e.g., "Daily lead follow-up nudge").
3. Step 2: describe what it should do, in plain English. The modal has 4 example prompts you can click to populate. The heavy-tier model compiles your description into a structured plan with target query + actions when you save.
4. Step 3: pick a schedule. Preset cron picker covers Every hour / Every 4 hours / Daily morning / Weekdays 9am / Weekly Monday / etc. Or pick "Custom cron" for arbitrary schedules.
5. Step 4: guardrails. Max actions per run (default 25, max 500). Optional "require approval" — when on, every action queues as a pending AiAction instead of executing.
6. Step 5: optionally limit allowed action types (send_email / send_sms / create_task / create_note / move_stage / add_tag / etc.). Empty = all allowed.
7. Click "Create Agent". The agent's detail page opens with the compiled plan, run history (empty initially), and a "▶ Run now" button to fire it manually.

## Tips
- Action template language: use {{contact.id}} / {{contact.firstName}} / etc. in plan params, and {{now-7d}} / {{now-2h}} for date math in conditions. Resolved per-record at execution time.
- Approval mode (requireApproval=true) creates pending AiAction rows that admins approve in the AI Actions page. Useful for audit-heavy workflows or new agents you don't fully trust yet.
- Per-run cost is bounded by maxActionsPerRun. Each action that calls an AI sub-feature (e.g., a draft_message) consumes its own tokens — keep maxActionsPerRun low until you trust the agent.
- Run history shows every action: type, target, executed/queued/failed status, error message if any. Click any run to expand and audit.
- Competitor Social Monitor template: pick it in "+ New Agent" > Browse Templates > Marketing, enter up to 5 competitor websites, and it runs every morning (7am by default). It checks each competitor's website for changes, their blog/RSS posts, news coverage, and — when your admin has added the keys — new YouTube videos and a web search for their recent public social posts. CRMown AI writes a digest (what happened, why it matters, what to do) from those facts only and emails it to you. It cannot read LinkedIn, Facebook, Instagram or X company pages directly; the digest links to them. The websites you enter become your Marketing > Competitors list (max 5).
- Templates auto-localize: when you open the "+ New Agent" modal, the starter templates (Lead Follow-Up Nudger, Stale Deal Closer, etc.) render in your effective language (User.locale → Org.primaryLanguage). The plain-English description that gets compiled into the agent's plan is also translated, so non-English orgs get a localized brief out of the box. Translations are cached system-wide — the first user to load templates in a new language pays one CRMown AI call; every user after that gets cached results.

## Example
A 12-rep sales team sets up "Every weekday at 9am, find leads with score > 70 and lastContactAt > 5 days ago, create a follow-up task for the assigned rep with subject 'AI: Re-engage <name>'". The agent runs Mon-Fri at 9am, scans ~200 leads, surfaces 14 stale-but-hot ones, creates the tasks. Reps start their day with a curated list instead of guessing. Within a month, win rate on that segment went from 12% to 19%.

## Troubleshooting
- **"Could not parse description" error on create** — The description was too vague for the heavy-tier model to compile (e.g., "be a good agent"), or referenced fields/actions that aren't in the registry. Fix: Use one of the 4 example prompts in the modal as a template. Be specific about WHEN, WHO (filter), and WHAT (action).
- **Agent runs but does 0 actions** — The query returned 0 matches. Either the conditions are too narrow, or there genuinely aren't any matching contacts right now. Fix: Open the agent detail page > Compiled plan section. Verify the conditions match what you intended. Loosen the filter and re-run.
- **"Agent is not active" error on a scheduled run** — You paused the agent but the scheduler fired anyway (rare race condition). The run is short-circuited with no DB write. Fix: No fix needed — it's by design. The repeatable job still exists; the next tick will be skipped too until you reactivate.

## Error messages
- `Invalid cron expression` — Your custom cron isn't valid 5-field format (minute hour day-of-month month day-of-week). Use the preset picker or test with crontab.guru.
- `No valid actions in compiled plan` — The model returned actions that all failed validation (unknown action type, or filtered by allowedActions). Rephrase the description to use clearer action verbs ("send email", "create task", etc.).

## Plans
Included in every plan. Each create / update is one heavy-tier model call (compiles the description); each scheduled run executes the compiled plan (cost scales with maxActionsPerRun + how many of those actions are AI-powered — send_email with AI draft costs more than create_task). Toggleable per-org under Settings > AI Usage > AI Features (key: ai_agents).