> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/6.0/6.5/getting-started/ai-copilot.md).

# AI Copilot

<figure><img src="/files/4fbPV53CwJIpBUdEj7rk" alt=""><figcaption></figcaption></figure>

AI Copilot is an assistant built into the Appmixer Designer that builds, edits and explains flows from natural language. Ask it to "Create a flow that posts new Typeform responses to Slack" and it designs the flow directly on the canvas — selecting connectors, wiring components, and filling in parameters.

Copilot can:

* **Build new flows** from a natural-language description.
* **Edit existing flows** — add, replace or remap components in the open flow. For running flows, Copilot works on a draft so the live flow keeps running unchanged.
* **Explain flows** — describe what an existing flow does, step by step.

## Enabling Copilot

Copilot ships as a system plugin of the Appmixer engine. It is loaded when it is listed in the `SYSTEM_PLUGINS` environment variable and an LLM API key is configured:

```
SYSTEM_PLUGINS=copilot
COPILOT_LLM_API_KEY=sk-ant-...
```

Additional configuration:

| Environment Variable       | Default             | Description                                                                                   |
| -------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| `COPILOT_LLM_PROVIDER`     | `anthropic`         | LLM provider.                                                                                 |
| `COPILOT_LLM_API_KEY`      | *(unset)*           | LLM provider API key. The plugin is skipped when no API key is set.                           |
| `COPILOT_LLM_MODEL`        | `claude-sonnet-4-6` | LLM model used by the assistant.                                                              |
| `COPILOT_MAX_TOKENS`       | `16384`             | Maximum tokens per LLM response.                                                              |
| `COPILOT_MAX_TURNS`        | `25`                | Maximum agent turns per chat request.                                                         |
| `COPILOT_CONVERSATION_TTL` | `3600000`           | How long (ms) a conversation is retained on the server.                                       |
| `COPILOT_PRICING_PATH`     | *(unset)*           | Optional path to a custom model pricing JSON file used for cost computation in the usage API. |

When the plugin is not enabled, the Copilot button is automatically hidden in the Designer.

## Using Copilot in the Designer

Open a flow in the Designer and click the Copilot button to open the chat panel. Type what you want to build or change. Copilot streams its progress, and when it produces a flow, the canvas is updated and reloaded.

* The conversation is retained per flow for the duration of your session, and restored when you re-open the panel.
* Replies are rendered as Markdown.
* When editing a **running** flow, Copilot's changes are applied to a draft — publish the draft to apply them (see [Flow Versioning](/6.0/6.5/api/flows.md#flow-versions)).

### Designer widget options

When embedding the Designer via the [Appmixer UI SDK](/6.0/6.5/appmixer-ui-sdk/ui-and-widgets/designer.md), the Copilot panel can be configured with the `options.copilot` object:

```javascript
appmixer.ui.Designer({
    el: '#designer',
    flowId: FLOW_ID,
    options: {
        copilot: {
            // Show the built-in, localized example prompts:
            examplePrompts: true

            // — or — provide your own (replaces the defaults):
            // examplePrompts: [
            //     'When a Stripe payment succeeds, add a row to Google Sheets',
            //     'Summarize new Zendesk tickets to Slack every morning'
            // ]

            // Omit or set false to keep them hidden (default).
        }
    }
});
```

## Monitoring AI Usage

Administrators can monitor Copilot consumption and cost in **Insights → AI usage** (Appmixer Studio). The dashboard shows total spend, daily consumption, and a per-user / per-group / per-scope breakdown, backed by the usage API below.

## Copilot API

All Copilot endpoints live under the `/system-plugins/copilot` prefix and require a valid access token.

### Chat

<mark style="color:green;">`POST`</mark> `https://api.YOUR_TENANT.appmixer.cloud/system-plugins/copilot/chat`

Send a chat message. The response is a Server-Sent Events (SSE) stream.

#### Request Body

| Name                                      | Type   | Description                                                                                                             |
| ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| message<mark style="color:red;">\*</mark> | string | The user's message.                                                                                                     |
| threadId                                  | string | Conversation thread ID. Omit to start a new conversation (a new ID is generated and returned in the `connected` event). |
| flowId                                    | string | Optional ID of the flow to give Copilot as context, enabling editing/explaining of that flow.                           |

#### SSE events

`connected` (carries the `threadId`), `text-delta` (streamed assistant text), `tool-call` / `tool-result` / `tool-error` (progress of the assistant's tool use), `flow-result` (the generated flow descriptor with `flowName` and optional `followUpQuestions`), `done` (carries token `usage`) and `error`.

### Get Conversation

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/system-plugins/copilot/conversations/:threadId`

Return the transcript of a prior conversation (`{ threadId, messages: [{ role, content }] }`). Users can only read their own threads. Returns an empty message list once the conversation TTL has lapsed.

### Enabled Check

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/system-plugins/copilot/enabled`

Returns `{ "enabled": true }` when the Copilot plugin is loaded. Clients use this to decide whether to show Copilot UI.

### Usage

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/system-plugins/copilot/usage`

Aggregated LLM usage and cost. Admin only.

#### Query Parameters

| Name    | Type   | Description                                                                 |
| ------- | ------ | --------------------------------------------------------------------------- |
| from    | string | Start of the period (ISO date). Defaults to the start of the current month. |
| to      | string | End of the period (ISO date). Defaults to now.                              |
| groupBy | string | `user` (default), `group` or `scope`.                                       |
| user    | string | Filter by user ID.                                                          |
| group   | string | Filter by group ID.                                                         |
| scope   | string | Filter by scope.                                                            |
| q       | string | Free-text filter.                                                           |

### Daily Usage

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/system-plugins/copilot/usage/daily`

Daily consumption totals for a month (`month=YYYY-MM`, defaults to the current month; optional `user`, `group`, `scope` filters). Admin only.

### User Usage

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/system-plugins/copilot/usage/user/:userId`

Individual LLM request breakdown for a user (optional `from`/`to`). Admins can view any user; non-admin users can only view their own usage.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.appmixer.com/6.0/6.5/getting-started/ai-copilot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.