> ## 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.
# Agent Builder
> Build, explore, and ship changes to your agent in natural language inside PolyAI Studio. Every change runs on a branch you can review before merging.
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.
**Availability (Beta).** Agent Builder is available to **project admins** on enterprise clusters. During the Beta, non-admin members on a project can't access Agent Builder — permissions will become more granular over time. See [Role permissions](/user-management/access-control-scope) for what each role can do. Bug reports and feedback are welcome in your usual PolyAI support channel.
## 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.
More patterns and copy-paste examples in the [prompting guide](/agent-builder/prompting).
## 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 |
Heavy requests get broken down into smaller reasoning steps under the hood. You don't manage those directly; they appear inline in the conversation log.
## 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](/environments-and-versions/introduction); 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 to `Main`.
## 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 →](/agent-builder/usage-and-limits)
## A full session, step by step
The steps you'll repeat for most build work, with screenshots from a real session.
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.
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.
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.
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.
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.
After you send revisions, the plan is marked **Changes requested** and your feedback is shown above the regenerated plan.
When you **Approve**, the changes apply to your branch. Every applied edit is summarized in a **changes made** card.
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](/environments-and-versions/introduction) 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.
## Related pages
Patterns for getting consistently good results.
Your fair-use allowance, reset cadence, and what to do when you hit it.
The building blocks the assistant uses to structure conversations.
Knowledge the assistant reads from and writes to.
Promote the assistant's branches from `Main` to Live.