Instructions
Instructions are the always-on part of your agent: who it is, how it talks, what it must and must not do. You write them as an ordered list of Prompt blocks on the agent's Instructions page, and you can make any block apply only in some situations, such as on Telegram or outside business hours.
The Instructions page also holds the agent's Model, Memory, Guardrails, Handoff, Team, Web search, Context, Fallback reply and Versions sections. This page covers the Prompt section. For the rest, see Model and behavior, Guardrails and privacy and Publishing and versions.
How prompt blocks work
A prompt block has a title and a text. When a customer writes, Peki takes the blocks that apply right now, in order, and turns each one into a section of the model's instructions:
## Identity & tone
You are Mia, the assistant of Bright Smile Dental. Reply in the customer's language, short and warm.
## Booking rules
Never confirm an appointment yourself. Collect the name, phone and preferred day, then hand off.
The title becomes a ## heading the model reads, so write titles that describe the block ("Refund rules", not "Block 3").
Every new agent starts with one block, Identity & tone. An agent always needs at least one block, so you can't remove the last one.
Block fields
| Field | What it does | Limit |
|---|---|---|
| Title | Shown to the model as the block's heading. | Required, up to 100 characters |
| Text (What should the agent do?) | The instructions themselves. Plain text or Markdown. Can contain variables like {{business.name}}. | Required |
| Condition (Always active / Conditional) | When the block is sent. See Conditions. | Optional |
The draft only saves when every block has a title and text. Until then you see Every block needs a title and text before the draft saves.
Add, reorder and remove blocks
- Open the agent and go to Instructions.
- Under Prompt blocks, click Add block below the list. A block called New block appears at the end.
- Give it a title and write the text.
- To move a block, drag it by the handle on its left (Drag to reorder). The handle also works with the keyboard: focus it, press Space, use the arrow keys, then press Space again.
- To delete a block, hover over it and click Remove.
The counter next to Prompt blocks shows how many blocks the agent has. Blocks you added or changed since the live version show added in draft or edited in draft, so you can see what your next publish changes.
Order matters
Blocks are sent in the order you see them. Put the most important context first: who the agent is and who it serves, then the rules, then the situational blocks. When two blocks seem to disagree, the model tends to follow the one that is more specific, so say clearly which rule wins ("If a customer is tagged vip, the free-shipping threshold below doesn't apply").
Kinds of blocks
Peki doesn't force a structure, but most good agents use a few kinds of blocks:
| Kind | What goes in it | Usually |
|---|---|---|
| Identity and tone | Name, role, the business, voice, language, reply length. | Always active, first |
| Scope and facts | What the business offers, opening hours, prices, policies the agent must quote exactly. | Always active |
| Rules | What the agent must never say or do, when to hand off, what to collect. | Always active |
| Situational | Extra instructions for one channel, after hours, or for tagged customers. | Conditional |
| Formatting | How replies look on a channel (short lines on Telegram, no tables). | Conditional on channel |
Long, step-by-step procedures for one kind of request (returns, sizing, bulk orders) work better as Skills: the agent loads them only when needed, so your always-on prompt stays short. Large reference material (a price list, a manual) belongs in Knowledge.
Conditions
By default a block is Always active: it's sent with every message. Click Always active on a block to open the condition menu and choose Only when… to send the block only when a condition is true. The block then shows Conditional and a tag that describes the condition, like when: channel is Telegram.
Each block can have one condition. These are all the conditions Peki supports:
| Condition | Options | Where the value comes from |
|---|---|---|
| Channel | is / is not: Web widget or Telegram | The channel the conversation came from. |
| Business hours | Outside business hours / During business hours | Settings → Business hours, in your workspace timezone. |
| Customer language | is / is not: Turkish, English, German, French, Spanish, Arabic, Russian, Italian or Dutch | Detected from each customer message. |
| Customer tag | has tag / doesn't have tag: a tag you type, like vip | The customer's tags in the Inbox. |
Rules to know
- A missing fact never matches. If Peki doesn't know the value, the block isn't sent, whichever option you picked.
- If business hours aren't set, a business-hours block is never sent, neither "during" nor "outside". The menu warns you: Business hours aren't set yet, so this block is never sent. Use Set business hours to fix it.
- If the language can't be detected yet (for example the first message is only a photo), a language block isn't sent, even with is not.
- Language is remembered. Peki detects the language from each message with words in it and keeps it for the conversation, so a short follow-up like "ok" keeps the earlier language.
- Tags are lower case. The tag you type is trimmed and stored in lower case, up to 40 characters. Tags on customers are matched exactly, so
vipdoesn't matchvip-gold. - "doesn't have tag" matches customers with no tags. A new customer with no tags gets a "doesn't have tag
vip" block. - Business hours follow the workspace timezone and handle windows that run past midnight.
- Test conversations count as the web widget unless you pick another channel in the Test panel.
Conditions only choose which blocks are sent. They don't change what the model can do: tools, skills and knowledge stay available either way.
Use the Test panel's simulation controls to check conditional blocks without waiting for the real situation: pick a channel, set Hours to Open or Closed, and type Customer tags like vip, wholesale. See Testing.
Variables in text
You can put variables in any block's text. Peki fills them in on every message, so the model reads the real value.
Write a variable as {{name}}, or click { } (Insert variable) on a block to insert one at the cursor. The menu lists:
| Variable | Value |
|---|---|
{{customer.name}} | The customer's name (Inbox, or the Test panel). Empty when unknown. |
{{business.name}} | Your workspace name. |
{{today}} | Today's date with the weekday, in your workspace timezone. Written in English. |
| Your own variables | Created in Settings → Variables, for example {{support_phone}} or {{return_days}}. |
Example:
## Contact
If the customer wants to call, give them {{support_phone}}. We answer calls on weekdays.
Returns are accepted within {{return_days}} days of delivery.
Things to know:
- Your own variables are workspace-wide. Change a value in Settings → Variables and every agent uses it right away, without publishing.
- A variable that doesn't exist becomes empty. Peki warns you under the block: Unknown variable {{name}} — it will be empty. Create it in Settings → Variables.
- With personal-data protection on (the default),
{{customer.name}}reaches the model as a placeholder like[NAME_1]. The customer still sees their real name in the reply.
See Variables and secrets for naming rules and limits.
Preview the final prompt
Above the blocks, Preview final prompt shows the size of the agent's instructions (≈ N tokens, for a plain web chat). Click it to open Final prompt: This is exactly what the model receives as instructions in this situation. It uses your unsaved edits too.
In the panel you can pretend a situation: Test as (channel), Hours (Real time, Open, Closed), Language, Customer tags and Customer name. The panel then shows:
- Each block marked Included or Skipped, with its condition.
- The full instructions text, with variables filled in.
- A note on what else the model gets on every reply: the last N messages of the conversation (from Memory) and the customer's new message.
What Peki adds after your blocks
Your blocks come first. After them, Peki adds sections of its own, depending on your settings. In order:
| Section | When it's added |
|---|---|
## Skills | The agent has skills: their names and when to use them. |
## Knowledge | The agent found passages that match the message (never in the preview: they depend on the customer's message). |
## Scope | The topic guardrail is on. |
## Confidentiality | The leak guardrail is on. |
## Personal data | Personal-data protection is on (the default). |
## Handoff | Handoff is on (the default), with your When to ask for a person text. |
## Records | The agent has record tables. |
## Actions the team approves | Some tools or actions need approval. |
## Web search | Web search is on. |
## Team replies | People from your team wrote in this conversation (live conversations only). |
## Customer | Customer profile is on and something is known: name, tags, team notes. |
## Current date and time | Current date and time is on (the default), including whether you're open right now. |
These sections are written in English for the model. The agent still answers in the customer's language. You don't need to repeat them in your blocks: for example, you don't need to tell the agent today's date.
The preview is built by the same code as a real reply, so it can't differ from what the model really gets.
Best practices
- Be specific and concrete. "Reply in at most 3 short sentences" works better than "be concise".
- Say what to do, not only what not to do. Pair every "never" with what to do instead.
- Keep facts in one place. If a price changes often, put it in a variable or in Knowledge, not in three blocks.
- Tell the agent how to use its tools. "When the customer gives an order number, look it up with
order_statusbefore you answer." - Don't paste secrets. Instructions are sent to the model on every message. API keys belong in secrets.
- Watch the size. Every block is sent with every message and costs tokens. Move long procedures to skills and reference text to Knowledge.
- Test each condition with the preview and the Test panel before you publish.
Example: online store
## Identity & tone
You are Leo, the assistant of {{business.name}}, an online store for running shoes.
Reply in the customer's language. Be friendly and brief: at most 3 short sentences unless the customer asks for detail.
## What you can help with
Orders, shipping, returns, sizing and product questions. For anything else, say politely that you can only help with the store.
## Rules
- Never promise a delivery date. Give the carrier's estimate from the order_status tool.
- Never offer discounts or free shipping that isn't in these instructions.
- If an order is lost or damaged, apologise, collect the order number and hand off to a person.
## Shipping
Shipping is free over $75. Standard delivery takes 2–4 business days.
## After hours (condition: when: outside business hours)
The team is offline now. Help as much as you can.
If the customer needs a person, say that someone will reply tomorrow morning, and hand off anyway.
## VIP customers (condition: when: customer has tag vip)
This customer is a VIP. Shipping is always free for them, whatever the order total.
## Telegram format (condition: when: channel is Telegram)
Keep each reply under 400 characters. Don't use tables or headings.
Example: dental clinic
## Identity & tone
You are Mia, the front-desk assistant of Bright Smile Dental. Be warm and calm; many patients are nervous.
Reply in the customer's language.
## What you do
Answer questions about treatments, prices and opening hours, and help patients request an appointment.
## Medical safety
You are not a dentist. Never diagnose or recommend medication.
If someone describes severe pain, swelling or bleeding, tell them to call {{emergency_phone}} right away.
## Appointments
To request an appointment, collect: full name, phone number, the treatment and two preferred times.
Then tell the patient the clinic will confirm by phone, and hand off.
## Turkish-speaking patients (condition: when: customer writes in Turkish)
Our Turkish-speaking dentist works on Tuesdays and Thursdays. Offer those days first.
Example: SaaS support desk
## Identity & tone
You are the support assistant of Acme Analytics. Be precise and technical when the user is technical,
plain when they're not. Use Markdown code blocks for code and settings.
## Scope
Help with account, billing, integrations and dashboards. Don't give legal or security advice.
## Troubleshooting order
1. Ask which plan and which integration they use, if you don't know yet.
2. Search your knowledge for the matching guide and follow it.
3. If the guide doesn't solve it, collect the workspace URL and the error text, then hand off.
## Billing
You can explain invoices and plans, but never issue refunds or change a subscription. Hand off for those.
## Outside support hours (condition: when: outside business hours)
Live support is offline. Tell the user we reply within one business day.