Docs

Help desk / Teach the agent

Runbooks

Tell the agent how to handle a kind of request: when the runbook applies, the steps to follow and the tools to use

A runbook tells the agent how to handle one kind of request. It has two parts:

  • A match condition that decides which tickets the runbook applies to.
  • Agent instructions: the steps the agent follows, in plain language, with the tools, forms and knowledge it can use.

Runbooks are how you give the agent a standard procedure for a request type, and the tools to carry it out.

To see it in action first, watch How runbooks work, with three examples, a three-minute video.

How runbooks are matched

Each runbook has one of three match types. You choose it under Match condition in the editor.

Match typeWhen the runbook applies
Request matchThe request text matches a description you write. This is the default.
Department requestEvery ticket assigned to the runbook's department. A department can have only one runbook of this type.
NoneNever matched. A system attaches the runbook to a ticket by its ID: pass the ID as runbook_id when you create the ticket. The runbook's page shows the ID.

When a ticket is created, Risotto:

  1. Analyzes the request.
  2. Finds the runbooks that match it.
  3. Gives the agent the matched runbooks' instructions and tools.
  4. Lets the agent decide whether to follow a runbook and use its tools.

Matching vs. relevance

A ticket's side panel lists the runbooks that matched it under Runbook (or Runbooks). Each one links to the version that matched, shown as "Title (vN)".

  • Green check: the agent followed the runbook.
  • No check ("Matched but not applied"): the runbook matched, but the agent judged it not relevant to this request.

If a runbook keeps matching but never gets the check, tighten its Description or narrow its scope rather than forcing the agent to use it. Matching runs on the full request text, not a summary of it, so describe requests the way people actually write them.

Knowledge search vs. runbooks

Every ticket gets a knowledge search: the agent retrieves the passages most similar to the request as the requestor wrote it. That is best-effort retrieval. If the request is phrased differently from the article, or several articles are close, the right page can be missed even though it is indexed, and there is nothing that forces the agent to apply a particular policy.

A runbook is the deterministic layer on top. When it matches, the agent receives your instructions and tools for that kind of request every time, and a knowledge directive can pin the one authoritative source. Use a runbook whenever a request type has a policy the agent must always follow (an exception process, a required approval, a specific form), and rely on search alone for general how-to questions.

Create a runbook

  1. Open the editor

    Go to Runbooks and click Create runbook, beside the Search runbooks box. The list groups runbooks by department, with Org-wide first.

    To start from a template instead, click Browse templates, open a template and click Use this template. The editor opens with the template filled in. The button is available once the template's tools are enabled and configured in your organization. The HR group has time off and home address templates for Workday, BambooHR, HiBob, and Rippling. See Workday, BambooHR, HiBob, and Rippling.

  2. Set the title and match condition

    Enter a title that says what the runbook handles. Under Match condition, keep Request match and describe in the Description box when the runbook should be used (see Writing the description). In the side panel, choose the Department the runbook belongs to.

  3. Write the agent instructions

    Under Agent instructions, write the steps the agent follows. Type # to insert a tool, @ to mention a person or a group, and / for formatting. Each tool you insert gets a row in the Tools card below.

  4. Save the runbook

    Click Save. Risotto shows "Runbook created successfully" and opens the runbook's page. A new runbook is saved turned off.

  5. Turn it on

    On the runbook's page, turn on the Enabled switch at the top right. The agent only uses enabled runbooks.

    If the runbook uses a tool that is turned off, the page shows References disabled tools, and you can't turn the runbook on until those tools are enabled.

You can also ask the Assistant to write a runbook. Describe the procedure in plain English, or paste your standard operating procedure, and the Assistant creates the runbook. An external AI agent can do the same through the Risotto MCP server, with the runbooks:write scope.

Runbook commands

On a runbook's page, press ⌘K (Ctrl+K on Windows and Linux) to see the commands for that runbook. On the Runbooks page, right-click a runbook's row, or click its ⋯ menu, to see the same commands:

  • Edit runbook (shortcut e)
  • Test runbook match…: opens the Test Runbook Match dialog, where you type a request and see whether this runbook matches it. It shows only for runbooks with a Request match condition.
  • Duplicate runbook: makes a copy of the runbook and opens it.
  • Disable runbook or Enable runbook. Enable runbook does not show while the runbook uses a disabled tool.
  • Delete runbook…: asks you to confirm in the Delete runbook? dialog. You cannot undo a delete.

You see these commands only for runbooks that you can edit: as an Org Admin or Manager, or as a Supervisor of the runbook's department.

Writing the description

