> ## Documentation Index
> Fetch the complete documentation index at: https://botflow.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agent

> Chat with AI to build, edit, and debug your app — no copy-pasting required.

The AI agent is the heart of Botflow. It has full access to your project's file system: it reads files, writes diffs, installs packages, and runs terminal commands — all in response to plain-English instructions.

## How the agent works

When you send a message, the agent:

1. **Reads context** — it inspects your file tree and loads the files most relevant to your request.
2. **Plans** — it decides which files need to change and how.
3. **Executes tool calls** — each action (read, edit, command, preview refresh) is shown in the chat as a collapsible step.
4. **Replies** — it summarises what it did and explains any tricky choices.

You can see every tool call in real time as it happens. Click any step to expand it and read the raw diff or command output.

## Models

Botflow supports a curated selection of frontier models. Switch between them at any time using the model selector in the top-left of the workspace.

| Model                 | Provider  | Context window | Images |
| --------------------- | --------- | -------------- | ------ |
| **GPT-5.3** (default) | OpenAI    | 400k tokens    | ✓      |
| **GPT-5.4**           | OpenAI    | 400k tokens    | ✓      |
| **Claude Sonnet 4**   | Anthropic | 200k tokens    | ✓      |
| **Claude Opus 4.7**   | Anthropic | 200k tokens    | ✓      |
| **Gemini 3.1 Pro**    | Google    | 1M tokens      | ✓      |
| **MiniMax-M2.5**      | Fireworks | 32k tokens     | —      |
| **GLM-5.1**           | Fireworks | 202k tokens    | —      |
| **Kimi K2.6**         | Fireworks | 131k tokens    | —      |

<Note>
  The token counter at the bottom of the agent panel shows your estimated usage against the selected model's limit. When you approach the limit, start a new session with **Reset** or break your work into smaller tasks.
</Note>

## Provider setup

The agent needs credentials to call a model. You can supply these three ways:

### 1. Platform credits (Pro / Max)

Pro and Max plans include a monthly allotment of platform-managed credits. Credits are normalised across models — 1 MiniMax token = 1 credit, for example, while cached input tokens cost less. No API key required.

### 2. Bring your own API key

In [Settings → Connections](/docs/features/settings#connections), paste your key for any of these providers:

* **OpenAI** (`sk-...`)
* **Anthropic** (`sk-ant-...`)
* **Google AI Studio** (`AIza...`)
* **Fireworks AI**
* **Moonshot**

Your key is stored encrypted and never exposed to the frontend.

### 3. OAuth sign-in

For OpenAI and Anthropic you can sign in via OAuth instead of pasting a key:

* **Claude OAuth** — authorise Botflow to use your Anthropic account. Click **Connect with Claude** in Settings → Connections and follow the PKCE flow.
* **Codex OAuth** — authorise Botflow to use your OpenAI account via a device-code flow. You'll be shown a short code to enter at `openai.com/device`.

OAuth tokens are refreshed automatically and never exposed in the UI.

## Writing good prompts

### Be specific about what you want

| Vague                | Better                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| "Fix the login"      | "The login form doesn't show an error when the password is wrong. Show a red message below the input."       |
| "Make it look nicer" | "Use a dark background (#0f0f0f), white text, and Inter font. Increase the card border radius to 12px."      |
| "Add a feature"      | "Add a sidebar that lists all users from the /api/users endpoint and highlights the currently selected one." |

### Ask for explanations

```
Explain what the useKanban hook does and why the state is structured that way
```

The agent will walk through the code in plain English — useful when you inherit an AI-generated project and want to understand it before editing.

### Scope your requests

The agent works best when asked to do one thing at a time. Instead of "refactor the entire app", try "refactor the card component to use a compound-component pattern".

## Example prompts by task

### Adding new features

```
Add a new page at /pricing with three pricing tiers: Free, Pro, and Max. Use a card layout with feature comparison checkboxes.
```

```
Create a contact form that sends submissions to a Convex HTTP endpoint. Include validation for email format and required fields.
```

```
Add dark mode support using Tailwind's dark variant. Add a toggle in the navbar that persists the preference in localStorage.
```

### Fixing bugs

```
The app crashes with "Cannot read properties of undefined" when loading the dashboard. Find the issue and fix it.
```

```
The submit button stays disabled even when all fields are filled. Check the form validation logic and fix it.
```

```
Memory leak warning in the console when navigating away from the chart page. Find and clean up the subscription.
```

### Refactoring code

```
Extract the user card into a separate component at components/UserCard.tsx. Keep the same props interface.
```

```
Convert this class component to a functional component with hooks. Preserve all existing behavior.
```

```
Split the large utils.ts file into smaller modules: date.ts, string.ts, and validation.ts. Update all imports.
```

### Integrating APIs

```
Add Stripe checkout for the Pro plan. Create a Convex action that creates a checkout session and returns the URL.
```

```
Integrate the GitHub API to fetch the user's repositories. Display them in a grid with star count and description.
```

```
Add Resend email integration. Create a Convex function that sends a welcome email when a new user signs up.
```

### Working with Convex

```
Add a Convex schema for a blog with posts and comments. Each post has a title, content, authorId, and publishedAt.
```

```
Create a real-time query that shows online users. Update the presence every 30 seconds.
```

```
Add a scheduled job that runs every hour and sends a digest email with new posts.
```

### Debugging assistance

```
I'm getting a CORS error when calling the API from the frontend. What's causing this and how do I fix it?
```

```
The build is failing with a TypeScript error in the auth module. Here's the error: [paste error]. Fix it.
```

```
Why is this useEffect running twice on mount? Is this normal in React 18?
```

### Undoing changes

```
Undo that last change — it broke the layout. Revert to the previous version.
```

```
You deleted the wrong file. Restore the components/Button.tsx file from before your last edit.
```

```
Stop what you're doing and go back to the version before you started refactoring.
```

<Note>
  The agent can only work with files in your current project. If you reference external code or documentation, paste the relevant snippets into the chat or attach a screenshot.
</Note>

## Attaching images

Models that support vision (GPT-5.3, GPT-5.4, Claude, Gemini) can accept images alongside your message. Click the **paperclip icon** in the input bar to attach a screenshot, mockup, or design file.

Use cases:

* "Make the UI look like this design" (attach a Figma export or screenshot)
* "What's wrong with this error?" (attach a browser screenshot)
* "Recreate this chart component" (attach a reference image)

## Context window and Reset

Every message you send adds to the conversation context. When the token counter approaches the model's limit, responses may become slower or less accurate. Click **Reset** in the toolbar to start a fresh conversation — your files are untouched, only the chat history is cleared.

<Warning>
  Reset clears the entire chat history permanently. There is no undo. If you want to save a particularly useful exchange, copy it before resetting.
</Warning>

## Tool calls reference

The agent uses a set of built-in tools to interact with your project. These are shown in the chat as expandable steps.

| Tool                                | What it does                                      |
| ----------------------------------- | ------------------------------------------------- |
| `read`                              | Reads the contents of a file                      |
| `write`                             | Writes an entire file                             |
| `edit`                              | Makes a targeted edit to a file                   |
| `applyDiff`                         | Applies a patch-style edit to a file              |
| `bash`                              | Runs a shell command in the project's sandbox     |
| `glob`                              | Finds files matching a glob pattern               |
| `grep`                              | Searches for a pattern across the project         |
| `listFiles`                         | Lists files in a directory                        |
| `startDevServer` / `refreshPreview` | Starts the dev server or reloads the live preview |
| `askQuestion`                       | Asks you a question when it needs a decision      |
| `endTurn`                           | Signals the agent has finished its task           |