Skip to content

Working locally

The PolyAI ADK is a CLI tool and Python package for managing PolyAI Agent Studio projects locally.

It provides a Git-like workflow for synchronizing project configuration between your local filesystem and the Agent Studio platform, so agent development can fit into normal engineering build, review, and collaboration cycles.

What “working locally” means

With the ADK, you are not building an agent only inside the browser.

Instead, you work with a project on your machine, where you can:

  • edit agent resources directly
  • review changes with Git-style workflows
  • validate changes before pushing
  • use AI coding tools such as Cursor or Claude Code
  • test and iterate before merging in Agent Studio

  • Local files

    Agent configuration lives on disk in a structured project directory.

  • CLI workflow

    Pull, edit, validate, push, and review changes using the poly CLI.

  • Platform sync

    Agent Studio remains the source of deployment, preview, and branch merging.

  • Developer tooling

    The local workflow works naturally with editors, terminals, and AI-assisted coding tools.

What a local project contains

Each local ADK project represents an Agent Studio project.

A project can define a voice or webchat agent, and its runtime behavior is controlled by resources such as flows, functions, topics, settings, and configuration files.

A typical project structure looks like this:

<account>/<project>/
├── _gen/                               # Generated stubs — do not edit
├── agent_settings/                     # Agent identity and behavior
│   ├── personality.yaml
│   ├── role.yaml
│   ├── rules.txt
│   └── experimental_config.json        # Optional
├── config/                             # Configuration
│   ├── entities.yaml                   # Optional
│   ├── handoffs.yaml                   # Optional
│   ├── sms_templates.yaml              # Optional
│   └── variant_attributes.yaml         # Optional
├── voice/                              # Voice channel settings
│   ├── configuration.yaml
│   ├── speech_recognition/
│   └── response_control/
├── chat/                               # Chat channel settings
│   └── configuration.yaml
├── flows/                              # Optional — flow definitions
├── functions/                          # Global functions
├── topics/                             # Knowledge base topics
└── project.yaml                        # Project metadata

Generated files

Files under _gen/ are generated stubs and should not be edited directly.

How local work maps to Agent Studio

The ADK does not replace Agent Studio. It acts as the local development layer around it.

A typical flow looks like this:

  1. initialize or pull a project locally
  2. create or switch to a branch
  3. edit resources on disk
  4. validate and inspect changes
  5. push changes back to Agent Studio
  6. test and review the branch in Agent Studio
  7. merge when ready

This means the local filesystem becomes your main editing surface, while Agent Studio remains the place where work is previewed, reviewed, and deployed.

Standard CLI workflow

The standard workflow is:

  1. initialize the local project with poly init if it is not already present
  2. pull the latest project configuration with poly pull
  3. create a branch with poly branch create {name}
  4. edit files locally
  5. inspect changes with poly diff and poly status
  6. validate locally with poly validate
  7. push changes with poly push
  8. test and chat with the agent using poly chat
  9. optionally generate a review gist with poly review
  10. merge the branch in Agent Studio

Run commands from the project folder

ADK commands are expected to be run from within the local project directory. If needed, use the --path flag to point to a project explicitly.

Resource reference syntax

Many ADK resources support references to other resources or values.

These placeholders are used in prompts, rules, topic actions, and related text fields:

Syntax Resolves to Common use
{{fn:function_name}} Global function Rules, topic actions, advanced step prompts
{{ft:function_name}} Flow transition function Advanced step prompts within the same flow
{{entity:entity_name}} Collected entity value Flow prompts
{{attr:attribute_name}} Variant attribute Rules, prompts, greetings, personality, role
{{twilio_sms:template_name}} SMS template Rules, topic actions
{{ho:handoff_name}} Handoff destination Rules
{{vrbl:variable_name}} State variable Prompts, topic actions, SMS templates

These references make the local project composable: settings, prompts, and behaviors can refer to resources by name rather than hard-coding values.

Why local development matters

Working locally makes the ADK especially useful for teams that want to:

  • review changes before deployment
  • reuse patterns across projects
  • work with large or complex resource trees
  • generate or modify resources using coding agents
  • fit agent development into existing engineering processes

A Git-like workflow for Agent Studio

The ADK is easiest to understand if you think of it as a synchronization layer between your local project files and the Agent Studio platform.