Skip to content

Build an agent with the ADK

Early access

The PolyAI ADK is currently in Early Access. Availability is limited, and some functionality may change before general release.

Join the waitlist

This guide walks through how to go from a blank slate to a production-ready voice agent with a real backend using Agent Studio, the PolyAI ADK, and optionally 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 A coding agent uses the ADK on your behalf, generating and pushing the project files from a brief.

  • 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 deploys

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

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, merge, and deploy the agent

Local project structure

When an Agent Studio project is linked locally, it follows this general structure:

<account>/<project>/
├── agent_settings/
│   ├── personality.yaml
│   ├── role.yaml
│   ├── rules.txt
│   └── experimental_config.json
├── config/
│   ├── entities.yaml
│   ├── handoffs.yaml
│   ├── sms_templates.yaml
│   └── variant_attributes.yaml
├── voice/
│   ├── configuration.yaml
│   ├── speech_recognition/
│   │   ├── asr_settings.yaml
│   │   ├── keyphrase_boosting.yaml
│   │   └── transcript_corrections.yaml
│   └── response_control/
│       ├── pronunciations.yaml
│       └── phrase_filtering.yaml
├── chat/
│   └── configuration.yaml
├── flows/
│   └── {flow_name}/
│       ├── flow_config.yaml
│       ├── steps/
│       │   └── {step_name}.yaml
│       ├── function_steps/
│       │   └── {function_step}.py
│       └── functions/
│           └── {function_name}.py
├── functions/
│   ├── start_function.py
│   ├── end_function.py
│   └── {function_name}.py
├── topics/
│   └── {topic_name}.yaml
└── project.yaml

This structure mirrors the parts of the agent that Agent Studio understands: settings, flows, functions, topics, channel configuration, and supporting resources.

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.

Step 1 — Initialise your project

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

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

This creates the local project structure and writes the metadata needed to connect the folder to Agent Studio.

Step 2 — Pull remote config and set up the environment

Pull the current configuration into your local project.

poly pull
poly pull -f

At this point, configure any API keys or environment variables needed for the project.

Run commands from the project folder

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

Step 3 — Run the agent locally

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

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 for agent settings, voice settings, chat settings, flows, functions, topics, entities, handoffs, variants, SMS templates, variables, speech recognition, response control, and experimental config.

Step 5 — Customise the agent

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

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.

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 behaviour.

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.

Handoffs, SMS, and variants

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

ASR and response control

Tune speech recognition and control TTS behaviour.

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 <file>
poly validate
poly format
poly revert --all
poly revert <file>

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 against sandbox

Validate the behaviour in the sandbox environment.

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
poly review --before main --after my-feature

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

Step 10 — Deploy to production

Once the changes are pushed and validated, merge the branch in Agent Studio and deploy the project.

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 to execute the same development loop on your behalf.

  • You provide the brief

    Requirements, business rules, integrations, and API documentation.

  • The coding agent generates the project

    It uses the ADK to inspect the SDK, generate files, and push the result.

  • You review and deploy

    Agent Studio remains the place where the work is checked, merged, and deployed.

No manual flow-building required

In this workflow, the coding agent does the heavy lifting of building the agent, while Agent Studio remains the place where the work is reviewed, tested, and deployed.

Step 1 — Gather requirements

Collect the project context before you begin.

This should include anything the coding agent will need in order to produce a working agent, such as:

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

The more complete and structured the input is, the better the generated output is likely to be.

Front-load the context

This workflow works best when you gather the important information up front rather than feeding it in piecemeal later.

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 agent will populate the project in later steps.

Think of Agent Studio as the deployment target

Agent Studio is where the project lives, but the coding agent does most of the actual building work.

Step 3 — Launch the coding agent via the CLI

Open your command line interface and launch your coding agent.

At this stage:

  • the ADK must already be installed
  • the Agent Studio project must already exist
  • the coding agent should be linked to the project using the ADK

A typical starting point is:

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

The ADK acts as the bridge between your local development environment and Agent Studio in the cloud. It allows the coding agent to read from and write back to the project.

Step 4 — Feed context to the coding agent

Now provide the coding agent with the information you gathered earlier.

This is the core input step. Include:

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

The coding agent can also use the docs command to inspect the SDK and understand the available resources.

poly docs --all

Reusing proven patterns from earlier projects can improve both speed and output quality.

Step 5 — Let the agent build

Once the context has been provided, let the coding agent generate the project files.

The coding agent can produce the assets needed for the agent, including:

  • Conversation flows

    Dialogue 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 assets are structured for Agent Studio and prepared to be pushed back to the platform.

Step 6 — Push back to Agent Studio

Once the coding agent has generated the project files, it uses the ADK to push them back into 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 step

The branch-based workflow makes it possible to inspect what was generated before merging it into the main project.

Step 7 — Review, merge, and deploy

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:

  1. merge the branch into the main project
  2. deploy the project

At that point, the agent is live.

CLI command overview

Command Description
poly init Initialise 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

Summary

Metric Value
Manual workflow Supported
AI-agent workflow Supported
Production-ready path Yes

The overall loop is straightforward:

  1. create or connect a project
  2. build locally using the ADK
  3. push to Agent Studio
  4. review, merge, and deploy

Next steps