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

# Working locally

With the ADK, you work on Agent Studio projects from your local machine instead of exclusively through the browser.

Your local filesystem becomes your primary editing surface. You can:

* edit agent resources directly
* review changes with Git-style workflows
* validate changes before pushing
* work in **VS Code** or **Cursor** with the [PolyAI ADK extension](/adk/reference/tooling#polyai-adk-extension-for-vs-code-and-cursor), or pair the ADK with [AI coding agents](/adk/reference/tooling#claude-code) such as **Claude Code**
* test and iterate before merging in Agent Studio

<CardGroup>
  <Card title="Local files">
    Agent configuration lives on disk in a structured project directory.
  </Card>

  <Card title="CLI workflow">
    Pull, edit, validate, push, and review changes using the `poly` CLI.
  </Card>

  <Card title="Platform sync" href="/adk/reference/branch_merge">
    Agent Studio remains the source of deployment and preview. Branches can be merged with [`poly branch merge`](/adk/reference/branch_merge) from the CLI or through the Agent Studio UI.
  </Card>

  <Card title="Developer tooling">
    The local workflow works naturally with editors, terminals, and AI-assisted coding tools.
  </Card>
</CardGroup>

## What a local project contains

Each local ADK project represents an Agent Studio project.

A project can define a voice or webchat agent, and its runtime behavior is controlled by resources such as flows, functions, topics, settings, and configuration files.

A typical project structure looks like this:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
<account>/<project>/
├── _gen/                               # Generated stubs - do not edit
├── agent_settings/                     # Agent identity and behavior
│   ├── languages.yaml                  # Optional
│   ├── personality.yaml
│   ├── role.yaml
│   ├── rules.txt
│   ├── safety_filters.yaml             # Optional
│   └── experimental_config.json        # Optional
├── config/                             # Configuration
│   ├── entities.yaml                   # Optional
│   ├── handoffs.yaml                   # Optional
│   ├── sms_templates.yaml              # Optional
│   ├── translations.yaml               # Optional
│   └── variant_attributes.yaml         # Optional
├── context/                            # Optional - document context files
│   └── {document_name}.md
├── voice/                              # Voice channel settings
│   ├── configuration.yaml
│   ├── safety_filters.yaml             # Optional
│   ├── speech_recognition/
│   └── response_control/
├── chat/                               # Chat channel settings
│   ├── configuration.yaml
│   └── safety_filters.yaml             # Optional
├── flows/                              # Optional - flow definitions
├── functions/                          # Global functions
├── topics/                             # Knowledge base topics
├── test_suite/                         # Optional - simulated conversation tests
└── project.yaml                        # Project metadata
```

<Info>
  **Generated files**

  Files under `_gen/` are generated stubs and should not be edited directly.
</Info>

## How local work maps to Agent Studio

The ADK does not replace Agent Studio. It acts as the local development layer around it.

A typical flow looks like this:

1. initialize or pull a project locally
2. create or switch to a branch
3. edit resources on disk
4. validate and inspect changes
5. push changes back to Agent Studio
6. test and review the branch in Agent Studio
7. merge when ready

This means the local filesystem becomes your main editing surface, while Agent Studio remains the place where work is previewed, reviewed, and deployed.

## Standard CLI workflow

See the [CLI working pattern](/adk/reference/cli#working-pattern) for the full step-by-step. The short version: init → pull → branch → edit → validate → push → review → merge → chat.

<Tip>
  **Run commands from the project folder**

  ADK commands are expected to be run from within the local project directory. If needed, use the `--path` flag to point to a project explicitly.
</Tip>

## Resource reference syntax

Many ADK resources support references to other resources or values.

These placeholders are used in prompts, rules, topic actions, and related text fields:

| Syntax                         | Resolves to                                       | Common use                                   |
| ------------------------------ | ------------------------------------------------- | -------------------------------------------- |
| `{{fn:function_name}}`         | [Global function](/adk/reference/functions)       | Rules, topic actions, advanced step prompts  |
| `{{ft:function_name}}`         | [Flow transition function](/adk/reference/flows)  | Advanced step prompts within the same flow   |
| `{{entity:entity_name}}`       | [Collected entity value](/adk/reference/entities) | Flow prompts                                 |
| `{{attr:attribute_name}}`      | [Variant attribute](/adk/reference/variants)      | Rules, prompts, greetings, personality, role |
| `{{twilio_sms:template_name}}` | [SMS template](/adk/reference/sms)                | Rules, topic actions                         |
| `{{ho:handoff_name}}`          | [Handoff destination](/adk/reference/handoffs)    | Rules                                        |
| `{{vrbl:variable_name}}`       | [State variable](/adk/reference/variables)        | Prompts, topic actions, SMS templates        |

These references let settings, prompts, and behaviors point to resources by name rather than repeating hard-coded values.

<Tip>
  **A Git-like workflow for Agent Studio**

  Think of the ADK as a synchronization layer between your local files and the Agent Studio platform.
</Tip>

## Related pages

<CardGroup>
  <Card title="CLI reference" href="/adk/reference/cli">
    Review the main ADK commands and their purpose.
  </Card>

  <Card title="Tests" href="/adk/reference/tests">
    Write simulated conversation test cases under `test_suite/`.
  </Card>

  <Card title="Multi-user workflows and guardrails" href="/adk/concepts/multi-user-and-guardrails">
    Learn how branching, validation, and review fit into collaborative work.
  </Card>
</CardGroup>