Procedures

Procedures give your voice agent focused instructions for specific situations without loading every situation's full instructions into every call. The agent chooses a Procedure from its trigger, loads its content silently while it handles that request, and returns to its normal instructions when the Procedure is complete.

How Procedures work#

Each enabled Procedure has a trigger that describes when it applies and Procedure content that tells the agent what to do.

At the start of a call, the agent receives a small routing catalog containing the key and trigger for every enabled Procedure. It uses semantic matching—the meaning of the conversation, not an exact phrase or keyword—to choose a Procedure. When a caller's request matches, the agent silently activates that Procedure before responding. The internal activation is not announced to the caller.

While active, the Procedure content is appended to the end of the agent's base prompt. It adds situational guidance; it does not replace the base prompt, personality, safety rules, or available tools. When the request is complete or the conversation moves to a different situation, the agent silently stops the Procedure and retains a short internal summary of the request's final state.

Only one Procedure can be active at a time. The agent must stop the current Procedure before starting or resuming another one.

Occurrences and corrections#

Every separate activation of the same Procedure is numbered as an occurrence, beginning with occurrence 1. For example, two unrelated address changes in one call become occurrences 1 and 2.

If the caller later corrects or continues a completed request, the agent resumes that original occurrence instead of creating a new one. The updated final summary replaces the earlier summary. This keeps a correction attached to the request it belongs to and lets Procedure-specific Structured Data consolidate the original and resumed conversation segments into one result.

Quick start#

1. In the Cartra dashboard, open the agent you want to configure.
2. Select Procedures, then choose Add procedure.
3. Enter a Procedure key, display name, trigger, and Procedure content.
4. Turn on Enabled when the Procedure is ready to use.
5. Select Save in the editor. This applies the editor draft to the pending agent configuration; it does not publish the change yet.
6. Select the agent-level Save Changes button to publish all pending agent changes.
7. Place a new test call. Saved changes take effect on the next call, not a call already in progress.

You can select an existing Procedure to edit it, use the arrows to organize the list, toggle it on or off from the list, or delete it. Deleting a Procedure also removes its Procedure-specific Structured Data configuration after you publish the agent changes.

Configure each field#

The order in the dashboard is organizational only. It is not a deterministic routing priority. If two triggers overlap, moving one above the other does not guarantee that it will be selected.

Write effective triggers#

Describe the caller's intent and relevant boundaries, not a list of exact phrases. Include what belongs in the Procedure and, when confusion is likely, what does not.

Good:

The caller wants to update, replace, or correct a mailing or service address on an existing account. Do not use for a new-customer quote.

Avoid broad triggers such as “The caller needs account help.” Broad or overlapping triggers make semantic routing less predictable. Do not put workflow steps, scripts, or variables in the trigger; those belong in Procedure content.

Write effective Procedure content#

Write content as instructions to the agent. Give it the goal, required questions, confirmation rules, decision points, and what counts as complete. Keep universal behavior in the base prompt and include only situation-specific guidance in the Procedure.

Do not tell the agent to announce that it is starting or stopping a Procedure. Activation is intentionally silent. If a step requires a tool, refer to the customer-facing action and the tool behavior already configured for the agent; a Procedure does not create tools or permissions. To give the agent searchable reference documents, configure agent-wide access as described in the Knowledge Base guide.

Address-change example#

The following generic example collects and confirms an address correction without assuming a particular CRM or policy system.

Procedure content:

**Goal**
Help the caller request an address change.

**Steps**
1. Determine which account, policy, or service the caller means.
2. Ask whether the mailing address, service address, or both are changing.
3. Confirm the current address when it is needed to identify the account.
4. Collect the complete new address, including unit number and postal code.
5. Ask for the effective date. Today is {{system__current_date}}.
6. Read back the address and effective date and get explicit confirmation.
7. Use the configured account-update action if one is available. Otherwise,
   explain the next step without claiming the change was completed.

**Completion**
Summarize the confirmed old and new address, affected account, effective date,
and whether the update was submitted or requires follow-up.

Adapt the questions and completion rule to your business. Keep credentials, private tool arguments, and secrets out of Procedure content.

Variables in Procedure content#

Procedure content can use {{system__...}} values supplied by Cartra and any Dynamic Variable already defined on the agent. Triggers cannot use placeholders.

System placeholders#

The supported system placeholders are:

Dynamic Variables#

To use a custom value such as {{account_number}}, first define account_number under Dynamic Variables. A value can come from its default or from a configured tool assignment. The placeholder name must match the definition exactly. Unknown custom placeholders prevent the agent configuration from being saved.

At runtime, an enabled Procedure cannot activate until every custom Dynamic Variable used in its content has a value. If a used custom value is removed while the Procedure is active, Cartra stops that occurrence rather than leaving unresolved instructions active. Updates to a Dynamic Variable—or to the current language—refresh the active Procedure content.

Caller details may not exist at the beginning of every call. Write instructions that tolerate an unavailable caller name, callback number, or phone number, and have the agent ask for information it truly needs.

Prompt Preview#