The Description is what the request is matched against. Say when the runbook applies. Be specific, but you don't have to be exhaustive. For example:

  • "A user asks for a Slack channel to be created"
  • "Someone needs to onboard a new employee"
  • "There's a report of a hardware issue with Apple products such as MacBooks or iPhones"

See Writing effective descriptions for what makes matching work well.

Writing the instructions

Write numbered steps that tell the agent what to do:

1. If the user hasn't provided a name, ask them for the channel name.
2. Ask if the channel is for a team or a project, if this information is not provided.
3. If the channel is for a team, make sure the channel name starts with "team-". A project channel starts with "project-".
4. Ask if the channel should be public or private, if it's not clear from the request.
5. Use [Manage Slack Channels] to create the channel.
6. Resolve the ticket.

Using tools in runbooks

Tools let the agent act, not just answer. To insert one, type # in the instructions, or click Tool in the editor's toolbar, and pick it from the list. The list starts with your knowledge sources (see directives), then your tools by platform.

  • Only referenced tools are available. The agent gets the tools that the runbook inserts, nothing else. If you type a tool's name as plain text, the agent does not get that tool. Core tools are always available and need no reference.
  • Up to 10 tools. A runbook can use at most 10 tools, not counting core tools. Using the same tool more than once (for example, with different arguments) counts as one. The picker shows how many you have used, and Risotto won't save a runbook with more. Forms don't count.

Org Admins choose the approval policy for a whole runbook under Approval in the editor's side panel, or for one tool with the Approval select on its row in the Tools card.

Setting a tool's arguments in advance

Each tool you insert gets a row in the Tools card, below Agent instructions, with a pill for every argument the tool takes. For each argument you decide who supplies the value:

  • Set by author: click the argument's pill and enter a value. The agent never sees or changes this argument; Risotto merges your value into the tool call at run time.
  • Set by agent: leave the pill empty (it reads "Agent decides"), or click Let the agent decide in the pill to clear a value. The agent fills the argument from the conversation.

Use this to lock down the parts of a call that should never vary, such as the Slack channel a message is posted to, the group a user is added to, or a flag that must always be set, while leaving the requester-specific parts to the agent. To call the same tool with different fixed values in different steps, insert it more than once; each reference has its own arguments.

Referring to the ticket in a tool call

The agent that runs a runbook knows the references of the current ticket. When a step needs one of them in a tool argument, the agent copies the value exactly. The agent knows these values when they exist:

  • The Risotto ticket ID.
  • The linked ticket in your ticketing system, for example a Jira key, and its URL. This value exists only when the ticket is already synced to that system.
  • The Slack thread of the ticket: the channel ID and the thread timestamp. This value exists only for tickets that start in Slack. It is the thread where the requestor posted the request, or the DM after the request moves to a DM. It is not the thread of the ticket card in the agent channel.

For example, a step can say: "Post weigh <linked Jira key> in this ticket's Slack thread with Send Slack Channel Message." Tell the agent which reference to use. The agent mentions the linked ticket to the requestor only when the runbook tells it to.

Collecting structured input with forms

