Skip to content
Radioso Docs home
Open app

Author a directive

Use a directive when you want the agent to handle one kind of conversation in a particular way. For example: when a customer sounds anxious, slow down, confirm what they need, and do not rush them into a choice. The rule stays separate from the agent’s general persona, so you can see, change, and test it on its own.

A directive steers a reply. It is not a procedure and it does not perform an action. Use the agent’s Profile for a voice or rule that belongs on every answer; use a routine when the request needs a sequence of steps, collected information, or an action such as a Slack post.

In an agent’s Directives tab, choose New directive. Your edits are saved to the agent’s private draft. The draft is the version you test; it becomes part of visitor conversations only when you choose Review & Publish and publish it.

The Directives tab as a list of one-line rows: two directives that each name the situation they apply to, a customized Readable formatting row marked with a layers icon and "Always · using your version", and a collapsed Radioso defaults group below.

The tab lists your rules one to a line: a switch, the rule’s name, and when it applies. Select a row to open the rule in a panel beside the list. The panel shows the full instruction, the priority, and which part of the turn the rule shapes, and it holds the Edit and Delete buttons. A rule the coherence check finds in conflict with another carries a Conflict label, and a banner above the list opens the first of them.

Describe the rule

Give the directive a short Name that helps your team recognize it later, such as Anxious customer. Then choose When this applies:

  • Always applies the instruction to every reply. Use it for a rule that is narrower than the agent’s Profile, but still needs to be visible and independently managed.
  • In a specific situation opens Situation. Describe the circumstance in plain language, such as “the customer sounds worried about a missed delivery.” Radioso matches the situation by meaning, so describe the situation rather than trying to anticipate exact phrases.

In Instruction, say how the agent should reply when the rule applies. Keep it concrete: “Acknowledge the delay, state only what the order data supports, and offer the next useful step.” This is guidance the agent follows, not a message it repeats word for word. Press Enter to break the instruction across lines when a rule reads better as two or three of them; the breaks are part of what the agent reads.

React to answer coverage

Use Answer coverage signal when the rule should apply only after the agent has assessed whether the available workspace evidence answered the request. Choose values such as Partly answered, Unanswered, or Needs clarification, and optionally narrow them by reason. The directive then steers the reply in that same turn. A coverage signal does not change whether citations are valid and does not make a routine run.

Know which rules share the contextual allowance

An Always directive is included on every reply without using the allowance for situation-specific rules. When its dependencies also match, that dependency chain stays with it outside the allowance. This keeps standing requirements in force even when several other directives match the same message.

For In a specific situation directives, Radioso ranks the matches using their confidence and priority. It includes up to eight contextual directives whose combined instructions fit within an estimated 2,400-token allowance. Matches beyond either limit are held back and recorded in the turn trace.

If an expected contextual directive is held back, make its Situation more specific or raise its Priority relative to the rules it competes with. Use Always only when the instruction genuinely belongs on every reply; it is a standing requirement, not a way to win contextual ranking.

Decide how it fits with other rules

Priority orders guidance when two matching directives disagree. It is a best-effort ordering for the agent rather than a way to remove another rule. A blank value is 50. The built-in answer directives are currently ranked at 90 for supported links, 80 for representing the organization, and 60 for concise, readable formatting. Set a whole number from 0 to 100 when your rule needs to land above, between, or below those rules.

Use Replaces when another directive must be absent while this one applies. It removes the selected directive from that reply, which is stronger than priority.

Customize a built-in

The three built-in directives, Readable formatting, Speak as the organization, and Inline source links, wait in a collapsed Radioso defaults group under your rules. Open one to read its instruction. Choose Customize to start a new directive with that built-in already selected in Replaces and its instruction copied into Instruction, so your version begins as an editable copy of the default. Change the words you want, set the name and priority, and save.