System Prompt Preview shows the base prompt plus the routing catalog for enabled Procedures. The catalog contains enabled Procedure keys and triggers only. Procedure content is loaded only after a matching situation occurs during a live call, so no Procedure content—active or inactive—appears in Prompt Preview.

Dynamic Variable preview overrides affect Prompt Preview only and are not saved. Because Procedure content is not activated in the preview, use a test call to verify its fully resolved wording and behavior.

Procedures versus Tasks#

Procedures keep the caller with the main agent and temporarily add focused instructions. Tasks hand a conversation to a separately configured task agent with its own instructions, tools, and completion behavior.

An agent cannot have enabled Tasks and enabled Procedures at the same time. Disabled entries can remain saved in either configuration, but at least one side must have no enabled entries before the other can be enabled. If Cartra reports that an existing Task conflicts with a Procedure but the Task is not visible in your dashboard, contact Cartra to have the agent configuration reviewed.

Choose Procedures when the main agent should keep the conversation and only needs situational guidance. Use Tasks when the workflow needs an isolated agent context or a dedicated set of task tools.

Structured Data for Procedures#

Structured Data is optional, asynchronous post-call extraction. It does not change the live prompt and does not add latency to the conversation. See the Structured Data guide for the complete setup, schema, results, and troubleshooting reference.

In the agent's Structured Data settings you can configure:

• Call-wide data, evaluated once against all visible caller and assistant messages in the call.
• Procedure data, evaluated separately for every occurrence of a Procedure whose extraction scope is enabled.

For each scope, turn on Enabled, describe what to extract, and define the fields and types. Select the modal Save, then publish with the agent-level Save Changes button.

Procedure occurrence results are separate. If address_change is activated for two unrelated requests, Structured Data produces occurrence 1 and occurrence 2 independently. If the caller later corrects occurrence 1, Cartra combines the messages from its original and resumed segments into the single occurrence 1 result so the later explicit correction can replace the earlier value.

After processing finishes, open the call in the dashboard and select the Structured Data tab to review the result and any missing, ambiguous, conflicting, or invalid fields.

To send extraction results to another system, configure a post-call webhook and enable Structured Data inclusion. Procedure results identify the Procedure key and one-based occurrence number. See the Post-call webhooks guide for the payload, status, signature, and retry contract.

Authoring practices#

• Give each Procedure one clear business intent.
• Make triggers mutually distinct and include important exclusions.
• Put universal voice, safety, and escalation rules in the base prompt.
• Put only situation-specific steps and completion criteria in Procedure content.
• Tell the agent when to confirm information and when it may claim an action succeeded.
• Refer only to tools and Dynamic Variables already configured on the agent.
• Keep keys stable. Use the display name for wording you may want to change.
• Treat list order as organization, not routing priority.
• Start disabled while drafting, then enable and publish when ready.

Test before publishing broadly#

After selecting Save Changes, place new calls that cover:

1. A clear positive match using wording different from the trigger.
2. A nearby request that should not activate the Procedure.
3. A call that moves from one Procedure to another.
4. Two separate requests that should become two occurrences.
5. A correction to a completed request that should resume the original occurrence.
6. Missing and populated Dynamic Variable values.
7. Every tool action, confirmation, escalation, and completion path named in the Procedure.
8. Call-wide and Procedure-specific Structured Data, including corrected values.

Review the transcript and Structured Data results. Refine the trigger when the wrong Procedure is selected; refine Procedure content when selection is correct but the conversation is not.

Troubleshooting#

The Procedure never activates#

• Confirm Enabled is on and Save Changes was selected.
• Start a new call; existing calls keep the configuration they started with.
• Make the trigger describe the caller's intent in plain language.
• Confirm every custom placeholder is a configured Dynamic Variable with a runtime value.
• Check that enabled Tasks are not preventing Procedures from being enabled.

The wrong Procedure activates#

• Narrow broad triggers and add meaningful exclusions.
• Remove overlap between Procedures that cover similar situations.
• Test with realistic caller wording. Routing is semantic, not deterministic or based on dashboard order.

The agent ignores or contradicts Procedure content#

• Confirm the correct Procedure activated by comparing the conversation with its trigger.
• Put the specific requirement and completion rule directly in Procedure content.
• Remove conflicting instructions from the base prompt or other configuration.
• Verify that any named action or tool is actually available to the main agent.

Changes do not appear in calls#

Selecting Save inside a Procedure or Structured Data editor only applies the draft to the pending agent configuration. Select Save Changes, wait for the saved confirmation, and place a new call.

Structured Data is missing#

• Enable the intended call-wide or Procedure scope and publish with Save Changes.
• A Procedure scope is evaluated only when that Procedure has an occurrence containing visible caller or assistant messages.
• Wait for asynchronous post-call processing to finish, then check the call's Structured Data tab.
• For webhooks, also enable Structured Data inclusion in the post-call webhook settings.

Current limitations#

• Trigger selection is semantic and probabilistic, not a deterministic rules engine or keyword router.
• Dashboard order does not define routing priority.
• Only one Procedure can be active at a time.
• Enabled Procedures and enabled Tasks cannot be used together.
• Procedure content is not displayed as active content in System Prompt Preview.
• Procedures can use only tools and Dynamic Variables already configured on the agent.