Key concepts
This page explains the ideas you meet everywhere in Peki and how they fit together. Read it once and the rest of the docs will make sense. For a short definition of every term, see the Glossary.
The big picture
A workspace holds your team and your agents. Each agent has a draft you edit and published versions customers talk to. Customers reach the published version through channels. Each exchange is a conversation with a customer, and your team follows every conversation in the Inbox.
Workspace
A workspace is a separate space with its own agents, channels, team, keys and credits. Nothing is shared between workspaces. Most people need one; an agency serving several clients might use one per client.
A workspace has:
- A name, a default language (English or Turkish) and a currency (USD, EUR or TRY).
- A time zone and business hours, used by automations, by instruction blocks set to "during" or "outside business hours", and by the agent's sense of the current date and time.
- Members, each with a role.
- API keys for calling Peki from your own systems.
- A plan and a credit balance.
You can belong to several workspaces and switch between them. See Accounts and workspaces.
Members and roles
Everyone in a workspace has one role. Each role can do everything the roles before it can.
| Role | What it can do |
|---|---|
| Viewer | Read only. |
| Operator | Answers customers in the Inbox: takes over, replies, hands back, resolves. |
| Editor | Builds agents: edits the draft, uses the Copilot, tests, publishes. |
| Admin | Members, API keys, secrets and workspace settings. |
| Owner | Everything, including adding or removing other owners and deleting the workspace. |
See Members and roles for the full list.
Agent
An agent is one AI assistant with one job, for example "Smile Dental front desk" or "ShopX order support". It has its own instructions, tools, knowledge, channels, conversations and analytics. A workspace can have many agents, and agents can ask each other for help as an agent team.
What an agent is made of:
- Instructions: ordered prompt blocks it always follows. A block can be Always active or Conditional: only on one channel, only during or outside business hours, only for customers with a tag, or only when the customer writes in a given language.
- Tools: HTTP tools, each one API call the agent can make.
- Functions: small TypeScript programs that run in a sandbox.
- Skills: how-to steps loaded only for one kind of question.
- Knowledge: documents, web pages and text the agent searches.
- Settings: model and fallback model, temperature, memory, sessions, context, fallback reply, guardrails, handoff, web search and team.
- Records tables: the fields of the data it collects.
- Automations: jobs it runs on its own.
- Channels: where customers reach it.
Use ⌘K (Ctrl+K on Windows and Linux) anywhere in Peki to search your agents and jump to one.
Draft and published versions
Every agent has exactly one draft and any number of published versions.
- The draft is what you and the Copilot edit. It saves as you go. The Test panel always uses the draft.
- Publishing turns the draft into the next numbered version, v1, v2, v3 and so on, and makes it live on every connected channel at once. You can add a short note about what changed.
- The live version is the one customers talk to. There is only one at a time.
- Restoring copies an earlier version into the draft. History stays as it is, and nothing goes live until you publish again.
The Instructions header shows the draft number and how many unpublished changes it has. Instructions → Versions lists every version with who published it, and can compare any version with the live one.
Some things are not versioned and apply right away:
| Applies right away | Waits for Publish |
|---|---|
| Channel settings (website chat look, allowed sites, Telegram on or off) | Instructions, tools, Functions, skills |
| Knowledge sources | Model, memory, guardrails, handoff, web search, team |
| Workspace variables | Records table settings |
| Business hours | Starter questions |
Your records are never versioned: restoring an older version keeps every lead and appointment. See Publishing and versions.
Publishing needs a package. On the free plan you can build, test and connect channels, but Publish is locked. See Plans and credits.
Copilot
The Copilot is an AI assistant inside Peki that builds the agent with you. You tell it what you want in plain words; it edits the draft, researches APIs, writes tools and Functions, tests everything with real calls and test conversations, and reports back.
- One chat per agent. Each agent has one Copilot chat that keeps its whole build history.
- Cards. The Copilot stops and shows a card when it needs you: option cards for a choice, a secure field for an API key, a Telegram card for a bot token, and approval cards for anything with real effects, like publishing.
- Undo. Every Copilot turn can be undone with Undo this turn.
- Cost. Each reply shows its cost underneath. The Copilot uses credits.
- Model. You choose the Copilot's model above its message box. This is separate from the model your agent uses to answer customers.
See Copilot overview.
Agent document
The Document page describes the agent in plain words, in ten sections: business, job, what it can do, what it takes in, what it gives back, limits, handoff, tone and languages, channels, and open items. The Copilot writes it during onboarding and keeps it current as it changes the agent.
You can edit any section. The Copilot never overwrites a section you wrote: it shows its suggestion next to yours and you decide. After you edit a section, Apply to the agent asks the Copilot to make the matching changes. You can export the Document as Markdown or PDF. See The Agent document.
Channels
A channel is a place where customers reach the agent:
- Website chat: a chat bubble or an inline chat box on your website, added with one line of code.
- Telegram: your own Telegram bot, answered by the agent.
- Sessions API: for your own app or chat screen, with streaming replies.
Customers always talk to the published version, on every channel. See Channels overview.
Conversations and sessions
A conversation (also called a session) is one exchange between a customer and an agent. It holds the messages, any files, the traces of each reply, handoff events and the customer's rating.
How a new conversation starts:
- On the website chat, the customer can click New conversation. On Telegram, they can send
/new. Through the Sessions API, your app starts a session. - Otherwise, a customer's message continues their latest conversation, unless it was resolved or has been quiet too long. By default that's 24 hours; you can change it to 1 hour, 7 days, or never (only when resolved) in the agent's Memory settings.
Conversations have two kinds:
- Live conversations are with real customers and the published version. They count in Analytics.
- Test conversations come from the Test panel and use the draft. They show in the Inbox as "Test panel" and never count in Analytics.
Each reply keeps a trace: the model, the prompt blocks, tools, skills and Knowledge it used, tokens and timing. Click Why? under a reply in the Inbox to see it.
Customers
A customer is a person who talks to your agent. Peki creates one automatically the first time someone writes on a channel. A customer has a name (if known), tags, notes, the channel and handle they use, their language, when they were first seen and their conversations.
You can edit a customer's name, tags and notes in the Inbox under Customer details. With the Customer profile setting on, the agent sees the customer's name and tags, so a block like "for customers tagged vip" can apply. See Customers.
Handoff and the Inbox
Handoff is how a customer reaches a person. When the customer asks for one, or your handoff rule says so, the conversation shows in the Inbox under Needs you. The agent keeps helping until a teammate clicks Take over. While a teammate has the conversation, the agent stays quiet. Hand back to AI returns it to the agent, and Resolve closes it. See Human handoff.
Records and approvals
Records are your own tables of data the agent collects, like leads, appointments, orders and support requests. The agent saves what customers tell it, and a records fill can complete a table after a conversation goes quiet. See Records.
Approvals let your team check an action before it happens: a tool call, a Function, a table save or an automation's message. The action waits in Inbox → Approvals until someone approves, edits and approves, or rejects it. Requests expire after 24 hours. See Approvals.
Automations
Automations let the agent act on its own: on a schedule, when another system calls its webhook, or when something happens inside Peki (a Peki event). A typical automation checks something cheaply with a Function, continues only if something changed, then lets the agent write a message and sends it to Telegram. See Automations and Triggers.
Credits and plans
Everything that uses AI costs credits: building with the Copilot, test conversations, your agents' replies, automations, records fills, analytics and reading Knowledge sources. One credit is $0.01.
- A new user's first workspace gets 500 free credits once.
- The Free plan lets you build, test and connect channels. Publishing needs a package. Packages are coming soon.
- When credits run out, the Copilot, tests, automations and new Knowledge stop with a message. Nothing you built is lost. Live agents of paid workspaces keep answering customers.
Settings → Plan & credits shows your plan, balance, what you used this month and a history of every change. See Plans and credits and Usage.
Privacy by default
A few rules hold everywhere in Peki:
- Personal data is masked before the model sees it. Names (optional), phone numbers, emails, ID numbers, card numbers and IBANs become placeholders like
[PHONE_1]. Your tools still get the real values. - Keys never reach the model. They're stored encrypted, belong to one agent, and are sent only to the sites you allowed.
- Model calls go only to providers that keep no data and never train on it.
- Anything with real effects needs a person: publishing, restoring, widget changes from the Copilot, writes during Copilot tests and automation writes.
See Data and privacy and Security model.