Skip to content

Commit e4c24a6

Browse files
zchpeterclaude
zchpeter
and
claude
committed
docs: add Page Agent documentation
Add a top-level page for the Page Agent feature — an in-app AI assistant that can read pages, call APIs, navigate the console, and walk users through workflows. Registers the page in the Administration > General nav group alongside AI Assistant. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent afb8edd commit e4c24a6

File tree

4 files changed

+275
-0
lines changed

4 files changed

+275
-0
lines changed

‎docs/ai-assistant.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,4 @@ Go to Bytebase console, click **Settings > General**. Scroll down to **AI Assist
2727
## Features
2828

2929
- [SQL Editor AI Assistant](/sql-editor/ai-assistant)
30+
- [Page Agent](/page-agent)

‎docs/content/docs/page-agent/architecture.svg‎

Lines changed: 133 additions & 0 deletions
Loading

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,7 @@
281281
"administration/mode",
282282
"integrations/mcp",
283283
"ai-assistant",
284+
"page-agent",
284285
"change-database/environment-policy/overview",
285286
"administration/database-group",
286287
"administration/customize-logo",

‎docs/page-agent.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
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+
![Page Agent Architecture](/content/docs/page-agent/architecture.svg)
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.
61+
>
62+
> **Agent:** *(Reads the current page to inspect the issue and SQL review results)*
63+
>
64+
> **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:
65+
> ```sql
66+
> INSERT INTO orders_archive (id, customer_id, created_at)
67+
> SELECT id, customer_id, created_at
68+
> FROM orders
69+
> WHERE YEAR(created_at) = 2023;
70+
> ```
71+
> 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:
72+
> ```sql
73+
> INSERT INTO orders_archive (id, customer_id, created_at)
74+
> SELECT id, customer_id, created_at
75+
> FROM orders
76+
> WHERE created_at >= '2023-01-01' AND created_at < '2024-01-01';
77+
> ```
78+
> Want me to update the SQL in the editor and re-run the check?
79+
80+
Other things you can ask:
81+
82+
- "Why did the SQL review fail on this issue?"
83+
- "The plan check says I have a naming convention error — can you fix it?"
84+
- "Rewrite my migration to pass all the review checks"
85+
86+
### Granting permissions
87+
88+
A teammate needs access to a project, and you want to set it up without navigating to settings.
89+
90+
> **You:** Give alice@example.com developer access to the Payment project.
91+
>
92+
> **Agent:** I'll add Alice as a project developer. Let me look up the project members API.
93+
> *(Discovers the project IAM API → calls it to add the role binding)*
94+
>
95+
> **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.
96+
97+
Other things you can ask:
98+
99+
- "Who has access to the Production environment?"
100+
- "Remove bob@example.com from the HR project"
101+
- "What roles does alice@example.com have?"
102+
103+
### Querying data across your workspace
104+
105+
Get a quick overview of resources without clicking through multiple pages.
106+
107+
> **You:** What databases are in the "Payment" project?
108+
>
109+
> **Agent:** Let me check.
110+
> *(Calls the Bytebase API to list databases in the Payment project)*
111+
>
112+
> **Agent:** The Payment project has 4 databases:
113+
>
114+
> | Database | Environment | Engine |
115+
> |---|---|---|
116+
> | payment_prod | Production | PostgreSQL 15 |
117+
> | payment_staging | Staging | PostgreSQL 15 |
118+
> | payment_dev | Dev | PostgreSQL 15 |
119+
> | payment_analytics | Production | ClickHouse |
120+
121+
Other things you can ask:
122+
123+
- "How many pending issues are there in the HR project?"
124+
- "Show me all PostgreSQL instances"
125+
- "What SQL review policies are configured for production?"
126+
127+
## Tips
128+
129+
- **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."
130+
- **Ask follow-ups.** The agent remembers the full conversation, so "now do the same for production" works after a staging change.
131+
- **Let it navigate.** You don't need to be on the right page first — the agent will go where it needs to.
132+
- **Watch the tool calls.** The chat shows each API call or UI action the agent takes, so you always know what happened.
133+
134+
## Important notes
135+
136+
<Warning>
137+
138+
The agent uses AI to plan and execute actions. Always review what it did — issue created, SQL written, permissions granted — before moving on.
139+
140+
</Warning>

0 commit comments

Comments
 (0)