Agentic automation & model providers

Some automations don't just notify — they act. When a deal hits a stage or a contact lands, you can have hdls run a real AI agent that reads the triggering record and makes the right changes through your products' tools. No receiver to host, no key plumbing in your own code: the agent runs inside hdls, scoped to your workspace, and is off until you turn it on.

💬 Just ask

"When a new contact is created, enrich it and open a CRM deal."

"Turn on agentic automation, cap it at 50 runs a day, and use Claude."

"Show me what that agent would do before I enable it."

You don't call these tools by hand — tell your assistant. The reference below is for when you want the details.

`run_agent` vs. waking your own agent

There are two ways an automation can involve an agent — don't confuse them:

	`run_agent` (this page)	`agent` webhook (Triggers)
Runs	Inside hdls (a managed LLM loop)	Your external receiver (a signed POST)
You host	nothing	a `/wake` endpoint
Tools	your products' CRUD, auto-scoped	whatever your receiver does
Model	OpenAI or Claude (you choose)	your receiver's own model
Turn on	`set_agentic_automation` (off by default)	just add the trigger

Use run_agent when you want hdls to do the work for you. Use the agent webhook target when you already run your own headless agent and just want hdls to wake it.

How a `run_agent` automation works

You declare it as a trigger action (create_trigger with a run_agent target — see Triggers, schedules & waking agents for the trigger mechanics). When the rule fires, hdls:

Checks the off-by-default gate — if your workspace hasn't enabled agentic automation, the run is skipped (not failed).
Resolves the model provider and budgets (below).
Builds a toolset from the product schemas you scoped it to — one create / update / search / get / delete tool per table you're allowed to touch — and runs a bounded model⇄tool loop.
Acts through the same tenant-scoped, member-role path as your named product tools, so RLS, grants, and audit all still apply. An agent scoped to contacts + crm physically cannot reach any other product's data.

Each run is logged step-by-step (every model turn and tool call) for audit.

Scoping & safety (always on)

Member role, your tenant only — never owner/admin, never another workspace.
Scoped to the products you name — a tool call outside the granted scopes is refused.
Bounded — step cap, wall-clock timeout, and a recursion-depth cap so an agent can't loop forever or spawn agents without limit.
Idempotent — the same record transition won't be re-run.

Turning it on — `set_agentic_automation`

Owner only. Agentic automation is OFF by default; nothing runs until an owner opts in. You can also set safety budgets and the default model provider in the same call. (In the console, this is the Agentic automation page under Admin.)

Field	Meaning
`enabled`	The opt-in. `false` (default) = no `run_agent` action ever fires.
`paused`	Instant kill switch — halt runs while keeping the opt-in.
`default_provider`	`openai` or `anthropic` (Claude). `null` = platform default (OpenAI).
`max_runs_per_day`	Daily agent-run cap. `null` = unlimited.
`max_run_tokens`	Per-run token ceiling. `null` = unlimited.
`max_concurrent_runs`	In-flight agents per workspace. `null` = unlimited.

Over-budget runs are skipped, not failed. Read the current state any time with get_agentic_automation (any role).

// tool: set_agentic_automation   (owner only)
{ "enabled": true, "default_provider": "anthropic", "max_runs_per_day": 50, "max_run_tokens": 20000 }

Choosing the model provider

run_agent can run on OpenAI or Anthropic (Claude). The effective provider for any run is resolved in this order:

the rule's own provider   →   your workspace default_provider   →   platform default (OpenAI)

Set the workspace default with set_agentic_automation (default_provider), or on the console Agentic automation page.
Override per rule by setting provider on the run_agent action when you create the trigger — handy when one workflow wants Claude and another OpenAI.
The chosen provider's API key must be configured on the server (OPENAI_API_KEY / ANTHROPIC_API_KEY). If it isn't, the run skips gracefully with a clear reason — it never errors the workflow.
You can also pin a specific model per rule; otherwise each provider uses its default (a small, fast model).

Switching providers changes nothing else — the same scoped tools, budgets, RLS, and audit apply. Only the model behind the loop changes.

Preview before you trust it — `explain_agent`

See exactly what an agent would do — without running it or paying a cent. explain_agent returns the resolved system prompt, the exact namespaced toolset and scopes, the resolved provider, and whether the gate would skip it.

// tool: explain_agent
{ "skill_id": "enrich-and-open-deal", "scopes": ["contacts", "crm"], "provider": "anthropic" }

Audit — what did the agents do?

list_agent_runs — recent run_agent runs for the workspace: status, timing, how many model turns + tool calls each made (optionally filter by rule_id).
get_agent_run — one run's full transcript: each model turn and each tool call with its result.

Both are read-only (admin+).

Limits & gotchas

Off by default — an owner must set_agentic_automation { enabled: true }.
Provider key required — selecting Claude without ANTHROPIC_API_KEY set (or OpenAI without OPENAI_API_KEY) makes runs skip, not fail.
Budgets skip, they don't fail — an over-cap or over-concurrency run is recorded as skipped and retried on the next sweep where applicable.
Scopes are required — a run_agent action must name at least one product schema; it can only act within those.
Same ~1 minute latency / at-least-once as all triggers — see Triggers, schedules & waking agents.

Agentic automation & model providers

run_agent vs. waking your own agent

How a run_agent automation works