> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# 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](https://polyai.github.io/adk/)

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](https://docs.astral.sh/uv/) to manage Python and virtual environments.

```bash
# 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:

```bash
export POLY_ADK_KEY=<your-api-key>
```

Generate API keys from your account at [studio.poly.ai](https://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:

```text
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:

```yaml
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.

> **Warning**
>
> **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](/advanced/secrets/overview)

Store API keys and credentials securely for use in your functions

#### [Code-driven flows](/advanced/code-driven-flows/transition-functions)

Build flows with transition functions for complex conversation paths

#### [Agents API](/api-reference/build-deploy/agents-api/overview)

Create, configure, and deploy agents programmatically via REST

#### [Full ADK docs](https://polyai.github.io/adk/)

Tutorials, examples, and complete CLI reference