Build an agent with the ADK

This guide walks through how to go from a blank slate to a production-ready voice agent using Agent Studio, the PolyAI ADK, and — optionally — the PolyAI ADK extension for VS Code or Cursor, or a coding agent such as Claude Code. There are two common ways to build with the ADK:

Workflow	Description
CLI workflow	The hands-on developer path. You run the commands yourself, edit files locally, and push changes back to Agent Studio.
AI-agent workflow	You provide a brief; a coding tool uses the ADK to generate and push the project files on your behalf.

You provide context

Gather the requirements, business rules, API information, and reference material.

The agent or developer builds

Using the ADK, the project files are created, edited, validated, and prepared locally.

Agent Studio hosts and publishes

The generated work is pushed back into Agent Studio, where it can be reviewed and published.

Architecture at a glance

Role	Responsibility
You	Provide requirements, project context, and business rules
PolyAI ADK	Connect the local project to Agent Studio and manage sync, validation, and tooling
Coding agent	Optionally generate and update files using the ADK
Agent Studio	Host, preview, review, and publish the agent

Local project structure

See Working locally — What a local project contains for the full directory tree. In short, the project mirrors what Agent Studio understands: agent_settings/, flows/, functions/, topics/, voice/, chat/, and config/.

Workflow 1 - CLI workflow

The CLI workflow is the manual developer path. You use the ADK directly, edit the project locally, and push changes back to Agent Studio. You can run this workflow in whichever editing surface you prefer: a plain terminal, or VS Code / Cursor with the PolyAI ADK extension for resource-aware navigation and validation. Both count as the CLI workflow — the difference is only the editing surface.

Step 1 - Initialize your project

Link a local folder to an existing Agent Studio project. The agent must already exist in Agent Studio.

poly init

poly init walks you through interactive dropdowns for region, account, and project. It creates the project directory and pulls the current configuration. Change into the project directory before running any further commands. See First commands for flag options and details.

Step 2 - Set up the environment

Configure any API keys or environment variables needed for the project. poly init pulls the current configuration automatically, but you can run poly pull at any time to refresh it:

poly pull
poly pull -f

Run commands from the project folderAll CLI commands should be run from within the local project folder, unless you explicitly use the relevant path flag.

Step 3 - Chat with the agent

Start an interactive chat session to confirm the connection works and inspect runtime behavior.

poly chat runs against Agent Studio, not your local filespoly chat connects to the last pushed state of your current Branch (or to the sandbox deployment when you are on main). Push first, or use poly chat --push.

poly chat
poly chat --environment sandbox --channel voice
poly chat --functions --flows --state

Step 4 - Review the docs and understand the SDK

Use the CLI docs command to inspect the available resources and learn how they fit together.

poly docs --all
poly docs flows functions topics

Resource-specific documentation is available in the reference section: agent settings, voice settings, chat settings, flows, functions, topics, entities, handoffs, variants, SMS templates, variables, speech recognition, response control, safety filters, languages, translations, and experimental config.

Step 5 - Customize the agent

This is the core build phase. Create a Branch, edit resources locally, track changes, and push them back.

Read the anti-patterns page firstBefore editing, review the common anti-patterns to avoid flow control bugs, logging noise, and prompt logic mistakes that are easy to introduce but hard to debug.

Branching

poly branch create my-feature
poly branch switch my-feature
poly branch current
poly branch list

Functions

Create or modify backend functions the agent calls at runtime. See the functions reference for the full API. Typical locations include:

global functions under the functions directory
lifecycle hooks such as start and end functions
flow-scoped functions
function steps inside flows

Topics

Add or edit knowledge-base topics used for retrieval.

Agent settings

Update the personality, role, and rules that define the agent’s global behavior.

Flows

Build conversation flows, including prompts, step transitions, entities, and function steps.

Channel-specific settings

Adjust greeting messages, disclaimers, and style prompts for voice and chat.

Safety filters

Configure content safety filtering at the project level and per channel.

Handoffs, SMS, and variants

Define escalation paths, SMS templates, and per-variant configuration.

Languages and translations

Configure supported languages and localized text strings for multilingual agents.

ASR and response control

Tune speech recognition and control TTS behavior.

Experimental config

Enable or tune experimental features where needed.

Step 6 - Track and validate changes

Inspect the local changes before pushing.

poly status
poly diff
poly diff --files <file>
poly validate
poly format
poly revert
poly revert <file>

poly format may crash on projects with YAML sub-resourcesRunning poly format on a project that contains YAML-defined sub-resources (such as config/handoffs.yaml or voice/configuration.yaml) can produce errors like:

