Agent Zero AI framework
Document first-run onboarding flow
Alessandro818bda0385c3
diff --git a/docs/README.md b/docs/README.mdindex 1b8615604..655dc0e44 100644--- a/docs/README.md+++ b/docs/README.md@@ -12,6 +12,7 @@ docs focus on practical setup, screenshots, and user workflows.## Quick Start- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.+- **[First-Run Onboarding](guides/onboarding.md):** Choose Cloud or Local, add a provider key, and select main and utility models.- **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).- **[A0 CLI Connector](guides/a0-cli-connector.md):** Install the host connector for a running Agent Zero instance, use the command palette, and switch Browser modes.- **[Self Update](guides/self-update.md):** How the in-app updater works (technical reference).@@ -21,6 +22,7 @@ docs focus on practical setup, screenshots, and user workflows.## User Guides- **[Usage Guide](guides/usage.md):** Practical tour of Agent Zero's main workflows.+- **[First-Run Onboarding](guides/onboarding.md):** Set up OpenRouter, our proxy API or another provider with the guided wizard.- **[Browser Guide](guides/browser.md):** Use the built-in Browser, live Canvas surface, annotations, screenshots, host browser mode, and extensions.- **[Desktop Guide](guides/desktop.md):** Use the built-in Linux desktop, GUI apps, and LibreOffice Writer/Calc/Impress Cowork.- **[A0 CLI Connector](guides/a0-cli-connector.md):** Terminal-first host connector for Agent Zero, with screenshots of the host picker, connected shell, command palette, and Browser modes.@@ -61,6 +63,7 @@ docs focus on practical setup, screenshots, and user workflows.- [Quick Start](#quick-start)- [Quickstart Guide](quickstart.md)+ - [First-Run Onboarding](guides/onboarding.md)- [Installation Guide](setup/installation.md)- [How to Update Agent Zero](setup/installation.md#how-to-update-agent-zero)- [Manual Installation (Advanced)](setup/installation.md#manual-installation-advanced)diff --git a/docs/guides/onboarding.md b/docs/guides/onboarding.mdnew file mode 100644index 000000000..012e56c5c--- /dev/null+++ b/docs/guides/onboarding.md@@ -0,0 +1,74 @@+# First-Run Onboarding++Use onboarding the first time you open Agent Zero, or any time the Web UI says+your models still need setup. The wizard helps you pick a provider, add the+needed key or connection, choose the main model, choose the utility model, and+start chatting.++This example uses **Agent Zero API** with a fake demo key and+`claude-opus-4-6`. Replace the demo key with your own key.++## Choose Cloud Or Local++Open the Web UI and click **Start Onboarding** from the welcome banner. On the+first screen, choose whether Agent Zero should use a hosted provider or a local+model server.++++Choose **Cloud** when you want to use Agent Zero API, OpenRouter, Anthropic,+OpenAI, Google, Venice, or another hosted provider. Choose **Local** when you+want to connect to Ollama, LM Studio, or another model server running on your+machine.++## Pick Agent Zero API++On the Cloud provider screen, click **Agent Zero API**.++++The ChatGPT/Codex account option is also available on this Cloud screen if you+want to connect by device code instead of pasting a provider key.++## Add The Key And Main Model++Paste your Agent Zero API key in **API key**. The screenshot uses a fake example+key, and the field is masked.++Click the magnifier in **Main model** to open the model list, then choose+`claude-opus-4-6`.++++After the model is selected, click **Choose utility model**.++++## Choose The Utility Model++The utility model handles supporting work such as summarizing, organizing+memory, and other background tasks.++Leave **Use same as Main Model** checked if you want both roles to use+`claude-opus-4-6`.++++You can also uncheck **Use same as Main Model** and choose a different utility+provider and model. For example, you might keep a strong main model for chat and+use a faster or cheaper model for utility tasks.++Click **Finish setup** when the utility model looks right.++## Start Chatting++The ready screen confirms that model setup is done. Optional setup cards may+appear for integrations such as Telegram, Email, WhatsApp, or plugins.++++Click **Start Chatting** to create a chat and begin using Agent Zero.++> [!IMPORTANT]+> Do not reuse the fake key shown in this guide. Paste your own provider key,+> and do not share screenshots that reveal real keys or private account details.diff --git a/docs/quickstart.md b/docs/quickstart.mdindex a9852fa05..59c569fe3 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -53,22 +53,21 @@ Once `a0` connects, open or create a chat there. The reasoning still belongs toFor the full setup flow, host picker screenshots, command palette guidance, Browser mode commands, manual fallback install paths, remote-host tips, and a copy-ready brief for another agent, see the [A0 CLI Connector guide](guides/a0-cli-connector.md).-### Open the Web UI and configure your API key+### Open the Web UI and complete onboardingOpen your browser and navigate to `http://localhost:<PORT>`. The Web UI will-show the onboarding banner. Click **Start Onboarding** to set your models and-API key.+show the onboarding banner. Click **Start Onboarding** to choose Cloud or+Local, add a provider key or account connection, and select your main and+utility models.-Click **Add your API key** to open Settings and configure:--- **Default Provider:** OpenRouter (supports most models with a single API key)-- **Alternative Providers:** Anthropic, OpenAI, Ollama/LM Studio (local models), and many others-- **Model Selection:** Choose your chat model (e.g., `anthropic/claude-sonnet-4-6` for OpenRouter)+For a screenshot walkthrough using **Agent Zero API** with+`claude-opus-4-6`, see the [First-Run Onboarding guide](guides/onboarding.md).> [!NOTE]-> Agent Zero supports any LLM provider, including local models via Ollama. For detailed provider configuration and local model setup, see the [Installation Guide](setup/installation.md#choosing-your-llms).+> Agent Zero supports hosted providers and local models. You can use the same+> provider for main and utility work, or choose separate providers for each.### Start your first chatdiff --git a/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png b/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.pngnew file mode 100644index 000000000..c46498169Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png differdiff --git a/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png b/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.pngnew file mode 100644index 000000000..b899b35adBinary files /dev/null and b/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png differdiff --git a/docs/res/usage/onboarding/onboarding-cloud-provider.png b/docs/res/usage/onboarding/onboarding-cloud-provider.pngnew file mode 100644index 000000000..efcb181fdBinary files /dev/null and b/docs/res/usage/onboarding/onboarding-cloud-provider.png differdiff --git a/docs/res/usage/onboarding/onboarding-ready.png b/docs/res/usage/onboarding/onboarding-ready.pngnew file mode 100644index 000000000..81b215f68Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-ready.png differdiff --git a/docs/res/usage/onboarding/onboarding-start.png b/docs/res/usage/onboarding/onboarding-start.pngnew file mode 100644index 000000000..5102833d1Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-start.png differdiff --git a/docs/res/usage/onboarding/onboarding-utility-same-model.png b/docs/res/usage/onboarding/onboarding-utility-same-model.pngnew file mode 100644index 000000000..992497535Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-utility-same-model.png differdiff --git a/docs/setup/installation.md b/docs/setup/installation.mdindex e97f0457e..9d153943a 100644--- a/docs/setup/installation.md+++ b/docs/setup/installation.md@@ -300,7 +300,10 @@ docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero## Step 3: Configure Agent Zero-The UI will show a warning banner "Missing LLM API Key for current settings". Click on `Add your API key` to enter Settings and start configuring A0.+The UI will show a welcome banner when model setup is missing. Click+**Start Onboarding** to choose Cloud or Local, add a provider key or account+connection, and select your main and utility models. For the screenshot+walkthrough, see the [First-Run Onboarding guide](../guides/onboarding.md).### Settings Configuration