> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/extend/adk",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Agent Development Kit (ADK)

> Python CLI and package for building, managing, and deploying PolyAI agents locally.

The Agent Development Kit (ADK) is a Python CLI (`polyai-adk` on PyPI) for building PolyAI agents locally. Pull your Agent Studio project as YAML and Python files, edit with any tool, and push changes back — all from the command line.

<Note>
  For installation, authentication, and usage instructions, visit the [ADK documentation](https://polyai.github.io/adk/).
</Note>

<Note>
  New users must currently sign up for an account at [studio.poly.ai](https://studio.poly.ai) (not [studio.us.poly.ai](https://studio.us.poly.ai)).
</Note>

## Why use ADK

<CardGroup cols={3}>
  <Card title="Bulk authoring" icon="layer-group">
    Generate topics, flows, or entities programmatically — push in one command
  </Card>

  <Card title="Version control" icon="code-branch">
    YAML and Python files work with any version control system for reviews and rollback
  </Card>

  <Card title="AI-assisted editing" icon="wand-magic-sparkles">
    Edit YAML and Python files with coding assistants (Cursor, Claude Code, etc.), then push
  </Card>

  <Card title="CI/CD pipelines" icon="rotate">
    Run `poly push` in GitHub Actions or any CI/CD pipeline
  </Card>

  <Card title="Multi-project workflows" icon="diagram-project">
    Manage multiple agent projects from one environment
  </Card>

  <Card title="No UI required" icon="terminal">
    Build, test, and deploy agents entirely from the command line
  </Card>
</CardGroup>

## How it works

ADK uses a pull-edit-push workflow:

<Steps>
  <Step title="Initialize">
    Link a local directory to an Agent Studio project with `poly init`.
  </Step>

  <Step title="Pull">
    Run `poly pull` to download your project as structured YAML files organized by resource type — topics, flows, entities, and agent settings.
  </Step>

  <Step title="Edit">
    Edit with any tool — IDE, scripts, or AI coding assistants. YAML handles configuration, Python handles functions.
  </Step>

  <Step title="Push">
    Run `poly push` to diff your local changes against the remote state and send updates to Agent Studio. Your agent updates immediately in the target environment.
  </Step>
</Steps>

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

## CLI commands

| Command     | Description                                        |
| ----------- | -------------------------------------------------- |
| `poly init` | Link a local directory to an Agent Studio project  |
| `poly pull` | Download the current project state as YAML files   |
| `poly push` | Diff local changes against remote and send updates |
| `poly docs` | Print documentation for any ADK resource type      |

## Project structure

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
topics/
  Frequently Asked Questions.yaml
  Billing Issues.yaml
flows/
  greeting/
    flow_config.yaml
    flow_step_welcome.yaml
    flow_step_billing_check.yaml
entities/
  billing_amount.yaml
agent_settings/
  role.yaml
  personality.yaml
  rules.yaml
```

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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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?
```

Cross-references between resources use human-readable name tags like `{{fn:check_billing}}` rather than raw IDs. ADK resolves these automatically at push time.

## Who it's for

* **Development teams** — version control, CI/CD, and code review for agent development
* **Teams at scale** — manage many agents from a single environment
* **Automation** — generate and update agents programmatically (e.g., create topics from a spreadsheet, then `poly push`)

## Get started

Installation, authentication, and usage instructions:

<Card title="ADK documentation" icon="book" href="https://polyai.github.io/adk/">
  Guides, CLI reference, and examples.
</Card>

## Related

<CardGroup cols={2}>
  <Card title="Extend with code" icon="code" href="/extend/introduction">
    Write Python functions and connect APIs in Agent Studio
  </Card>

  <Card title="API reference" icon="square-terminal" href="/api-reference/introduction">
    Update and configure agents with PolyAI's REST APIs
  </Card>
</CardGroup>