[Errno 20] Not a directory: '.../config/handoffs.yaml/handoffs/Default_handoff'

This is a known bug in how the formatter resolves paths inside YAML files. Use --files to format specific Python files instead:

poly format --files functions/my_function.py

poly validate may fail on platform-generated functionsProjects built via Quick Agent Setup often include server-generated functions such as handoff.py or hangup.py whose signatures do not declare a conv: Conversation parameter. The ADK’s local validator will reject these, blocking poly push.The cleanest fix is to add conv: Conversation to the function signature yourself:

def handoff(conv: Conversation):
    ...

Alternatively, skip local validation and let the platform validate the push instead:

poly push --skip-validation

Step 7 - Push changes

Push the local changes back to Agent Studio.

poly push
poly push --dry-run
poly push -f
poly push --skip-validation

Step 8 - Test in Sandbox

Your Branch lives in Sandbox, so you can test it before you publish. Run poly chat on the Branch to chat against its last pushed state. Add --environment sandbox to chat against the sandbox deployment of main instead of your Branch.

Pushing before chattingPush your latest changes before chatting, because poly chat connects to the last pushed state. Target a specific environment with --environment sandbox, --environment pre-release (Staging), or --environment live.

poly chat --environment sandbox
poly chat --environment sandbox --functions --flows

Step 9 - Iterate on quality

Review, refine, and test again. You can also use the review command to share diffs with teammates.

poly review create
poly review create --before main --after my-feature

Make test calls, inspect transcripts, refine prompts, flows, and functions, and then re-push.

Step 10 - Publish to Live

Once the changes are pushed and validated, publish the Branch to Live. Publishing merges the Branch’s changes onto Live and creates a new version you can roll back to. To try the agent on a real phone number first, move the Branch to Staging (Branches and Sub-branches modes only). See Environments and versions.

Publishing from the CLI or the Agent Studio web UIFrom the CLI, run poly branch merge '<commit message>' to merge the current Branch into main. On the new deployment system, merging into main publishes the Branch to Live. In the Agent Studio web UI, open the Branch and click Publish in the top-right corner. Test the Branch with poly chat before you merge. See the Branch merging reference for the full conflict-resolution flow.

Step 11 - Monitor performance

Use Agent Studio analytics to monitor containment, CSAT, handle time, and flagged transcripts. Pull changes back locally as needed and continue iterating.

Workflow 2 - AI-agent workflow

The AI-agent workflow uses a coding agent — such as Claude Code, or an in-editor agent in VS Code or Cursor paired with the PolyAI ADK extension — to run the same development loop on your behalf.

You provide the brief

Requirements, business rules, integrations, and API documentation.

The coding tool generates the project

It uses the ADK to read documentation, generate files, and push the result.

You review and publish

Agent Studio remains the place where the work is checked and published.

Step 1 - Gather requirements

Collect the project context before you begin. Include anything the coding tool will need to produce a working agent:

API endpoint URLs
business rules
use-case descriptions
internal notes or emails
reference material
links to API documentation

The more complete and structured your input is, the less correction the output requires.

Front-load the contextGather everything up front. Providing context piecemeal produces piecemeal output.

Step 2 - Create a new project in Agent Studio

Open Agent Studio and create a brand-new project. The project starts empty:

no knowledge base
no flows
no configuration

That blank starting point is intentional. The coding tool populates the project in later steps.

Think of Agent Studio as the deployment targetAgent Studio is where the project lives, but the coding tool generates the actual content.

Step 3 - Start the coding tool via the CLI

Open your terminal and start the coding tool. At this stage:

the ADK must already be installed
the Agent Studio project must already exist
the coding tool should initialize and link the project using the ADK

poly init --region <region> --account_id <account_id> --project_id <project_id>

poly init pulls the current configuration automatically — there is no need to run poly pull separately. The ADK acts as the bridge between your local environment and Agent Studio, letting the coding tool read from and write back to the project.

Run poly docs --all before generating any filesImmediately after initializing, run poly docs --all to produce a complete resource reference. Without it, a coding agent has no schema context for resource structure and field names, and will hallucinate them.Note that poly docs --all documents the ADK’s resource layer (topics, flows, entities, variants, and so on) but does not cover every runtime Conversation method. In particular, conv.send_sms_template, conv.send_sms, and conv.caller_number are not present in the output. For the full runtime API, direct the coding agent to the conv object reference on the platform docs.

Step 4 - Give the coding tool its context

