![PolyAI](logo.png)

# Agent Development Kit (ADK)

[![PyPI version](https://img.shields.io/pypi/v/polyai-adk)](https://pypi.org/project/polyai-adk/)
[![Python version](https://img.shields.io/pypi/pyversions/polyai-adk)](https://pypi.org/project/polyai-adk/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Develop with Claude Code](https://img.shields.io/badge/Develop%20with-Claude%20Code-DC9E63?logo=claude)](https://claude.ai/download)

A CLI and Python package for managing [Agent Studio](https://studio.us.poly.ai) projects locally. It provides a Git-like workflow for synchronizing project configurations between your local filesystem and the Agent Studio platform.

## Prerequisites

You must have access to a workspace in PolyAI Agent Studio before using this tool. Access and an API key are provided by your PolyAI contact. To request access to the PolyAI platform, reach out to [developers@poly-ai.com](mailto:developers@poly-ai.com).

## Installation

```bash
pip install polyai-adk
```

Once installed, use the `poly` command to manage your projects:

```bash
poly init       # Initialize a project (interactive)
poly pull       # Pull latest configuration
poly push       # Push local changes
poly status     # View project status
poly diff       # View local changes
poly branch     # Manage branches
poly format     # Format resources
poly validate   # Validate configuration
poly review     # Create a review gist
```

## Usage
A whitelisted API key is needed to run any of the poly commands.

1. Create an API key at https://studio.[us/uk/eu].poly.ai/<account-name>/data-access
2. Contact an engineer from the developer platform team team to whitelist your API key on Kong
3. Add the key to your env variable (typically ~/.zshrc or ~/.bashrc), and name it POLY_ADK_KEY

Once you do that, you'll be able to access agents under the <account-name> for the namespace in which the API key is generated.

*We are in the process of automating the whitelisting of the API key, and limiting the external ADK to just the production namespace.*

## Usage

Run `poly --help` to see all available commands and options. Each command also supports `--help` for detailed syntax (e.g. `poly push --help`).

### `poly init`

Initialize a new Agent Studio project locally. Runs interactively by default, prompting for region, account, and project. You can also pass these directly:

```bash
poly init
poly init --region us-1 --account_id 123 --project_id my_project
poly init --base-path /path/to/projects
poly init --format   # format resources after init
```

### `poly pull`

Pull the latest project configuration from Agent Studio:

```bash
poly pull
poly pull --force     # overwrite all local changes
poly pull --format    # format resources after pulling
```

### `poly push`

Push local changes to Agent Studio:

```bash
poly push
poly push --dry-run          # preview what would be pushed
poly push --skip-validation  # skip local validation before pushing
poly push --force            # overwrite remote changes
poly push --format           # format resources before pushing
```

### `poly status`

View changed, new, and deleted files in your project:

```bash
poly status
```

### `poly diff`

Show diffs between your local project and the remote version:

```bash
poly diff              # all changes
poly diff file1.yaml   # specific files
```

### `poly revert`

Revert local changes:

```bash
poly revert --all                  # revert everything
poly revert file1.yaml file2.yaml  # revert specific files
```

### `poly branch`

Manage branches (default branch is `main`):

```bash
poly branch list
poly branch current
poly branch create my-feature
poly branch switch my-feature
poly branch switch my-feature --force  # discard uncommitted changes
```

### `poly format`

Format project resources (Python via ruff, YAML/JSON via in-process formatting). Use `--check` to only report files that would change; use `--ty` to also run type checking.

```bash
poly format              # all resources
poly format file1.py     # specific files
poly format --check      # check only, no writes
```

### `poly validate`

Validate project configuration locally:

```bash
poly validate
```

### `poly review`

Create a GitHub gist for reviewing changes, similar to a pull request:

```bash
poly review                                      # local vs remote
poly review --before main --after feature-branch  # compare branches
poly review --delete                              # delete all review gists
```

### `poly chat`

Start an interactive chat session with your agent:

```bash
poly chat
poly chat --environment live
poly chat --channel webchat
poly chat --metadata   # show functions, flows, and state each turn
```

## Development Setup

### Prerequisites

- Python 3.14 or higher
- [uv](https://github.com/astral-sh/uv) (`brew install uv`)

### Getting Started

```bash
git clone https://github.com/PolyAI-LDN/local_agent_studio.git
cd local_agent_studio
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install
```

### Running Tests

```bash
pytest
```

Test files are located in `src/poly/tests/`.

### Project Structure

- `src/poly/cli.py` - CLI interface
- `src/poly/project.py` - Core project management
- `src/poly/resources/` - Resource type implementations
- `src/poly/handlers/` - API handler implementations
- `src/poly/tests/` - Test suite
- `src/poly/types/` - Python type definitions for the Agent Studio runtime

## Bugs & Feature Requests

Please report bugs or request features via the [GitHub Issues](https://github.com/PolyAI-LDN/local_agent_studio/issues) page.

## Contributing

Contributions are welcome! The project uses **ruff** for linting/formatting (enforced via pre-commit hooks) and **pytest** for testing. Please ensure all tests pass before submitting a pull request.

We recommend using [Claude Code](https://claude.ai/download) for development. The repo includes a `.claude/` directory with project-specific instructions and permissions pre-configured.

## Releases

This project uses [python-semantic-release](https://python-semantic-release.readthedocs.io/) to automate versioning and publishing. Version bumps are determined from [conventional commit](https://www.conventionalcommits.org/) messages:

| Commit prefix | Version bump | Example |
|---|---|---|
| `fix:` | Patch (2.0.4 → 2.0.5) | `fix: handle missing config file` |
| `feat:` | Minor (2.0.4 → 2.1.0) | `feat: add poly export command` |
| `feat!:` / `BREAKING CHANGE:` | Major (2.0.4 → 3.0.0) | `feat!: redesign resource schema` |
| `chore:`, `docs:`, `ci:` | No release | `docs: update README` |

When a commit is merged to `main`, the release workflow automatically:

1. Determines the next version from commit history
2. Updates the version in `pyproject.toml`
3. Creates a git tag and GitHub Release

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.