A customization that applies Always and replaces only that built-in becomes the built-in’s row in the list, marked with a layers icon in place of a switch. The row reads as the built-in’s title until you give the directive a name of your own; then it shows your name and the built-in it stands in for. Open it to choose which version is in use, Radioso default or Your version. Your text is kept either way, so switching back to the default and forth again loses nothing. When your version is close to the default, the panel sets it against the default’s current text and marks the words you added and removed. Delete your version gives the built-in back to the defaults group.

A customization that applies only in a situation, or one that replaces other rules as well, is a rule in its own right and stays in the list under its own name. The built-in remains in the defaults group, and its panel names the rule that replaces it and when.

Keep something out of the answer

A directive can withhold part of what a visitor asks for. Say your course pages list prices that change every season, and you’d rather the agent never quote one. An Always directive such as “Leave every price and fee out of the answer, even when the documents state them. Point the visitor to the course page and to reception for current prices.” keeps the figures out, while the agent still answers the rest of the question from your documents: the dates, what the course includes, how to book.

The built-in rule for representing the organization (priority 80) asks the agent to state supported facts directly. The two work together: your rule decides what the answer leaves out, and the built-in decides how the agent states what it does say. If a withheld detail still reaches a reply, give your directive a priority above 80.

Check that a reply followed it

Before the agent writes an answer from your documents, it commits, for each directive in play, to what that directive requires of this answer — “leave out every fee; point to the course page and reception”. It writes the answer against those commitments, then grades the finished answer on each one. Choose Flow on the reply and open its compose stage: each directive shows its commitment, its grade, and the agent’s note. A directive the answer was given but returned no grade for is listed under Not graded. The same record is in the turn_trace and test_chat_turn_trace tools on the operator MCP server.

A reply that graded one of its directives as not followed is listed under the Unmet directives chip in Quality → Review, so you can find it without opening every conversation. The chip is opt-in: those replies stay out of the default queue and the Inbox count until you choose it. The grade is the agent’s own judgment of its answer: use it to find replies worth reading, and read the reply before you trust the verdict either way. The reply itself is sent as written.

Directives on a routine turn

While a routine is running, the current step decides what the reply asks for or does. Your directives still apply to that reply, as guidance for how it is said: tone, formality, wording, and what it must not claim. Where a directive would change what the step asks — sending the visitor to reception when the step asks for their email, or pointing them to a fees page when the step asks for their dates — the step wins, and the agent still asks the step’s question. Contact details, phone numbers, and links a directive mentions stay out of the routine’s replies unless the step asks for them. This holds for every step, including one that answers from your documents before it asks its question.

In practice, an Always rule such as “hand accommodation questions to reception” keeps steering open answers, and a booking routine that collects the visitor’s name and email keeps collecting them. The rule needs no carve-out for each routine. When you want a routine to hand off, give it a Hand off ending or a branch that reaches one.

The turn trace names every directive that shaped a routine step. The routine turn’s directive_steering stage carries routineStep: the routine, the step, directivesAppliedAs: "subordinate_to_step_instruction", and each directive’s id and name under steeringDirectives. Read it with test_chat_turn_trace or turn_trace from the operator MCP server.

Turn a rule off

Every authored directive has a switch on its row in the directive list. Turn it off to take the rule out of play immediately, without losing its name, condition, or instruction. This is the fastest way to confirm that a rule is the source of a bad reply before you rewrite it, or to compare an agent’s answers with and without it. A disabled directive stays in the list, dimmed with its switch off, so you can find it and turn it back on. The switch is also at the top of the rule’s panel.

This is different from Replaces, which redirects one specific built-in to your directive rather than switching anything off, and from deleting the directive, which discards the name, condition, and instruction for good. When you are not sure a rule should go away permanently, turn it off first. For a customized built-in, choosing Radioso default in its panel is the same off switch: the default governs again and your version waits.

Add a skill only when it helps answer

