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

# Getting started with PolyAI

> Install the PolyAI ADK and run poly setup to go from an empty machine to a local Agent Studio project you can edit, push, and deploy.

The fastest way to get up and running is entirely from the command line. Two steps — install the ADK, then run `poly setup` — take you from an empty machine to a local project you can edit, push, and deploy.

Using an AI coding assistant? See [Set up with an AI coding assistant](https://docs.poly.ai/adk/get-started/agentic-setup.md) to hand it the whole setup with one prompt.

***

## Step 1 — Install the ADK

You need **uv** to manage the Python environment. If you already have it, skip the first line.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -LsSf https://astral.sh/uv/install.sh | sh   # or: brew install uv
```

Then create a virtual environment and install the ADK:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv venv --python=3.14 --seed
source .venv/bin/activate
pip install polyai-adk
```

Confirm it worked:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly --help
```

> [!NOTE]
>
> **Suppress SyntaxWarnings from platform-generated code**
>
> Platform-generated code uses regex patterns (such as `\d`) that trigger `SyntaxWarning` in Python 3.14's stricter string handling. This produces 40+ warning lines on every `poly` command and obscures normal output.
>
> To suppress them, set this before running any `poly` command:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> export PYTHONWARNINGS=ignore
> ```

> [!TIP]
>
> **Optional — install the VS Code / Cursor extension**
>
> If you plan to work in **VS Code** or **Cursor**, you can also install the [PolyAI ADK extension](https://docs.poly.ai/adk/reference/tooling.md#polyai-adk-extension-for-vs-code-and-cursor) for resource-aware editing on top of the CLI. The extension is additive — the `poly` command remains the source of truth for every workflow.

## Step 2 — Run `poly setup`

One command handles the rest of onboarding, for both self-serve and enterprise accounts:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly setup
```

It runs four steps, skipping any that are already done — so it's safe to re-run at any time:

1. **Sign in** — opens a browser window, fetches (or creates) an API key for your user, and saves it to `~/.poly/credentials.json` so future `poly` commands pick it up automatically. This can be on any device, not just the machine running the CLI.
2. **Shell completion** — installs tab completion for bash, zsh, or fish.
3. **AI agent skills** — installs the ADK's skills into coding agents detected on your machine (Claude Code, Cursor, Codex, and others), so they know the `poly` workflow.
4. **Project** — optionally creates a new Agent Studio project or connects an existing one.

You're prompted to pick a region when signing in. Choose based on your account type, or pass it directly to skip the prompt:

| Region | Account type |
| - | - |
| `studio` | Self-serve — signed up at [studio.poly.ai](https://studio.poly.ai) |
| `us-1`, `euw-1`, `uk-1` | Enterprise — a workspace provisioned by PolyAI |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly setup --region studio   # or us-1, euw-1, uk-1
```

If you're not sure which account type you have, your PolyAI contact can confirm.

> [!TIP]
>
> **Already signed in?**
>
> If `poly setup` detects an existing API key (from the credential file or an environment variable), it skips straight past authentication to the remaining steps.

### Sign in only — `poly login`

To set up credentials without the rest of `poly setup`, `poly login` runs just the sign-in step:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly login --region us-1   # or euw-1, uk-1, studio
```

`poly login`:

1. Opens a browser window so you can sign in.
2. Fetches (or creates) an API key for your user.
3. Saves it to `~/.poly/credentials.json` under the region you specified, so future `poly` commands pick it up automatically.

If you omit `--region`, the CLI prompts you to pick one. To sign in to more than one region from the same machine, re-run `poly login` with each region — the credential file stores them side by side.

### Need an API key for the PolyAI APIs or Dialog RSN? — `poly apikey`

`poly apikey` is a separate, non-interactive command for getting an account API key into `POLY_API_KEY` for use in your own code (the PolyAI APIs, Dialog RSN) — it's not for setting up the ADK itself, and it's the command behind [Set up with an AI coding assistant](https://docs.poly.ai/adk/get-started/agentic-setup.md).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly apikey --region studio
```

#### Manual API key export

If you'd rather create the key yourself in the Agent Studio UI:

1. Log in to Agent Studio for your region and open your workspace.
2. In the **API Keys** tab (next to the **Users** tab), click **+ API key**.

![Generating an API key in Agent Studio — API Keys tab selected, showing the + API key button in the top-right](https://mintcdn.com/polyai/Q1iSzph0uOFxTBjX/adk/assets/api-keys-tab.png?fit=max\&auto=format\&n=Q1iSzph0uOFxTBjX\&q=85\&s=224f1046f4d7895187674ff0ee62f297)

Then export the key:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POLY_ADK_KEY=<your-api-key>
```

To make it permanent, add the export line to your shell profile (`~/.zshrc` or `~/.bashrc`). If you work across more than one region, use the region-scoped variables in [per-region API keys](#per-region-api-keys) below.

> [!NOTE]
>
> **How the ADK resolves API keys**
>
> The ADK checks for credentials in the following order:
>
> 1. **Credential file** — `~/.poly/credentials.json` (written by `poly setup` or `poly login`)
> 2. **Region-specific env var** — e.g. `POLY_ADK_KEY_US`
> 3. **General env var** — `POLY_ADK_KEY`
>
> The first match wins. If nothing is found, the CLI raises an error.

## Step 3 — Start building

If `poly setup` created a project for you, `cd` into the project directory. Otherwise, connect to an existing project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly init
```

[`poly init`](https://docs.poly.ai/adk/reference/cli#poly-init) walks you through interactive dropdowns to pick a region, account, and project, then pulls the configuration locally.

From inside your project directory, the core workflow is:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly status              # see what's changed
poly diff                # inspect changes in detail
poly branch create dev   # work on a branch
poly push                # push changes to Agent Studio
poly chat                # talk to your agent
```

Edit flows, functions, topics, and other resources in your editor of choice — they're just YAML and Python files. Push when you're ready to test in Agent Studio.

> [card] [Build an agent with the ADK](https://docs.poly.ai/adk/tutorials/build-an-agent.md)
>
> Follow the full step-by-step tutorial for local development.

> [card] [First commands](https://docs.poly.ai/adk/get-started/first-commands.md)
>
> Explore the full set of CLI commands available to you.

***

## Seed an agent from your website

If you're starting from scratch and want a working baseline, you can generate an agent from your company website inside Agent Studio. This gives you topics and agent settings pre-populated from your site's public content — a useful starting point before building locally.

1. Open [Agent Studio](https://studio.poly.ai) for self-serve, or your region's URL for enterprise, and sign in with the same account you authenticated with above.
2. Click **+ Agent** → **Quick Agent Setup**.
3. Enter your website URL and click **Create agent**.

![Quick setup button Agent Studio](https://mintcdn.com/polyai/Q1iSzph0uOFxTBjX/adk/assets/quick-agent-setup.png?fit=max\&auto=format\&n=Q1iSzph0uOFxTBjX\&q=85\&s=ed584e06cd2635031e9b894bb5657228)

Agent Studio crawls your site and generates a configuration — usually within a few minutes. Once it's ready, pull it into your local project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly pull
```

> [!TIP]
>
> **What gets generated**
>
> Agent Studio populates **topics** (knowledge base entries) and basic **agent settings** (personality, role, rules) from your website's public content. It does not generate flows, variants, entities, handoffs, or integrations — those are for you to build locally with the ADK.

***

## Already have an agent in Agent Studio?

If you have an existing project — built in the browser, by a PolyAI team, or by any other method — connect it to the ADK with `poly init` once your API key is set up:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Any account type:
poly setup --region studio       # or us-1, euw-1, uk-1 — sign in and save your API key (skip if already done)
poly init                        # interactive prompts to pick region, account, and project

# Sign-in only (poly login):
poly login --region us-1         # or euw-1, uk-1, studio
poly init

# Enterprise accounts (manual key export, fallback):
export POLY_ADK_KEY=<your-api-key>   # see "Manual API key export" above
poly init
```

`poly init` creates a local directory and pulls the full project configuration. From there the standard `poly status` / `poly push` / `poly pull` workflow applies.

***

## Per-region API keys

If you work across multiple regions, you can set region-scoped environment variables. The ADK checks the credential file first, then region-scoped env vars, then `POLY_ADK_KEY`.

| Region | Environment variable |
| - | - |
| `us-1` | `POLY_ADK_KEY_US` |
| `euw-1` | `POLY_ADK_KEY_EUW` |
| `uk-1` | `POLY_ADK_KEY_UK` |
| `studio` | `POLY_ADK_KEY_STUDIO` |
| `staging` | `POLY_ADK_KEY_STAGING` |
| `dev` | `POLY_ADK_KEY_DEV` |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POLY_ADK_KEY_US=<your-us-api-key>
export POLY_ADK_KEY=<your-fallback-api-key>   # used for any other region
```

***

## Next step

> [card] [What is the ADK?](https://docs.poly.ai/adk/get-started/what-is-the-adk.md)
>
> Understand what the ADK does and how it fits into Agent Studio.
