Agent Development Kit (ADK)

The Agent Development Kit (ADK) is a Python CLI for building PolyAI agents locally. Pull your Agent Studio project as YAML and Python files, edit in your IDE (or with a coding assistant like Claude), version with Git, and push from the command line.

Full ADK documentation

Installation, tutorials, CLI reference, and examples.

How it works

ADK uses a Git-like workflow: init → pull → branch → edit → validate → push → review → merge.

Initialize

Link a local directory to an Agent Studio project with poly init. Select your region, account, and project interactively or pass them as flags.

Pull

Run poly pull to download your project as structured YAML and Python files organized by resource type.

Branch

Use poly branch switch <name> to work on a branch, keeping your changes isolated from the live agent.

Edit

Edit with any tool — VS Code, Cursor, or AI coding assistants. YAML handles configuration, Python handles functions.

Validate and push

Run poly validate to check your changes locally, then poly push to diff against the remote state and send updates to Agent Studio.

Test

Run poly chat to start an interactive chat session with your agent and verify behavior before merging.

ADK is fully compatible with Agent Studio and the APIs. Switch between surfaces at any time.

Prerequisites

Install uv

ADK uses uv to manage Python and virtual environments.

# macOS
brew install uv
# Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

Authenticate

Self-serve accounts — run poly start to sign in automatically.

Enterprise accounts — run poly login --region <region>, or export your API key directly:

export POLY_ADK_KEY=<your-api-key>

Generate API keys from your account at studio.poly.ai.

CLI commands

Command	Description
`poly init`	Link a local directory to an Agent Studio project
`poly pull`	Download the current project state as YAML and Python files
`poly push`	Diff local changes against remote and send updates
`poly status`	View changed, new, and deleted files
`poly diff`	Show differences between local and remote
`poly validate`	Validate project configuration locally
`poly branch`	Manage project branches (`switch`, `delete`, `merge`)
`poly chat`	Start an interactive chat session with your agent
`poly format`	Format project resources
`poly review`	Create a GitHub gist for reviewing changes
`poly revert`	Revert local changes
`poly docs`	Print documentation for any ADK resource type

Run poly --help for the full list, or poly <command> --help for flags and options.

Project structure

After pulling, your local directory contains human-readable files organized by resource type:

agent_settings/        # Identity, behavior, personality, rules
  role.yaml
  personality.yaml
  rules.txt
topics/                # Knowledge base content (RAG-retrieved)
  Frequently Asked Questions.yaml
  Billing Issues.yaml
functions/             # Python business logic
  check_billing.py
flows/                 # Multi-step guided conversations
  greeting/
    flow_config.yaml
    flow_step_welcome.yaml
    flow_step_billing_check.yaml
config/                # Entities, handoffs, SMS templates, translations
  entities/
    billing_amount.yaml
  handoffs/
  sms_templates.yaml
  variant_attributes.yaml
voice/                 # Voice channel settings
chat/                  # Chat channel settings
test_suite/            # Conversation tests

Each YAML file represents a single resource. For example, a topic file:

enabled: true
actions: ""
content: |
  We accept Visa, Mastercard, and PayPal.
  Refunds take 3–5 business days.
example_queries:
  - What payment methods do you accept?
  - How long do refunds take?
  - Can I pay with PayPal?

Resource references

Cross-references between resources use human-readable placeholder tags. ADK resolves these automatically at push time.

Syntax	Reference type
`{{fn:function_name}}`	Global functions
`{{entity:entity_name}}`	Collected entity values
`{{attr:attribute_name}}`	Variant attributes
`{{ho:handoff_name}}`	Handoff destinations
`{{vrbl:variable_name}}`	State variables

Resource architecture

ADK resources fall into two categories:

Category	Resources	Purpose
Knowledge / facts	Topics	Subject-specific content retrieved via RAG when contextually relevant
Behavior / logic	Rules, flows, functions	Define what the agent does and when

Quick guide: Always-true instructions belong in rules.txt. Subject-specific information belongs in topics. Comparisons, calculations, or API calls belong in functions.

Common mistakes to avoid:

Putting behavioral instructions in topic content instead of topic actions
Putting facts in rules.txt — this wastes context; keep facts in topics
Using prose conditionals for branching — use Python functions instead, since models can’t reliably detect empty variables

Next steps

Secrets management

Store API keys and credentials securely for use in your functions

Code-driven flows

Build flows with transition functions for complex conversation paths

Agents API

Create, configure, and deploy agents programmatically via REST

Full ADK docs

Tutorials, examples, and complete CLI reference