When a step needs several details from the requester at once (a new hire's name, start date and department; the specifics of an equipment order), attach a form instead of writing a chain of clarifying questions. The agent presents the form as an interactive Slack form or Microsoft Teams card (or collects the fields conversationally on other channels), then continues the runbook with the answers.

Forms are in the Forms card below the instructions: click Add form to build one, or Insert existing form to reuse one shared by other runbooks. The form is inserted into your instructions as a chip. Place it in its own step, for example "Collect the request details with [form]."

See Runbook Forms for field types, how requesters experience the form, and limits.

Steering knowledge with directives

Knowledge directives are rules you attach to a runbook that control which indexed knowledge the agent is allowed to read on tickets the runbook applies to. Use them when a runbook should rely on one authoritative source, or when a source should never be used for a particular kind of request.

Directive modes

ModeWhat it does
Only useWhen the agent follows this runbook, it reads only the document or sources you pin. If they don't hold the answer, the ticket is escalated to a person.
Never useWhen this runbook matches, the agent never reads that source. Answers and citations can't come from it.

Adding a directive

  1. Open the directive dialog

    In the runbook editor, click Add directive under Knowledge in the side panel. The Add knowledge directive dialog opens.

  2. Choose a mode

    Select Only use or Never use. The dialog opens on Only use each time.

  3. Pick the source

    Search your indexed sources and select one. For Only use, you can instead pin a single document under Or pin one document by pasting the page's URL. The page must already be in one of your organization's indexed sources. A knowledge base article can be pinned the same way. For a Confluence Cloud page, any link to the page works: the address bar URL, the short link from Copy link (/wiki/x/...), or an edit link. Risotto matches the page by its page ID. The page must be indexed, and the runbook's department must be able to read it. If no indexed page matches, the dialog shows "No indexed document this runbook can read has that URL."

  4. Add it

    Click Add directive. The directive is inserted as a chip at the end of your instructions. Move it into the relevant step if you like.

You can also type # in the instructions. The picker lists your sources under Only use first, then Never use. Select a source to insert its directive chip where you typed.

Testing matches with saved matches

Saved Matches keeps a set of example requests for a runbook, each marked as one that should or should not match, and runs them against live matching. Use it as a reusable checklist for your Description: change it, run the tests again, and see what still matches.

To try a single request without saving it, click Test Match in the same place.

  1. Open Saved Matches

    On the runbook's page, click Saved Matches under Actions in the side panel. You see it if you can edit the runbook.

  2. Add example requests

    Click Add test and enter a request the way a user would phrase it, for example "I need access to the prod database." You can save up to 20 tests per runbook.

  3. Set the expectation

    For each test, choose should match or should not match under Expected. Include both kinds: requests this runbook should catch, and similar requests it should leave alone.

  4. Save and run

    Click Save & Run. Risotto saves your tests and runs each one against current matching. Each result appears under Actual, with a summary such as "4 of 5 passed" above the table.

Reading the results

  • Green check: the result agreed with your expectation (the test passed).
  • Red mark: the result disagreed with your expectation (the test failed).
  • matched / did not match: whether this runbook matched the request.
  • When a request matched other runbooks instead, hover the info icon to see which. This shows when another runbook is taking requests you meant for this one.

When you reopen the dialog, it shows your last results. Changing the runbook's title or Description clears them, because they were measured against the old wording. Run the tests again to see how your change affected matching.

Saving a new version

When you Save a change to the title, match condition or instructions, Risotto shows the current version beside your change and creates a new version of the runbook when you click Create Version (for example Create Version v3). Changes to other settings, such as whether the runbook is enabled, its department, its approval policy or a tool's set arguments, are saved without a new version.

Reviewing changes with drafts

Rather than publishing edits straight away, you can propose them as a draft: one proposed revision that waits for someone to review and publish it.

Saving a draft

In the editor of an existing runbook, click Save as draft instead of Save. This stages your title, match condition, instructions and knowledge directives as a proposal without changing the live runbook. Each runbook has at most one open draft; saving again updates it.

Reviewing and publishing

When a runbook has a draft, its page shows a Pending draft by banner, and the runbooks list marks it Pending draft.

  1. Open the review page

    Click Review changes on the banner.

  2. Read the changes

    Each changed field (Title, When and Then) is shown as a diff against the live version, marked as added, cleared or reworded. To check matching before you publish, click Run against draft on the saved match tests, or Test Draft Match in the side panel.

  3. Approve or reject

    Click Approve to publish the draft as a new version of the runbook, or Reject to discard it. When you reject, you can add a reason for the person who proposed it.

Editing a runbook that has a draft

Opening the editor on a runbook with a draft loads the draft, so you pick up where the proposal left off, and a banner says who proposed it. To change the live runbook instead, click Edit the live version instead.

Restoring an earlier version

Each time you publish a change, Risotto saves a new version of the runbook. You can restore an earlier one from the version history.

  1. Open the version history

    On the runbook's page, click History beside Version in the side panel. The button appears once the runbook has more than one version.

  2. Open the version

    Click the version you want to restore. To see what changed between two versions first, choose them beside Compare and click View changes.

  3. Restore it

    Click Restore this version, then Confirm. Risotto shows "Version N restored as vM" and opens the runbook.

  • A restore publishes the earlier version's title, match condition and instructions as a new version. The version that was current stays in the history, so you can restore it later.
  • The runbook keeps its current enabled state, match type, department and tool settings.
  • Restore this version doesn't appear on the current version, and Risotto refuses a version identical to the current one.
  • Org Admins and Managers can restore any runbook. A department Supervisor can restore the runbooks of their own departments.

Best practices

Writing effective descriptions

Descriptions are matched semantically against the full request text. Describe what the user is asking for, in the words they actually use.

Lead sentence + example phrases. A short sentence followed by 3–6 quoted user phrasings matches better than a dense paragraph.

✅ Do:

The user is reporting an issue with a Zoom Room or conference room AV equipment.

Examples:

- "Zoom Room is down"
- "TV in [room] won't turn on"
- "Can't start a meeting in the boardroom"
- "Conference room mic isn't working"

✅ Put key terms first. Matching weighs the start of the description more. Moving distinctive terms (for example "leave / OOO / bereavement") to the front improves matching.

❌ Don't put instructions in the description. Text like "Do not assume the user is a manager unless explicitly stated" doesn't help matching and dilutes it. Put that guidance in the instructions.

❌ Don't rely on exclusions. Adding "Exclude facilities issues like broken doors…" often makes the runbook more similar to the requests you're trying to exclude. Tighten what the runbook does cover instead.

✅ Keep descriptions from overlapping. More than one runbook can match a request. The agent prefers the most specific match, but if two runbooks' descriptions cover the same requests, the agent can pick a different one from ticket to ticket. Narrow each description to the requests that only its runbook handles, then check the result with saved matches.

✅ Match the runbook's scope. If the runbook only handles one variant of a request, don't write a description broad enough to match related requests it can't resolve. Either narrow the description or extend the instructions to cover those cases.

❌ Don't:

a user asks for VPN access, but only if they're a full-time employee who has completed security training...
  • Too detailed and complex
  • Hard for semantic matching to process
  • Conditional logic belongs in the instructions

Structuring instructions

Keep instructions short and clear. Tell the agent what to do, not what not to do.

  • Number your steps, one action per conversational turn.
  • Quote literal responses the agent should send word for word.
  • Reference tools explicitly: say when, how and why to use each one.
  • Combine actions that should happen in a single turn into one step (see below).
  • Handle decision points inline rather than splitting them into many small runbooks.

One step = one conversational turn

If a reply and an escalation should happen together, put them in the same step. Listed separately, the agent replies, waits for the user to respond, and only then escalates.

Any message the agent sends to the requestor ends its turn. The agent cannot send a message and then continue to work in the same turn. If a step tells the agent to reply, the agent then waits for the requestor. To make the agent do more work first, put that work before the reply, or combine the reply with Escalate in one step.

✅ Do:

1. Tell the user, "Thanks — I'm looping in a human teammate now." Then immediately use the Escalate tool.

❌ Don't:

1. Tell the user a human will help shortly.
2. Escalate to a human.

Combine paths that share a lookup

When several branches depend on the same lookup (for example Get User Context), nest them under a single lookup rather than repeating it in parallel paths.

✅ Do:

1. Use Get User Context to retrieve the user's department.
2. Based on department:
   - **Engineering**: …
   - **Sales**: …
   - **Other**: …

❌ Don't:

Path A: Engineering users…
Path B: Sales users…
Path C: Other users…

(Each path calls Get User Context separately, which is wasteful and harder to maintain.)

✅ Example:

## Software installation request

1. Use [Find Approved Apps] to verify the software is approved for company use.
2. Use [Get User Profile] to confirm the user has administrative privileges.
3. If the software is not approved or the user is not authorized, tell the user, "This app needs manual review — I'll loop in a teammate." Then immediately use the Escalate tool.
4. Otherwise, use [Install Remote App] to install the software, then resolve the ticket.

❌ Don't:

Handle software requests appropriately by confirming appropriate privileges and installing the software correctly

Using tools effectively

When you reference a tool, make the agent's job unambiguous: name the tool, when to use it, and why.

  • Escalate: preferred phrasing is "Immediately use the Escalate tool. Do not tell the user you are doing this; simply call the tool." Don't list it as a bare step like 4. Escalate.: the agent may announce it or hesitate.
  • Research Answer: be explicit about the topic, as in "Use Research Answer to look up our PTO carryover policy." Avoid vague phrasing like "research the policy."
  • Get User Context: returns a filtered set of identity provider profile values. Leave it out if no later step uses the result; it adds time and noise.

Use org-level instructions for behavior across runbooks

If a behavior should apply to every runbook (for example "Greet users warmly," tone or terminology), put it in Additional Instructions rather than repeating it in each runbook.

Troubleshooting

Runbook not matching

  1. Check that the runbook is enabled.
  2. Make the description more specific to the request type.
  3. Use the words people actually use in their requests.
  4. Try the request with Test Match, or keep a set of examples in Saved Matches.

Runbook can't be turned on

The runbook uses a tool that is turned off. The runbook's page lists the tools under References disabled tools. Enable them, then turn on the runbook.

Tools not working

  1. Check that the tools the runbook uses are enabled.
  2. Check that the tools are available to your organization.
  3. Check the limit of 10 tools per runbook, not counting core tools.

Form not appearing

  1. Check that the form chip is inside a step in the instructions.
  2. Check the Forms card for an "Unknown form" or "Not found" row: the form was deleted.
  3. Tickets from email, Jira or the web collect the fields conversationally, not as a form.
  4. See Runbook Forms troubleshooting.

Agent not following instructions

  1. Make steps more specific and actionable.
  2. Break complex workflows into smaller runbooks.
  3. Add context explaining why each step is important.
  4. Use clearer, more direct language.

Something wrong or missing? Report an issue · View as Markdown