Skip to content

Working locally

With the ADK, you work on Agent Studio projects from your local machine instead of exclusively through the browser.

Your local filesystem becomes your primary editing surface. You can:

  • edit agent resources directly
  • review changes with Git-style workflows
  • validate changes before pushing
  • work in VS Code or Cursor with the PolyAI ADK extension, or pair the ADK with AI coding agents such as 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 and preview. Branches can be merged with poly branch merge from the CLI or through the Agent Studio UI.

  • 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
│   ├── languages.yaml                  # Optional
│   ├── personality.yaml
│   ├── role.yaml
│   ├── rules.txt
│   ├── safety_filters.yaml             # Optional
│   └── experimental_config.json        # Optional
├── config/                             # Configuration
│   ├── entities.yaml                   # Optional
│   ├── handoffs.yaml                   # Optional
│   ├── sms_templates.yaml              # Optional
│   ├── translations.yaml               # Optional
│   └── variant_attributes.yaml         # Optional
├── voice/                              # Voice channel settings
│   ├── configuration.yaml
│   ├── safety_filters.yaml             # Optional
│   ├── speech_recognition/
│   └── response_control/
├── chat/                               # Chat channel settings
│   ├── configuration.yaml
│   └── safety_filters.yaml             # Optional
├── flows/                              # Optional - flow definitions
├── functions/                          # Global functions
├── topics/                             # Knowledge base topics
├── test_suite/                         # Optional - simulated conversation tests
└── 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

See the CLI working pattern for the full step-by-step. The short version: init → pull → branch → edit → validate → push → review → merge → chat.

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 let settings, prompts, and behaviors point to resources by name rather than repeating hard-coded values.

A Git-like workflow for Agent Studio

Think of the ADK as a synchronization layer between your local files and the Agent Studio platform.