diff --git a/docs/docs/assets/api-key-data-access.png b/docs/docs/assets/api-key-data-access.png new file mode 100644 index 0000000..7f13afc Binary files /dev/null and b/docs/docs/assets/api-key-data-access.png differ diff --git a/docs/docs/concepts/anti-patterns.md b/docs/docs/concepts/anti-patterns.md index aa02f0a..a2fd7c1 100644 --- a/docs/docs/concepts/anti-patterns.md +++ b/docs/docs/concepts/anti-patterns.md @@ -3,7 +3,7 @@ title: Common anti-patterns description: Avoid common mistakes when building flows, writing prompts, and handling control flow in the PolyAI ADK. --- -This page collects common implementation mistakes that make agents harder to reason about, harder to maintain, or more likely to behave incorrectly at runtime. +This page collects common implementation mistakes that make agents harder to predict, harder to maintain, or more likely to behave incorrectly at runtime. The general rule is simple: keep prompts focused on conversation, keep Python focused on deterministic logic, and make control flow explicit. @@ -71,9 +71,9 @@ Implement the check in Python and transition to the correct step or flow explici When branching logic is buried in prompts: -- behavior becomes harder to test +- behavior becomes harder to test and verify - routing becomes harder to debug -- the agent becomes more dependent on model interpretation for deterministic behavior +- deterministic behavior becomes dependent on how the model interprets the instruction
@@ -172,9 +172,8 @@ If the user is expected to answer, put the full question in the utterance and le ## Design principle -When in doubt: - - make control flow explicit - keep prompts conversational - keep code deterministic -- prefer simple, testable paths over clever prompt tricks \ No newline at end of file +- prefer simple, testable paths over clever prompt tricks + diff --git a/docs/docs/concepts/multi-user-and-guardrails.md b/docs/docs/concepts/multi-user-and-guardrails.md index f678edb..b463599 100644 --- a/docs/docs/concepts/multi-user-and-guardrails.md +++ b/docs/docs/concepts/multi-user-and-guardrails.md @@ -69,9 +69,7 @@ You can also use: ## Validation as a guardrail -Before pushing, the ADK can validate the project locally. - -This is one of the main guardrails in the workflow. It helps catch issues early, before they are pushed into Agent Studio. +Run `poly validate` before pushing to catch issues locally, before they reach Agent Studio. Examples of what validation protects against include: @@ -82,7 +80,7 @@ Examples of what validation protects against include: !!! info "Validate before pushing" - In collaborative workflows, `poly validate` should be treated as a normal part of the editing cycle, not as an optional afterthought. + In collaborative workflows, treat `poly validate` as a standard step in the editing cycle, not an optional one. ## Pulling and merge behavior @@ -94,25 +92,23 @@ poly pull If the pulled changes conflict with your own local edits, the ADK will merge them and surface merge markers where conflicts occur. -That means the local workflow is not isolated from Agent Studio UI work — both sides can affect branch state, and developers should be aware of that. +The local workflow is not isolated from Agent Studio UI work - both sides affect branch state. Keep that in mind when collaborating. ## Review workflow -When changes are ready for review, the ADK can help generate a review artifact using: +When changes are ready for review, generate a review artifact: ~~~bash poly review ~~~ -This can be used to compare: +Use this to compare: - local changes against the remote project - one branch against another - a feature branch against `main` or `sandbox` -A GitHub environment token is required for this step. - -The review flow is useful when you want to share changes without asking a reviewer to inspect the raw local filesystem. +A GitHub environment token is required. The output lets reviewers inspect changes without access to your local filesystem. ## Guardrails inherited from Agent Studio diff --git a/docs/docs/concepts/working-locally.md b/docs/docs/concepts/working-locally.md index 6a06fab..438518d 100644 --- a/docs/docs/concepts/working-locally.md +++ b/docs/docs/concepts/working-locally.md @@ -3,15 +3,9 @@ title: Working locally description: Understand how the PolyAI ADK maps Agent Studio projects onto a local development workflow. --- -The **PolyAI ADK** is a CLI tool and Python package for managing **PolyAI Agent Studio** projects locally. +With the ADK, you work on Agent Studio projects from your local machine instead of exclusively through the browser. -It provides a Git-like workflow for synchronizing project configuration between your local filesystem and the Agent Studio platform, so agent development can fit into normal engineering build, review, and collaboration cycles. - -## What “working locally” means - -With the ADK, you are not building an agent only inside the browser. - -Instead, you work with a project on your machine, where you can: +Your local filesystem becomes your primary editing surface. You can: - edit agent resources directly - review changes with Git-style workflows @@ -57,7 +51,7 @@ A typical project structure looks like this: ~~~text // -├── _gen/ # Generated stubs — do not edit +├── _gen/ # Generated stubs - do not edit ├── agent_settings/ # Agent identity and behavior │ ├── personality.yaml │ ├── role.yaml @@ -74,7 +68,7 @@ A typical project structure looks like this: │ └── response_control/ ├── chat/ # Chat channel settings │ └── configuration.yaml -├── flows/ # Optional — flow definitions +├── flows/ # Optional - flow definitions ├── functions/ # Global functions ├── topics/ # Knowledge base topics └── project.yaml # Project metadata @@ -111,9 +105,9 @@ The standard workflow is: 5. inspect changes with `poly diff` and `poly status` 6. validate locally with `poly validate` 7. push changes with `poly push` -8. test and chat with the agent using `poly chat` -9. optionally generate a review gist with `poly review` -10. merge the branch in Agent Studio +8. optionally generate a review gist with `poly review` +9. merge the branch in Agent Studio +10. test by chatting with the agent using `poly chat` — this connects to main on the Sandbox, so merge your branch first !!! tip "Run commands from the project folder" @@ -135,21 +129,32 @@ These placeholders are used in prompts, rules, topic actions, and related text f | `{{ho:handoff_name}}` | Handoff destination | Rules | | `{{vrbl:variable_name}}` | State variable | Prompts, topic actions, SMS templates | -These references make the local project composable: settings, prompts, and behaviors can refer to resources by name rather than hard-coding values. +These references let settings, prompts, and behaviors point to resources by name rather than repeating hard-coded values. -## Why local development matters +!!! tip "A Git-like workflow for Agent Studio" -Working locally makes the ADK especially useful for teams that want to: + Think of the ADK as a synchronization layer between your local files and the Agent Studio platform. -- review changes before deployment -- reuse patterns across projects -- work with large or complex resource trees -- generate or modify resources using coding agents -- fit agent development into existing engineering processes +## Development setup from source -!!! tip "A Git-like workflow for Agent Studio" +If you are contributing to the ADK itself or working directly from the repository, you can set it up locally from source instead. + +~~~bash +git clone https://github.com/polyai/adk.git +cd adk +uv venv --python=3.14 --seed +source .venv/bin/activate +uv pip install -e ".[dev]" +pre-commit install +~~~ + +This installs the project in editable mode and enables the repository's development hooks. To run the test suite: + +~~~bash +pytest +~~~ - The ADK is easiest to understand if you think of it as a synchronization layer between your local project files and the Agent Studio platform. +Test files are located in `src/poly/tests/`. ## Related pages diff --git a/docs/docs/development/docs.md b/docs/docs/development/docs.md index 1bbd72b..d2ccf8a 100644 --- a/docs/docs/development/docs.md +++ b/docs/docs/development/docs.md @@ -1,11 +1,11 @@ --- title: Build an agent with the ADK -description: Go from a blank Agent Studio project to a production-ready voice agent using the PolyAI ADK and an AI coding agent. +description: Go from a blank Agent Studio project to a production-ready voice agent using the PolyAI ADK and a coding tool such as Claude Code. --- # Build an agent with the ADK -This guide walks through how to go from a blank slate to a production-ready voice agent with a real backend using **PolyAI ADK**, **Agent Studio**, and a coding agent such as **Claude Code**. +This guide walks through how to go from a blank slate to a production-ready voice agent with a real backend using **PolyAI ADK**, **Agent Studio**, and a coding tool such as **Claude Code**. The intended workflow is simple: @@ -17,23 +17,23 @@ The intended workflow is simple: Gather the project requirements, business rules, API information, and reference material. -- **The coding agent builds** +- **The coding tool builds** --- - Using the ADK, the coding agent generates the files needed for the agent. + Using the ADK, the coding tool generates the project files. - **Agent Studio hosts and deploys** --- - The generated work is pushed back into Agent Studio, where it can be reviewed, merged, and deployed. + The generated work is pushed into Agent Studio, where it can be reviewed, merged, and deployed.
!!! info "No manual flow-building required" - This workflow is designed so that the coding agent does the heavy lifting of building the agent, while Agent Studio remains the place where the finished work is reviewed, tested, and deployed. + In this workflow, the coding tool generates the project files. Agent Studio is where the output is reviewed, tested, and deployed. ## Architecture at a glance @@ -43,11 +43,11 @@ The intended workflow is simple: | **Claude Code + ADK** | Generate project files and push changes | | **Agent Studio** | Host, preview, review, and deploy the agent | -## Step 1 — Gather requirements +## Step 1 - Gather requirements -Collect the project context from your team’s communication channels before you begin. +Collect the project context from your team's communication channels before you begin. -This should include anything the coding agent will need to produce a working agent, such as: +Include anything needed to produce a working agent: - API endpoint URLs - business rules @@ -56,13 +56,13 @@ This should include anything the coding agent will need to produce a working age - reference material - links to relevant documentation -The more complete and structured the input is, the better the coding agent’s output will be. +The more complete and structured your input, the less correction the output requires. !!! tip "Front-load the context" - This workflow works best when you gather the requirements up front rather than feeding them in piecemeal later. + Gather everything up front. Providing context piecemeal produces piecemeal output. -## Step 2 — Create a new project in Agent Studio +## Step 2 - Create a new project in Agent Studio Open **Agent Studio** and create a brand-new project. @@ -72,42 +72,53 @@ The project starts empty: - no flows - no configuration -That blank starting point is intentional. The coding agent will populate the project in later steps. +That blank starting point is intentional. The coding tool populates the project in later steps. !!! note "Think of Agent Studio as the deployment target" - Agent Studio is where the project lives, but the coding agent does most of the actual building work. + Agent Studio is where the project lives, but the coding tool generates the actual content. -## Step 3 — Launch the coding agent via the CLI +## Step 3 - Start the coding tool via the CLI -Open your command line interface and launch your coding agent. +Open your terminal and start your coding tool. At this stage: - the ADK must already be installed -- the new Agent Studio project should already exist -- the coding agent should be linked to the project using the ADK +- the new Agent Studio project must already exist +- the coding tool should initialize and link the project using the ADK -The ADK acts as the bridge between your local development environment and Agent Studio in the cloud. It allows the coding agent to read from and write back to the project. +~~~bash +poly init --region --account_id --project_id +poly pull +~~~ -## Step 4 — Feed context to the coding agent +The ADK acts as the bridge between your local environment and Agent Studio. It lets the coding tool read from and write back to the project. -Now provide the coding agent with the information you gathered earlier. +## Step 4 - Give the coding tool its context -This is the core input step. Include: +Provide the coding tool with the information you gathered earlier. + +Include: - the project-specific requirements -- the URL to the business’s public API documentation +- the URL to the business's public API documentation - any relevant internal project context - best practices or patterns from previous projects -Reusing proven patterns from earlier projects can improve both speed and output quality. +Use the docs command to generate a reference file the coding tool can read: + +~~~bash +poly docs --all +~~~ -## Step 5 — Let the agent build +Including patterns from earlier projects reduces correction time and improves consistency. -Once the context has been provided, let the coding agent generate the project files. +## Step 5 - Generate the project files -The coding agent can produce the assets needed for the agent, including: +Once the context is in place, the coding tool generates the project files. + +This produces the assets the agent needs, including:
@@ -115,7 +126,7 @@ The coding agent can produce the assets needed for the agent, including: --- - Dialogue logic and routing for the agent. + Dialogue logic and routing. - **Callable functions** @@ -127,7 +138,7 @@ The coding agent can produce the assets needed for the agent, including: --- - Information the agent can reference when answering questions. + Information the agent can retrieve when answering questions. - **API integrations** @@ -137,13 +148,13 @@ The coding agent can produce the assets needed for the agent, including:
-The generated assets are structured for Agent Studio and prepared to be pushed back to the platform. +The generated files follow ADK structure and are ready to push to Agent Studio. -## Step 6 — Push back to Agent Studio +## Step 6 - Push to Agent Studio -Once the coding agent has generated the project files, it uses the ADK to push them back into Agent Studio. +Once the files are generated, use the ADK to push them to Agent Studio. -A new branch is created in the project so the generated work can be reviewed safely before anything goes live. +A new branch is created so the generated work can be reviewed safely before anything goes live. When you switch to that branch in Agent Studio, you should see the generated changes, such as: @@ -156,11 +167,11 @@ When you switch to that branch in Agent Studio, you should see the generated cha The branch-based workflow makes it possible to inspect what was generated before merging it into the main project. -## Step 7 — Review, merge, and deploy +## Step 7 - Review, merge, and deploy Review the generated work inside Agent Studio. -Check that the key parts of the agent look correct: +Check the key parts of the agent: - flows - functions @@ -174,23 +185,13 @@ Once everything looks right: At that point, the agent is live. -## Summary - -| Metric | Value | -|---|---| -| **Steps** | 7 | -| **Total time** | ~30 minutes | -| **Manual flows built** | 0 | - -The overall loop is straightforward: +## The overall loop 1. provide context -2. let the coding agent generate the project assets -3. use the ADK to push them into Agent Studio +2. generate the project files using the coding tool +3. push to Agent Studio with the ADK 4. review, merge, and deploy -By reusing patterns from previous projects, the coding agent can produce production-grade output much faster than a fully manual workflow. - ## Next steps
diff --git a/docs/docs/get-started/access-and-waitlist.md b/docs/docs/get-started/access-and-waitlist.md index b6fd0c0..8fe5b3e 100644 --- a/docs/docs/get-started/access-and-waitlist.md +++ b/docs/docs/get-started/access-and-waitlist.md @@ -3,42 +3,28 @@ title: Access and waitlist description: Learn how access to the PolyAI ADK currently works during the Early Access Program. --- -!!! warning "Early access" - - The PolyAI ADK is currently in Early Access. Availability is limited, and some functionality may change before general release. - - [Join the waitlist](https://fehky.share-eu1.hsforms.com/2oSGLpUctRvyqXcb6K44DAQ){ target="_blank" rel="noopener" } - The **PolyAI ADK** is currently available through an **Early Access Program (EAP)**. -To use the ADK, you must have access to a **workspace in PolyAI Agent Studio** before using the tool. - ## Current availability -The ADK is not yet generally available. - -At the moment, access is limited to users who have been granted access through the Early Access Program. +The ADK is not yet generally available. Access is limited to participants in the Early Access Program. ## What you need -Before using the ADK, you must have: +To use the ADK, you must have: - access to a **PolyAI Agent Studio workspace** - an **API key** -Without these, you will not be able to use the ADK with Agent Studio projects. +Both are provided by your PolyAI contact. Without them, the ADK cannot connect to Agent Studio. ## Requesting access -If you are an existing client and would like to gain access to the PolyAI ADK, or if you are interested in trying the ADK with Agent Studio, submit a request using the relevant waitlist or interest form. - -!!! info "Early access only" - - Access to the ADK is currently managed through the Early Access Program, so availability is controlled rather than open by default. +If you are an existing client or are interested in trying the ADK, submit a request using the waitlist or interest form linked above. ## Planned availability -The PolyAI ADK is currently scheduled for a **general availability release in Q2 2026**. +The PolyAI ADK is scheduled for **general availability in Q2 2026**. ## Next steps @@ -46,11 +32,11 @@ If you already have the required access, continue to the prerequisites page.
-- **Pre-requisites** +- **Prerequisites** --- Confirm the local tools and access requirements needed before installation. - [Open pre-requisites](./prerequisites.md) + [Open prerequisites](./prerequisites.md)
\ No newline at end of file diff --git a/docs/docs/get-started/first-commands.md b/docs/docs/get-started/first-commands.md index 77cc83a..72a80e6 100644 --- a/docs/docs/get-started/first-commands.md +++ b/docs/docs/get-started/first-commands.md @@ -9,13 +9,13 @@ Once the ADK is installed, the fastest way to get oriented is to inspect the CLI ## View top-level help -To see all available commands and options, run: +Run `poly --help` to see every available command: ~~~bash poly --help ~~~ -Each command also supports its own help output. For example: +Each command also accepts `--help` for its own flags and options: ~~~bash poly push --help @@ -95,15 +95,9 @@ The ADK provides the following core commands:
-## Recommended starting point +## Explore any command -A good way to explore the CLI is: - -1. run `poly --help` -2. identify the command you need -3. run that command with `--help` - -For example: +To learn what a command does and what flags it accepts, run it with `--help`: ~~~bash poly init --help @@ -113,7 +107,7 @@ poly push --help ## Next step -Once you understand the CLI shape, continue to the command reference or the tutorial. +Continue to the command reference for a complete listing, or go straight to the tutorial to see a real workflow.
diff --git a/docs/docs/get-started/installation.md b/docs/docs/get-started/installation.md index ffac1cd..6ac8c26 100644 --- a/docs/docs/get-started/installation.md +++ b/docs/docs/get-started/installation.md @@ -3,62 +3,59 @@ title: Installation description: Install the PolyAI ADK and prepare your local environment. --- -!!! warning "Early access" - - The PolyAI ADK is currently in Early Access. Availability is limited, and some functionality may change before general release. - - [Join the waitlist](https://fehky.share-eu1.hsforms.com/2oSGLpUctRvyqXcb6K44DAQ){ target="_blank" rel="noopener" } - The **PolyAI ADK** can be installed as a Python package. ## Install the ADK -Install the package with pip: +We recommend installing in a virtual environment rather than installing to the global system Python. If you don't have `uv` installed, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/){ target="_blank" rel="noopener" }. + +Run the following to create a virtual environment: ~~~bash -pip install polyai-adk +uv venv --python=3.14 --seed ~~~ -Once installed, you can use the `poly` command to interact with Agent Studio projects locally. +Activate the virtual environment: -## Verify the installation +~~~bash +source .venv/bin/activate +~~~ -To confirm that the CLI is available, run: +Install the package with pip: ~~~bash -poly --help +pip install polyai-adk ~~~ -If installation has completed successfully, this will display the top-level command help. +## Generate API key + +Log in to Agent Studio and open your workspace. In the **Data Access** tab (next to the **Users** tab), click **+ API Key** in the top right to generate a key. -## Development setup from source +![Generating an API key in Agent Studio — Data Access tab with the + API Key button highlighted](../assets/api-key-data-access.png) -If you are contributing to the ADK itself or working directly from the repository, you can set it up locally from source instead. +Then set it as an environment variable: ~~~bash -git clone https://github.com/polyai/adk.git -cd adk -uv venv -source .venv/bin/activate -uv pip install -e ".[dev]" -pre-commit install +export POLY_ADK_KEY= ~~~ -This installs the project in editable mode and enables the repository’s development hooks. +The `POLY_ADK_KEY` environment variable must be set before running any `poly` commands. To make it permanent, add the export line to your shell profile (for example, `~/.zshrc` or `~/.bashrc`). + +Once the ADK is installed and your API key is set, you can use the `poly` command to interact with Agent Studio projects locally. -## Running tests +## Verify the installation -To run the test suite: +Confirm the CLI is available: ~~~bash -pytest +poly --help ~~~ -Test files are located in `src/poly/tests/`. +You should see the top-level command help if installation succeeded. ## Next step -Once the ADK is installed, continue to the first commands page to explore the CLI. +Continue to the first commands page to explore the CLI.
@@ -69,4 +66,4 @@ Once the ADK is installed, continue to the first commands page to explore the CL Learn the core ADK commands and how to inspect the CLI. [Open first commands](./first-commands.md) -
\ No newline at end of file +
diff --git a/docs/docs/get-started/prerequisites.md b/docs/docs/get-started/prerequisites.md index 5e84f40..3074ab3 100644 --- a/docs/docs/get-started/prerequisites.md +++ b/docs/docs/get-started/prerequisites.md @@ -1,9 +1,9 @@ --- -title: Pre-requisites +title: Prerequisites description: Understand the access requirements and local tools needed before using the PolyAI ADK. --- -Before using the **PolyAI ADK**, you need both the correct **platform access** and the required **local tools**. +Before using the **PolyAI ADK**, you need the correct **platform access** and the required **local tools**. ## Platform access @@ -20,47 +20,37 @@ If you need access to the PolyAI platform, contact: ## Local requirements -You will also need the following installed on your machine: +Install the following tools before continuing: -
- -- **Python 3.14 or higher** +| Tool | Version | Notes | +|---|---|---| +| **uv** | latest | Manages Python and virtual environments | +| **Git** | any | Required to clone the repository or contribute | - --- +### Install uv - The ADK requires a modern Python runtime. +`uv` manages Python versions for you, including the version required by the ADK. Install it with: -- **uv** - - --- - - Recommended for local development setup from source. - -- **Git** - - --- - - Required if you plan to clone the repository or contribute from source. - -
- -## Install uv +~~~bash +curl -LsSf https://astral.sh/uv/install.sh | sh +~~~ -If you use Homebrew on macOS, you can install `uv` with: +Alternatively, with Homebrew on macOS: ~~~bash brew install uv ~~~ -## Before you continue +See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/){ target="_blank" rel="noopener" } for more options. -Before moving on, make sure you have: +## Checklist -- confirmed access to **Agent Studio** -- obtained an **API key** -- installed **Python 3.14+** -- installed `uv` if you are using the development setup -- confirmed that **Git** is available locally +Before continuing, confirm: + +- [ ] You have access to an **Agent Studio workspace** +- [ ] You have obtained an **API key** from your PolyAI contact +- [ ] `uv` is installed +- [ ] `git` is available locally ## Next step @@ -75,4 +65,4 @@ Once these requirements are in place, continue to installation. Install the ADK and set up your local environment. [Open installation](./installation.md) - \ No newline at end of file + diff --git a/docs/docs/get-started/walkthrough-video.md b/docs/docs/get-started/walkthrough-video.md index 88992d0..578db8c 100644 --- a/docs/docs/get-started/walkthrough-video.md +++ b/docs/docs/get-started/walkthrough-video.md @@ -3,9 +3,9 @@ title: Walkthrough Video description: Watch a walkthrough of building a production-ready voice agent with the PolyAI ADK. --- -This walkthroug shows how quickly a production-ready voice agent can be built using the **PolyAI ADK**. +This walkthrough shows how quickly a production-ready voice agent can be built using the **PolyAI ADK**. -It gives a practical look at the developer workflow and shows how the ADK fits into modern AI-assisted agent development. +It gives a practical look at the developer workflow and shows how the ADK fits into a coding-tool-assisted development process. ## Watch the video diff --git a/docs/docs/get-started/what-is-the-adk.md b/docs/docs/get-started/what-is-the-adk.md index 277083f..a8a87a2 100644 --- a/docs/docs/get-started/what-is-the-adk.md +++ b/docs/docs/get-started/what-is-the-adk.md @@ -3,50 +3,40 @@ title: What is the PolyAI ADK? description: Learn what the PolyAI Agent Development Kit is, why it exists, and how it supports local development workflows for Agent Studio. --- -!!! warning "Early access" +The **PolyAI ADK (Agent Development Kit)** is a **CLI tool and Python package** for managing **Agent Studio** projects on your local machine. - The PolyAI ADK is currently in Early Access. Availability is limited, and some functionality may change before general release. +It gives you a Git-like workflow for synchronizing project configuration between your local filesystem and the Agent Studio platform. - [Join the waitlist](https://fehky.share-eu1.hsforms.com/2oSGLpUctRvyqXcb6K44DAQ){ target="_blank" rel="noopener" } +## What you can do with the ADK -The **PolyAI ADK (Agent Development Kit)** is a **CLI tool and Python package** for interacting with **Agent Studio** projects on your local machine. - -It provides a Git-like workflow for synchronizing project configurations between your local filesystem and the Agent Studio platform. - -The ADK originated as **Local Agent Studio**, an internal Deployment team tool, and was later repackaged for external use with changes such as API key authentication and the removal of internal-only process references. - -## What it enables - -With the ADK, developers can: - -- build and edit Agent Studio projects locally -- synchronize project configuration with Agent Studio -- use Git-based workflows alongside agent development -- work with AI coding tools such as **Cursor** or **Claude Code** -- accelerate onboarding and agent building +- Build and edit Agent Studio projects locally using standard tooling +- Synchronize project configuration with Agent Studio using `poly push` and `poly pull` +- Branch, validate, and review changes before deployment +- Use AI coding tools such as **Claude Code** to generate and update project files +- Collaborate across multiple developers on the same project ## Why it exists -The ADK was designed to move developer workflows out of the browser and into a local development environment. +The ADK moves development work out of the browser and into your local environment. -Instead of editing everything directly inside Agent Studio, developers can pull a project locally, make changes using standard development tooling, and push those changes back to the platform. +Instead of editing everything directly inside Agent Studio, you pull a project locally, make changes using your normal tools, and push those changes back to the platform. -This makes it easier to: +This makes it straightforward to: -- iterate quickly -- collaborate across multiple contributors -- run validation and tests before deployment -- use coding agents to automate work that would otherwise be manual +- iterate quickly without browser round-trips +- collaborate across a team without overwriting each other's work +- validate and test changes before pushing them live +- automate repetitive build work with coding tools ## Multi-developer workflows -The ADK was designed with **multi-user collaboration** in mind. +The ADK supports team workflows out of the box. -It preserves the same guardrails as Agent Studio, so developers should not be able to push changes that are incompatible with the project. +It preserves the same guardrails as Agent Studio, so developers cannot push changes that are incompatible with the project. !!! tip "Git-like, but for Agent Studio" - The ADK is best understood as a developer workflow layer for Agent Studio: pull, edit locally, validate, and push. + Think of the ADK as the local development layer for Agent Studio: pull, edit locally, validate, and push. ## Next steps diff --git a/docs/docs/index.md b/docs/docs/index.md index ff43081..617497d 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -5,15 +5,9 @@ description: Documentation for the PolyAI Agent Development Kit. ![PolyAI ADK](assets/poly-ai-adk.png) -!!! warning "Early access" - - The PolyAI ADK is currently in Early Access. Availability is limited, and some functionality may change before general release. - - [Join the waitlist](https://fehky.share-eu1.hsforms.com/2oSGLpUctRvyqXcb6K44DAQ){ target="_blank" rel="noopener" } - Build, edit, and deploy Agent Studio projects locally with the **PolyAI ADK**. -The ADK gives developers a local, Git-like workflow for working with Agent Studio projects using standard tooling, validation, and AI-assisted development. +The ADK gives you a local, Git-like workflow for Agent Studio projects: pull, edit with standard tooling, validate, and push. ## Start here @@ -23,14 +17,14 @@ The ADK gives developers a local, Git-like workflow for working with Agent Studi --- - Learn what the ADK is, why it exists, and how it fits into Agent Studio workflows. + Understand what the ADK does and where it fits in the Agent Studio workflow. [Read the overview](get-started/what-is-the-adk.md) - **Installation** --- - Set up the ADK locally and prepare your development environment. + Install the ADK and prepare your local environment. [Open installation](get-started/installation.md) - **Build an agent** @@ -44,20 +38,19 @@ The ADK gives developers a local, Git-like workflow for working with Agent Studi --- - Review the core commands available in the `poly` CLI. + See every `poly` command and its flags. [Open CLI reference](reference/cli.md) ## What this site covers -This documentation is organised around the developer journey: +This documentation follows the developer journey: -- understanding what the ADK is -- getting access and installing it -- learning the core CLI workflow -- building and reviewing agents -- looking up commands, testing, and tooling details +- understanding what the ADK is and how to get access +- installing it and running the first commands +- building, reviewing, and deploying agents +- reference for all CLI commands, resource types, and tooling ## Recommended path @@ -65,7 +58,7 @@ If you are new to the ADK, follow this order: 1. read **What is the PolyAI ADK?** 2. check **Access and waitlist** -3. complete **Pre-requisites** +3. complete **Prerequisites** 4. follow **Installation** 5. use **First commands** 6. continue to **Build an agent with the ADK** \ No newline at end of file diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 2582f0b..3b1feeb 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -5,7 +5,7 @@ description: Reference for the core commands provided by the PolyAI ADK CLI.

The PolyAI ADK is accessed through the poly command. -Use the CLI help output as the first source of truth. +When in doubt about a flag or option, run the command with --help - that output reflects your installed version exactly.

## Start with help @@ -22,9 +22,9 @@ Each command also supports its own help output. For example: poly push --help ~~~ -!!! tip "Use help output as the source of truth" +!!! tip "Help output reflects your installed version" - The installed CLI is the fastest way to confirm the commands and flags available in your local environment. + This reference page covers the standard commands. Run `poly --help` to confirm the exact flags available in your environment. ## Core commands @@ -155,6 +155,10 @@ poly review --delete Start an interactive chat session with your agent. +!!! warning "Merge before chatting" + + `poly chat` connects to the **main branch** of your Sandbox environment in Agent Studio — not your local files, and not your current branch. To test changes made on a feature branch, you must first push the branch with `poly push`, merge it in Agent Studio, and then run `poly chat`. + Examples: ~~~bash @@ -176,7 +180,7 @@ poly docs --all poly docs --all --output rules.md ~~~ -Use `--output` to write the documentation to a local file. This is useful when working with AI coding tools — pass the output file as context to give the agent accurate knowledge of ADK resource types and conventions. +Use `--output` to write the documentation to a local file. This is useful when working with AI coding tools - pass the output file as context to give the agent accurate knowledge of ADK resource types and conventions. ## Machine-readable JSON output diff --git a/docs/docs/reference/experimental_config.md b/docs/docs/reference/experimental_config.md index 4838a93..b5fc798 100644 --- a/docs/docs/reference/experimental_config.md +++ b/docs/docs/reference/experimental_config.md @@ -9,7 +9,7 @@ description: Enable experimental features and advanced runtime settings for an a The experimental config file is an optional JSON file used to enable experimental features and advanced runtime settings for an agent.

-It can be used for things such as: +Use it for: - feature flags - ASR tuning @@ -66,11 +66,11 @@ The ADK validates `experimental_config.json` against this schema when you run: poly validate ~~~ -If the configuration is invalid, it will fail validation locally. Invalid experimental config in deployed agents is not read by the runtime. +Invalid configuration fails `poly validate` locally. Experimental config that fails validation is not read by the runtime in deployed agents. !!! info "Validate before pushing" - Because experimental config can affect runtime behavior in subtle ways, it should always be validated locally before changes are pushed. + Experimental config can affect runtime behavior in subtle ways. Always run `poly validate` locally before pushing changes. ## When to use it diff --git a/docs/docs/reference/flows.md b/docs/docs/reference/flows.md index c93d23d..1ec9d84 100644 --- a/docs/docs/reference/flows.md +++ b/docs/docs/reference/flows.md @@ -248,7 +248,7 @@ Python should be used for: Function steps live in `function_steps/*.py`. -These are deterministic Python steps with no LLM decision-making involved. They are ideal for: +These are deterministic Python steps. They execute directly, with no model interpretation. Use them for: - API calls - validation diff --git a/docs/docs/reference/functions.md b/docs/docs/reference/functions.md index fac827f..551db1d 100644 --- a/docs/docs/reference/functions.md +++ b/docs/docs/reference/functions.md @@ -83,13 +83,13 @@ Every `.py` file must define a function with the same name as the file, excludin That function is the entry point when the file is called by the model or runtime. -Use this import pattern: +Every function file must include this import line: ~~~python from _gen import * # ~~~ -This line must match the expected pattern exactly. +Do not modify this line. The ADK matches it exactly when reading function files. ## Decorators @@ -147,7 +147,7 @@ Prefer naming functions after the **event that should trigger them**, rather tha - `store_first_name` - `send_confirmation` -This helps the model understand when the function should be called. +This tells the model when to call the function. ## Returns and control flow diff --git a/docs/docs/reference/response_control.md b/docs/docs/reference/response_control.md index 3877ce9..4743574 100644 --- a/docs/docs/reference/response_control.md +++ b/docs/docs/reference/response_control.md @@ -6,7 +6,7 @@ description: Control how voice-agent output is filtered and pronounced before it # Response control

-Response control resources manage what the agent says before it reaches the user. +Response control resources process the agent's output before it is spoken.

They are used to adjust spoken output by: diff --git a/docs/docs/reference/sms.md b/docs/docs/reference/sms.md index 44397f4..b112f72 100644 --- a/docs/docs/reference/sms.md +++ b/docs/docs/reference/sms.md @@ -87,7 +87,7 @@ SMS templates can be referenced in rules, topics, and related instructions using {{twilio_sms:template_name}} ~~~ -This lets the model refer to the correct SMS template by name, rather than embedding the message body directly into prompt text. +This lets you reference the correct template by name without embedding the full message body in prompt text. ## Using variables diff --git a/docs/docs/reference/speech_recognition.md b/docs/docs/reference/speech_recognition.md index e4070d8..34fe2ac 100644 --- a/docs/docs/reference/speech_recognition.md +++ b/docs/docs/reference/speech_recognition.md @@ -9,7 +9,7 @@ description: Configure how the agent processes spoken input on the voice channel Speech recognition resources control how the agent processes user speech input on the voice channel.

-These resources live under `voice/speech_recognition/` and are used to tune how the agent listens, recognises, and post-processes spoken input. +These resources live under `voice/speech_recognition/` and are used to tune how the agent listens, recognizes, and post-processes spoken input. ## Location diff --git a/docs/docs/reference/testing.md b/docs/docs/reference/testing.md index 93b2741..95323e3 100644 --- a/docs/docs/reference/testing.md +++ b/docs/docs/reference/testing.md @@ -1,6 +1,6 @@ --- title: Testing -description: Run tests and validate project changes when working with the PolyAI ADK. +description: Validate project changes when working with the PolyAI ADK. --- # Testing @@ -11,20 +11,6 @@ Testing helps confirm that your project changes behave as expected before they a In the ADK workflow, testing usually sits alongside validation and manual review in Agent Studio. -## Run the test suite - -Run tests with: - -~~~bash -pytest -~~~ - -Test files are located in: - -~~~text -src/poly/tests/ -~~~ - ## What testing is for Testing is useful when you want to: @@ -36,12 +22,6 @@ Testing is useful when you want to:
-- **Automated tests** - - --- - - Use `pytest` to run the project's test suite locally. - - **Validation** --- @@ -63,13 +43,8 @@ A typical development loop looks like this: 1. edit files locally 2. inspect changes with `poly status` and `poly diff` 3. run `poly validate` -4. run `pytest` where relevant -5. push changes with `poly push` -6. test the branch in Agent Studio - -!!! tip "Validation and testing are complementary" - - `poly validate` checks configuration correctness. `pytest` checks code behavior. They solve different problems and are both useful. +4. push changes with `poly push` +5. test the branch in Agent Studio ## What to test @@ -83,11 +58,9 @@ The exact tests will depend on the kind of work you are doing, but common areas ## Best practices -- run tests before pushing substantial changes -- keep tests focused and readable - use validation as part of the normal workflow, not just before merge - test important error paths, not only success cases -- combine automated testing with interactive review when behavior depends on conversation flow +- combine interactive review when behavior depends on conversation flow ## Related pages @@ -107,4 +80,4 @@ The exact tests will depend on the kind of work you are doing, but common areas See how testing fits into the end-to-end workflow. [Open build an agent](../tutorials/build-an-agent.md) -
\ No newline at end of file + diff --git a/docs/docs/reference/tooling.md b/docs/docs/reference/tooling.md index 7b72338..1567e39 100644 --- a/docs/docs/reference/tooling.md +++ b/docs/docs/reference/tooling.md @@ -26,23 +26,19 @@ Claude Code is particularly useful for: - applying patterns reused across previous projects - speeding up repetitive implementation work -#### Loading ADK rules into your coding agent +#### Loading ADK rules into Claude Code -Before using Claude Code or another AI coding tool, generate a local documentation file and reference it in your session: +Before starting a session with Claude Code or another coding tool, generate a documentation file and pass it as context: ~~~bash poly docs --all --output rules.md ~~~ -Then reference rules.md in your prompt or agent context. This gives your coding agent accurate knowledge of ADK resource types, constraints, and conventions. +Reference `rules.md` in your session prompt. This gives the coding tool accurate knowledge of ADK resource types, constraints, and conventions. ### VS Code extension -A **PolyAI ADK VS Code extension** is available in the VS Code Marketplace: - -- `https://marketplace.visualstudio.com/items?itemName=PolyAI.adk-extension` - -This can be useful when working directly with ADK resources in a local editor. +A **PolyAI ADK VS Code extension** is available in the VS Code Marketplace. Search for `PolyAI.adk-extension` or install it directly from the [marketplace listing](https://marketplace.visualstudio.com/items?itemName=PolyAI.adk-extension){ target="_blank" rel="noopener" }. ## Other local tools diff --git a/docs/docs/reference/topics.md b/docs/docs/reference/topics.md index fb3d18e..5fb4a4e 100644 --- a/docs/docs/reference/topics.md +++ b/docs/docs/reference/topics.md @@ -89,8 +89,7 @@ This split is important: content is for facts, actions are for behavior. ### Limits and guidance - use no more than **20** example queries -- cover meaningful variation, not every tiny wording change -- trust the model to generalize from the examples you give it +- cover meaningful variation, not every minor wording change ## Content @@ -164,9 +163,10 @@ Use markdown headers like `##` and `###` to break up branches or conditions. - prefer structured `##` branches in actions - disable topics with `enabled: false` during development instead of deleting them -!!! tip "Tell, don't script" +!!! tip “Tell, don't script” - Prefer instructions like “Tell the user that ...” over hard-coded dialogue such as `Say: '...'`. This gives the agent more room to behave naturally, especially across languages. + + Prefer instructions like “Tell the user that ...” over hard-coded dialogue such as `Say: '...'`. This lets the agent vary phrasing naturally, especially across languages. ## Related pages @@ -186,4 +186,4 @@ Use markdown headers like `##` and `###` to break up branches or conditions. See how variant attributes can be referenced from topic actions. [Open variants](./variants.md) - \ No newline at end of file + diff --git a/docs/docs/reference/variables.md b/docs/docs/reference/variables.md index f08b646..12fa7ef 100644 --- a/docs/docs/reference/variables.md +++ b/docs/docs/reference/variables.md @@ -6,11 +6,9 @@ description: Understand how state variables are discovered, stored, and referenc # Variables

-Variables are virtual resources that represent state values used in the agent's code. +Variables represent values stored in conv.state and are discovered automatically by scanning function code.

-Unlike most resources, variables do not have files on disk. They are discovered automatically by scanning function code for `conv.state.` usage. - ## How variables work When you assign a value to `conv.state.customer_name` in code, `customer_name` becomes a tracked variable. @@ -155,4 +153,4 @@ If you need to expose a structured value in prompts, convert it to a string in P See how state variables are used in reusable text messages. [Open SMS templates](./sms.md) - \ No newline at end of file + diff --git a/docs/docs/tutorials/build-an-agent.md b/docs/docs/tutorials/build-an-agent.md index 32f8c55..ef66f11 100644 --- a/docs/docs/tutorials/build-an-agent.md +++ b/docs/docs/tutorials/build-an-agent.md @@ -3,20 +3,14 @@ title: Build an agent with the ADK description: Follow the end-to-end workflow for going from a blank Agent Studio project to a production-ready voice agent with the PolyAI ADK. --- -!!! warning "Early access" - - The PolyAI ADK is currently in Early Access. Availability is limited, and some functionality may change before general release. - - [Join the waitlist](https://fehky.share-eu1.hsforms.com/2oSGLpUctRvyqXcb6K44DAQ){ target="_blank" rel="noopener" } - -This guide walks through how to go from a blank slate to a production-ready voice agent with a real backend using **Agent Studio**, the **PolyAI ADK**, and optionally a coding agent such as **Claude Code**. +This guide walks through how to go from a blank slate to a production-ready voice agent using **Agent Studio**, the **PolyAI ADK**, and optionally a coding tool such as **Claude Code**. There are two common ways to build with the ADK: | Workflow | Description | |---|---| | **CLI workflow** | The hands-on developer path. You run the commands yourself, edit files locally, and push changes back to Agent Studio. | -| **AI-agent workflow** | A coding agent uses the ADK on your behalf, generating and pushing the project files from a brief. | +| **AI-agent workflow** | You provide a brief; a coding tool uses the ADK to generate and push the project files on your behalf. |
@@ -128,7 +122,11 @@ At this point, configure any API keys or environment variables needed for the pr ### Step 3 - Run the agent locally -Start an interactive chat session to confirm the connection works and inspect runtime behaviour. +Start an interactive chat session to confirm the connection works and inspect runtime behavior. + +!!! warning "Chat runs against main on Sandbox" + + `poly chat` connects to the **main branch** of your Sandbox environment in Agent Studio — not your local files, and not your current feature branch. At this stage it is useful for confirming the connection works. To chat against your own changes, push and merge your branch in Agent Studio first. ~~~bash poly chat @@ -177,7 +175,7 @@ Add or edit knowledge-base topics used for retrieval. #### Agent settings -Update the personality, role, and rules that define the agent’s global behaviour. +Update the personality, role, and rules that define the agent’s global behavior. #### Flows @@ -193,7 +191,7 @@ Define escalation paths, SMS templates, and per-variant configuration. #### ASR and response control -Tune speech recognition and control TTS behaviour. +Tune speech recognition and control TTS behavior. #### Experimental config @@ -226,7 +224,11 @@ poly push --skip-validation ### Step 8 - Test against sandbox -Validate the behaviour in the sandbox environment. +Once your branch is merged in Agent Studio, test the agent by chatting with it against the Sandbox environment. + +!!! warning "Merge before chatting" + + `poly chat` connects to the **main branch** of your Sandbox — not your feature branch. Push your changes with `poly push`, merge the branch in Agent Studio, then run `poly chat`. ~~~bash poly chat --environment sandbox @@ -254,7 +256,7 @@ Use Agent Studio analytics to monitor containment, CSAT, handle time, and flagge ## Workflow 2 - AI-agent workflow -The AI-agent workflow uses a coding agent such as **Claude Code** to execute the same development loop on your behalf. +The AI-agent workflow uses a coding tool such as **Claude Code** to run the same development loop on your behalf.
@@ -264,11 +266,11 @@ The AI-agent workflow uses a coding agent such as **Claude Code** to execute the Requirements, business rules, integrations, and API documentation. -- **The coding agent generates the project** +- **The coding tool generates the project** --- - It uses the ADK to inspect the SDK, generate files, and push the result. + It uses the ADK to read documentation, generate files, and push the result. - **You review and deploy** @@ -280,13 +282,13 @@ The AI-agent workflow uses a coding agent such as **Claude Code** to execute the !!! info "No manual flow-building required" - In this workflow, the coding agent does the heavy lifting of building the agent, while Agent Studio remains the place where the work is reviewed, tested, and deployed. + In this workflow, the coding tool generates the project files. Agent Studio is where the output is reviewed, tested, and deployed. ### Step 1 - Gather requirements Collect the project context before you begin. -This should include anything the coding agent will need in order to produce a working agent, such as: +Include anything the coding tool will need to produce a working agent: - API endpoint URLs - business rules @@ -295,11 +297,11 @@ This should include anything the coding agent will need in order to produce a wo - reference material - links to API documentation -The more complete and structured the input is, the better the generated output is likely to be. +The more complete and structured your input is, the less correction the output requires. !!! tip "Front-load the context" - This workflow works best when you gather the important information up front rather than feeding it in piecemeal later. + Gather everything up front. Providing context piecemeal produces piecemeal output. ### Step 2 - Create a new project in Agent Studio @@ -311,55 +313,51 @@ The project starts empty: - no flows - no configuration -That blank starting point is intentional. The coding agent will populate the project in later steps. +That blank starting point is intentional. The coding tool populates the project in later steps. !!! note "Think of Agent Studio as the deployment target" - Agent Studio is where the project lives, but the coding agent does most of the actual building work. + Agent Studio is where the project lives, but the coding tool generates the actual content. -### Step 3 - Launch the coding agent via the CLI +### Step 3 - Start the coding tool via the CLI -Open your command line interface and launch your coding agent. +Open your terminal and start the coding tool. At this stage: - the ADK must already be installed - the Agent Studio project must already exist -- the coding agent should be linked to the project using the ADK - -A typical starting point is: +- the coding tool should initialize and link the project using the ADK ~~~bash poly init --region --account_id --project_id poly pull ~~~ -The ADK acts as the bridge between your local development environment and Agent Studio in the cloud. It allows the coding agent to read from and write back to the project. +The ADK acts as the bridge between your local environment and Agent Studio. It lets the coding tool read from and write back to the project. -### Step 4 - Feed context to the coding agent +### Step 4 - Give the coding tool its context -Now provide the coding agent with the information you gathered earlier. +Provide the coding tool with the information you gathered earlier. -This is the core input step. Include: +Include: - project-specific requirements - the URL to the business’s public API documentation - relevant internal context - useful patterns or best practices from previous projects -The coding agent can also use the docs command to inspect the SDK and understand the available resources. +Use the docs command to generate a reference file the coding tool can read: ~~~bash poly docs --all ~~~ -Reusing proven patterns from earlier projects can improve both speed and output quality. - -### Step 5 - Let the agent build +### Step 5 - Generate the project files -Once the context has been provided, let the coding agent generate the project files. +Once the context is in place, the coding tool generates the project files. -The coding agent can produce the assets needed for the agent, including: +This produces the assets the agent needs, including:
@@ -389,11 +387,11 @@ The coding agent can produce the assets needed for the agent, including:
-The generated assets are structured for Agent Studio and prepared to be pushed back to the platform. +The generated files follow ADK structure and are ready to push to Agent Studio. -### Step 6 - Push back to Agent Studio +### Step 6 - Push to Agent Studio -Once the coding agent has generated the project files, it uses the ADK to push them back into Agent Studio. +Once the files are generated, use the ADK to push them to Agent Studio. A new branch is created in the project so the generated work can be reviewed safely before anything goes live. @@ -443,15 +441,7 @@ At that point, the agent is live. | **poly chat** | Start an interactive session with the agent | | **poly docs** | Output resource documentation | -## Summary - -| Metric | Value | -|---|---| -| **Manual workflow** | Supported | -| **AI-agent workflow** | Supported | -| **Production-ready path** | Yes | - -The overall loop is straightforward: +## The overall loop 1. create or connect a project 2. build locally using the ADK diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a5c295f..539b365 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -55,6 +55,10 @@ markdown_extensions: permalink: true extra: + analytics: + provider: google + property: G-TTMRZWJPP4 + first_repo_url: https://github.com/polyai/adk first_repo_name: adk first_repo_icon: fontawesome/brands/github @@ -87,7 +91,7 @@ nav: - What is the PolyAI ADK?: get-started/what-is-the-adk.md - Walkthrough video: get-started/walkthrough-video.md - Access and waitlist: get-started/access-and-waitlist.md - - Pre-requisites: get-started/prerequisites.md + - Prerequisites: get-started/prerequisites.md - Installation: get-started/installation.md - First commands: get-started/first-commands.md diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..77c7d77 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block announce %} +
+ The PolyAI ADK is in early access, and changes will be pushed frequently. + Join the waitlist +
+{% endblock %}