Agent Development Kit (ADK)

Python CLI for building, managing, and deploying PolyAI agents locally with a Git-like pull-edit-push workflow.

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.

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

2. Pull

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

3. Branch

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

4. Edit

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

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

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

1. 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
   
2. 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