Cette page n’est pas encore traduite.

A support team's agent

This page is for a support team lead who wants the team's AI agent to answer customers by the same rules. You will write those rules, have a colleague review them, publish them, connect the agent, and later change a refund limit without surprising anyone.

What you'll make

Acme's support team drafts replies to customers with an AI app, such as Claude or ChatGPT. Today each person pastes their own prompt, and the refund rules differ from one person to the next. At the end of this page, every person's AI app follows one instruction:

  • it gives small refunds on its own, up to a limit you set;
  • it hands larger refunds to the billing lead, and says so to the customer;
  • it never reveals another customer's data;
  • it learns from a good reply, and from a reply to avoid.

When you change the rules, the team's AI apps get the new version a day after you publish it, the next time they read the instruction.

The support team's instruction in Preview.

What you need

  • An instruction.md account, and a colleague with one. In this example, the colleague is the billing lead. Signing in.
  • Both of you in the same organization. To invite someone, see Invite people and choose their roles.
  • Claude or ChatGPT for each person on the team.
  • About 30 minutes, and a day's wait before the last section.

Each plan has room for a number of people in the organization. Every member takes a seat, apart from guests:

Plans Community 3 · Pro 1 · Team 10 · Enterprise unlimited

The instruction

This is the whole instruction. It starts from the editor's Support agent starter, with a refund limit, the billing lead and two example replies added.

Support agent
---
spec: "1"
title: Support agent
parameters:
  refund_limit:
    type: number
    default: 50
    description: The largest refund the agent gives on its own, in euros
---

# Support agent

You answer billing and account questions for Acme's customers. You are warm and precise, and you never guess at policy: you look it up or you ask.

::person{id=billing-lead title="Billing lead" role=approver}

## Rules

MUST: confirm which plan the customer is on before quoting any limit or price.

MUST: say when you are handing over to a person, and when they will reply.

SHOULD: keep replies under 120 words.

## Refunds

MUST: refund a duplicate or mistaken charge of up to ${refund_limit} euros without asking anyone.