Provide the coding tool with the information you gathered earlier. Include:

project-specific requirements
the URL to the business’s public API documentation
relevant internal context
useful patterns or best practices from previous projects

Use the docs command to generate a reference file the coding tool can read:

poly docs --all

Step 5 - Generate the project files

Once the context is in place, the coding tool generates the project files. This produces the assets the agent needs, including:

Conversation flows

Dialog logic and routing for the agent.

Callable functions

Backend functions used during calls.

Knowledge base entries

Information the agent can reference when answering questions.

API integrations

Both real API connections and mock endpoints for testing.

The generated files follow ADK structure and are ready to push to Agent Studio.

Step 6 - Push to Agent Studio

Once the files are generated, use the ADK to push them to Agent Studio. A new Branch is created in the project so the generated work can be reviewed safely before anything goes live. When you switch to that Branch in Agent Studio, you should see the generated changes, such as:

updated greeting messages
new knowledge base entries
a built tracking flow
real and mock API integrations

Use the Branch review stepThe Branch-based workflow makes it possible to inspect what was generated before publishing it to Live.

Step 7 - Review and publish

Review the generated work inside Agent Studio. Check that the key parts of the agent look correct:

flows
functions
knowledge base entries
API integrations

Once everything looks right, publish the Branch to Live. From the CLI, merge it into main with poly branch merge; on the new deployment system that publishes it. In the Agent Studio web UI, open the Branch and click Publish in the top-right corner. At that point, the agent is live.

CLI command overview

Command	Description
poly init	Initialize a new project locally
poly pull	Pull remote config into the local project
poly push	Push local changes to Agent Studio
poly status	List changed files
poly diff	Show diffs
poly revert	Revert local changes
poly branch	Branch management
poly format	Format resource files
poly validate	Validate project configuration locally
poly review	Create a diff review page
poly chat	Start an interactive session with the agent
poly docs	Output resource documentation

The overall loop

create or connect a project
build locally using the ADK
push to Agent Studio
review and publish

Next steps

Restaurant booking agent

Apply the workflow to a real-world example with flows, functions, and variants.

Core concepts

Understand resource architecture, local development patterns, and team workflows.

CLI reference

Explore the available ADK commands and options.

You provide context

The agent or developer builds

Agent Studio hosts and publishes

​Architecture at a glance

​Local project structure

​Workflow 1 - CLI workflow

​Step 1 - Initialize your project

​Step 2 - Set up the environment

​Step 3 - Chat with the agent

​Step 4 - Review the docs and understand the SDK

​Step 5 - Customize the agent

​Branching

​Functions

​Topics

​Agent settings

​Flows

​Channel-specific settings

​Safety filters

​Handoffs, SMS, and variants

​Languages and translations

​ASR and response control

​Experimental config

​Step 6 - Track and validate changes

​Step 7 - Push changes

​Step 8 - Test in Sandbox

​Step 9 - Iterate on quality

​Step 10 - Publish to Live

​Step 11 - Monitor performance

​Workflow 2 - AI-agent workflow

You provide the brief

The coding tool generates the project

You review and publish

​Step 1 - Gather requirements

​Step 2 - Create a new project in Agent Studio

​Step 3 - Start the coding tool via the CLI

​Step 4 - Give the coding tool its context

​Step 5 - Generate the project files

Conversation flows

Callable functions

Knowledge base entries

API integrations

​Step 6 - Push to Agent Studio

​Step 7 - Review and publish

​CLI command overview

​The overall loop

​Next steps

Restaurant booking agent

Core concepts

CLI reference

Architecture at a glance

Local project structure

Workflow 1 - CLI workflow

Step 1 - Initialize your project

Step 2 - Set up the environment

Step 3 - Chat with the agent

Step 4 - Review the docs and understand the SDK

Step 5 - Customize the agent

Branching

Functions

Topics

Agent settings

Flows

Channel-specific settings

Safety filters

Handoffs, SMS, and variants

Languages and translations

ASR and response control

Experimental config

Step 6 - Track and validate changes

Step 7 - Push changes

Step 8 - Test in Sandbox

Step 9 - Iterate on quality

Step 10 - Publish to Live

Step 11 - Monitor performance

Workflow 2 - AI-agent workflow

Step 1 - Gather requirements

Step 2 - Create a new project in Agent Studio

Step 3 - Start the coding tool via the CLI

Step 4 - Give the coding tool its context

Step 5 - Generate the project files

Step 6 - Push to Agent Studio

Step 7 - Review and publish

CLI command overview

The overall loop

Next steps