Agent Builder is the chat panel on the Agent Studio home screen. Describe what you want, it reads your project and proposes a plan, you approve or revise. Nothing changes until you approve. Every edit lands on a branch, not on the live agent.Documentation Index
Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
Use this file to discover all available pages before exploring further.
How to ask
A few patterns produce noticeably better drafts:- State the business rule, not just the action. “Add a refund flow with a 30-day window, original payment method only” gets you a usable plan. “Add a refund flow” gets you something you’ll need to rewrite.
- One unit of work per request. One flow, one topic, one set of related changes. Easier to review and roll back.
- Name what to keep. On rewrites and cleanups, call out anything that should stay. Or ask for a plan first and read it before approving.
What it can change
Agent Builder operates on the same building blocks you’d edit by hand: flows, topics, entities, functions, integrations, handoffs, and agent settings. For any of these, it can read your current config, propose changes, and write them to a branch.| Building block | Examples of what the assistant can do |
|---|---|
| Flows | Create new flows; restructure steps, transitions, and conditions; rewrite step prompts |
| Topics | Create knowledge-base topics from a description; update wording or scope |
| Entities | Define entities and their values; update entity definitions used by flows |
| Functions | Wire flows to existing functions; describe and create new function specs |
| Integrations | Configure integrations and connect them to flows |
| Handoffs | Add transfer-to-human steps with the right conditions and metadata |
| Agent settings | Set or update purpose, role, and personality |
Modes
| Mode | What it does | When to use it |
|---|---|---|
| Agent | Plans a change, then applies it on approval. | Default for build work. |
| Plan | Plans a change but doesn’t apply it. | Comparing approaches before committing. |
| Ask | Read-only questions about your project. | ”What does this flow do?”, “Why did containment drop yesterday?” |
What to expect
Agent Builder edits the branch you’re on. It doesn’t publish or promote between environments; merging and promotion stay manual. Business knowledge comes from you. The assistant won’t invent prices, hours, policies, or names. If those are missing from your project, the plan surfaces them as questions. Every change is reviewable. Each applied edit produces a tracked-changes summary you can inspect, tweak, or revert before merging back toMain.
Limits
Agent Builder has a fair-use limit so usage stays predictable. The size and reset cadence are managed by PolyAI on your account. Current usage shows next to the message input. When you hit the limit, the assistant pauses until the next reset. A rest card replaces the input, and manual editing in Studio still works normally. Usage and limits →A full session, step by step
The full tour: chat → ask → branch → plan → approve → merge
The full tour: chat → ask → branch → plan → approve → merge
The steps you’ll repeat for most build work, with screenshots from a real session.
Start from the home screen
The chat panel opens with a prompt input and templates grouped by intent: Build, Test, Ask, and Analyze. Pick a suggestion, edit it, or type your own request. The Agent wizard entry under Build kicks off a guided builder for brand-new agents from a company URL. The usage indicator next to the send button shows your current spend.
Ask about your agent
For exploration, the assistant reads your agent settings, flows, topics, entities, and functions, then replies with answers grounded in your project. The tools it runs (
read, explore, and so on) appear inline before the final message.Make a change on a branch
The first time you ask for a change, Agent Builder creates a branch automatically and names it after the request. 
Main stays untouched while the assistant works on the branch. The branch chip replaces Main in the top-left for the rest of the session.Answer any clarifying questions
If your request is ambiguous, the assistant asks a clarifying multiple-choice question before it starts planning. Pick an option, type your own answer, or Skip to let the assistant choose.
Approve or revise the plan
Once it has enough context, the assistant presents a plan card with Approve and Reject buttons. Nothing is written until you approve. Click the plan card to expand the full breakdown. From the expanded view you can write feedback for the assistant to revise the plan, then Send to re-plan.
Merge to main
The Merge button in the top-right opens a dialog where you can add an optional message, then ship the branch back to 
Main. From there, your changes flow through the normal Sandbox → Live pipeline.Conversations and history
Chats are saved in the History panel on the left, scoped to the project. You can resume any past chat, switch between concurrent ones, or archive what you’re not using. The assistant remembers everything in the current chat. Follow-ups like “now do the same for the cancellation flow” work without repeating context. Drag in transcripts, policy docs, or screenshots to attach files; the assistant reads them as part of the request. Start a new chat when switching to unrelated work. Each chat carries its full history as context, so very long chats can slow responses or trigger automatic summarization.60-day free trial
Sign up at studio.poly.ai with any email address. You get 60 days of free access on the same Raven model and infrastructure that powers enterprise deployments — no separate sandbox mode, no toy version.If you don’t move to a paid plan at the end of the trial, your agents are deactivated, not deleted. They stop handling calls but stay on your account so you can pick them back up later.Security and hosting
Agent Builder runs on its own dedicated cluster, separate from enterprise infrastructure. Your account is isolated: conversations, configuration, and credentials are only visible to you. No cross-account access.Agent Builder is hosted in the US. EU and UK hosting are enterprise.Sensitive credentials (API keys, OAuth client secrets) belong in the Secrets Vault. Functions retrieve them at runtime, so they don’t end up in your code, logs, or version history.Moving to enterprise
Your work moves with you. When you need PSTN telephony, real-time configuration, contracted SLAs, or any other enterprise capability,poly pull the project with the ADK, then poly push onto an enterprise cluster. Request a demo when you’re ready.Frequently asked questions
What happens at the end of the 60-day free trial?
What happens at the end of the 60-day free trial?
Your PolyAI representative shares paid-plan options before your free period ends. If you don’t move to a paid plan, your agents are deactivated, not deleted. They stop handling calls but stay on your account so you can pick them back up later. Sign-up data, transcripts, and configuration are retained while the account is on file.
What about phone numbers and telephony?
What about phone numbers and telephony?
PSTN telephony is enterprise. Web Calling (WebRTC voice in the browser) is how voice is delivered on Agent Builder. Enterprise accounts can bring their own Twilio numbers via the ADK.
What happens to my data?
What happens to my data?
Your conversations, recordings, knowledge, and credentials are only visible to your account. There’s no cross-account access. If you ever want your data deleted entirely rather than just deactivated, your PolyAI representative can do that for you.
Related pages
Prompting guide
Patterns for getting consistently good results.
Usage and limits
Your fair-use allowance, reset cadence, and what to do when you hit it.
Flows
The building blocks the assistant uses to structure conversations.
Managed topics
Knowledge the assistant reads from and writes to.
Deployments
Promote the assistant’s branches from
Main to Live.