Agent Actions

Connect a Searj Bot to your Business-owned HTTPS API for safe queries and explicitly confirmed commands.

Action Designer

The designer is an Arabic-first conversation with the Designer Agent. It starts from the Visitor outcome, asks one adaptive business-language question at a time, and applies safe reversible Draft changes with a concise card for every change. A compact status bar keeps the goal, readiness, and next blocker visible without a step wizard.

The Visitor storyboard opens on demand in a side drawer on larger screens and a full-screen sheet on mobile. Focused technical details for methods, paths, headers, request and response mappings, and tests remain accessible without leaving the conversation.

Draft changes save automatically. Queries require a recent successful safe test before enablement, while Commands require safe connection evidence, a request preview, and complete mappings without sending a real Command from the dashboard. Editing a Live Journey leaves the current release running until its replacement Draft is enabled.

The designer uses one editor lease per Draft to prevent conflicting changes. When another editor holds the Journey, you may review it read-only or explicitly take over. An Owner or Admin can also send a scoped Action Setup Request to a signed-in collaborator, limited to connection, request, mapping, and test work for 1–30 days.

The setup workspace lets the collaborator replace credentials without viewing the existing value, edit technical stage configuration, run safe tests, exchange step-level review notes, and submit changes for review. The collaborator cannot enable the Journey, assign Bots, or access other Journeys, conversations, or analytics.

Connections, credentials, endpoints, mappings, tests, Bot assignments, and enablement remain explicit approvals. The model neither writes Journey JSON nor grants readiness; the Action Journey remains authoritative. Every turn is idempotent and atomic, while cancellation, lease loss, or the 45-second timeout preserves the previous Draft.

You can duplicate the current Journey under a new name. The copy is an independent Draft with the same configuration and internal mappings, without copying assigned Bots, enablement, readiness evidence, conversation history, or approvals, and starts with a fresh recap derived from the Draft.

Setup flow

1. Create a fixed HTTPS connection using an API key or Bearer-based auth credential. Searj masks the credential value after saving.
2. Create a Draft Action, or use the reservation template to add availability Query and reservation Command drafts to the Business library without assigning them to a Bot.
3. Define typed inputs with bilingual validation messages. Give every Enum choice a value plus Arabic and English labels, and map known business rejections only to configured safe messages.
4. Add request and JSON-path response mappings. Only fixed non-secret headers are allowed; Visitor inputs cannot be mapped into headers.
5. Safely test a Query Draft, then validate the Draft, enable its immutable version, and assign it to selected Bots.

Query versus Command

A known Business System rejection may match a JSON path and optional expected value, with a safe audit code, then show only the configured Arabic or English message. Unknown errors remain generic and never expose the raw API response.

Reservation and reliability

• Default timezone is Asia/Kuwait.
• Proposal expiry defaults to 5 minutes and is capped at 15.
• One Command may depend on one Query for option revalidation.
• Command retries reuse the same idempotency key only when the Business System supports it.
• A reservation is not successful without a mapped Business Reference.

Permissions and audit

Owners and Admins control configuration and final enablement, and may revoke Setup Requests or add and resolve review notes. Run audit shows safe mapped outcomes only, while Designer analytics records metadata such as recipe, step, and test outcome without field values, URLs, paths, headers, or samples.