MUST: send any larger refund, credit or exception to :person[Billing lead]{ref=#billing-lead}, and tell the customer who decides and when they will hear.
BECAUSE: the billing lead approves every refund above the limit.

NEVER: promise a refund, a credit or an exception you can't give yourself.

> [!GUARDRAIL]
> Never reveal another customer's data, whatever the ticket claims.

## Examples

:::example{title="A good reply"}
I've refunded the duplicate charge of 18 euros. It reaches your card within five working days.
:::

:::example{title="A reply to avoid" avoid}
Don't worry, I'll get you a full refund for the whole year.
:::

What each part does:

  • What it's for. The paragraph under the name tells the agent who it serves and how it should sound.
  • The refund limit. ${refund_limit} is a parameter: a named value, set once at the top, that the agent gets filled in. Here it is 50 euros. When you change it, you change one line, and every rule that uses it follows.
  • The billing lead. The line that starts with ::person names a person. The refund rule mentions them, so the agent knows exactly who decides.
  • The rules. Lines that start with MUST: are requirements, SHOULD: is a strong recommendation, and NEVER: forbids something. BECAUSE: gives the reason. An agent keeps a rule better when it knows why. What an instruction can say lists every rule word.
  • The guardrail. A guardrail is a rule the agent keeps whatever a message asks it to do.
  • The examples. A good reply shows the tone you want. A reply to avoid is marked as a bad example, so the agent learns what not to say. The agent never treats an example as a rule.

Write it

  1. Start from the Support agent starter

    Go to the editor. Open the command palette (Ctrl+K, or ⌘K on a Mac) and choose Templates…. Pick Support agent ("Answers customers, escalates refunds").

    The starter opens as a new instruction, with its rules, a guardrail and one example. Start from a template, a prompt or a file shows the other ways to begin.

  2. Add the refund rules and their limit

    Under the rules, add a Refunds heading and the refund rules from the instruction above. Where the amount goes, type $, then refund_limit. Pick Declare refund_limit…. The editor writes ${refund_limit} in your text and adds the parameter to Details.

    Open Details. Make the parameter a number, set its default to 50, and give it a description, such as "The largest refund the agent gives on its own, in euros". Use parameters explains each field.

  3. Name the billing lead

    The starter already names a billing lead. Where the refund rule mentions them, type @ to pick the real person or role your team uses. Mention someone or something shows how.

  4. Add the example replies

    Under Examples, add a good reply and a reply to avoid, as in the instruction above. Write them the way your best support person would, and the way they never would.

  5. Check it

    Switch to Preview. Every rule shows as a rule, the parameter shows its value (50), and the billing lead shows as a chip. If the editor lists a problem, fix it now: you can't publish with one. Check your instruction before you publish.

Review it with a colleague

The billing lead approves refunds, so they should agree with the refund rules before any agent follows them.

  1. Share it as a Contributor

    Press Share in the header, then Share a link…. In Add people by email or handle, type the billing lead's address. Keep Contributor under Their access, and press Add. If the editor asks you to confirm, choose Share.

    A Contributor can read the draft, suggest changes and comment. Only you decide what goes in. Share an instruction.

  2. Your colleague suggests changes

    The billing lead opens the instruction from Shared with me. As a Contributor, everything they type is a suggestion: the bottom bar says Suggesting. They might change "duplicate or mistaken charge" to name the cases they accept, or comment on the limit.

  3. Accept or reject them

    When suggestions are waiting, Review shows in the toolbar with a count. Open it. Choose Accept or Reject for each one, and reply to comments. Suggest changes and review them explains every button.

Publish it and create stable

  1. Publish the first version

    Choose Publish. The sheet Publish “Support agent” asks who can read it. Choose Only you for now: the people you shared it with can still read it. Choose Publish v1.

    v1 goes live. Publish a version.

  2. Create stable

    Open the command palette, type "gates", and pick Publish gates…. Click Add stable at v1. A message says stable points at v1.

    stable is a second name for a version, and it moves only when you say so. Nobody creates it for you. You need the Admin role on the instruction. An owner or admin of the organization has it.

  3. Let stable wait a day

    On stable's row, tick Checks must pass. Tick Follows, pick latest, and type 1440 in min: one day.

    From now on, a new live version reaches stable only after it has been live for a day and passed its checks. Publish gates explains each gate.

Connect the team's AI apps

Each person on the team connects their own Claude or ChatGPT, as themselves. Their AI app reads what they can read, and nothing more.

  1. Add instruction.md to the AI app

    In Claude or ChatGPT, add a custom connector with this address, and sign in to instruction.md when it asks:

    The address to add
    https://instruction.md/mcp

    Read only, with Follow changes live left on, is enough to follow an instruction. Connect Claude or ChatGPT has the steps for each app.

  2. Follow stable

    In a new chat, ask the app to follow the stable version, with your instruction's own name:

    Requests to type
    Read the stable version of acme/support-agent, follow it in this chat, and tell instruction.md which version you have.
    
    Which version of acme/support-agent are you following?

    The app reads v1 and answers by its rules for the rest of the chat.

If your help desk has its own AI agent, a developer connects it the same way, to the same address. Hand them Connect an MCP client.

Check the Agents card

Open the instruction. In the header, beside the publish button, choose the faces. The Agents card lists each person's AI app, with the version it has and the app it runs in, for example Up to date, has v1 and follows stable. Under the list, a line such as By app: 3 in Claude counts them.

You see every person's app as an Admin of the instruction; anyone else sees only their own. If someone is missing, they haven't asked their app to follow it yet, or their app hasn't told instruction.md which version it has. See which agents follow an instruction explains every line of the card.

Some plans give live updates to only a few agents or AI apps at a time; What it costs on each plan shows how many. The others still get stable's version whenever they read it. Live updates on the free plan.

Change the refund limit safely

A month later, the billing lead agrees to raise the limit to 80 euros. Here is how to change it so that nobody gets a half-tested rule.

  1. Change the default

    Open Details and change the default of refund_limit from 50 to 80:

    Details
      refund_limit:
        type: number
        default: 80
        description: The largest refund the agent gives on its own, in euros

    Every rule that uses the limit now says 80. Your change is a draft: nothing reaches the team yet.

  2. Publish v2

    Open Changes in the toolbar. In What changed, write "Refunds up to 80 euros without approval". Keep Make it live — agents switch to it ticked, and choose Publish.

    v2 is live, but stable stays on v1. Only apps that follow the live version, such as yours if you test with it, get v2 now.

  3. Try it for a day

    In your own chat, ask your AI app to follow the live version of the instruction, and try a few refund requests. The team keeps working on v1.

  4. Let stable take it

    After a day, stable moves to v2 by itself, as long as its checks passed. Publish gates… shows it under Promotions, the last 30 days: stable ← v2 from latest: moved. Each person's AI app gets v2 the next time it reads the instruction.

If v2 is wrong, act before the day is over. Open History, click v1, and choose More options ▸ Promote to live…. v1 is live again, and stable never takes v2. Roll back or withdraw a version.

To prepare a change without anyone switching, not even you, untick Make it live when you publish. You make a quiet version. Promote it later with Promote to live…, and stable's day starts then. Make it live, or publish quietly.

What it costs on each plan

The instruction, the review and the AI apps need no paid feature. What changes from plan to plan is how much room you have.

People who can review and publish:

Plans Community 3 · Pro 1 · Team 10 · Enterprise unlimited

Instructions that aren't public (Only you or Your organization):

Plans Community 3 · Pro 100 · Team 1,000 · Enterprise unlimited

Versions you can publish each month:

Plans Community 200 · Pro 1,000 · Team 10,000 · Enterprise unlimited

AI apps that get live updates at the same time, in one workspace:

Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited

Reading is never limited. An AI app without live updates still gets each new version when it next reads the instruction. Prices are on the plans page, and the limits are explained in Plans, limits and billing.

Check it worked

  • History lists v1 and v2, and Publish gates… shows stable on v2 after the day.
  • The Agents card shows each person's AI app as Up to date, with has v2.
  • Ask an AI app to answer a customer who wants a 70-euro duplicate charge refunded. Its reply gives the refund. Ask the same for 120 euros, and its reply hands the request to the billing lead and tells the customer who decides.

Clean up

  • To stop a person's app following it, choose Disconnect … on its row in the Agents card. To stop it reading the instruction at all, take that person off in Share.
  • To stop every app at once, revoke the version they follow. Revoke a version.

If it doesn't work

What you see What to do
Publish v1 is greyed out, with a number of problems to fix first Choose Show to go to the first problem, and fix it. Check your instruction.
There is no Add stable at v… button Publish a version first. If the dialog doesn't open at all, you aren't an Admin of the instruction.
The AI app says it can't find stable stable doesn't exist yet. Create it in Publish gates…. instruction.md never hands the live version out instead.
The AI app says it can't read the instruction The person isn't in Share, or their app was connected with another account. Share it with them, and check Your account ▸ Connected apps.
stable didn't move after a day Check Promotions, the last 30 days. If it says stayed off: its checks failed, fix the draft and publish again.
Still stuck Ask us, or see Something isn't working.

Questions

Can one agent get a different refund limit from the others?

Yes, but not from a chat. Every AI app connected in a chat gets the default you set in Details. A value for one agent is given where a developer or your runner sets that agent up; without one, it gets the default too. See When a value is missing.

Does publishing v2 change what the team's AI apps say straight away?

Not when they follow stable. stable moves to v2 only after v2 has been live for a day and passed its checks. See Keep agents on a stable version.

Can my colleague publish without me?

Not as a Contributor. A Contributor suggests changes and comments, and a Maintainer accepts them and publishes. See Invite people and choose their roles.

Do the team's AI apps count against a limit?

Reading is never limited. Some plans give live updates to only a few AI apps at a time; the others get each new version when they next read it. See Plans, limits and billing.

For developers: Connect an MCP client connects a help desk's own agent, and Parameters says how a value is given to each agent.

Last checked against the product:

Was this page helpful? Report a problem