Most directives do not need a skill. The instruction is the rule. If a matching reply needs an MCP tool or an extra pass over your knowledge, type # in the Instruction field and select an enabled, agent-selectable skill. A directive can have one such binding: it makes the skill available for the reply when the directive matches. When an MCP tool answers, the agent writes the reply from what the tool returned, in its own voice and the visitor’s language, with your directives applied and links placed on the names they point to. The visitor reads the agent’s answer; the tool’s text is the evidence it is written from. If the skill can’t run or fails on a turn, the agent answers from its other sources without claiming the tool’s results, and the turn’s trace shows why.

Why can’t I bind a Slack, email, webhook, or notify skill?

Those skills act outside the conversation and settle with an action result, not with the text the visitor should see. A directive needs a skill that can produce or inform that reply, so the editor offers MCP tools and knowledge retrieval instead. The message “Acts instead of replying. Use it in a routine step.” is a pointer to the right surface, not an error in your Slack configuration.

For example, if a customer asks for a manager to follow up, create a routine whose activation describes that request. Add a Slack Post step to the routine, then set the routine’s completion message to tell the customer what will happen next. You can also keep a directive for the same situation when its job is to shape the reply — for example, “Do not promise a response time.” The routine posts; the directive steers.

Test and publish the rule

Choose Save draft, then open Test Chat from the agent cockpit and try an example that should match. Inspect the turn’s Directives node to confirm the rule applied and to see how it shaped the answer. Try a nearby example that should not match as well; a specific situation should not accidentally become a standing rule.

Test Chat pins each conversation to the saved candidate you selected. Later draft edits stay private and do not change an earlier test. You can compare the draft with the published revision and run selected eval cases from Test Chat before publishing. Evals help you decide; they are optional, while validation and the explicit publish action are required.

When the rule is ready, choose Review & Publish. Review the directive changes and the test evidence, then publish the candidate you inspected. Keep making edits in the draft after publishing when you want to prepare another change. The published revision is shared by newly started conversations across the agent’s channels; an ongoing conversation keeps the version it started with.

Common failure modes

  • The rule applies too broadly: make Situation describe the customer state or request that should trigger it, rather than a topic word.
  • A built-in rule still affects the answer: use Replaces or Customize if it must be removed; priority only orders competing guidance.
  • A contextual rule matched but did not shape the answer: inspect the turn trace for a count or token-limit reason, then narrow its Situation or raise its Priority relative to the other contextual rules.
  • A rule that keeps something out of the answer was broken anyway: open the reply’s Flow and read the rule’s commitment and grade. When the commitment was right and the answer still broke it, raise the rule’s Priority above the built-in rules it competes with (80 for representing the organization).
  • A rule asks the agent to link a page, and the reply shows the page’s name as plain text: an answer from your documents links only to an address the agent was given in that turn, such as a document’s source URL, the page the visitor is on, your instructions and directives, or the conversation. An email address counts for mailto: links, never for a link to its domain’s website. Put the address in the directive, or give the document a source URL. A link to any other address shows as its text in chat on the web and in the embed, over the chat API and MCP, in email, and in answers from POST /api/v1/retrieval/answer, whoever calls it. On a streamed reply the compose stage counts it as unwrappedLinkCount. Replies that do not answer from your documents, such as a direct reply or a routine’s question, keep the links they are written with.
  • An answer-coverage rule did not run: open Turn diagnostics and check whether coverage was assessed. Older turns and failed assessments have no semantic verdict to match.
  • Slack, email, webhook, or notify does not appear after #: add it as a routine step. It acts, rather than producing the reply a directive needs.
  • A directive’s redirect or hand-off did not happen during a routine: the routine’s step decides what that reply asks for. Edit the step, or add a branch to a Hand off ending, when the flow should stop there.
  • A selected skill is unavailable: enable it and set its invocation mode to Agent selectable, then reopen the directive.
  • Not sure whether a directive is the cause of a bad reply: turn it off with the row switch and retry the conversation, rather than guessing from the instruction text.