Custom Actions

A Custom Action is one HTTPS request to your system, such as “create a job” or “look up an order”. You build it once in Crulon, use it in a Tool, and attach the Tool to an agent. The agent then calls your API while the caller is on the line.

Where: Build > Custom Actions
Plans: 3 on Starter, 10 on Pro, 25 on Scale: your plan’s Custom Tools limit. Versions of one Action share a place; drafts and deleted published Actions count.
Your API: HTTPS, JSON responses

How it fits together

Custom Action: the request itself, with its parameters and credential.
Tool: built in Build > Tool Builder. A Tool runs one or more Actions, with conditions, and has the description the agent reads to decide when to use it. See Give your agent Tools.
Agent: attach the published Tool under Business Tools.

The agent reads the Tool’s description and instructions, not the Action’s. Write the Tool’s description for the agent, and the Action’s for your team.

Create an Action

Open Build > Custom Actions and select Create Custom Action.

Field	What it does
Name	Permanent ID: lowercase letters, digits, underscores and dots
Version	`MAJOR.MINOR.PATCH`
Kind	READ fetches data; WRITE changes something
Parameters	The values the agent fills in. Each has a type, whether it’s required, and where it goes: body, path, query or a header
Method and URL	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`. Use `{name}` in the path for path parameters
Credential	How the request is signed (see below)
Allowed domains	Limit the hosts this Action may call
Static params	Values you fix that the agent can’t see or change, such as an account ID
Timeout	Up to 30 seconds; 10 seconds if you leave it blank
Response fields	Which parts of your response the agent gets. Leave empty to pass the whole response

The request

When the agent runs an Action, Crulon sends your API a JSON body. Under Request body in the editor, choose how it’s shaped:

Envelope (the default) wraps the agent’s values in parameters, next to the Action’s name and version and details of the call. Choose it when you’re building an endpoint for Crulon: one endpoint can handle several Actions by reading action_name.
Flat sends only the agent’s values, with the call details in headers. Choose it when you’re calling an API that already exists and expects a plain body, such as a booking or field-service system.

The arguments sit inside an envelope with the Action’s name and version, and who ran it, when:

JSON

{
  "action_namespace": "tenant:4821",
  "action_name": "create_job",
  "action_version": "1.0.0",
  "parameters": {
    "customer_phone": "+15550100123",
    "issue": "No heat upstairs"
  },
  "call_context": {
    "tenant_id": "4821",
    "action_id": "9f1c2d7e-3b4a-4c8e-9d21-6a5b0c7e8f10",
    "actor": "agent:118",
    "invoked_at": "2026-10-17T14:05:12.481Z"
  }
}

Field	What it is
`action_namespace`	Your workspace’s namespace for Custom Actions
`action_name`, `action_version`	The Action and the published version that ran
`parameters`	The values placed in the body, by parameter name. Values placed in the path, query or a header are sent there instead
`call_context.tenant_id`	Your Crulon workspace
`call_context.action_id`	The Action’s ID
`call_context.actor`	Who ran it, as `type:id`: `agent`, `user`, `app` or `system`, for example `agent:118`
`call_context.invoked_at`	When it ran, in ISO 8601

Requests with a body are sent as application/json. GET and DELETE requests carry no body.

Static params you set on the Action are merged in last, so they replace anything the agent supplied for the same name. Use them for values the agent must never choose, such as an account ID.

Credentials

Save credentials in Build > Custom Actions > Credentials. Once saved, a credential is never shown again; to change one, delete it and create a new one.

Type	Sent as
Bearer token	`Authorization: Bearer <token>`
API key	Your key in a header you name, such as `X-Api-Key`, with an optional prefix
Basic auth	`Authorization: Basic <username:password>`

A credential can have its own allowed domains, so it’s only ever sent to your hosts. Don’t put secrets in Extra headers: use a credential.

Limits

Limit	Value
Protocol	HTTPS only
Addresses	Private, local and internal network addresses are blocked
Redirects	Not followed
Timeout	30 seconds at most
Response	JSON only, up to 64 KB. A top-level array arrives under `results`
Calls	100 a minute per workspace, 50 a minute per Action
Retries	None. A failed call is not repeated

Test it

Select Run test in the Test call card. The test sends a real request with your credential and shows what Crulon sent, what your endpoint returned, and what the agent would receive.

The test is the only place you see your endpoint’s real error. It counts towards your rate limit.

Publish

Drafts can be tested but agents can’t use them. Select Publish to make a version available to Tools. Published versions can’t be edited: to change one, create the next version and publish that.

When your API fails

The agent is only told the tool is unavailable; details stay in Crulon’s logs. What the caller hears is set on the agent, per tool, under What the caller hears. If a write times out, the agent says it can’t confirm whether it went through, so your API should be safe to call twice.

Changes that need the caller’s yes

When a Tool changes something, the agent is told to say what it’s about to do and wait for a clear yes before it runs it. It’s the AI that asks, guided by these instructions, so test the wording with Talk in browser before you rely on it. Crulon adds one check: the agent can’t run the Tool until it marks that the caller agreed, and if it tries without asking, Crulon sends it back to ask.

The instruction comes from, in order:

The Confirmation text on the agent’s Tool, under Business Tools.
The Tool’s own confirmation text, from Tool Builder.
Crulon’s default sentence, when the Tool includes an Action marked Destructive.

WRITE Actions are marked Destructive unless you turn it off before you publish; you can’t change it once the version is published. A write that isn’t Destructive, with no confirmation text on the Tool or the agent, runs without asking.

How it fits togetherCopy Anchor Link

Create an ActionCopy Anchor Link

The requestCopy Anchor Link

CredentialsCopy Anchor Link

LimitsCopy Anchor Link

Test itCopy Anchor Link

PublishCopy Anchor Link

When your API failsCopy Anchor Link

Changes that need the caller’s yesCopy Anchor Link