The Agent document
The Agent document describes your agent in plain words: what it does, what it takes in, what it gives back and where its limits are. The Copilot writes it during onboarding and keeps it current as the agent changes. Anyone on your team can read it, editors can change it, and you can export it to share or to rebuild the agent somewhere else.
It lives on the agent's Document page, the first item in the agent's menu.
The Document page
The page shows the document read-only, one card per section.
| Element | What it does |
|---|---|
| Subtitle | Updated <date and time> once anything was written; before that, "What this agent does, in plain words. The Copilot keeps it current." |
| Edit | On each section, for editors. Opens the section as Markdown text. Save stores it; Cancel drops your change. |
| Who wrote it | Next to each section's title: Edited by you, Edited by a teammate or Written by the Copilot. |
| Not written yet | Shown on an empty section (editors see empty sections; viewers see only the written ones). |
| Apply to the agent | Appears after you save a section. See From the document to the agent. |
| Export .md | Downloads the document as Markdown. |
| Opens a print-ready page to save as PDF. | |
| Test, Copilot | Open the Test panel or the Copilot panel on the right. |
An agent without a document
Agents created with Or start empty, or before the Document existed, have an empty document. The page then shows No document yet and, for editors, Write it with the Copilot. That button opens the Copilot with this request ready to send:
Write the Agent document for this agent as it is now: fill every section you can from its instructions, tools, knowledge, tables and settings.
Press send and the Copilot fills the sections from what the agent really has.
The 10 sections
The document always has the same 10 sections, in this order. Each is plain Markdown, up to 4,000 characters.
| # | Section | What goes in it |
|---|---|---|
| 1 | Business | Who the business is, what it sells, who its customers are, contact details, opening hours. |
| 2 | Job | What the agent is for, in a few sentences. |
| 3 | What it can do | The kinds of questions and tasks it handles; its skills and Functions in plain words. |
| 4 | What it takes in | What customers tell or send it; the details it collects (tables and fields) and when. |
| 5 | What it gives back | Answers and the knowledge they come from, records it saves, messages, automation alerts, handoffs. |
| 6 | Limits | What it never says or promises; what it does when it doesn't know. |
| 7 | Handoff | When it hands a conversation to your team, and what it says outside business hours. |
| 8 | Tone and languages | Formality, languages, style. |
| 9 | Channels | Website widget, Telegram, API. |
| 10 | Open items | What is still missing or undecided. |
The document describes only what the agent really does now, never plans. Ideas and to-dos belong in Open items.
The Copilot writes the document in your language. Section titles follow the language you use Peki in.
Builder notes
Besides the 10 sections, each document has builder notes: the Copilot's technical notes, such as which APIs it chose and why, or what it tried and rejected. Up to 20,000 characters.
- The Copilot reads and writes them (Updated technical notes). They help it remember decisions across turns and days.
- They're not shown on the Document page, never included in exports, and hidden from viewers.
- If your agent had Copilot build notes from before the Document existed, they were moved, unchanged, into its builder notes.
- Undoing a Copilot turn doesn't roll builder notes back.
How it stays current
The Copilot reads the whole document, with who last edited each section, at the start of every turn.
- After every change that alters what the agent does, takes in or gives back, the Copilot updates the affected sections (Updated the Document), short and factual.
- Changes made by hand on other pages (for example, you edit an instruction block yourself) don't rewrite the document in the background. The next time the Copilot runs, it compares the agent with the document and offers to update the sections that no longer match.
- The document isn't versioned. It describes the draft and isn't part of published versions. Restoring an older version doesn't roll the document back; ask the Copilot to update it afterwards.
- Undo puts back the sections a Copilot turn wrote, unless a person edited that section after the turn started. See Undo.
- The Document page refreshes on its own when the Copilot writes to it.
A document that says the agent does something it doesn't is worse than none. If you notice a mismatch, ask: "Compare the agent with the Document and fix whatever no longer matches."
Section and document approvals
Your edits stay yours
A section a person wrote (any member of the workspace, or an API key) is protected. The Copilot never overwrites it silently. When it wants to change it, it pauses on a section card:
- Title: Change "<section>"? with "You wrote this section. The Copilot suggests new text:"
- Your text (Yours) next to the Copilot's (Suggested).
- Keep mine leaves your text as it is. Use the new text replaces it.
If you accept, the section still counts as yours, so it stays protected from silent changes. Any member's edit protects a section, and the protection doesn't expire. You can also answer the card in your own words; nothing changes until you choose.
Changing the document, and answering these cards, needs the editor role.
Approving the whole document
During onboarding, the Copilot asks you to approve the complete document before it builds the agent, on the Approve the Agent document card:
- A short summary of what the agent will do, and Open the document.
- Approve and build lets the Copilot build from it.
- To ask for changes, write them in the message box. The card then shows Not approved yet and the Copilot reworks the document.
See New agent onboarding.
From the document to the agent
Editing a section changes the document, not the agent. To bring the agent in line:
- Click Edit on a section, change it and click Save.
- Click Apply to the agent, which appears on that section.
- The Copilot panel opens with "Apply my change to the "<section>" section of the document to the agent." ready. Press send.
- The Copilot makes the matching changes (instructions, settings, tables and so on), with its usual cards and tests, and every change is undoable.
For example, change Limits to "Never quote prices for implants; say the dentist decides after an exam", then Apply to the agent: the Copilot adds or edits an instruction block and tests it.
Exporting
Anyone who can open the agent, viewers included, can export its document.
Markdown
Export .md downloads <agent name>.md. It contains:
- The agent's name as the title.
- Every section that has text, under its title, in the language you use Peki in.
- An Appendix generated from the agent's draft:
- Tools: HTTP tools, Functions and skills, by name and description.
- Tables: each table with its field names.
- Knowledge: knowledge sources by title, with the page address for web pages (without query strings or fragments).
- Channels: Website widget when the widget is on, and Telegram when a bot is connected and on.
- A closing line: "Created with Peki".
Never included: builder notes, keys, tokens or secrets, tool URLs and auth, Function code, skill steps.
# Smile Dental Assistant
## Business
Smile Dental is a dental clinic in the city centre...
## Job
Answers patients' questions and takes appointment requests...
## Appendix
### Tools
- book_request: Saves an appointment request
...
---
Created with Peki
PDF
PDF opens the document on a plain page in a new tab, with the same sections and appendix, and opens your browser's print dialog when it has loaded. Choose Save as PDF (or your system's equivalent) as the destination.
If the print dialog doesn't open, your browser may have blocked the new tab. Allow pop-ups for Peki and try again.
Using it as a portable spec
The exported document is a readable blueprint you own. Use it to:
- Share and review. Send the PDF to a manager, a legal reviewer or a client before you publish.
- Onboard your team. New colleagues learn what the agent does without opening Peki.
- Rebuild elsewhere. The Markdown describes the business, the job, inputs, outputs, limits, handoff, tone and channels, plus the list of tools, tables and knowledge sources. That's what you need to set up the same agent on another platform, or to brief a developer.
- Seed a new agent. Paste parts of it into a new agent's Copilot chat: "Build an agent from this description: …".
- Keep a record. Export before big changes to keep a snapshot of how the agent worked.
It's a document for people, not a file another platform can import: it doesn't contain prompts, tool schemas or keys.
From the API
The document is also available through the Peki API, with a user session or an API key (Authorization: Bearer <key>). Paths are relative to the base URL https://peki.ai/api. See API overview and Authentication.
| Method and path | What it does |
|---|---|
GET /agents/{agentId}/document | The document: sections (each with text, updatedAt, updatedBy), builderNotes (empty for viewers), updatedAt and empty. |
PUT /agents/{agentId}/document/sections/{key} | Replaces one section. Body: {"text": "..."}, up to 4,000 characters. Needs the editor role. Returns the whole document. |
GET /agents/{agentId}/document/export?locale=en | The Markdown export as a file. locale is en or tr. |
GET /agents/{agentId}/document/appendix?locale=en | The appendix as JSON: tools, tables, knowledge, channels. |
Section keys: business, job, capabilities, inputs, outputs, limits, handoff, tone, channels, openItems.
PUT https://peki.ai/api/agents/{agentId}/document/sections/limits
Authorization: Bearer <your API key>
Content-Type: application/json
{"text": "Never quote prices for implants. When unsure, offer to have the team call back."}
A section written through the API counts as written by a person, so the Copilot won't overwrite it without a section card.