|
| 1 | +--- |
| 2 | +title: Page Agent |
| 3 | +--- |
| 4 | + |
| 5 | +The Page Agent is an AI assistant built into Bytebase. It lives in a floating chat window that's available on every page — ask it anything in plain language, and it helps you get it done. |
| 6 | + |
| 7 | +## Why we built it |
| 8 | + |
| 9 | +Bytebase has a lot of features, and it's not always obvious how to accomplish what you're trying to do — even when the feature you need is already there. You might know what you want (archive old rows, grant a teammate access to a project, fix a failing plan check) but not which page to open, which buttons to click, or which settings control the behavior you're after. Or maybe you know exactly how to do it — you'd just rather hand it off and review the result instead of clicking through the flow yourself. |
| 10 | + |
| 11 | +The Page Agent is designed for both. It understands how Bytebase works end to end, so it can: |
| 12 | + |
| 13 | +- **Show you the way** — walk you through a workflow step by step when you want to do it yourself. |
| 14 | +- **Do it for you** — take the actions directly when you'd rather describe the outcome and check the result. |
| 15 | + |
| 16 | +You stay in control: the agent shows each step it takes so you can follow along, and you can stop or redirect it at any time. |
| 17 | + |
| 18 | +## Setup |
| 19 | + |
| 20 | +The Page Agent uses the same AI provider configuration as the rest of Bytebase. If you haven't enabled it yet, follow the steps in [AI Assistant](/ai-assistant) to configure your OpenAI, Claude, Gemini, or Azure OpenAI credentials. |
| 21 | + |
| 22 | +Once AI is configured, the Page Agent is available from any page in the Bytebase console. Click the agent toggle in the dashboard header to open the chat window. |
| 23 | + |
| 24 | +## How it works |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +The Page Agent has three layers: |
| 29 | + |
| 30 | +1. **Chat window** — A floating panel available from any page in the console. It stays open as you move between pages. |
| 31 | +2. **Agent loop** — Runs in your browser. When you ask a question, the agent thinks about what to do, takes an action (reading the page, calling an API, navigating somewhere), observes the result, and repeats until it has a complete answer. Each step is shown in the chat. |
| 32 | +3. **AI backend** — Bytebase routes your conversation to the AI provider configured in your workspace settings. Your credentials never leave your server. |
| 33 | + |
| 34 | +## Capabilities |
| 35 | + |
| 36 | +| Capability | Description | |
| 37 | +|---|---| |
| 38 | +| **Read the current page** | Understands which page you're on, what project, database, or issue you're viewing, and what state the UI is in | |
| 39 | +| **Call Bytebase APIs** | Queries and updates data directly — listing databases, creating issues, checking deployment status, and more | |
| 40 | +| **Navigate** | Goes to any page in the console on your behalf | |
| 41 | +| **Interact with the UI** | Clicks buttons, fills form fields, selects options — useful on pages with unsaved state like editors and creation forms | |
| 42 | +| **Discover APIs** | Browses the full Bytebase API catalog to find the right endpoint for a task | |
| 43 | +| **Load workflow guides** | Pulls in step-by-step instructions for common multi-step tasks like running queries, creating schema changes, or granting permissions | |
| 44 | + |
| 45 | +## Controls and audit |
| 46 | + |
| 47 | +The Page Agent operates within Bytebase's existing safety mechanisms: |
| 48 | + |
| 49 | +- **Uses your permissions.** The agent can only perform actions your account is authorized for. If you can't drop a table, neither can the agent. |
| 50 | +- **Goes through the normal approval flow.** Schema changes the agent creates are regular Bytebase issues — they respect your project's approval policies, plan checks, and rollout gates. The agent cannot bypass these. |
| 51 | +- **Audit-logged under your account.** Every API call, issue creation, and permission change is recorded in the audit log with your user name. |
| 52 | +- **Controlled by workspace AI settings.** The Page Agent is available only when AI is enabled in your workspace. Disabling [AI Assistant](/ai-assistant) in **Settings > General** turns off the Page Agent along with other AI features. |
| 53 | + |
| 54 | +## Use cases |
| 55 | + |
| 56 | +### Fixing a plan check error |
| 57 | + |
| 58 | +Your issue failed a SQL review check and you want help understanding and fixing the violation. |
| 59 | + |
| 60 | +> **You:** Help me fix this plan check error.<br /><br /> |
| 61 | +> **Agent:** *(Reads the current page to inspect the issue and SQL review results)*<br /><br /> |
| 62 | +> **Agent:** The SQL review flagged a violation: **"Do not apply functions or perform calculations on indexed fields in the WHERE clause."** The problem is in your INSERT...SELECT statement: |
| 63 | +> ```sql |
| 64 | +> INSERT INTO orders_archive (id, customer_id, created_at) |
| 65 | +> SELECT id, customer_id, created_at |
| 66 | +> FROM orders |
| 67 | +> WHERE YEAR(created_at) = 2023; |
| 68 | +> ``` |
| 69 | +> Wrapping `created_at` in `YEAR()` prevents the database from using the index on that column, forcing a full table scan. Here's a rewrite that keeps the index usable: |
| 70 | +> ```sql |
| 71 | +> INSERT INTO orders_archive (id, customer_id, created_at) |
| 72 | +> SELECT id, customer_id, created_at |
| 73 | +> FROM orders |
| 74 | +> WHERE created_at >= '2023-01-01' AND created_at < '2024-01-01'; |
| 75 | +> ``` |
| 76 | +> Want me to update the SQL in the editor and re-run the check? |
| 77 | +
|
| 78 | +Other things you can ask: |
| 79 | +
|
| 80 | +- "Why did the SQL review fail on this issue?" |
| 81 | +- "The plan check says I have a naming convention error — can you fix it?" |
| 82 | +- "Rewrite my migration to pass all the review checks" |
| 83 | +
|
| 84 | +### Granting permissions |
| 85 | +
|
| 86 | +A teammate needs access to a project, and you want to set it up without navigating to settings. |
| 87 | +
|
| 88 | +> **You:** Give alice@example.com developer access to the Payment project.<br /><br /> |
| 89 | +> **Agent:** I'll add Alice as a project developer. Let me look up the project members API. |
| 90 | +> *(Discovers the project IAM API → calls it to add the role binding)*<br /><br /> |
| 91 | +> **Agent:** Done! alice@example.com now has the **Project Developer** role on the Payment project. She can view databases, create issues, and run queries in SQL Editor. |
| 92 | +
|
| 93 | +Other things you can ask: |
| 94 | +
|
| 95 | +- "Who has access to the Production environment?" |
| 96 | +- "Remove bob@example.com from the HR project" |
| 97 | +- "What roles does alice@example.com have?" |
| 98 | +
|
| 99 | +### Querying data across your workspace |
| 100 | +
|
| 101 | +Get a quick overview of resources without clicking through multiple pages. |
| 102 | +
|
| 103 | +> **You:** What databases are in the "Payment" project?<br /><br /> |
| 104 | +> **Agent:** Let me check. |
| 105 | +> *(Calls the Bytebase API to list databases in the Payment project)*<br /><br /> |
| 106 | +> **Agent:** The Payment project has 4 databases: |
| 107 | +> |
| 108 | +> | Database | Environment | Engine | |
| 109 | +> |---|---|---| |
| 110 | +> | payment_prod | Production | PostgreSQL 15 | |
| 111 | +> | payment_staging | Staging | PostgreSQL 15 | |
| 112 | +> | payment_dev | Dev | PostgreSQL 15 | |
| 113 | +> | payment_analytics | Production | ClickHouse | |
| 114 | +
|
| 115 | +Other things you can ask: |
| 116 | +
|
| 117 | +- "How many pending issues are there in the HR project?" |
| 118 | +- "Show me all PostgreSQL instances" |
| 119 | +- "What SQL review policies are configured for production?" |
| 120 | +
|
| 121 | +## Tips |
| 122 | +
|
| 123 | +- **Be specific.** "Add a NOT NULL varchar(255) column called `display_name` to the `users` table in staging" works better than "change the users table." |
| 124 | +- **Ask follow-ups.** The agent remembers the full conversation, so "now do the same for production" works after a staging change. |
| 125 | +- **Let it navigate.** You don't need to be on the right page first — the agent will go where it needs to. |
| 126 | +- **Watch the tool calls.** The chat shows each API call or UI action the agent takes, so you always know what happened. |
| 127 | +
|
| 128 | +## Important notes |
| 129 | +
|
| 130 | +<Warning> |
| 131 | +
|
| 132 | +The agent uses AI to plan and execute actions. Always review what it did — issue created, SQL written, permissions granted — before moving on. |
| 133 | +
|
| 134 | +</Warning> |
0 commit comments