From 9a8da87c41185b2b3a909a0f94fa1274e390cd6f Mon Sep 17 00:00:00 2001 From: philipph-askui Date: Thu, 9 Jul 2026 14:47:00 +0200 Subject: [PATCH 1/7] docs: restructure and rewrite docs for current AskUI product - Add prominent quickstart guide (< 10 min: register, install, first run) - Rewrite home page with product overview, how it works, and why AskUI - Remove all Python/legacy SDK references from main docs; add Legacy section for Python SDK and TypeScript SDK with migration guidance - Correct CLI and AgentOS install story: CLI ships with Desktop installer, standalone AgentOS installer coming soon, no Python runtime (pure C#) - Restructure AgentOS nav: rename "How-to guides" to "Deployment" section, elevate Troubleshooting to top-level AgentOS page - Add CI examples page (GitHub Actions, GitLab CI, Azure DevOps) - Add Support section: FAQ, Get help (with diagnostic tool callout), index - Add Reference pages: environment variables, network requirements, glossary - Remove internal-only workspace API and inference API pages - Add Account & Billing pages: members (roles/invite), usage dashboard - Add uninstall guide (Windows + macOS) - Mark OpenAI-compatible BYOM providers as experimental with no support - Remove Discord links throughout; remove all scaffold placeholder notes Co-Authored-By: Claude Sonnet 4.6 --- app/(home)/page.tsx | 224 +++++++++++++++++- content/docs/account-billing/billing.mdx | 8 +- content/docs/account-billing/members.mdx | 77 ++++++ content/docs/account-billing/meta.json | 2 +- .../docs/account-billing/usage-dashboard.mdx | 47 ++++ content/docs/account-billing/workspaces.mdx | 5 - .../docs/agentos/deployment/ci-examples.mdx | 129 ++++++++++ .../deployment-ci.mdx => deployment/ci.mdx} | 4 +- .../local.mdx} | 8 +- content/docs/agentos/deployment/meta.json | 1 + .../multi-device.mdx} | 0 content/docs/agentos/how-to-guides/meta.json | 1 - content/docs/agentos/installation/service.mdx | 4 +- .../docs/agentos/installation/standalone.mdx | 12 +- content/docs/agentos/meta.json | 2 +- .../agentos/reference/system-requirements.mdx | 4 +- .../{how-to-guides => }/troubleshooting.mdx | 76 +++++- .../agentos/understanding/control-modes.mdx | 2 +- .../agentos/understanding/runtime-modes.mdx | 15 +- content/docs/get-started/install-cli.mdx | 17 +- content/docs/get-started/install-desktop.mdx | 12 +- content/docs/get-started/meta.json | 2 +- content/docs/get-started/uninstall.mdx | 65 +++++ content/docs/guides/index.mdx | 28 +++ content/docs/guides/meta.json | 1 + content/docs/index.mdx | 59 +++-- content/docs/legacy/index.mdx | 41 ++++ content/docs/legacy/meta.json | 1 + content/docs/legacy/python-sdk.mdx | 25 ++ content/docs/legacy/typescript-sdk.mdx | 26 ++ content/docs/meta.json | 2 +- content/docs/quickstart.mdx | 136 +++++++++++ .../docs/reference/environment-variables.mdx | 32 +++ content/docs/reference/glossary.mdx | 21 ++ content/docs/reference/inference-api.mdx | 10 - content/docs/reference/meta.json | 2 +- .../docs/reference/network-requirements.mdx | 52 ++++ content/docs/reference/workspace-api.mdx | 10 - content/docs/support/faq.mdx | 126 ++++++++++ content/docs/support/get-help.mdx | 74 ++++++ content/docs/support/index.mdx | 32 +++ content/docs/support/meta.json | 1 + content/docs/using-askui-desktop/cli.mdx | 2 +- .../using-askui-desktop/model-providers.mdx | 6 + 44 files changed, 1301 insertions(+), 103 deletions(-) create mode 100644 content/docs/account-billing/members.mdx create mode 100644 content/docs/account-billing/usage-dashboard.mdx create mode 100644 content/docs/agentos/deployment/ci-examples.mdx rename content/docs/agentos/{how-to-guides/deployment-ci.mdx => deployment/ci.mdx} (95%) rename content/docs/agentos/{how-to-guides/deployment-local.mdx => deployment/local.mdx} (87%) create mode 100644 content/docs/agentos/deployment/meta.json rename content/docs/agentos/{how-to-guides/deployment-multi-device.mdx => deployment/multi-device.mdx} (100%) delete mode 100644 content/docs/agentos/how-to-guides/meta.json rename content/docs/agentos/{how-to-guides => }/troubleshooting.mdx (67%) create mode 100644 content/docs/get-started/uninstall.mdx create mode 100644 content/docs/guides/index.mdx create mode 100644 content/docs/guides/meta.json create mode 100644 content/docs/legacy/index.mdx create mode 100644 content/docs/legacy/meta.json create mode 100644 content/docs/legacy/python-sdk.mdx create mode 100644 content/docs/legacy/typescript-sdk.mdx create mode 100644 content/docs/quickstart.mdx create mode 100644 content/docs/reference/environment-variables.mdx create mode 100644 content/docs/reference/glossary.mdx delete mode 100644 content/docs/reference/inference-api.mdx create mode 100644 content/docs/reference/network-requirements.mdx delete mode 100644 content/docs/reference/workspace-api.mdx create mode 100644 content/docs/support/faq.mdx create mode 100644 content/docs/support/get-help.mdx create mode 100644 content/docs/support/index.mdx create mode 100644 content/docs/support/meta.json diff --git a/app/(home)/page.tsx b/app/(home)/page.tsx index c936084..5012691 100644 --- a/app/(home)/page.tsx +++ b/app/(home)/page.tsx @@ -1,16 +1,222 @@ import Link from 'next/link'; +const HOW_IT_WORKS = [ + { + step: '1', + title: 'Describe your test', + body: 'Write test steps in plain Markdown. Tell the agent what to do: "sign in with the QA credentials", "check the green badge appears", "click Submit".', + }, + { + step: '2', + title: 'The agent acts on screen', + body: 'AskUI takes screenshots and uses a vision model to understand the UI. It clicks, types, and navigates like a real user, with no injected scripts.', + }, + { + step: '3', + title: 'Read the report', + body: 'Every step gets a status and a screenshot. PASSED means it actually passed. The agent never invents a workaround to reach "done".', + }, +]; + +const COMPONENTS = [ + { + name: 'Desktop App', + role: 'Author + run', + description: + 'The visual environment for building projects, writing prompts, and watching test runs execute on your screen.', + href: '/docs/get-started/install-desktop', + cta: 'Install Desktop', + }, + { + name: 'CLI', + role: 'Automate + scale', + description: + 'Run projects headless, in CI, on a schedule, or across a fleet of machines. Ships with the Desktop App installer.', + href: '/docs/get-started/install-cli', + cta: 'Install CLI', + }, + { + name: 'AgentOS', + role: 'Runtime layer', + description: + 'The service that gives the agent direct OS control: keyboard, mouse, and screen. Runs locally or as a background service.', + href: '/docs/agentos', + cta: 'Explore AgentOS', + }, +]; + +const WHY_ASKUI = [ + { + title: 'No selectors, no DOM', + description: + 'The agent reads the screen the way a person does. Tests work across web, desktop, and embedded UIs where the DOM is unavailable or too brittle to rely on.', + }, + { + title: 'Any model, no lock-in', + description: + 'Route agents to Claude, Gemini, OpenAI, or your own model provider. Switch models without rewriting tests. Cached steps on stable workflows cost nothing.', + }, + { + title: 'Any device, any OS', + description: + 'Windows, macOS, Linux, Android, iOS, and embedded screens. Companion Mode covers devices where software installation is not an option.', + }, + { + title: 'Audit-ready results', + description: + 'Every run produces a step-by-step report with a screenshot and status per step. PASSED means the step actually passed — the agent never improvises its way to done.', + }, +]; + +const WHERE_TO_START = [ + { + goal: 'New to AskUI', + action: 'Follow the Quickstart', + href: '/docs/quickstart', + detail: 'Account, install, and first run in under 10 minutes.', + }, + { + goal: 'Moving to CI', + action: 'Install the CLI', + href: '/docs/get-started/install-cli', + detail: 'Run your existing project headless with askui run.', + }, + { + goal: 'Remote machines', + action: 'Set up AgentOS', + href: '/docs/agentos', + detail: 'Install AgentOS as a service on the machine under test.', + }, +]; + export default function HomePage() { return ( -
-

Hello World

-

- You can open{' '} - - /docs - {' '} - and see the documentation. -

+
+ + {/* Hero */} +
+

+ AskUI Documentation +

+

+ UI automation in plain language +

+

+ Describe what to do. AskUI's AI agent acts on the real screen and returns a step-by-step + report with screenshots. No selectors, no recording, no code. +

+
+ + Quickstart (10 min) + + + Browse docs + +
+
+ + {/* How it works */} +
+
+

+ How it works +

+
+ {HOW_IT_WORKS.map(({ step, title, body }) => ( +
+
+ {step} +
+

{title}

+

{body}

+
+ ))} +
+
+
+ + {/* Components */} +
+
+

+ The three components +

+
+ {COMPONENTS.map(({ name, role, description, href, cta }) => ( +
+
+

{name}

+ + {role} + +
+

+ {description} +

+ + {cta} → + +
+ ))} +
+
+
+ + {/* Why AskUI */} +
+
+

+ Why AskUI +

+
+ {WHY_ASKUI.map(({ title, description }) => ( +
+

{title}

+

{description}

+
+ ))} +
+
+
+ + {/* Where to start */} +
+
+

+ Where to start +

+
+ {WHERE_TO_START.map(({ goal, action, href, detail }) => ( + +

+ {goal} +

+

{action}

+

{detail}

+ + ))} +
+
+
+
); } diff --git a/content/docs/account-billing/billing.mdx b/content/docs/account-billing/billing.mdx index 45e1e54..5a2c63c 100644 --- a/content/docs/account-billing/billing.mdx +++ b/content/docs/account-billing/billing.mdx @@ -40,8 +40,6 @@ Plans differ by price and included usage: - **Price** — an amount and currency, billed on a recurring interval. - **Included usage** — the allowance per period before overage applies. - -This page describes the billing model from the AskUI Hub. Specific plan names, -prices, and the enterprise/on-prem options are filled in during the Hub content -pass — for enterprise terms see [AgentOS → Enterprise](/docs/agentos/reference/enterprise). - +For specific plan names and pricing, visit [askui.com](https://www.askui.com) +or contact [sales@askui.com](mailto:sales@askui.com). For enterprise and +on-premise terms see [AgentOS — Enterprise](/docs/agentos/reference/enterprise). diff --git a/content/docs/account-billing/members.mdx b/content/docs/account-billing/members.mdx new file mode 100644 index 0000000..2ad51d8 --- /dev/null +++ b/content/docs/account-billing/members.mdx @@ -0,0 +1,77 @@ +--- +title: Members +description: Invite teammates to your workspace and manage their roles. +--- + +Each AskUI workspace can have multiple members. Members share access to the +workspace's projects, access tokens, and usage data. You manage membership +from **Settings** in the AskUI Hub. + +## Roles + +Every member is assigned one of three roles when invited. Roles cannot be +changed after a member joins — to change a role, remove the member and +re-invite them with the new role. + +| Role | What they can do | +|------|-----------------| +| **Owner** | Full control: manage subscription, billing, and other owners. Can delete the workspace. | +| **Admin** | Add and remove non-owner members, manage workspace resources and settings. Cannot manage billing or delete the workspace. | +| **Member** | View workspace resources and use the platform. Cannot add or remove members or change settings. | + +## Invite a member + + + +Go to **Settings** in the left sidebar of the AskUI Hub. + + +Open the **Members** section. + + +Click **Invite Workspace Member**. + + +Enter the invitee's email address, select their role, and send the invitation. + + + +The invitee receives an email with an invitation link. Invitations expire after +**7 days** if not accepted. + +## Accept an invitation + +When you receive a workspace invitation: + + + +Click the link in the invitation email. + + +You are taken to the **Invitations** page in the Hub, which shows all your +pending invitations with their workspace, assigned role, and expiry date. + + +Click **Accept** to join the workspace, or **Decline** to reject it. + + + +## Remove a member + + + +Go to **Settings** in the Hub and open the **Members** section. + + +Find the member in the list and click the remove (trash) icon next to their +name. + + +Confirm the removal when prompted. + + + + +Once a member joins, their role is fixed. If you need to change it, remove +them and invite them again with the correct role. + diff --git a/content/docs/account-billing/meta.json b/content/docs/account-billing/meta.json index c11df66..3f0e820 100644 --- a/content/docs/account-billing/meta.json +++ b/content/docs/account-billing/meta.json @@ -1 +1 @@ -{ "title": "Account & Billing", "pages": ["workspaces", "billing"] } +{ "title": "Account & Billing", "pages": ["workspaces", "billing", "usage-dashboard", "members"] } diff --git a/content/docs/account-billing/usage-dashboard.mdx b/content/docs/account-billing/usage-dashboard.mdx new file mode 100644 index 0000000..1828506 --- /dev/null +++ b/content/docs/account-billing/usage-dashboard.mdx @@ -0,0 +1,47 @@ +--- +title: Usage dashboard +description: How to read the AskUI Hub usage dashboard and track execution metrics. +--- + +The usage dashboard in the AskUI Hub gives you a live view of how your +workspace is consuming its plan allowance. Find it under **Billing** in the +Hub. + +## Key metrics + +At the top of the dashboard you will see three summary cards: + +| Metric | What it shows | +|--------|--------------| +| **Total Events** | Total executions in the selected date range | +| **Unique Users** | Number of distinct users or access tokens that triggered runs | +| **Avg. Events per Day** | Daily average over the selected period | + +Below the summary cards you will also see your subscription limit and the +current renewal date. + +## Filtering by date range + +Use the date picker in the top-right corner of the dashboard to select a +custom date range. This lets you compare usage across billing periods or zoom +in on a particular sprint or release cycle. + +## Usage over time chart + +The chart shows execution volume per user per day. Each user (or CI access +token) is represented by a distinct color. Use the checkboxes below the chart +to show or hide individual users — select **All** or **None** to toggle +quickly. + +This view is useful for: + +- Identifying peak activity periods +- Seeing which users or CI tokens are consuming the most usage +- Spotting unexpected spikes that might indicate a misconfigured pipeline + +## Usage by access token + +Runs triggered from CI via an access token appear in the chart attributed to +that token. If you have multiple CI pipelines, give each pipeline its own +access token (see [Workspaces and access tokens](/docs/account-billing/workspaces)) +so you can distinguish their usage in the dashboard. diff --git a/content/docs/account-billing/workspaces.mdx b/content/docs/account-billing/workspaces.mdx index 3cac652..3d6b377 100644 --- a/content/docs/account-billing/workspaces.mdx +++ b/content/docs/account-billing/workspaces.mdx @@ -46,8 +46,3 @@ see [Running from the CLI](/docs/using-askui-desktop/cli). Treat access tokens like passwords. Store them in your CI secret store, never in a Project's files. Rotate by creating a new token and deleting the old one. - - -This page summarizes workspace concepts from the AskUI Hub. Exact screens and -privilege names are filled in during the Hub content pass. - diff --git a/content/docs/agentos/deployment/ci-examples.mdx b/content/docs/agentos/deployment/ci-examples.mdx new file mode 100644 index 0000000..a6423a6 --- /dev/null +++ b/content/docs/agentos/deployment/ci-examples.mdx @@ -0,0 +1,129 @@ +--- +title: CI pipeline examples +description: Ready-to-use pipeline configurations for running AskUI tests in GitHub Actions, GitLab CI, and Azure DevOps. +--- + +These examples show how to run `askui run` in the most common CI environments. +All examples assume: + +- The AskUI Desktop installer has been run on the CI machine (or a + self-hosted runner with AskUI installed), since the CLI ships with the + Desktop installer. +- `ASKUI_WORKSPACE_ID` and `ASKUI_TOKEN` are stored as CI secrets. +- Your test project is checked into the repository. + + +Desktop automation on Windows requires AgentOS running as a service. Install +it via the AskUI Desktop installer on your runner before running the pipeline. +See [CI/CD integration](/docs/agentos/deployment/ci) for setup +details. + + +## GitHub Actions + +```yaml +# .github/workflows/askui.yml +name: AskUI Tests + +on: + push: + branches: [main] + pull_request: + +jobs: + test: + runs-on: windows-latest # or macos-latest for macOS desktop / web + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run AskUI tests + env: + ASKUI_WORKSPACE_ID: ${{ secrets.ASKUI_WORKSPACE_ID }} + ASKUI_TOKEN: ${{ secrets.ASKUI_TOKEN }} + run: askui run + + - name: Upload run reports + if: always() + uses: actions/upload-artifact@v4 + with: + name: askui-reports + path: reports/ +``` + +## GitLab CI + +```yaml +# .gitlab-ci.yml +askui-tests: + stage: test + tags: + - windows # use a self-hosted runner with AskUI installed + variables: + ASKUI_WORKSPACE_ID: $ASKUI_WORKSPACE_ID + ASKUI_TOKEN: $ASKUI_TOKEN + script: + - askui run + artifacts: + when: always + paths: + - reports/ + expire_in: 7 days +``` + +## Azure DevOps + +```yaml +# azure-pipelines.yml +trigger: + - main + +pool: + vmImage: windows-latest # or a self-hosted agent with AskUI installed + +steps: + - checkout: self + + - script: askui run + displayName: Run AskUI tests + env: + ASKUI_WORKSPACE_ID: $(ASKUI_WORKSPACE_ID) + ASKUI_TOKEN: $(ASKUI_TOKEN) + + - task: PublishBuildArtifacts@1 + condition: always() + inputs: + pathToPublish: reports/ + artifactName: askui-reports +``` + +## Connecting to a remote AgentOS + +If your CI runner is not the machine being automated (e.g. a Linux runner +automating a separate Windows VM), disable AgentOS autostart and point the +CLI at the remote instance: + +```bash +export ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART=false +export ASKUI_CONTROLLER_CLIENT_SERVER_ADDRESS=:26000 +askui run +``` + +See [Remote Windows VM](/docs/agentos/deployment/ci#remote-windows-vm) +for the full setup. + +## Storing credentials + +Never hardcode `ASKUI_WORKSPACE_ID` or `ASKUI_TOKEN` in your pipeline files. +Use your CI platform's secret store: + +| Platform | Where to add secrets | +|----------|---------------------| +| GitHub Actions | Repository Settings → Secrets and variables → Actions | +| GitLab CI | Settings → CI/CD → Variables | +| Azure DevOps | Pipeline → Edit → Variables | + +Create a dedicated access token per pipeline so you can rotate or revoke +individual pipelines without affecting others. See +[Workspaces](/docs/account-billing/workspaces). diff --git a/content/docs/agentos/how-to-guides/deployment-ci.mdx b/content/docs/agentos/deployment/ci.mdx similarity index 95% rename from content/docs/agentos/how-to-guides/deployment-ci.mdx rename to content/docs/agentos/deployment/ci.mdx index 75e20f0..faeb750 100644 --- a/content/docs/agentos/how-to-guides/deployment-ci.mdx +++ b/content/docs/agentos/deployment/ci.mdx @@ -114,7 +114,7 @@ Run automation on a macOS or Linux CI runner. AgentOS runs in standalone mode. **When to use:** Your CI pipeline runs on macOS or Linux and you want to automate the desktop on that same runner. -**Install:** `pip install askui-agent-os` +**Install:** [AskUI Desktop installer](/docs/get-started/install-desktop) (includes AgentOS). A standalone installer for CI use is coming soon. ```mermaid graph LR @@ -135,7 +135,7 @@ Automate Android or iOS devices connected to your CI runner via USB. **When to use:** Mobile testing in your pipeline — the device is physically connected to the CI runner. -**Install:** `pip install askui-agent-os` on the CI runner. +**Install:** [AskUI Desktop installer](/docs/get-started/install-desktop) (includes AgentOS) on the CI runner. A standalone installer is coming soon. ```mermaid graph LR diff --git a/content/docs/agentos/how-to-guides/deployment-local.mdx b/content/docs/agentos/deployment/local.mdx similarity index 87% rename from content/docs/agentos/how-to-guides/deployment-local.mdx rename to content/docs/agentos/deployment/local.mdx index d697f0f..c83dd13 100644 --- a/content/docs/agentos/how-to-guides/deployment-local.mdx +++ b/content/docs/agentos/deployment/local.mdx @@ -3,7 +3,7 @@ title: Local Development description: "Deploy AgentOS on your own machine for desktop, mobile, or hardware-based automation." --- -You're building and testing agents on your own machine. In all local scenarios, you install AgentOS via `pip install askui-agent-os`, and AskUI Desktop and the CLI connect to the local AgentOS instance over gRPC. +You're building and testing agents on your own machine. In all local scenarios, AgentOS is installed via the AskUI installer, and AskUI Desktop and the CLI connect to the local AgentOS instance over gRPC. ## Desktop @@ -11,7 +11,7 @@ Automate the desktop on your own Windows, macOS, or Linux machine. AgentOS runs **When to use:** Day-to-day development, debugging, and interactive testing. -**Install:** `pip install askui-agent-os` → [Standalone](/docs/agentos/installation/standalone) +**Install:** [AskUI Desktop installer](/docs/get-started/install-desktop) (includes AgentOS) → [Standalone](/docs/agentos/installation/standalone) ```mermaid graph LR @@ -32,7 +32,7 @@ Automate an Android or iOS device connected to your machine via USB. **When to use:** Mobile app testing, device interaction during development. -**Install:** `pip install askui-agent-os` → [Standalone](/docs/agentos/installation/standalone) +**Install:** [AskUI Desktop installer](/docs/get-started/install-desktop) (includes AgentOS) → [Standalone](/docs/agentos/installation/standalone) ```mermaid graph LR @@ -113,7 +113,7 @@ Control a target device through physical hardware connections — keyboard/mouse **When to use:** The target device can't have software installed on it (locked-down environments, embedded systems, kiosks). -**Install:** `pip install askui-agent-os` → [Standalone](/docs/agentos/installation/standalone) +**Install:** [AskUI Desktop installer](/docs/get-started/install-desktop) (includes AgentOS) → [Standalone](/docs/agentos/installation/standalone) ```mermaid graph LR diff --git a/content/docs/agentos/deployment/meta.json b/content/docs/agentos/deployment/meta.json new file mode 100644 index 0000000..dac2d1b --- /dev/null +++ b/content/docs/agentos/deployment/meta.json @@ -0,0 +1 @@ +{ "title": "Deployment", "pages": ["local", "ci", "ci-examples", "multi-device"] } diff --git a/content/docs/agentos/how-to-guides/deployment-multi-device.mdx b/content/docs/agentos/deployment/multi-device.mdx similarity index 100% rename from content/docs/agentos/how-to-guides/deployment-multi-device.mdx rename to content/docs/agentos/deployment/multi-device.mdx diff --git a/content/docs/agentos/how-to-guides/meta.json b/content/docs/agentos/how-to-guides/meta.json deleted file mode 100644 index fdebf55..0000000 --- a/content/docs/agentos/how-to-guides/meta.json +++ /dev/null @@ -1 +0,0 @@ -{ "title": "How-to guides", "pages": ["deployment-local", "deployment-ci", "deployment-multi-device", "troubleshooting"] } diff --git a/content/docs/agentos/installation/service.mdx b/content/docs/agentos/installation/service.mdx index d4ef6e4..6deb559 100644 --- a/content/docs/agentos/installation/service.mdx +++ b/content/docs/agentos/installation/service.mdx @@ -13,7 +13,7 @@ AgentOS is proprietary software, **free for non-commercial use**. For commercial - **Administrator rights** -To automate the login/lock screen (Secure Attention Sequence), a Group Policy setting must be enabled. See [Troubleshooting](/docs/agentos/how-to-guides/troubleshooting#agent-cant-press-ctrlaltdel) for details. +To automate the login/lock screen (Secure Attention Sequence), a Group Policy setting must be enabled. See [Troubleshooting](/docs/agentos/troubleshooting#agent-cant-press-ctrlaltdel) for details. ## Installation @@ -40,7 +40,7 @@ The installer includes a **Service Configuration** screen: - **Connection Scope:** Use **Public (0.0.0.0)** if AgentOS needs to be reachable from another machine (e.g. a remote CI runner). Keep **Private (127.0.0.1)** for local use only. - **Log Level:** `Info` for production, `Debug` for troubleshooting. -- **Allow CTRL+ALT+DEL:** Enable to automate the Windows lock/login screen (requires Group Policy — see [Troubleshooting](/docs/agentos/how-to-guides/troubleshooting#agent-cant-press-ctrlaltdel)). +- **Allow CTRL+ALT+DEL:** Enable to automate the Windows lock/login screen (requires Group Policy — see [Troubleshooting](/docs/agentos/troubleshooting#agent-cant-press-ctrlaltdel)). - **Allow control of administrative applications:** Enable only if you need to automate apps running as administrator. Click **Next**, then **Install**. diff --git a/content/docs/agentos/installation/standalone.mdx b/content/docs/agentos/installation/standalone.mdx index 5752dd5..eac9626 100644 --- a/content/docs/agentos/installation/standalone.mdx +++ b/content/docs/agentos/installation/standalone.mdx @@ -23,11 +23,13 @@ commercial deployments a license is required — see ## Install -AgentOS ships with AskUI Desktop (it includes an embedded runtime), so most -users get it automatically when they -[install AskUI Desktop](/docs/get-started/install-desktop). To run AgentOS -standalone on a machine without the desktop app, use the standalone installer -from your AskUI account. +AgentOS ships with the AskUI Desktop installer, so most users get it +automatically when they [install AskUI Desktop](/docs/get-started/install-desktop). + + +A dedicated AgentOS installer for machines without AskUI Desktop is in +progress. For now, use the AskUI Desktop installer to get AgentOS on a machine. + ## What's next? diff --git a/content/docs/agentos/meta.json b/content/docs/agentos/meta.json index 5bb0cbe..e978ab8 100644 --- a/content/docs/agentos/meta.json +++ b/content/docs/agentos/meta.json @@ -1 +1 @@ -{ "title": "AgentOS", "pages": ["index", "understanding", "installation", "how-to-guides", "reference", "release-notes"] } +{ "title": "AgentOS", "pages": ["index", "understanding", "installation", "deployment", "troubleshooting", "reference", "release-notes"] } diff --git a/content/docs/agentos/reference/system-requirements.mdx b/content/docs/agentos/reference/system-requirements.mdx index 59a2cc6..985a9a4 100644 --- a/content/docs/agentos/reference/system-requirements.mdx +++ b/content/docs/agentos/reference/system-requirements.mdx @@ -63,6 +63,4 @@ description: "Hardware, software, and platform requirements for AgentOS." ## Software Requirements - -**Python 3.10 or newer** is required to install the AgentOS runtime. Install from [python.org](https://python.org) if needed. - +AgentOS is installed via the AskUI installer and has no separate software prerequisites. diff --git a/content/docs/agentos/how-to-guides/troubleshooting.mdx b/content/docs/agentos/troubleshooting.mdx similarity index 67% rename from content/docs/agentos/how-to-guides/troubleshooting.mdx rename to content/docs/agentos/troubleshooting.mdx index 17acbb9..731bbad 100644 --- a/content/docs/agentos/how-to-guides/troubleshooting.mdx +++ b/content/docs/agentos/troubleshooting.mdx @@ -90,10 +90,84 @@ Check the `ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART` environment variable — if -This variable is intentionally set to `false` when connecting to a remote AgentOS instance — see [Remote Windows VM](/docs/agentos/how-to-guides/deployment-ci/#remote-windows-vm). +This variable is intentionally set to `false` when connecting to a remote AgentOS instance — see [Remote Windows VM](/docs/agentos/deployment/ci/#remote-windows-vm). ### Need to reinstall or remove **Do not** stop or remove the service from Windows Services manually. Always **uninstall the full AskUI AgentOS application** via Windows Add/Remove Programs. This ensures proper cleanup so the client falls back to standalone mode. + +## Proxy and SSL + +### Configure a proxy + +AskUI Desktop and the CLI respect the standard proxy environment variables. +Set them before launching: + + + + ```powershell + $env:HTTP_PROXY="http://proxy.example.com:8080" + $env:HTTPS_PROXY="http://proxy.example.com:8080" + $env:NO_PROXY="localhost,127.0.0.1" + ``` + + + ```bash + export HTTP_PROXY="http://proxy.example.com:8080" + export HTTPS_PROXY="http://proxy.example.com:8080" + export NO_PROXY="localhost,127.0.0.1" + ``` + + + +### Deep-packet-inspection proxies (Zscaler and similar) + +Some corporate proxies intercept HTTPS traffic and inject a custom root +certificate. This can cause SSL errors like: + +``` +SSL: CERTIFICATE_VERIFY_FAILED +``` + +**Solution:** Disable SSL verification as a temporary workaround while you +get the proxy certificate added to your system trust store: + + + + ```powershell + $env:ASKUI_HTTP_SSL_VERIFICATION="false" + ``` + + + ```bash + export ASKUI_HTTP_SSL_VERIFICATION=false + ``` + + + + +Disabling SSL verification reduces security. Re-enable it once your proxy +certificate is trusted by the OS certificate store. + + +The permanent fix is to add your proxy's root certificate to the system +certificate store. Contact your IT/network team for the certificate file and +import instructions for your OS. + +## Debugging run failures + +The fastest way to debug a failing run: + +1. Open the run report (`.md` file in your project's `reports/` folder or + inline in AskUI Desktop). +2. Find the first step with status `FAILED` or `BROKEN` — that is where to + focus. +3. Check the screenshot for that step. `FAILED` means the expected outcome + didn't match; `BROKEN` means an infrastructure problem (connection lost, + session expired) stopped the run. +4. For AgentOS issues, check the [logs](#logs) for more detail. + +If you cannot resolve the issue yourself, see [Get help](/docs/support/get-help) +for how to generate a diagnostic report and contact support. diff --git a/content/docs/agentos/understanding/control-modes.mdx b/content/docs/agentos/understanding/control-modes.mdx index 1e0ccc5..fae7197 100644 --- a/content/docs/agentos/understanding/control-modes.mdx +++ b/content/docs/agentos/understanding/control-modes.mdx @@ -42,7 +42,7 @@ For a detailed breakdown of what each mode can do, see [Capabilities](/docs/agen - + diff --git a/content/docs/agentos/understanding/runtime-modes.mdx b/content/docs/agentos/understanding/runtime-modes.mdx index 75e86b8..9a5aa4c 100644 --- a/content/docs/agentos/understanding/runtime-modes.mdx +++ b/content/docs/agentos/understanding/runtime-modes.mdx @@ -11,11 +11,16 @@ AgentOS runs as a regular process in the current user's session. **Best for:** Local development, interactive desktop use, and manual testing. -```bash -pip install askui-agent-os -``` +AgentOS is installed via the AskUI installer. A dedicated standalone installer +(without AskUI Desktop) is coming soon. -That's it — AskUI Desktop and the CLI use the local AgentOS instance automatically. + +For now, standalone AgentOS is installed as part of the +[AskUI Desktop installer](/docs/get-started/install-desktop). A separate +standalone installer is in progress. + + +Once installed, AskUI Desktop and the CLI use the local AgentOS instance automatically. ## OS Service @@ -36,7 +41,7 @@ The OS service requires the [Windows installer](/docs/agentos/installation/servi | **Logon screen control** | No | Yes | | **Send CTRL+ALT+DEL** | No | Yes (Secure Attention Sequence) | | **Privileges** | Current user | SYSTEM | -| **Install method** | `pip install` | Windows installer | +| **Install method** | AskUI installer (standalone coming soon) | Windows installer | **Not sure which to pick?** Start with **standalone** for development. Move to the **OS service** when you need CI/CD, headless VMs, or RDP resilience. diff --git a/content/docs/get-started/install-cli.mdx b/content/docs/get-started/install-cli.mdx index 4d674dc..896b60c 100644 --- a/content/docs/get-started/install-cli.mdx +++ b/content/docs/get-started/install-cli.mdx @@ -13,13 +13,14 @@ produces. Use it locally for scripted runs, in CI, or on a schedule. **Install the CLI** -The CLI ships with the AskUI installer, alongside AskUI Desktop and -[AgentOS](/docs/agentos). - - -Per-platform download links land here once the release pipeline is live. If -you received a preview build, place the `askui` executable somewhere on your -`PATH`. +The CLI ships with the **AskUI Desktop installer** — installing AskUI Desktop +also installs the `askui` CLI on your machine. Follow the +[Install AskUI Desktop](/docs/get-started/install-desktop) guide if you +haven't done that yet. + + +A standalone CLI installer (without the Desktop App) is in progress. For now, +the CLI is only available as part of the Desktop App installation. @@ -50,7 +51,7 @@ You should see the `askui run` usage with its options. `adb` must be on your `PATH` and the device (or emulator) visible to - `adb devices`. See the [ADB setup guide](/docs/agentos/how-to-guides/deployment-local#android-setting-up-adb). + `adb devices`. See the [ADB setup guide](/docs/agentos/deployment/local#android-setting-up-adb). diff --git a/content/docs/get-started/install-desktop.mdx b/content/docs/get-started/install-desktop.mdx index 6f108a9..939e5ee 100644 --- a/content/docs/get-started/install-desktop.mdx +++ b/content/docs/get-started/install-desktop.mdx @@ -13,12 +13,13 @@ It runs on Windows and macOS. -**Run the installer** and follow the guided setup. +**Run the installer** and follow the guided setup. The installer includes both +AskUI Desktop and the `askui` CLI. - Run the `.exe` and accept the prompts. AskUI Desktop installs with an - embedded Python runtime — no separate Python install is required. + Run the `.exe` and accept the prompts. The installer is self-contained — + no additional runtimes required. Open the `.dmg` and drag AskUI Desktop to Applications. On first launch, @@ -38,8 +39,3 @@ It runs on Windows and macOS. - - -This is a scaffold page. Real download links and version-specific notes go here -once the release pipeline is wired up. - diff --git a/content/docs/get-started/meta.json b/content/docs/get-started/meta.json index f80ce48..224015d 100644 --- a/content/docs/get-started/meta.json +++ b/content/docs/get-started/meta.json @@ -1 +1 @@ -{ "title": "Get Started", "pages": ["install-desktop", "install-cli", "onboarding", "licensing", "first-run"] } +{ "title": "Get Started", "pages": ["install-desktop", "install-cli", "onboarding", "licensing", "first-run", "uninstall"] } diff --git a/content/docs/get-started/uninstall.mdx b/content/docs/get-started/uninstall.mdx new file mode 100644 index 0000000..c10308c --- /dev/null +++ b/content/docs/get-started/uninstall.mdx @@ -0,0 +1,65 @@ +--- +title: Uninstall AskUI +description: Remove AskUI Desktop and the CLI from Windows or macOS. +--- + +Uninstalling AskUI Desktop also removes the `askui` CLI, as both ship together +in the same installer. + + + + + + Open **Settings** and go to **Apps** (or open **Control Panel** and go to + **Programs and Features**). + + + Find **AskUI Desktop** in the list of installed applications. + + + Select it and click **Uninstall**, then follow the prompts. + + + + The uninstaller removes AskUI Desktop, the CLI, and AgentOS. It also cleans + up environment variables and the `.askui` folder in your user profile. + + **Silent uninstall (Windows):** + + ```powershell + "" /qn + ``` + + To write a detailed log during uninstall: + + ```powershell + "" /qn /l*vx uninstall.log + ``` + + + + + Open **Finder** and go to **Applications**. + + + Drag **AskUI Desktop** to the Trash, or right-click and select + **Move to Trash**. + + + Empty the Trash to complete the removal. + + + + To also remove configuration files and logs from your home directory: + + ```bash + rm -rf ~/.askui + ``` + + + + +After uninstalling, the `askui` command will no longer be available in your +terminal. Reinstall via the +[AskUI Desktop installer](/docs/get-started/install-desktop) to get it back. + diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx new file mode 100644 index 0000000..e413d07 --- /dev/null +++ b/content/docs/guides/index.mdx @@ -0,0 +1,28 @@ +--- +title: Guides +description: Best-practice guides for authoring reliable AskUI tests — with more to come. +--- + +These guides go deeper than the reference docs. They explain *why* things work +the way they do and give you patterns you can apply directly to your projects. + +## Available guides + + + + How to structure a Project's prompts so runs are reliable, reusable, and + debuggable — the four-file layout, per-folder rules, and how to handle + credentials safely. + + + The deeper theory behind the five-part prompt structure, with a complete + worked example. + + + +## Coming soon + +- **Video tutorials** — end-to-end walkthroughs of common testing scenarios +- **CI/CD patterns** — how to wire AskUI into GitHub Actions, GitLab CI, and Jenkins +- **Multi-device fleet setup** — running the same suite across many machines in parallel +- **Flaky test debugging** — how to read a failing report and pinpoint the root cause diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json new file mode 100644 index 0000000..d5e530a --- /dev/null +++ b/content/docs/guides/meta.json @@ -0,0 +1 @@ +{ "title": "Guides", "pages": ["index"] } diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 56bbf09..d147e7c 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -1,37 +1,60 @@ --- title: AskUI Documentation -description: Author and run AI-driven UI tests with AskUI Desktop and the AskUI CLI. +description: AI-driven UI automation — author tests in plain language, run them on desktop, browser, or Android, and scale to CI and multi-device fleets. --- -Author and run AI-driven UI tests — on the desktop and from the command line. +**AskUI** lets you automate any UI by describing what to do in plain language. There is no selector to write and no recording to maintain — you describe a step ("click the login button", "fill in the email field with the QA credentials"), an AI agent carries it out on the real screen, and a report shows you exactly what happened and why. -[Get started](/docs/get-started/install-desktop) · [Prompting best practices](/docs/using-askui-desktop/prompting-best-practices) +You can author and run tests interactively in the **Desktop App**, drive the same tests headlessly from the **CLI** (locally or in CI), and rely on **AgentOS** as the low-level runtime that gives the agent direct OS control — keyboard, mouse, and screen. -## Where to start +## How these docs are organized - - The local host for authoring and running AI-driven UI tests. Build a test - Project, write prompts, and watch runs execute on your machine. + + Go from zero to a passing test in under 10 minutes. Covers account creation, + installation, and your first run. - [Install AskUI Desktop →](/docs/get-started/install-desktop) + [Start here →](/docs/quickstart) - - Run the same Projects headless — in CI, on a schedule, or across many - devices. + + Everything about AskUI Desktop: installation, projects, prompts, model + providers, and reading run reports. - [Install the CLI →](/docs/get-started/install-cli) + [Install Desktop →](/docs/get-started/install-desktop) - - How to structure a Project's prompts so runs are reliable, reusable, and - debuggable. + + Run projects headless in CI, on a schedule, or across many devices. The CLI + ships with the Desktop App installer. - [Read the guide →](/docs/using-askui-desktop/prompting-best-practices) + [CLI docs →](/docs/get-started/install-cli) - The runtime layer that gives agents direct control over a machine's OS — - keyboard, mouse, screen, and system functions. + The runtime layer that gives agents direct OS control. Installation, + deployment modes, and enterprise configuration. [Explore AgentOS →](/docs/agentos) + + Best-practice guides for prompting, structuring projects, and getting + reliable runs — with more to come. + + [Browse guides →](/docs/guides) + + + Workspaces, access tokens, and plans. + + [Manage account →](/docs/account-billing/workspaces) + + +## The three components + +| Component | What it is | When you need it | +|-----------|-----------|-----------------| +| **AskUI Desktop** | GUI app for authoring and running tests | Always — this is where you write and review tests | +| **AskUI CLI** | Headless runner (`askui run`) | CI pipelines, scheduled runs, multi-device fleets | +| **AgentOS** | OS-level control runtime | Desktop and Android targets (installed automatically for local runs) | + +## Not sure where to start? + +Go to the **[Quickstart](/docs/quickstart)** — it walks you through account creation, installation, and a first passing test in under 10 minutes. diff --git a/content/docs/legacy/index.mdx b/content/docs/legacy/index.mdx new file mode 100644 index 0000000..b6a51aa --- /dev/null +++ b/content/docs/legacy/index.mdx @@ -0,0 +1,41 @@ +--- +title: Legacy SDKs +description: The AskUI Python SDK and TypeScript SDK are no longer supported. Use AskUI Desktop and the CLI instead. +--- + + +The Python SDK and TypeScript SDK are legacy products. They receive no bug +fixes, security updates, or new features. We strongly recommend migrating to +**AskUI Desktop** and the **AskUI CLI**. + + +AskUI previously offered two code-based SDKs for authoring UI automation: + +- **Python SDK** — write automation scripts in Python against the AskUI runtime. +- **TypeScript SDK** — write automation scripts in TypeScript/Node.js against the AskUI runtime. + +Both SDKs required writing code to interact with the AskUI agent. They are no +longer actively developed or supported. + +## Why we moved on + +The SDK approach required users to learn an API, manage a language runtime, and +maintain code as their UI changed. AskUI Desktop replaces all of that with +plain-language prompts that describe what to do rather than how to do it — no +selectors, no boilerplate, no SDK version upgrades. + +## What to use instead + + + + Author tests in plain Markdown and run them interactively on your machine. + No code, no selectors, no SDK. + + + Run the same projects headless in CI or on a schedule with a single + command. Ships with the Desktop App installer. + + + Get from zero to a passing test in under 10 minutes. + + diff --git a/content/docs/legacy/meta.json b/content/docs/legacy/meta.json new file mode 100644 index 0000000..1139c21 --- /dev/null +++ b/content/docs/legacy/meta.json @@ -0,0 +1 @@ +{ "title": "Legacy", "pages": ["index", "python-sdk", "typescript-sdk"] } diff --git a/content/docs/legacy/python-sdk.mdx b/content/docs/legacy/python-sdk.mdx new file mode 100644 index 0000000..73e11e2 --- /dev/null +++ b/content/docs/legacy/python-sdk.mdx @@ -0,0 +1,25 @@ +--- +title: Python SDK (legacy) +description: The AskUI Python SDK is no longer supported. Use AskUI Desktop and the CLI instead. +--- + + +The Python SDK is a legacy product. It receives no bug fixes, security +updates, or new features. Use **AskUI Desktop** and the **AskUI CLI** for all +new projects. + + +The AskUI Python SDK allowed writing UI automation scripts in Python against +the AskUI agent runtime. It is no longer actively developed or supported. + +## Migrate to AskUI Desktop + +AskUI Desktop replaces the SDK workflow entirely. Instead of writing Python +code to interact with UI elements, you describe test steps in plain Markdown +and the AI agent carries them out on the real screen. + +You do not need to rewrite automation logic line by line. The prompt-based +approach means most test scenarios can be expressed more concisely than the +equivalent SDK code. + +**[Get started with AskUI Desktop](/docs/get-started/install-desktop)** diff --git a/content/docs/legacy/typescript-sdk.mdx b/content/docs/legacy/typescript-sdk.mdx new file mode 100644 index 0000000..9446ffb --- /dev/null +++ b/content/docs/legacy/typescript-sdk.mdx @@ -0,0 +1,26 @@ +--- +title: TypeScript SDK (legacy) +description: The AskUI TypeScript SDK is no longer supported. Use AskUI Desktop and the CLI instead. +--- + + +The TypeScript SDK is a legacy product. It receives no bug fixes, security +updates, or new features. Use **AskUI Desktop** and the **AskUI CLI** for all +new projects. + + +The AskUI TypeScript SDK allowed writing UI automation scripts in +TypeScript/Node.js against the AskUI agent runtime. It is no longer actively +developed or supported. + +## Migrate to AskUI Desktop + +AskUI Desktop replaces the SDK workflow entirely. Instead of writing +TypeScript code to interact with UI elements, you describe test steps in plain +Markdown and the AI agent carries them out on the real screen. + +You do not need to rewrite automation logic line by line. The prompt-based +approach means most test scenarios can be expressed more concisely than the +equivalent SDK code. + +**[Get started with AskUI Desktop](/docs/get-started/install-desktop)** diff --git a/content/docs/meta.json b/content/docs/meta.json index 79b7447..17b97d2 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1 +1 @@ -{ "pages": ["index", "get-started", "using-askui-desktop", "agentos", "account-billing", "reference"] } +{ "pages": ["index", "quickstart", "get-started", "using-askui-desktop", "agentos", "guides", "account-billing", "reference", "support", "legacy"] } diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx new file mode 100644 index 0000000..f02e651 --- /dev/null +++ b/content/docs/quickstart.mdx @@ -0,0 +1,136 @@ +--- +title: Quickstart +description: Go from zero to a passing AskUI test in under 10 minutes. +--- + +This guide takes you from a blank machine to a passing test in under 10 minutes. +You will create an AskUI account, install the Desktop App, and run your first +test — no selectors, no code, just plain language. + + +A Windows or macOS machine. No prior automation experience required. + + +--- + +## Step 1 — Create your account (2 min) + + + +**Go to the AskUI Hub** and sign up with your work email. + + +**Accept the terms and privacy policy.** One-time step — required to continue. + + +**Verify your email.** We send a link to your inbox; click it to activate your +account. (Didn't arrive? You can resend from the prompt.) + + +**You land in the Hub.** The Hub is where you manage your workspace, access +tokens, and usage. Leave it open — you will come back to it in a moment. + + + +--- + +## Step 2 — Install AskUI Desktop (3 min) + + + +**Download the installer** from your AskUI Hub account page. + + +**Run the installer** for your platform. + + + + Run the `.exe` and follow the guided setup. The installer is + self-contained — no additional runtimes required. + + + Open the `.dmg` and drag AskUI Desktop into Applications. On first launch, + grant **Accessibility** and **Screen Recording** permissions under + **System Settings → Privacy & Security**. These allow the agent to read + your screen and control input. + + + + +**Launch AskUI Desktop** and sign in with the account you just created. + + + +--- + +## Step 3 — Run your first test (5 min) + + + +**Create a new Project.** AskUI Desktop scaffolds the standard folder structure +for you — `tests/`, `prompts/`, `procedures/`, `plans/`, `secrets/` — and +pre-seeds it with an example test. + + +**Open `prompts/ui_information.md`** and describe your app in a few sentences: +what its main screens are, how you can tell you are signed in, and any quirks +(e.g. "a loading spinner appears for 2–3 seconds after login"). This is the +single most important file for reliable runs. + +```markdown +# About this app +A web app for managing support tickets. +The main view is a table of open tickets. +A green badge in the top-right shows the logged-in user's name. +``` + + +**Open the example test** in `tests/` and read through it. The steps are +written in plain Markdown — no code, no XPath. Adjust a step or two to match +your own app. + +```markdown +# Login test + +## Steps + +1. Open the app at https://app.example.com +2. Sign in using the QA credentials. +3. Verify the green badge appears with the user's name. +``` + + +**Click Run.** AskUI Desktop launches the agent, which acts on the screen step +by step and writes a report with a screenshot per step. + + +**Read the report.** Each step shows its status (`PASSED`, `FAILED`, `WARN`, +`SKIPPED`, or `BROKEN`) and a screenshot. A green run means every step +actually passed — the agent doesn't improvise. + + + +--- + +## What's next + +You have a working project. Here is where to go from here: + + + + Learn how to structure prompts so your runs stay reliable as your test suite + grows — the four-file layout, `rules.md`, and how to avoid brittle tests. + + + Understand what each folder in a Project does and how the runner picks up + setup, teardown, and shared procedures automatically. + + + Once your project runs locally, move it to CI in minutes with `askui run`. + Works with GitHub Actions, GitLab CI, and any headless environment. + + + Running tests on a remote machine or in a multi-device fleet? Learn how to + install and configure AgentOS as a background service. + + diff --git a/content/docs/reference/environment-variables.mdx b/content/docs/reference/environment-variables.mdx new file mode 100644 index 0000000..5ea8719 --- /dev/null +++ b/content/docs/reference/environment-variables.mdx @@ -0,0 +1,32 @@ +--- +title: Environment variables +description: All environment variables recognised by AskUI Desktop, the CLI, and AgentOS. +--- + +## Authentication + +| Variable | Description | +|----------|-------------| +| `ASKUI_WORKSPACE_ID` | Your workspace identifier. Required when using the AskUI Hub as the model provider. | +| `ASKUI_TOKEN` | Your workspace access token. Required when using the AskUI Hub as the model provider. See [Workspaces](/docs/account-billing/workspaces). | + +## AgentOS connection + +| Variable | Default | Description | +|----------|---------|-------------| +| `ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART` | `true` | Set to `false` to prevent the CLI from starting a local AgentOS instance automatically. Use this when connecting to a remote AgentOS. | +| `ASKUI_CONTROLLER_CLIENT_SERVER_ADDRESS` | `localhost:23000` | Address of the AgentOS gRPC server to connect to. Override when using a remote AgentOS instance. | + +## Proxy + +| Variable | Description | +|----------|-------------| +| `HTTP_PROXY` | URL of an HTTP proxy server (e.g. `http://proxy.example.com:8080`). | +| `HTTPS_PROXY` | URL of an HTTPS proxy server. | +| `NO_PROXY` | Comma-separated list of hosts that should bypass the proxy (e.g. `localhost,127.0.0.1`). | + +## TLS/SSL + +| Variable | Default | Description | +|----------|---------|-------------| +| `ASKUI_HTTP_SSL_VERIFICATION` | `true` | Set to `false` to disable SSL certificate verification. Use only as a last resort in environments with deep-packet-inspection proxies. See [Proxy and SSL troubleshooting](/docs/agentos/troubleshooting#proxy-and-ssl). | diff --git a/content/docs/reference/glossary.mdx b/content/docs/reference/glossary.mdx new file mode 100644 index 0000000..aea0307 --- /dev/null +++ b/content/docs/reference/glossary.mdx @@ -0,0 +1,21 @@ +--- +title: Glossary +description: Definitions for key terms used across AskUI documentation. +--- + +| Term | Definition | +|------|-----------| +| **Access token** | A credential that authenticates the CLI or an external integration with the AskUI Hub. Every token belongs to exactly one workspace and has an expiry date. See [Workspaces](/docs/account-billing/workspaces). | +| **AgentOS** | The runtime layer that gives the AI agent direct OS-level control: keyboard, mouse, screen capture, and system functions. Runs on Windows, macOS, and Linux. | +| **Annotation** | A marked region around a UI element with metadata including its name, text content, and bounding box coordinates. | +| **Bounding box** | A rectangle defined by coordinates that describes the location and size of a UI element on screen. | +| **Companion Mode** | An AgentOS control mode where AgentOS runs on an external device (e.g. Raspberry Pi) and controls the target through hardware interfaces. No software installation on the target is required. | +| **Credentials** | The combination of a **workspace ID** and an **access token** for the same workspace. | +| **Element** | A graphical user interface component: a button, text field, menu item, image, etc. | +| **Host Mode** | An AgentOS control mode where AgentOS runs directly on the target machine and controls it via OS-level APIs. | +| **Inference** | The process of sending a screenshot to the AI model to identify and locate UI elements. | +| **Project** | A folder structure created by AskUI Desktop containing tests, prompts, procedures, plans, and secrets. The unit of work for authoring and running tests. | +| **Procedure** | A reusable multi-step sequence (e.g. "log in") stored in `procedures/` and invoked from test steps by name. | +| **Run report** | The output of a test run: a Markdown file with a status and screenshot per step. Statuses are `PASSED`, `FAILED`, `WARN`, `SKIPPED`, or `BROKEN`. | +| **Workspace** | The account-level container in the AskUI Hub that owns access tokens, usage events, and billing. Every AskUI account belongs to one or more workspaces. | +| **Workspace ID** | The unique identifier for a workspace. Used together with an access token to authenticate with the AskUI Hub. | diff --git a/content/docs/reference/inference-api.mdx b/content/docs/reference/inference-api.mdx deleted file mode 100644 index b3d5cdc..0000000 --- a/content/docs/reference/inference-api.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Inference API -description: Reference for the AskUI Inference API. ---- - -The inference endpoints that power screen understanding and element detection. - - -Stub page in the scaffold — fill in during the full content migration. - diff --git a/content/docs/reference/meta.json b/content/docs/reference/meta.json index 33b40bc..ad27ecf 100644 --- a/content/docs/reference/meta.json +++ b/content/docs/reference/meta.json @@ -1 +1 @@ -{ "title": "Reference", "pages": ["workspace-api", "inference-api"] } +{ "title": "Reference", "pages": ["environment-variables", "network-requirements", "glossary"] } diff --git a/content/docs/reference/network-requirements.mdx b/content/docs/reference/network-requirements.mdx new file mode 100644 index 0000000..41aa6d2 --- /dev/null +++ b/content/docs/reference/network-requirements.mdx @@ -0,0 +1,52 @@ +--- +title: Network requirements +description: Domains and ports that must be reachable for AskUI to function. +--- + +AskUI requires outbound HTTPS access (port 443) to the following domains. +If your environment uses a firewall or corporate proxy, add these to your +allowlist. + +## Required domains + +| Domain | Purpose | +|--------|---------| +| `*.askui.com` | Catch-all for all AskUI services | +| `hub.askui.com` | AskUI Hub: account, billing, workspace management | +| `workspaces.askui.com` | Workspace API and access token validation | +| `inference.askui.com` | AI inference for screen understanding | +| `files.askui.com` | Asset and installer downloads | +| `tracking.askui.com` | Anonymous usage telemetry | +| `tracking-cdn.askui.com` | Telemetry CDN | + +All connections use **HTTPS on port 443**. No inbound ports are required. + +## Proxy configuration + +If your network routes traffic through a proxy, set the standard proxy +environment variables before running AskUI Desktop or the CLI: + +```bash +export HTTP_PROXY="http://proxy.example.com:8080" +export HTTPS_PROXY="http://proxy.example.com:8080" +export NO_PROXY="localhost,127.0.0.1" +``` + +On Windows PowerShell: + +```powershell +$env:HTTP_PROXY="http://proxy.example.com:8080" +$env:HTTPS_PROXY="http://proxy.example.com:8080" +$env:NO_PROXY="localhost,127.0.0.1" +``` + +For deep-packet-inspection proxies (e.g. Zscaler) that inject custom SSL +certificates, see +[Proxy and SSL troubleshooting](/docs/agentos/troubleshooting#proxy-and-ssl). + +## Air-gapped and on-premise deployments + +Enterprise customers can deploy AskUI in air-gapped environments or +on-premise. In these setups the inference endpoint is hosted internally and +no external network access is required. Contact your account manager for +details. diff --git a/content/docs/reference/workspace-api.mdx b/content/docs/reference/workspace-api.mdx deleted file mode 100644 index 93713bc..0000000 --- a/content/docs/reference/workspace-api.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Workspace API -description: Reference for the AskUI Workspace API. ---- - -Programmatic access to workspaces, Projects, and runs. - - -Stub page in the scaffold — fill in during the full content migration. - diff --git a/content/docs/support/faq.mdx b/content/docs/support/faq.mdx new file mode 100644 index 0000000..83a3d47 --- /dev/null +++ b/content/docs/support/faq.mdx @@ -0,0 +1,126 @@ +--- +title: FAQ +description: Frequently asked questions about AskUI. +--- + +## General + +### What is AskUI? + +AskUI is an AI-driven UI automation platform. You describe what to do in plain +language, and an AI agent acts on the real screen — clicking, typing, and +navigating — then produces a step-by-step report with screenshots. No +selectors, no recording, no code required. + +### What makes AskUI different from other automation tools? + +Traditional tools rely on CSS selectors, XPath, or element IDs that break when +the UI changes. AskUI reads the screen visually, so tests are resilient to +layout changes and work across any interface — including embedded UIs and +legacy apps where the DOM is inaccessible. + +### What platforms and interfaces does AskUI support? + +- **Desktop:** Windows, macOS, Linux +- **Mobile:** Android, iOS (Simulators, experimental) +- **Web:** Any browser +- **Embedded / hardware:** Devices without software access via Companion Mode + +### Is AskUI secure? + +Yes. AskUI is ISO 27001 certified and GDPR compliant. On-premise and +air-gapped deployment options are available for customers who need their data +to stay within their own infrastructure. See the +[Trust Center](https://trust.askui.com) for details. + +--- + +## Getting started + +### How do I get started? + +Follow the [Quickstart](/docs/quickstart) — it takes under 10 minutes and +covers account creation, installation, and running a first test. + +### Do I need to write code? + +No. Tests are written in plain Markdown. There is no API to learn and no +programming language required. + +### Can I try AskUI for free? + +Yes. Sign up at the [AskUI Hub](https://hub.askui.com) to start a free trial +with full feature access. + +--- + +## Technical questions + +### Can I use AskUI in CI/CD pipelines? + +Yes. The AskUI CLI (`askui run`) runs your test projects headless in any CI +environment. See [CI examples](/docs/agentos/deployment/ci-examples) for +GitHub Actions, GitLab CI, and Azure DevOps pipeline configurations. + +### Which AI models does AskUI use? + +By default, AskUI routes through the AskUI Hub's inference service. You can +also bring your own model provider (Claude, Gemini, OpenAI, or a custom +endpoint) — see [Model providers](/docs/using-askui-desktop/model-providers). + +### Does AskUI work with virtual machines? + +Yes. AgentOS works on VMware, VirtualBox, Hyper-V, and cloud VMs (AWS, Azure, +GCP). For headless VM scenarios in CI, use AgentOS as an OS service — +see [CI/CD integration](/docs/agentos/deployment/ci). + +### Does AskUI work behind a corporate firewall or proxy? + +Yes. Set the standard `HTTP_PROXY` / `HTTPS_PROXY` environment variables +before running. For deep-packet-inspection proxies (e.g. Zscaler), see +[Proxy and SSL troubleshooting](/docs/agentos/troubleshooting#proxy-and-ssl). +For the list of domains to allowlist, see +[Network requirements](/docs/reference/network-requirements). + +--- + +## Pricing and licensing + +### How is AskUI priced? + +AskUI offers a free trial, team plans (pay-per-use), and enterprise plans with +custom pricing and SLA. Contact [sales@askui.com](mailto:sales@askui.com) for +enterprise terms. + +### Is there an on-premise option? + +Yes. Enterprise customers can deploy AskUI fully on-premise or in an +air-gapped environment. Contact your account manager or +[sales@askui.com](mailto:sales@askui.com). + +--- + +## Common use cases + +### What can I automate with AskUI? + +End-to-end testing, regression testing, cross-browser and mobile testing, RPA +workflows, legacy system integration, data entry automation, and any scenario +where the interface is the source of truth. + +### Can AskUI automate embedded or proprietary UIs? + +Yes. Because AskUI reads the screen rather than the DOM, it works on any +interface that produces a visible output — including embedded HMI screens, +industrial control panels, and legacy applications with no accessible +automation API. + +--- + +## Getting help + +### Where can I get help? + +- [Troubleshooting guides](/docs/agentos/troubleshooting) +- [support@askui.com](mailto:support@askui.com) +- [Get help](/docs/support/get-help) diff --git a/content/docs/support/get-help.mdx b/content/docs/support/get-help.mdx new file mode 100644 index 0000000..d9bbaf1 --- /dev/null +++ b/content/docs/support/get-help.mdx @@ -0,0 +1,74 @@ +--- +title: Get help +description: How to report bugs and contact the AskUI team. +--- + +## Before reaching out + +Working through these steps first usually resolves the issue faster than +opening a ticket: + + + +**Check the run report.** Open the failing run's report and look at the step +that failed. The screenshot and status (`FAILED` vs `BROKEN`) usually point +directly at the problem. See [Reading a run report](/docs/using-askui-desktop/run-report). + + +**Check the troubleshooting guide.** The most common AgentOS and connectivity +issues are documented in [Troubleshooting](/docs/agentos/troubleshooting). + + + +## Diagnostic report + + +We are building a diagnostic tool that automatically checks your system +configuration — installed versions, network connectivity, AgentOS reachability, +environment variables, and more — and writes a structured report. You will be +able to send this report directly to support so we can tell you exactly what is +wrong, for example why a remote AgentOS cannot be reached. + + +## What to include in a bug report + +A good bug report gets you a faster answer. Include: + +- **AskUI Desktop version** — shown in the app's About screen +- **Operating system and version** — e.g. Windows 11 22H2, macOS 14.4 +- **Steps to reproduce** — the exact sequence of actions that causes the issue +- **Expected behavior** — what should happen +- **Actual behavior** — what actually happens, including any error messages +- **The run report** — the `.md` file or a screenshot of the failing step +- **AgentOS logs** (for AgentOS issues) — see + [Logs](/docs/agentos/troubleshooting#logs) + +## Contact channels + +| Channel | Best for | Response time | +|---------|----------|--------------| +| [support@askui.com](mailto:support@askui.com) | Bug reports, technical issues | 24-48 business hours | +| [feedback@askui.com](mailto:feedback@askui.com) | Feature requests, docs feedback | - | + +Mark your email subject **URGENT** for critical production issues. + +## Enterprise support + +Enterprise customers have access to: +- A dedicated support channel +- Priority response times +- Direct access to the engineering team +- Custom onboarding and training sessions + +Contact your account manager to activate enterprise support. + +## Status and known issues + +- **Service status:** [status.askui.com](https://status.askui.com) +- **Security and compliance:** [trust.askui.com](https://trust.askui.com) +- **GitHub issues:** [github.com/askui](https://github.com/askui) + +## Community resources + +- [YouTube](https://youtube.com/@askui) — tutorials and walkthroughs +- [Blog](https://blog.askui.com) — product updates and deep-dives diff --git a/content/docs/support/index.mdx b/content/docs/support/index.mdx new file mode 100644 index 0000000..dfb09db --- /dev/null +++ b/content/docs/support/index.mdx @@ -0,0 +1,32 @@ +--- +title: Support +description: Get help with AskUI — troubleshooting, FAQs, community, and contacting the team. +--- + + + + Answers to common questions about platform support, pricing, security, and + on-premise options. + + + How to report bugs, what to include, and where to reach the team and + community. + + + Step-by-step fixes for common AgentOS and connectivity issues. + + + +## Status and trust + +| Resource | Link | +|----------|------| +| Service status | [status.askui.com](https://status.askui.com) | +| Security and compliance (Trust Center) | [trust.askui.com](https://trust.askui.com) | + +## Contact + +| Channel | Use for | +|---------|---------| +| [support@askui.com](mailto:support@askui.com) | Bug reports and technical issues | +| [feedback@askui.com](mailto:feedback@askui.com) | Feature requests and documentation feedback | diff --git a/content/docs/support/meta.json b/content/docs/support/meta.json new file mode 100644 index 0000000..5031d55 --- /dev/null +++ b/content/docs/support/meta.json @@ -0,0 +1 @@ +{ "title": "Support", "pages": ["index", "faq", "get-help"] } diff --git a/content/docs/using-askui-desktop/cli.mdx b/content/docs/using-askui-desktop/cli.mdx index bbc28ec..70ced34 100644 --- a/content/docs/using-askui-desktop/cli.mdx +++ b/content/docs/using-askui-desktop/cli.mdx @@ -204,4 +204,4 @@ jobs: Pin `--workspace` to a fixed path so the artifact upload finds the reports, and upload with `if: always()` so failing runs keep their evidence. For setting up the machine under test, see -[AgentOS CI deployment](/docs/agentos/how-to-guides/deployment-ci). +[AgentOS CI deployment](/docs/agentos/deployment/ci). diff --git a/content/docs/using-askui-desktop/model-providers.mdx b/content/docs/using-askui-desktop/model-providers.mdx index 4c6d7ee..ad876ef 100644 --- a/content/docs/using-askui-desktop/model-providers.mdx +++ b/content/docs/using-askui-desktop/model-providers.mdx @@ -41,6 +41,12 @@ any Anthropic‑compatible endpoint (including a self‑hosted server such as vL + +OpenAI-compatible providers are experimental. They may work with capable +vision models, but we do not test against them and cannot offer support for +issues specific to this configuration. + + Run against any **OpenAI Chat Completions–compatible API** — [OpenRouter](https://openrouter.ai), OpenAI, or a self‑hosted server (vLLM, SGLang, llama.cpp, Ollama). From 2b1efc2391196ee461b4eb0034094388286736c7 Mon Sep 17 00:00:00 2001 From: Jonas Menesklou Date: Thu, 9 Jul 2026 15:31:22 +0200 Subject: [PATCH 2/7] docs: drop secrets/ references and rework landing page hero - Remove the secrets/ folder from all scaffold/structure lists (quickstart, first-run, project-structure, glossary) since the app no longer scaffolds it - Reword credentials guidance to a generic local credentials file instead of secrets/credentials.txt - Rework the landing page hero: new breadth-led headline and subhead, larger type, and a subtle brand-tinted glow Co-Authored-By: Claude Opus 4.8 --- app/(home)/page.tsx | 60 +++++++++++-------- content/docs/get-started/first-run.mdx | 2 +- content/docs/quickstart.mdx | 2 +- content/docs/reference/glossary.mdx | 2 +- .../agents-and-prompts.mdx | 2 +- .../using-askui-desktop/project-structure.mdx | 3 +- .../prompting-best-practices.mdx | 5 +- 7 files changed, 42 insertions(+), 34 deletions(-) diff --git a/app/(home)/page.tsx b/app/(home)/page.tsx index 5012691..3421b74 100644 --- a/app/(home)/page.tsx +++ b/app/(home)/page.tsx @@ -94,32 +94,40 @@ export default function HomePage() {
{/* Hero */} -
-

- AskUI Documentation -

-

- UI automation in plain language -

-

- Describe what to do. AskUI's AI agent acts on the real screen and returns a step-by-step - report with screenshots. No selectors, no recording, no code. -

-
- - Quickstart (10 min) - - - Browse docs - +
+
+
+

+ AskUI Documentation +

+

+ One agent for every interface +

+

+ AskUI drives web, desktop, mobile, and embedded screens from plain-language steps + — no selectors, no recording. Every run comes back as a screenshot-backed report. +

+
+ + Quickstart (10 min) + + + Browse docs + +
diff --git a/content/docs/get-started/first-run.mdx b/content/docs/get-started/first-run.mdx index 44ce880..fb49ce4 100644 --- a/content/docs/get-started/first-run.mdx +++ b/content/docs/get-started/first-run.mdx @@ -10,7 +10,7 @@ Let's run a test end to end. This assumes you've **Create a Project.** AskUI Desktop scaffolds the standard folders for you — -`tests/`, `prompts/`, `procedures/`, `plans/`, `secrets/` — pre-seeded with +`tests/`, `prompts/`, `procedures/`, `plans/` — pre-seeded with an example login test and the four prompt parts. diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx index f02e651..a49493e 100644 --- a/content/docs/quickstart.mdx +++ b/content/docs/quickstart.mdx @@ -68,7 +68,7 @@ tokens, and usage. Leave it open — you will come back to it in a moment. **Create a new Project.** AskUI Desktop scaffolds the standard folder structure -for you — `tests/`, `prompts/`, `procedures/`, `plans/`, `secrets/` — and +for you — `tests/`, `prompts/`, `procedures/`, `plans/` — and pre-seeds it with an example test. diff --git a/content/docs/reference/glossary.mdx b/content/docs/reference/glossary.mdx index aea0307..98b7e4b 100644 --- a/content/docs/reference/glossary.mdx +++ b/content/docs/reference/glossary.mdx @@ -14,7 +14,7 @@ description: Definitions for key terms used across AskUI documentation. | **Element** | A graphical user interface component: a button, text field, menu item, image, etc. | | **Host Mode** | An AgentOS control mode where AgentOS runs directly on the target machine and controls it via OS-level APIs. | | **Inference** | The process of sending a screenshot to the AI model to identify and locate UI elements. | -| **Project** | A folder structure created by AskUI Desktop containing tests, prompts, procedures, plans, and secrets. The unit of work for authoring and running tests. | +| **Project** | A folder structure created by AskUI Desktop containing tests, prompts, procedures, and plans. The unit of work for authoring and running tests. | | **Procedure** | A reusable multi-step sequence (e.g. "log in") stored in `procedures/` and invoked from test steps by name. | | **Run report** | The output of a test run: a Markdown file with a status and screenshot per step. Statuses are `PASSED`, `FAILED`, `WARN`, `SKIPPED`, or `BROKEN`. | | **Workspace** | The account-level container in the AskUI Hub that owns access tokens, usage events, and billing. Every AskUI account belongs to one or more workspaces. | diff --git a/content/docs/using-askui-desktop/agents-and-prompts.mdx b/content/docs/using-askui-desktop/agents-and-prompts.mdx index 1116b67..0b9e966 100644 --- a/content/docs/using-askui-desktop/agents-and-prompts.mdx +++ b/content/docs/using-askui-desktop/agents-and-prompts.mdx @@ -49,7 +49,7 @@ screenshots and input, and — critically — that **does not improvise**: It also sets two conventions the agent relies on: - **Credentials** are never embedded in a test. When a step references "the QA - credentials", the agent reads them from `secrets/credentials.txt` at run time. + credentials", the agent reads them from a local credentials file at run time. - **Scratchpad** — the agent can persist information across steps with `scratchpad_write_tool` / `scratchpad_read_tool`, but only when explicitly prompted to. diff --git a/content/docs/using-askui-desktop/project-structure.mdx b/content/docs/using-askui-desktop/project-structure.mdx index d68f1e4..4ca8b64 100644 --- a/content/docs/using-askui-desktop/project-structure.mdx +++ b/content/docs/using-askui-desktop/project-structure.mdx @@ -16,7 +16,6 @@ testing lives in one Project folder, split into a few well-known areas. - @@ -33,7 +32,7 @@ testing lives in one Project folder, split into a few well-known areas. Start from the scaffold: a new Project comes pre-seeded with the four prompt -parts, an example login test, a `smoke` plan, and a `secrets/` README. Fill in +parts, an example login test, and a `smoke` plan. Fill in the placeholders rather than starting from a blank page. diff --git a/content/docs/using-askui-desktop/prompting-best-practices.mdx b/content/docs/using-askui-desktop/prompting-best-practices.mdx index 7023322..285bdeb 100644 --- a/content/docs/using-askui-desktop/prompting-best-practices.mdx +++ b/content/docs/using-askui-desktop/prompting-best-practices.mdx @@ -90,7 +90,7 @@ them by name and let the agent read them at run time: Sign in using the QA credentials. ``` -The agent resolves "the QA credentials" by reading `secrets/credentials.txt` +The agent resolves "the QA credentials" by reading a local credentials file with its file tools at execution time. Real credentials never appear in `tests/*.md` or the prompts. @@ -133,6 +133,7 @@ Before you commit a Project's prompts, confirm: - [ ] `prompts/` has all four parts, each scoped to its one job. - [ ] App-specific knowledge lives in `ui_information.md`, not the system prompt. - [ ] Folder behaviour is tuned in `rules.md` / `setup.md` / `teardown.md`. -- [ ] No credentials in any `tests/` or `prompts/` file — only in `secrets/`. +- [ ] No credentials in any `tests/` or `prompts/` file — keep them in a local + file the agent reads at run time. - [ ] `report_format.md` uses the standard status vocabulary. - [ ] Repeated sequences are extracted into `procedures/`. From 7afa9ccb627e2ffa837955e966b0559d2f027f07 Mon Sep 17 00:00:00 2001 From: philipph-askui Date: Thu, 9 Jul 2026 16:33:25 +0200 Subject: [PATCH 3/7] docs: restructure FAQ into subpages, move troubleshooting to Support - Split monolithic FAQ into subpages under faq/ (General, Getting started, Technical, Runs & reports, Pricing & licensing, Use cases) - Move troubleshooting-oriented FAQ content into troubleshooting.mdx: new sections for Connection & session issues, Agent behavior, and Performance & cost - Move troubleshooting.mdx from agentos/ to support/; update all inbound links across service.mdx, get-help.mdx, environment-variables, network-requirements, and support/index - Absorb IT firewall and admin-rights questions into FAQ Technical page - FAQ index now points to Troubleshooting for error/symptom queries Co-Authored-By: Claude Sonnet 4.6 --- content/docs/agentos/installation/service.mdx | 4 +- content/docs/agentos/meta.json | 2 +- content/docs/agentos/troubleshooting.mdx | 173 ---------- content/docs/faq/general.mdx | 32 ++ content/docs/faq/getting-started.mdx | 19 ++ content/docs/faq/index.mdx | 32 ++ content/docs/faq/meta.json | 1 + content/docs/faq/pricing-licensing.mdx | 38 +++ content/docs/faq/runs-reports-cost.mdx | 33 ++ content/docs/faq/technical.mdx | 59 ++++ content/docs/faq/use-cases.mdx | 17 + content/docs/meta.json | 2 +- .../docs/reference/environment-variables.mdx | 2 +- .../docs/reference/network-requirements.mdx | 2 +- content/docs/support/faq.mdx | 126 -------- content/docs/support/get-help.mdx | 4 +- content/docs/support/index.mdx | 4 +- content/docs/support/meta.json | 2 +- content/docs/support/troubleshooting.mdx | 303 ++++++++++++++++++ 19 files changed, 545 insertions(+), 310 deletions(-) delete mode 100644 content/docs/agentos/troubleshooting.mdx create mode 100644 content/docs/faq/general.mdx create mode 100644 content/docs/faq/getting-started.mdx create mode 100644 content/docs/faq/index.mdx create mode 100644 content/docs/faq/meta.json create mode 100644 content/docs/faq/pricing-licensing.mdx create mode 100644 content/docs/faq/runs-reports-cost.mdx create mode 100644 content/docs/faq/technical.mdx create mode 100644 content/docs/faq/use-cases.mdx delete mode 100644 content/docs/support/faq.mdx create mode 100644 content/docs/support/troubleshooting.mdx diff --git a/content/docs/agentos/installation/service.mdx b/content/docs/agentos/installation/service.mdx index 6deb559..8cd3452 100644 --- a/content/docs/agentos/installation/service.mdx +++ b/content/docs/agentos/installation/service.mdx @@ -13,7 +13,7 @@ AgentOS is proprietary software, **free for non-commercial use**. For commercial - **Administrator rights** -To automate the login/lock screen (Secure Attention Sequence), a Group Policy setting must be enabled. See [Troubleshooting](/docs/agentos/troubleshooting#agent-cant-press-ctrlaltdel) for details. +To automate the login/lock screen (Secure Attention Sequence), a Group Policy setting must be enabled. See [Troubleshooting](/docs/support/troubleshooting#agent-cant-press-ctrlaltdel) for details. ## Installation @@ -40,7 +40,7 @@ The installer includes a **Service Configuration** screen: - **Connection Scope:** Use **Public (0.0.0.0)** if AgentOS needs to be reachable from another machine (e.g. a remote CI runner). Keep **Private (127.0.0.1)** for local use only. - **Log Level:** `Info` for production, `Debug` for troubleshooting. -- **Allow CTRL+ALT+DEL:** Enable to automate the Windows lock/login screen (requires Group Policy — see [Troubleshooting](/docs/agentos/troubleshooting#agent-cant-press-ctrlaltdel)). +- **Allow CTRL+ALT+DEL:** Enable to automate the Windows lock/login screen (requires Group Policy — see [Troubleshooting](/docs/support/troubleshooting#agent-cant-press-ctrlaltdel)). - **Allow control of administrative applications:** Enable only if you need to automate apps running as administrator. Click **Next**, then **Install**. diff --git a/content/docs/agentos/meta.json b/content/docs/agentos/meta.json index e978ab8..cc64568 100644 --- a/content/docs/agentos/meta.json +++ b/content/docs/agentos/meta.json @@ -1 +1 @@ -{ "title": "AgentOS", "pages": ["index", "understanding", "installation", "deployment", "troubleshooting", "reference", "release-notes"] } +{ "title": "AgentOS", "pages": ["index", "understanding", "installation", "deployment", "reference", "release-notes"] } diff --git a/content/docs/agentos/troubleshooting.mdx b/content/docs/agentos/troubleshooting.mdx deleted file mode 100644 index 731bbad..0000000 --- a/content/docs/agentos/troubleshooting.mdx +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Troubleshooting -description: "Diagnose and fix common AgentOS issues." ---- - -The troubleshooting steps below apply to AgentOS running as a **Windows service**. For standalone mode on macOS or Linux, check the terminal output for errors. - -## Logs - -The AskUI Core Service and the Remote Device Controller write to two separate locations. For troubleshooting, collect logs from **both**: - -**Remote Device Controller** (runs in the interactive user session): - -``` -%userprofile%\.askui\Logs -``` - -**AskUI Core Service** (runs as SYSTEM): - -``` -C:\Windows\System32\config\systemprofile\.askui\logs -``` - -## Common Issues - -### Restart the AgentOS service - -Many issues are resolved by restarting the service. To restart it via Task Manager: - -1. Open **Task Manager** (`Ctrl+Shift+Esc`). -2. Switch to the **Services** tab (the puzzle-piece icon). -3. Search for **`AskuiCoreService`**. -4. Right-click the entry and choose **Restart**. - -### Agent can't press CTRL+ALT+DEL - -The login/lock screen cannot be automated unless the local security policy allows services to simulate a Secure Attention Sequence (SAS). To enable it: - -1. Open the **Group Policy Editor** (`gpedit.msc`). -2. Navigate to **Computer Configuration → Administrative Templates → Windows Components → Windows Logon Options**. -3. Set **Disable or enable software Secure Attention Sequence** to **Enabled**. - -Also verify that `SERVICE_ENABLE_SAS` is set to `1` (default) in the [Silent installer parameters](/docs/agentos/installation/silent/#parameters). - - -The service includes a `windows.forceSas` option that overrides group policies. This is **not recommended** as it may trigger system integrity checks. Configure the GPE policy instead. - - -### AgentOS returns empty images or shuts down when the RDP Client window is minimized - -Minimizing the RDP Client window simulates a display disconnect on the remote machine. The Remote Device Controller loses access to the display — depending on the state, it either returns empty screenshots or shuts itself down entirely, ending any running automation. - -Mitigate with one of the following: - -- Start the job while RDP is connected and the window is maximized. -- Disconnect the RDP session (rather than minimizing it) before starting the job. -- On the **RDP client machine** (the one running `mstsc`), set a registry value to keep the session active when minimized: - - Open `regedit`, navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client`, and create a `DWORD` value named `RemoteDesktop_SuppressWhenMinimized` with data `2`. - -### Agent can't interact with apps running as Administrator - -Windows prevents non-elevated processes from sending input to elevated (Run as Administrator) applications. If your agent can't click or type into an app running as Administrator, you need to start the Remote Device Controller in elevated mode. - -To enable elevated mode: - -- **Service Installer (GUI)**: Open **Windows Add/Remove Programs**, find AskUI AgentOS, click **Modify**, and enable the elevated execution engine option. Alternatively, reinstall AgentOS with the option enabled. -- **Silent Installer**: Set `SERVICE_EXECUTION_ENGINE_ELEVATED` to `1` — see [Silent installer parameters](/docs/agentos/installation/silent/#parameters). - - -Running the execution engine elevated grants it higher privileges. Only enable this when you need to automate applications that run as Administrator. - - -### `ipv4:127.0.0.1:23000 unavailable` in Standalone mode - -If the client fails to connect with an error like `ipv4:127.0.0.1:23000 unavailable` while running in **Standalone** runtime mode, autostart of the local AgentOS instance is likely disabled. - -Check the `ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART` environment variable — if it is set to `false`, the client will not start AgentOS automatically and there is nothing listening on port `23000`. Either unset the variable or set it to `true`: - - - - ```powershell - $env:ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART="true" - ``` - - - ```bash - export ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART=true - ``` - - - -This variable is intentionally set to `false` when connecting to a remote AgentOS instance — see [Remote Windows VM](/docs/agentos/deployment/ci/#remote-windows-vm). - -### Need to reinstall or remove - - -**Do not** stop or remove the service from Windows Services manually. Always **uninstall the full AskUI AgentOS application** via Windows Add/Remove Programs. This ensures proper cleanup so the client falls back to standalone mode. - - -## Proxy and SSL - -### Configure a proxy - -AskUI Desktop and the CLI respect the standard proxy environment variables. -Set them before launching: - - - - ```powershell - $env:HTTP_PROXY="http://proxy.example.com:8080" - $env:HTTPS_PROXY="http://proxy.example.com:8080" - $env:NO_PROXY="localhost,127.0.0.1" - ``` - - - ```bash - export HTTP_PROXY="http://proxy.example.com:8080" - export HTTPS_PROXY="http://proxy.example.com:8080" - export NO_PROXY="localhost,127.0.0.1" - ``` - - - -### Deep-packet-inspection proxies (Zscaler and similar) - -Some corporate proxies intercept HTTPS traffic and inject a custom root -certificate. This can cause SSL errors like: - -``` -SSL: CERTIFICATE_VERIFY_FAILED -``` - -**Solution:** Disable SSL verification as a temporary workaround while you -get the proxy certificate added to your system trust store: - - - - ```powershell - $env:ASKUI_HTTP_SSL_VERIFICATION="false" - ``` - - - ```bash - export ASKUI_HTTP_SSL_VERIFICATION=false - ``` - - - - -Disabling SSL verification reduces security. Re-enable it once your proxy -certificate is trusted by the OS certificate store. - - -The permanent fix is to add your proxy's root certificate to the system -certificate store. Contact your IT/network team for the certificate file and -import instructions for your OS. - -## Debugging run failures - -The fastest way to debug a failing run: - -1. Open the run report (`.md` file in your project's `reports/` folder or - inline in AskUI Desktop). -2. Find the first step with status `FAILED` or `BROKEN` — that is where to - focus. -3. Check the screenshot for that step. `FAILED` means the expected outcome - didn't match; `BROKEN` means an infrastructure problem (connection lost, - session expired) stopped the run. -4. For AgentOS issues, check the [logs](#logs) for more detail. - -If you cannot resolve the issue yourself, see [Get help](/docs/support/get-help) -for how to generate a diagnostic report and contact support. diff --git a/content/docs/faq/general.mdx b/content/docs/faq/general.mdx new file mode 100644 index 0000000..58193de --- /dev/null +++ b/content/docs/faq/general.mdx @@ -0,0 +1,32 @@ +--- +title: General +description: What AskUI is, how it works, platform support, and security. +--- + +### What is AskUI? + +AskUI is an AI-driven UI automation platform. You describe what to do in plain +language, and an AI agent acts on the real screen — clicking, typing, and +navigating — then produces a step-by-step report with screenshots. No +selectors, no recording, no code required. + +### What makes AskUI different from other automation tools? + +Traditional tools rely on CSS selectors, XPath, or element IDs that break when +the UI changes. AskUI reads the screen visually, so tests are resilient to +layout changes and work across any interface — including embedded UIs and +legacy apps where the DOM is inaccessible. + +### What platforms and interfaces does AskUI support? + +- **Desktop:** Windows, macOS, Linux +- **Mobile:** Android, iOS (Simulators, experimental) +- **Web:** Any browser +- **Embedded / hardware:** Devices without software access via Companion Mode + +### Is AskUI secure? + +Yes. AskUI is ISO 27001 certified and GDPR compliant. On-premise and +air-gapped deployment options are available for customers who need their data +to stay within their own infrastructure. See the +[Trust Center](https://trust.askui.com) for details. diff --git a/content/docs/faq/getting-started.mdx b/content/docs/faq/getting-started.mdx new file mode 100644 index 0000000..c42b981 --- /dev/null +++ b/content/docs/faq/getting-started.mdx @@ -0,0 +1,19 @@ +--- +title: Getting started +description: First steps, free trial, and whether you need to write code. +--- + +### How do I get started? + +Follow the [Quickstart](/docs/quickstart) — it takes under 10 minutes and +covers account creation, installation, and running a first test. + +### Do I need to write code? + +No. Tests are written in plain Markdown. There is no API to learn and no +programming language required. + +### Can I try AskUI for free? + +Yes. Sign up at the [AskUI Hub](https://hub.askui.com) to start a free trial +with full feature access. diff --git a/content/docs/faq/index.mdx b/content/docs/faq/index.mdx new file mode 100644 index 0000000..aa270d7 --- /dev/null +++ b/content/docs/faq/index.mdx @@ -0,0 +1,32 @@ +--- +title: Overview +description: Frequently asked questions about AskUI — capabilities, runs, billing, and more. +--- + + + + What AskUI is, how it works, platform support, and security. + + + First steps, free trial, and whether you need to write code. + + + CI/CD, model providers, virtual machines, proxy, and installation + requirements. + + + Run status meanings and when to clear the cache. + + + Plans, on-premise options, billing errors, and reading credit consumption. + + + What you can automate, including embedded and proprietary UIs. + + + +--- + +Experiencing a specific error or unexpected behavior? See +[Troubleshooting](/docs/support/troubleshooting) for step-by-step fixes, or +[Get help](/docs/support/get-help) to contact the team. diff --git a/content/docs/faq/meta.json b/content/docs/faq/meta.json new file mode 100644 index 0000000..cf7b788 --- /dev/null +++ b/content/docs/faq/meta.json @@ -0,0 +1 @@ +{ "title": "FAQ", "pages": ["index", "general", "getting-started", "technical", "runs-reports-cost", "pricing-licensing", "use-cases"] } diff --git a/content/docs/faq/pricing-licensing.mdx b/content/docs/faq/pricing-licensing.mdx new file mode 100644 index 0000000..8756260 --- /dev/null +++ b/content/docs/faq/pricing-licensing.mdx @@ -0,0 +1,38 @@ +--- +title: Pricing & licensing +description: Plans, on-premise options, billing errors, and reading credit consumption. +--- + +### How is AskUI priced? + +AskUI offers a free trial, team plans (pay-per-use), and enterprise plans with +custom pricing and SLA. Contact [sales@askui.com](mailto:sales@askui.com) for +enterprise terms. + +### Is there an on-premise option? + +Yes. Enterprise customers can deploy AskUI fully on-premise or in an +air-gapped environment. Contact your account manager or +[sales@askui.com](mailto:sales@askui.com). + +### I get a billing or credit error during a run. + +This is an account issue, not a broken installation. It means AskUI could not +authorize the run against your workspace — usually because credits are +exhausted or the subscription has lapsed. + +Steps to resolve: +1. Open **AskUI Hub → Workspace → Billing** and check your subscription status + and remaining credits. +2. If credits are exhausted, top up or upgrade your plan. +3. If the error persists on an active paid plan, contact + [support@askui.com](mailto:support@askui.com) with your workspace ID and + the error message from the run report. + +### How do I see how many credits a run consumed? + +- **Per run:** open the run report — the header shows total tokens and cost + for that run. +- **Across all runs:** go to **AskUI Hub → Workspace → Usage**. See the + [Usage dashboard](/docs/account-billing/usage-dashboard) for a breakdown + by run, test case, and access token. diff --git a/content/docs/faq/runs-reports-cost.mdx b/content/docs/faq/runs-reports-cost.mdx new file mode 100644 index 0000000..2e46a64 --- /dev/null +++ b/content/docs/faq/runs-reports-cost.mdx @@ -0,0 +1,33 @@ +--- +title: Runs & reports +description: Understanding run statuses and caching behavior. +--- + +### What is the difference between a failed and a broken status? + +- **`FAILED`** — the agent completed the step but the outcome did not match + expectations. This typically points to a bug in the application under test: + a button did not appear, a value was wrong, a transition did not happen. + Investigate the app. +- **`BROKEN`** — the run could not complete a step due to an infrastructure or + environment issue: AgentOS unreachable, step limit reached, model error, or + network timeout. Investigate the environment, not the app. Check the + [Troubleshooting guide](/docs/support/troubleshooting) first. +- **`WARN`** — the step completed but something unexpected was noted. The run + continues. + +See [Reading a run report](/docs/using-askui-desktop/run-report) for the full +status reference. + +### Should I use caching, and when should I clear it? + +Caching stores context between steps so the agent can re-use it without +recapturing the full screen. It makes long runs faster and cheaper. + +**Clear the cache when:** +- You deploy an update to the application under test. +- The UI layout or visual design changes. +- A run produces passes on actions that should have failed (a sign of stale + cache returning an outdated screen state). + +Rule of thumb: **clear before any run that follows a deployment.** diff --git a/content/docs/faq/technical.mdx b/content/docs/faq/technical.mdx new file mode 100644 index 0000000..50e5201 --- /dev/null +++ b/content/docs/faq/technical.mdx @@ -0,0 +1,59 @@ +--- +title: Technical +description: CI/CD, model providers, virtual machines, proxy, and installation requirements. +--- + +### Can I use AskUI in CI/CD pipelines? + +Yes. The AskUI CLI (`askui run`) runs your test projects headless in any CI +environment. See [CI examples](/docs/agentos/deployment/ci-examples) for +GitHub Actions, GitLab CI, and Azure DevOps pipeline configurations. + +### Which AI models does AskUI use? + +By default, AskUI routes through the AskUI Hub's inference service. You can +also bring your own model provider (Claude, Gemini, OpenAI, or a custom +endpoint) — see [Model providers](/docs/using-askui-desktop/model-providers). + +### Does AskUI work with virtual machines? + +Yes. AgentOS works on VMware, VirtualBox, Hyper-V, and cloud VMs (AWS, Azure, +GCP). For headless VM scenarios in CI, use AgentOS as an OS service — +see [CI/CD integration](/docs/agentos/deployment/ci). + +### Does AskUI work behind a corporate firewall or proxy? + +Yes. Set the standard `HTTP_PROXY` / `HTTPS_PROXY` environment variables +before running. For deep-packet-inspection proxies (e.g. Zscaler), see +[Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). +For the list of domains to allowlist, see +[Network requirements](/docs/reference/network-requirements). + +### What does our IT team need to allow for AskUI to work? + +All AskUI traffic uses standard HTTPS (port 443). The full list of domains and +ports to allowlist is in [Network requirements](/docs/reference/network-requirements) +— that page is written so it can be shared directly with an IT department. + +Key notes for IT: +- Both IPv4 and IPv6 are supported; no non-standard ports are required. +- If the network uses deep-packet inspection (e.g. Zscaler), the AskUI + certificate chain must be trusted — see + [Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). +- Contact [support@askui.com](mailto:support@askui.com) to request a + one-pager formatted for IT firewall review. + +### I don't have admin rights on the target machine. Can I still install and run AskUI? + +AskUI Desktop installs per-user on Windows and macOS and does not require +administrator rights for the standard installation. + +Limitations without admin rights: +- **AgentOS in Host Mode** requires OS-level permission to simulate keyboard + and mouse input. On locked-down machines, IT may need to whitelist the + AgentOS process or grant input-simulation permissions. +- **Running AgentOS as a system service** (for unattended or CI use) does + require elevated privileges. + +If your machines are managed centrally, contact your IT team to request the +necessary input-simulation permissions for the AgentOS executable. diff --git a/content/docs/faq/use-cases.mdx b/content/docs/faq/use-cases.mdx new file mode 100644 index 0000000..10da118 --- /dev/null +++ b/content/docs/faq/use-cases.mdx @@ -0,0 +1,17 @@ +--- +title: Common use cases +description: What you can automate with AskUI, including embedded and proprietary UIs. +--- + +### What can I automate with AskUI? + +End-to-end testing, regression testing, cross-browser and mobile testing, RPA +workflows, legacy system integration, data entry automation, and any scenario +where the interface is the source of truth. + +### Can AskUI automate embedded or proprietary UIs? + +Yes. Because AskUI reads the screen rather than the DOM, it works on any +interface that produces a visible output — including embedded HMI screens, +industrial control panels, and legacy applications with no accessible +automation API. diff --git a/content/docs/meta.json b/content/docs/meta.json index 17b97d2..4244df7 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1 +1 @@ -{ "pages": ["index", "quickstart", "get-started", "using-askui-desktop", "agentos", "guides", "account-billing", "reference", "support", "legacy"] } +{ "pages": ["index", "quickstart", "get-started", "using-askui-desktop", "agentos", "guides", "account-billing", "reference", "faq", "support", "legacy"] } diff --git a/content/docs/reference/environment-variables.mdx b/content/docs/reference/environment-variables.mdx index 5ea8719..cef23af 100644 --- a/content/docs/reference/environment-variables.mdx +++ b/content/docs/reference/environment-variables.mdx @@ -29,4 +29,4 @@ description: All environment variables recognised by AskUI Desktop, the CLI, and | Variable | Default | Description | |----------|---------|-------------| -| `ASKUI_HTTP_SSL_VERIFICATION` | `true` | Set to `false` to disable SSL certificate verification. Use only as a last resort in environments with deep-packet-inspection proxies. See [Proxy and SSL troubleshooting](/docs/agentos/troubleshooting#proxy-and-ssl). | +| `ASKUI_HTTP_SSL_VERIFICATION` | `true` | Set to `false` to disable SSL certificate verification. Use only as a last resort in environments with deep-packet-inspection proxies. See [Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). | diff --git a/content/docs/reference/network-requirements.mdx b/content/docs/reference/network-requirements.mdx index 41aa6d2..557c443 100644 --- a/content/docs/reference/network-requirements.mdx +++ b/content/docs/reference/network-requirements.mdx @@ -42,7 +42,7 @@ $env:NO_PROXY="localhost,127.0.0.1" For deep-packet-inspection proxies (e.g. Zscaler) that inject custom SSL certificates, see -[Proxy and SSL troubleshooting](/docs/agentos/troubleshooting#proxy-and-ssl). +[Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). ## Air-gapped and on-premise deployments diff --git a/content/docs/support/faq.mdx b/content/docs/support/faq.mdx deleted file mode 100644 index 83a3d47..0000000 --- a/content/docs/support/faq.mdx +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: FAQ -description: Frequently asked questions about AskUI. ---- - -## General - -### What is AskUI? - -AskUI is an AI-driven UI automation platform. You describe what to do in plain -language, and an AI agent acts on the real screen — clicking, typing, and -navigating — then produces a step-by-step report with screenshots. No -selectors, no recording, no code required. - -### What makes AskUI different from other automation tools? - -Traditional tools rely on CSS selectors, XPath, or element IDs that break when -the UI changes. AskUI reads the screen visually, so tests are resilient to -layout changes and work across any interface — including embedded UIs and -legacy apps where the DOM is inaccessible. - -### What platforms and interfaces does AskUI support? - -- **Desktop:** Windows, macOS, Linux -- **Mobile:** Android, iOS (Simulators, experimental) -- **Web:** Any browser -- **Embedded / hardware:** Devices without software access via Companion Mode - -### Is AskUI secure? - -Yes. AskUI is ISO 27001 certified and GDPR compliant. On-premise and -air-gapped deployment options are available for customers who need their data -to stay within their own infrastructure. See the -[Trust Center](https://trust.askui.com) for details. - ---- - -## Getting started - -### How do I get started? - -Follow the [Quickstart](/docs/quickstart) — it takes under 10 minutes and -covers account creation, installation, and running a first test. - -### Do I need to write code? - -No. Tests are written in plain Markdown. There is no API to learn and no -programming language required. - -### Can I try AskUI for free? - -Yes. Sign up at the [AskUI Hub](https://hub.askui.com) to start a free trial -with full feature access. - ---- - -## Technical questions - -### Can I use AskUI in CI/CD pipelines? - -Yes. The AskUI CLI (`askui run`) runs your test projects headless in any CI -environment. See [CI examples](/docs/agentos/deployment/ci-examples) for -GitHub Actions, GitLab CI, and Azure DevOps pipeline configurations. - -### Which AI models does AskUI use? - -By default, AskUI routes through the AskUI Hub's inference service. You can -also bring your own model provider (Claude, Gemini, OpenAI, or a custom -endpoint) — see [Model providers](/docs/using-askui-desktop/model-providers). - -### Does AskUI work with virtual machines? - -Yes. AgentOS works on VMware, VirtualBox, Hyper-V, and cloud VMs (AWS, Azure, -GCP). For headless VM scenarios in CI, use AgentOS as an OS service — -see [CI/CD integration](/docs/agentos/deployment/ci). - -### Does AskUI work behind a corporate firewall or proxy? - -Yes. Set the standard `HTTP_PROXY` / `HTTPS_PROXY` environment variables -before running. For deep-packet-inspection proxies (e.g. Zscaler), see -[Proxy and SSL troubleshooting](/docs/agentos/troubleshooting#proxy-and-ssl). -For the list of domains to allowlist, see -[Network requirements](/docs/reference/network-requirements). - ---- - -## Pricing and licensing - -### How is AskUI priced? - -AskUI offers a free trial, team plans (pay-per-use), and enterprise plans with -custom pricing and SLA. Contact [sales@askui.com](mailto:sales@askui.com) for -enterprise terms. - -### Is there an on-premise option? - -Yes. Enterprise customers can deploy AskUI fully on-premise or in an -air-gapped environment. Contact your account manager or -[sales@askui.com](mailto:sales@askui.com). - ---- - -## Common use cases - -### What can I automate with AskUI? - -End-to-end testing, regression testing, cross-browser and mobile testing, RPA -workflows, legacy system integration, data entry automation, and any scenario -where the interface is the source of truth. - -### Can AskUI automate embedded or proprietary UIs? - -Yes. Because AskUI reads the screen rather than the DOM, it works on any -interface that produces a visible output — including embedded HMI screens, -industrial control panels, and legacy applications with no accessible -automation API. - ---- - -## Getting help - -### Where can I get help? - -- [Troubleshooting guides](/docs/agentos/troubleshooting) -- [support@askui.com](mailto:support@askui.com) -- [Get help](/docs/support/get-help) diff --git a/content/docs/support/get-help.mdx b/content/docs/support/get-help.mdx index d9bbaf1..f3f743c 100644 --- a/content/docs/support/get-help.mdx +++ b/content/docs/support/get-help.mdx @@ -16,7 +16,7 @@ directly at the problem. See [Reading a run report](/docs/using-askui-desktop/ru **Check the troubleshooting guide.** The most common AgentOS and connectivity -issues are documented in [Troubleshooting](/docs/agentos/troubleshooting). +issues are documented in [Troubleshooting](/docs/support/troubleshooting). @@ -41,7 +41,7 @@ A good bug report gets you a faster answer. Include: - **Actual behavior** — what actually happens, including any error messages - **The run report** — the `.md` file or a screenshot of the failing step - **AgentOS logs** (for AgentOS issues) — see - [Logs](/docs/agentos/troubleshooting#logs) + [Logs](/docs/support/troubleshooting#logs) ## Contact channels diff --git a/content/docs/support/index.mdx b/content/docs/support/index.mdx index dfb09db..3d33ab6 100644 --- a/content/docs/support/index.mdx +++ b/content/docs/support/index.mdx @@ -4,7 +4,7 @@ description: Get help with AskUI — troubleshooting, FAQs, community, and conta --- - + Answers to common questions about platform support, pricing, security, and on-premise options. @@ -12,7 +12,7 @@ description: Get help with AskUI — troubleshooting, FAQs, community, and conta How to report bugs, what to include, and where to reach the team and community. - + Step-by-step fixes for common AgentOS and connectivity issues. diff --git a/content/docs/support/meta.json b/content/docs/support/meta.json index 5031d55..509495b 100644 --- a/content/docs/support/meta.json +++ b/content/docs/support/meta.json @@ -1 +1 @@ -{ "title": "Support", "pages": ["index", "faq", "get-help"] } +{ "title": "Support", "pages": ["index", "troubleshooting", "get-help"] } diff --git a/content/docs/support/troubleshooting.mdx b/content/docs/support/troubleshooting.mdx new file mode 100644 index 0000000..ee352b8 --- /dev/null +++ b/content/docs/support/troubleshooting.mdx @@ -0,0 +1,303 @@ +--- +title: Troubleshooting +description: Diagnose and fix common issues with AskUI Desktop, AgentOS, and runs. +--- + +## Logs + +The AskUI Core Service and the Remote Device Controller write to two separate locations. For troubleshooting, collect logs from **both**: + +**Remote Device Controller** (runs in the interactive user session): + +``` +%userprofile%\.askui\Logs +``` + +**AskUI Core Service** (runs as SYSTEM): + +``` +C:\Windows\System32\config\systemprofile\.askui\logs +``` + +--- + +## Connection & session issues + +### Connection error or session mismatch at run start + +Connection errors and session mismatches happen when AgentOS and Desktop have +lost sync — most often after a machine restart or sleep cycle. + +**Correct restart order for multi-machine setups:** +1. Restart AgentOS on the target machine(s) first. +2. Then reconnect from AskUI Desktop. + +If the error persists, use the **Restart** button on the Devices page in the +Desktop sidebar to force a clean session reset. If the problem recurs after +restarts, check whether the target machine received a new IP address from DHCP +— see the entry below. + +### Tests won't start after a reboot or power outage + +Work through this checklist: + +1. **Verify all services are running.** Open the Devices page in AskUI Desktop + and confirm every connected machine shows a green status. +2. **Check for IP address changes.** DHCP can reassign addresses after a + restart, breaking a stored connection. Use hostnames instead of static + IPs wherever possible. +3. **Look for stale configuration.** Old connection settings in your project + or workspace config may point to a previous address. Update or remove them + and re-add the device. + +### Run stops when RDP session is disconnected or screen is locked + +- **Remote Desktop (Windows) — session disconnect:** Disconnecting an RDP + session suspends the virtual display. AgentOS in Host Mode loses its view of + the screen and the run ends. Either keep the RDP session connected and the + window visible during the run, or run AgentOS as a **system service** so it + operates independently of the interactive session — see + [Running as a service](/docs/agentos/installation/service). +- **Remote Desktop (Windows) — window minimized:** Minimizing the RDP client + window (`mstsc`) simulates a display disconnect on the remote machine. The + Remote Device Controller loses access to the display and may return empty + screenshots or shut down. To prevent this, set a registry value on the + machine running the RDP client: + + Open `regedit`, navigate to + `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client`, and create a + `DWORD` value named `RemoteDesktop_SuppressWhenMinimized` with data `2`. + +- **Locked screen:** A locked session hides the display on both Windows and + macOS. Either keep the machine unlocked during unattended runs, or use a + virtual display tool that persists across lock events. + +For fully unattended CI scenarios, the recommended setup is AgentOS as an OS +service — see [CI/CD integration](/docs/agentos/deployment/ci). + +--- + +## Agent behavior + +### Agent clicks the wrong element or misses small buttons + +Vague element descriptions are the most common cause. Make descriptions +specific: + +- **Use spatial anchors:** "the button in the bottom-right corner, below the + Save dialog" is far more reliable than "the button". +- **Include distinguishing features:** label text, color, icon shape, or + position relative to a unique landmark on the screen. +- **For very small targets:** explicitly instruct the agent to zoom before + acting — for example, "zoom in on the toolbar area, then click the small + red X icon". + +See [Prompting best practices](/docs/using-askui-desktop/prompting-best-practices) +for a full guide on writing reliable element descriptions. + +### Agent misinterprets a screen state + +The agent has no built-in knowledge of your application's UI. Add that +knowledge to `ui_information.md` in your project's `prompts/` folder. +Describe screens the agent commonly confuses — loading overlays, login walls, +modal dialogs, error banners. Example: + +``` +A grey semi-transparent overlay with a spinner in the centre means the page +is loading. Wait for it to disappear completely before taking any action. +``` + +See [Agents and prompts](/docs/using-askui-desktop/agents-and-prompts) for the +full prompt structure. + +### Agent stops in the middle of a long test + +Each run has a step limit that prevents runaway executions. If a test hits +that limit, it ends with status `BROKEN`. + +To avoid this: +- **Extract procedures:** move repeated sequences (e.g. "log in") into + `procedures/` and call them by name from your tests. +- **Split large tests:** break a long end-to-end flow into smaller focused + test cases, each with its own clear goal. + +See [Project structure](/docs/using-askui-desktop/project-structure) for how +procedures and test files are organised. + +--- + +## Performance & cost + +### Run cost increased unexpectedly + +Common drivers: + +| Driver | What to check | +|--------|--------------| +| Stale screenshot cache | Cache holds old, large screenshots re-sent each step. Clear the cache after any UI change. | +| Oversized images or logs | Very large screen captures or log files raise the token count per step. | +| Retry loops | A failing step the agent retries many times multiplies cost. Look for high step counts on single actions in the run report. | + +Open the run report and check the token count per step — the costliest steps +are usually the ones to optimize. For a cross-run view, see the +[Usage dashboard](/docs/account-billing/usage-dashboard). + +### Run got slower or crashed during a very long execution + +Log and trace files grow continuously over a run. Very large files can exhaust +memory or significantly slow the host machine. + +Mitigations: +- Keep test cases short and focused — split a large suite into smaller cases, + each producing its own report. +- Archive or delete old run artifacts from the `reports/` folder in your + project periodically. +- If a run must be long, monitor disk and memory usage on the AgentOS host + and set up log rotation if your OS supports it. + +--- + +## AgentOS service issues (Windows) + +The steps in this section apply to AgentOS running as a **Windows system service**. For standalone mode on macOS or Linux, check the terminal output for errors. + +### Restart the AgentOS service + +Many issues are resolved by restarting the service. To restart it via Task Manager: + +1. Open **Task Manager** (`Ctrl+Shift+Esc`). +2. Switch to the **Services** tab (the puzzle-piece icon). +3. Search for **`AskuiCoreService`**. +4. Right-click the entry and choose **Restart**. + +### Agent can't press CTRL+ALT+DEL + +The login/lock screen cannot be automated unless the local security policy allows services to simulate a Secure Attention Sequence (SAS). To enable it: + +1. Open the **Group Policy Editor** (`gpedit.msc`). +2. Navigate to **Computer Configuration → Administrative Templates → Windows Components → Windows Logon Options**. +3. Set **Disable or enable software Secure Attention Sequence** to **Enabled**. + +Also verify that `SERVICE_ENABLE_SAS` is set to `1` (default) in the [Silent installer parameters](/docs/agentos/installation/silent/#parameters). + + +The service includes a `windows.forceSas` option that overrides group policies. This is **not recommended** as it may trigger system integrity checks. Configure the GPE policy instead. + + +### Agent can't interact with apps running as Administrator + +Windows prevents non-elevated processes from sending input to elevated (Run as Administrator) applications. If your agent can't click or type into an app running as Administrator, you need to start the Remote Device Controller in elevated mode. + +To enable elevated mode: + +- **Service Installer (GUI)**: Open **Windows Add/Remove Programs**, find AskUI AgentOS, click **Modify**, and enable the elevated execution engine option. Alternatively, reinstall AgentOS with the option enabled. +- **Silent Installer**: Set `SERVICE_EXECUTION_ENGINE_ELEVATED` to `1` — see [Silent installer parameters](/docs/agentos/installation/silent/#parameters). + + +Running the execution engine elevated grants it higher privileges. Only enable this when you need to automate applications that run as Administrator. + + +### `ipv4:127.0.0.1:23000 unavailable` in Standalone mode + +If the client fails to connect with an error like `ipv4:127.0.0.1:23000 unavailable` while running in **Standalone** runtime mode, autostart of the local AgentOS instance is likely disabled. + +Check the `ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART` environment variable — if it is set to `false`, the client will not start AgentOS automatically and there is nothing listening on port `23000`. Either unset the variable or set it to `true`: + + + + ```powershell + $env:ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART="true" + ``` + + + ```bash + export ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART=true + ``` + + + +This variable is intentionally set to `false` when connecting to a remote AgentOS instance — see [Remote Windows VM](/docs/agentos/deployment/ci/#remote-windows-vm). + +### Need to reinstall or remove + + +**Do not** stop or remove the service from Windows Services manually. Always **uninstall the full AskUI AgentOS application** via Windows Add/Remove Programs. This ensures proper cleanup so the client falls back to standalone mode. + + +--- + +## Proxy and SSL + +### Configure a proxy + +AskUI Desktop and the CLI respect the standard proxy environment variables. +Set them before launching: + + + + ```powershell + $env:HTTP_PROXY="http://proxy.example.com:8080" + $env:HTTPS_PROXY="http://proxy.example.com:8080" + $env:NO_PROXY="localhost,127.0.0.1" + ``` + + + ```bash + export HTTP_PROXY="http://proxy.example.com:8080" + export HTTPS_PROXY="http://proxy.example.com:8080" + export NO_PROXY="localhost,127.0.0.1" + ``` + + + +### Deep-packet-inspection proxies (Zscaler and similar) + +Some corporate proxies intercept HTTPS traffic and inject a custom root +certificate. This can cause SSL errors like: + +``` +SSL: CERTIFICATE_VERIFY_FAILED +``` + +**Solution:** Disable SSL verification as a temporary workaround while you +get the proxy certificate added to your system trust store: + + + + ```powershell + $env:ASKUI_HTTP_SSL_VERIFICATION="false" + ``` + + + ```bash + export ASKUI_HTTP_SSL_VERIFICATION=false + ``` + + + + +Disabling SSL verification reduces security. Re-enable it once your proxy +certificate is trusted by the OS certificate store. + + +The permanent fix is to add your proxy's root certificate to the system +certificate store. Contact your IT/network team for the certificate file and +import instructions for your OS. + +--- + +## Debugging run failures + +The fastest way to debug a failing run: + +1. Open the run report (`.md` file in your project's `reports/` folder or + inline in AskUI Desktop). +2. Find the first step with status `FAILED` or `BROKEN` — that is where to + focus. +3. Check the screenshot for that step. `FAILED` means the expected outcome + didn't match; `BROKEN` means an infrastructure problem (connection lost, + session expired) stopped the run. +4. For AgentOS issues, check the [logs](#logs) for more detail. + +If you cannot resolve the issue yourself, see [Get help](/docs/support/get-help) +for how to generate a diagnostic report and contact support. From dd1d57e2e53261aa2de00263f225f7946d803ca8 Mon Sep 17 00:00:00 2001 From: philipph-askui Date: Thu, 9 Jul 2026 17:32:40 +0200 Subject: [PATCH 4/7] docs: move prompting guides under Guides, shorten Agents & Prompts - Move prompting-best-practices and system-prompt from using-askui-desktop/ to guides/ - Add new writing-tests guide - Refactor guides into three focused pages: what-goes-where, system-prompt quality, test quality - Shorten agents-and-prompts.mdx to show only real defaults, cross-reference guides - Update all inbound links across quickstart, first-run, project-structure, troubleshooting Co-Authored-By: Claude Sonnet 4.6 --- content/docs/get-started/first-run.mdx | 2 +- content/docs/get-started/install-desktop.mdx | 4 +- content/docs/get-started/licensing.mdx | 3 +- content/docs/guides/index.mdx | 20 +- content/docs/guides/meta.json | 2 +- .../docs/guides/prompting-best-practices.mdx | 147 ++++++++++++++ content/docs/guides/system-prompt.mdx | 192 ++++++++++++++++++ content/docs/guides/writing-tests.mdx | 155 ++++++++++++++ content/docs/quickstart.mdx | 2 +- content/docs/support/troubleshooting.mdx | 2 +- .../agents-and-prompts.mdx | 85 +++----- content/docs/using-askui-desktop/meta.json | 2 +- .../using-askui-desktop/project-structure.mdx | 2 +- .../prompting-best-practices.mdx | 139 ------------- .../using-askui-desktop/system-prompt.mdx | 163 --------------- 15 files changed, 541 insertions(+), 379 deletions(-) create mode 100644 content/docs/guides/prompting-best-practices.mdx create mode 100644 content/docs/guides/system-prompt.mdx create mode 100644 content/docs/guides/writing-tests.mdx delete mode 100644 content/docs/using-askui-desktop/prompting-best-practices.mdx delete mode 100644 content/docs/using-askui-desktop/system-prompt.mdx diff --git a/content/docs/get-started/first-run.mdx b/content/docs/get-started/first-run.mdx index fb49ce4..68b9f4f 100644 --- a/content/docs/get-started/first-run.mdx +++ b/content/docs/get-started/first-run.mdx @@ -17,7 +17,7 @@ an example login test and the four prompt parts. **Fill in `ui_information.md`.** Tell the agent about your app: its primary screens, how to tell it's signed in, and any dialog quirks. This is the most valuable prompt to get right — see -[Prompting best practices](/docs/using-askui-desktop/prompting-best-practices). +[Prompting best practices](/docs/guides/prompting-best-practices). **Open the example test** in `tests/` and adjust the steps to your app. diff --git a/content/docs/get-started/install-desktop.mdx b/content/docs/get-started/install-desktop.mdx index 939e5ee..8a1fc28 100644 --- a/content/docs/get-started/install-desktop.mdx +++ b/content/docs/get-started/install-desktop.mdx @@ -3,7 +3,7 @@ title: Install AskUI Desktop description: Download and install the AskUI Desktop app on Windows or macOS. --- -AskUI Desktop is the local host for authoring and running AI-driven UI tests. +AskUI Desktop is the key entry point for authoring and running AI-driven UI tests. It runs on Windows and macOS. @@ -22,7 +22,7 @@ AskUI Desktop and the `askui` CLI. no additional runtimes required. - Open the `.dmg` and drag AskUI Desktop to Applications. On first launch, + Drag AskUI Desktop to Applications. On first launch, grant **Accessibility** and **Screen Recording** permissions under **System Settings → Privacy & Security** so the agent can read the screen and control input. diff --git a/content/docs/get-started/licensing.mdx b/content/docs/get-started/licensing.mdx index 71aaa73..a456c69 100644 --- a/content/docs/get-started/licensing.mdx +++ b/content/docs/get-started/licensing.mdx @@ -29,8 +29,7 @@ license key** instead of signing in. -**Paste your license key** and select **Continue**. The key is validated and -stored **encrypted on this device** — it never leaves the machine. +**Paste your license key** and select **Continue**. diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx index e413d07..389efce 100644 --- a/content/docs/guides/index.mdx +++ b/content/docs/guides/index.mdx @@ -3,20 +3,20 @@ title: Guides description: Best-practice guides for authoring reliable AskUI tests — with more to come. --- -These guides go deeper than the reference docs. They explain *why* things work -the way they do and give you patterns you can apply directly to your projects. - ## Available guides - - How to structure a Project's prompts so runs are reliable, reusable, and - debuggable — the four-file layout, per-folder rules, and how to handle - credentials safely. + + The mental model: which content belongs in system prompt files, test files, + setup/teardown, and procedures — with a quick-reference table. + + + What to write in each of the five parts — UI information, error discipline, + Additional Rules, style principles, and a complete worked example. - - The deeper theory behind the five-part prompt structure, with a complete - worked example. + + How to write steps the agent acts on reliably — element descriptions, + credentials, procedures, and when to use setup/teardown. diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json index d5e530a..5c2f910 100644 --- a/content/docs/guides/meta.json +++ b/content/docs/guides/meta.json @@ -1 +1 @@ -{ "title": "Guides", "pages": ["index"] } +{ "title": "Guides", "pages": ["index", "prompting-best-practices", "system-prompt", "writing-tests"] } diff --git a/content/docs/guides/prompting-best-practices.mdx b/content/docs/guides/prompting-best-practices.mdx new file mode 100644 index 0000000..5f5f5f2 --- /dev/null +++ b/content/docs/guides/prompting-best-practices.mdx @@ -0,0 +1,147 @@ +--- +title: What goes where +description: Understand which content belongs in system prompt files, test files, setup/teardown, and procedures — and why. +--- + +AskUI Desktop separates three concerns that are easy to mix up: + +- **Who the agent is** — the system prompt (`prompts/` folder): capabilities, device facts, app knowledge, report format. +- **What to do on this run** — test files (`tests/`): the specific steps for each scenario. +- **Shared lifecycle** — setup, teardown, and rules: actions that run before or after groups of tests. + +Getting this right is what makes Projects maintainable. When a run misbehaves, you know exactly which file to look at. + +## The system prompt (`prompts/`) + +The system prompt is assembled once at run start and applies to every test in the Project. It lives in four files: + + + + + + + + + + + + + Who the agent is and the rules it always follows. Stable — you rarely edit + this. Defines the agent as an autonomous tester that acts via screenshots, + clicks, and typing, plus error-handling discipline. + + + Facts about the machine under test: OS version, how many displays and which + one to use, coordinate origin. Swap this file to retarget a run at a + different machine. + + + **Where the agent learns your app** — primary areas, navigation, state + indicators, and dialog quirks. This is the file you invest the most in. + + + The report the agent writes: Markdown structure plus the status vocabulary — + `PASSED`, `FAILED`, `SKIPPED`, `WARN`, `BROKEN`. + + + +Each file has a different lifecycle: `system_capabilities` is essentially +constant; `device_information` changes per machine; `ui_information` grows as +you learn the app; `report_format` is typically shared org-wide. Keeping them +separate means a change to one never risks the others. + +For what to actually write in each file, see +[Writing a good system prompt](/docs/guides/system-prompt). + +## Test files (`tests/`) + +Each file in `tests/` (or a subfolder) is one test case — a plain Markdown +file listing the steps the agent should carry out and verify. A test file +describes **what to do in this specific scenario**, not how the agent works or +what the app looks like. + +**What belongs in a test file:** +- The steps for this scenario, in natural language +- Expected results the agent should verify +- References to credentials by name (never the credentials themselves) +- Calls to procedures by name for repeated sequences + +**What does not belong in a test file:** +- App knowledge or UI descriptions → `ui_information.md` +- Device facts → `device_information.md` +- Shared steps that run for every test → setup/teardown +- Repeated multi-step sequences → procedures + +For how to write steps the agent acts on reliably, see +[Writing good tests](/docs/guides/writing-tests). + +## Setup, teardown, and rules + +Each test folder can carry three conventional files the runner picks up +automatically for every test inside it: + + + + Runs **before** every test in the folder — outer folders first. Use it for + shared preconditions: logging in, navigating to a starting page, seeding + test data. + + + Runs **after** every test in the folder — innermost folder first. Use it + for cleanup: logging out, resetting state, deleting test data. + + + Execution rules that patch the system prompt for this folder only — + interaction style, error-handling overrides, credential conventions. Use + this instead of editing `system_capabilities.md` when one suite needs + different behaviour. + + + +Setup and teardown cascade with folder nesting: a top-level `setup.md` runs +before a subfolder's `setup.md`, which runs before each test. Teardown +unwinds in reverse. + + +If a suite needs different behaviour, add a `rules.md` in its folder — not by +editing `system_capabilities.md`, which changes behaviour for every test in +the Project. + + +## Procedures (`procedures/`) + +A procedure is a reusable multi-step sequence stored in `procedures/` and +called by name from a test step: + +```markdown +# tests/checkout.md +Sign in using the QA credentials. +Add the first product to the cart. +Complete checkout. +``` + +```markdown +# procedures/sign_in.md +Navigate to the login page. +Enter the QA username and password. +Click Sign in and wait for the dashboard. +``` + +Use a procedure whenever the same sequence appears in more than one test or +setup file. Fix it once and every caller updates automatically. + +--- + +## Quick reference + +| What | File | +|------|------| +| Agent identity and global rules | `prompts/system_capabilities.md` | +| Target machine facts | `prompts/device_information.md` | +| App-specific UI knowledge | `prompts/ui_information.md` | +| Report structure and status vocabulary | `prompts/report_format.md` | +| Folder-level behaviour patches | `/rules.md` | +| Shared preconditions | `/setup.md` | +| Shared cleanup | `/teardown.md` | +| Reusable step sequences | `procedures/.md` | +| Individual test scenarios | `tests/.md` | diff --git a/content/docs/guides/system-prompt.mdx b/content/docs/guides/system-prompt.mdx new file mode 100644 index 0000000..b8398c7 --- /dev/null +++ b/content/docs/guides/system-prompt.mdx @@ -0,0 +1,192 @@ +--- +title: Writing a good system prompt +description: What to write in each part of the AskUI system prompt — UI information, error discipline, Additional Rules, and a complete worked example. +--- + +System prompts are one of your biggest levers on agent reliability. If test +cases consistently fail, engineering the system prompt is often the fix. This +page covers **what to write in each of the five parts** — the theory, content +criteria, and a complete worked example. + +For an overview of which file each part lives in, see +[What goes where](/docs/guides/prompting-best-practices). + +## Why system prompts matter + +A system prompt is one of the most important control surfaces in modern AI +engineering. Rather than fine-tuning model weights, it effectively reprograms +the model for the duration of a run — shaping how it produces every subsequent +token under a new set of constraints, priorities, and abilities. + +Simple tasks need little or no system prompt. But an AskUI agent must plan and +execute **multi-step interactions on UIs it may never have seen**, across +devices with completely different input models (scroll vs. swipe), correctly +identifying interaction affordances. A good system prompt is how you give the +agent the instructions and knowledge it needs. + +## The five parts + +Structure the prompt as **XML**, with one tag per part. A consistent, +detailed, contradiction-free prompt lets the agent reason, plan, and act more +reliably. + +### 1 · System capabilities — set error discipline + +`system_capabilities.md` defines the agent's identity and its always-on rules. +The AskUI default is a good starting point — edit it with care, as small +changes can cause unexpected behaviour across every test. + +The most important thing to get right here is **error discipline**: + +- **Max 2 attempts per step.** After two failures, the agent stops and marks + the step `FAILED`. No third try, no creative workarounds, no navigating back + to retry. This keeps runs honest — a result of `PASSED` means the steps + actually passed. +- **`FAILED` vs `BROKEN` are different.** A step whose result does not match + the expectation is `FAILED` — a problem with the app under test. An + infrastructure error (connection lost, session expired, RPC error) is + `BROKEN` — the agent writes the report and calls `exception_tool` to abort, + because no further test can pass on broken infrastructure. + + +This discipline is why run reports are trustworthy: a green run means the +steps actually passed, not that the agent improvised its way to "done". + + +### 2 · Device information — describe the machine + +`device_information.md` tells the agent what it is operating on. Keep it +factual and specific: + +- Device type (desktop, Android phone, in-car HMI) +- Operating system and version +- Number of displays and which one to use +- Any device-specific input constraints + +Swap this file to retarget a Project at a different machine without touching +anything else. + +### 3 · UI information — your biggest lever + +`ui_information.md` is where you teach the agent your application. This is +the part you invest the most in, and the part most likely to fix a failing +test. Include: + +- **How interactions work** on your interface (single-page navigation, lazy + loading, drag-and-drop patterns). +- **Where relevant functions are located** — primary areas, navigation + structure, where key actions live. +- **Which interaction patterns are non-standard** — anything that would + surprise a first-time user. +- **State indicators** — what "logged in", "loading", "error" look like + visually so the agent can read the screen correctly. +- **Common pitfalls and what not to do** — if there is a destructive action + that's easy to trigger accidentally, say so explicitly. + +If the agent consistently misinterprets a screen state (treating a loading +overlay as a blank page, for example), add a description here. The agent has +no built-in knowledge of your app — everything it needs to recognise must be +written down. + +### 4 · Report format — make output predictable + +`report_format.md` tells the agent how to structure its output. Be explicit: +Markdown or JSON, required sections, and the status vocabulary. Using the +standard AskUI status vocabulary (`PASSED`, `FAILED`, `SKIPPED`, `WARN`, +`BROKEN`) ensures run reports are readable by AskUI Desktop's report viewer. + +### 5 · Additional rules — patch specific issues + +Additional rules are per-folder `rules.md` files that patch the system prompt +for one suite without touching the Project-wide files. Use them when the agent +consistently struggles with a specific situation. + +A good additional rule describes: +- **How the agent identifies the stuck situation** — what it sees on screen. +- **What it should do** — the exact sequence to follow. +- **What it should not do** — rule out the wrong approach explicitly. + +Think of each rule as a targeted bug fix. For example, if the agent +consistently misses a small *Save* button, describe exactly where it is, what +it looks like, and what to do when asked to click it. + +--- + +## Style principles + + + + Wrap each part in an XML tag and use bullet-point lists within each part. + Structured prompts are easier to audit and easier for the model to parse. + + + Stick to clear English throughout — the prompt, test cases, all inputs. + Mixed languages degrade performance. + + + Contradicting rules produce undefined behaviour. Review each part against + the others before committing. + + + If you feel you are being too detailed, you are doing it right. Only you + know your UI — pass all relevant information. + + + +--- + +## A complete example + +A minimal system prompt with all five parts, for a web-search agent: + +```xml + +* You are an autonomous AI agent that operates User Interfaces such as apps, websites, or software. +* Your primary goal is to execute tasks efficiently and reliably while + maintaining system stability. +* Operate independently and make informed decisions without requiring + user input. +* When you cannot find something (application window, ui element etc.) on + the currently selected/active display/screen, check the other available + displays by listing them and checking which one is currently active and + then going through the other displays one by one until you find it or + you have checked all of them. +* When using your function calls, they take a while to run and send back + to you. Where possible/feasible, try to chain multiple of these calls + all into one function calls request. + + +Here are some details on the device you will be operating: +* Device Type: Personal Computer +* Operating System: macOS +* Internet Access: Available + + +* When asked to perform web tasks try to open the browser (firefox, + chrome, safari, ...) if not already open. Often you can find the + browser icons in the toolbars of the operating systems. +* When viewing a page it can be helpful to zoom out/in so that you can + see everything on the page. Either that, or make sure you scroll + down/up to see everything before deciding something isn't available. +* Uses single-page navigation with URL updates. + + +* Provide a clear and concise summary of actions taken. +* Use Markdown formatting for better readability. +* Include any relevant observations or findings. +* Highlight any issues or errors encountered. + + +* If asked to open a browser window, tab or website, always make sure that you open a new window. If you cannot see a window you just opened, it might have appeared on another screen than you are currently looking at. +**DO NEVER:** + - Complete a purchase without explicit user confirmation. + - Submit any payment information. + - Delete any items from saved lists. + +``` + + +Once your prompt is solid, run it from the [CLI](/docs/using-askui-desktop/cli) +across your test suite and read the +[run report](/docs/using-askui-desktop/run-report) to see where to tighten it. + diff --git a/content/docs/guides/writing-tests.mdx b/content/docs/guides/writing-tests.mdx new file mode 100644 index 0000000..332fa0e --- /dev/null +++ b/content/docs/guides/writing-tests.mdx @@ -0,0 +1,155 @@ +--- +title: Writing good tests +description: How to write clear, reliable test steps — element descriptions, credentials, procedures, and setup/teardown. +--- + +A test file is a plain Markdown file listing the steps and verifications the +agent should carry out. The agent reads it, acts on the real screen, and writes +a report. Whether that run is reliable depends almost entirely on how clearly +the steps are written. + +## One goal per test file + +Each test file should describe **one coherent scenario** with a clear, +verifiable outcome. Tests with multiple independent goals are harder to debug +— when the run fails, you cannot tell which goal it failed on. + +```markdown + +# Verify that a new user can complete registration + +Navigate to the registration page. +Fill in the registration form with valid data. +Submit the form. +Verify that the confirmation page is shown. +``` + +```markdown + +# Registration and login + +Register a new account, then log in with the new credentials. +``` + +## Write steps the agent can act on reliably + +The agent identifies UI elements from screenshots. Vague descriptions force it +to guess; specific descriptions make each step unambiguous. + +**Use spatial anchors.** Describe where an element is relative to something +stable on screen: + +```markdown + +Click the button. + + +Click the Save button in the bottom-right corner of the dialog, below the +comment field. +``` + +**Include distinguishing features.** Name the label, color, icon, or position +that makes the element unique: + +```markdown + +Click the icon. + + +Click the red trash-can icon to the right of the row labelled "Draft report". +``` + +**Instruct the agent to zoom for small targets.** If a button or icon is +small, say so explicitly: + +```markdown +Zoom in on the toolbar area, then click the small pencil icon on the far right. +``` + +**State what to verify, not just what to do.** A step without a verification +always passes: + +```markdown + +Click Submit. + + +Click Submit. Verify that the success banner "Changes saved" appears at the +top of the page. +``` + +## Never embed credentials in test files + +Test files are version-controlled. Credentials must not be. Reference them by +name and let the agent read them from a local file at run time: + +```markdown + +Sign in using the QA admin credentials. + + +Sign in with username "admin@example.com" and password "hunter2". +``` + +The agent resolves named credentials by reading a local credentials file with +its file tools at execution time. See +[What goes where](/docs/guides/prompting-best-practices) for the Project +structure that supports this. + +## Use procedures for repeated sequences + +When the same multi-step sequence appears in more than one test — signing in, +navigating to a starting state, seeding data — extract it into a procedure: + +```markdown +# procedures/sign_in.md +Navigate to https://app.example.com/login. +Enter the QA username and password. +Click Sign in and wait for the dashboard to appear. +``` + +Call it from any test or setup file: + +```markdown +Sign in using the QA credentials. +``` + +Procedures keep tests short and focused. They also mean a changed flow (a new +login page, a renamed field) only needs fixing in one place. + +## Use setup and teardown for shared state + +**Setup files** run before every test in a folder. Use them for preconditions +that every test in that folder needs: + +- Logging in +- Navigating to a known starting page +- Seeding or resetting test data + +**Teardown files** run after every test. Use them for cleanup: + +- Logging out +- Deleting data created during the test +- Resetting application state + +If a precondition is needed by every test in a folder, put it in `setup.md` +rather than at the top of each test file. If a step is needed by only some +tests, keep it inline. + + +Setup and teardown are not the same as procedures. Setup/teardown run +automatically for every test in the folder; procedures are called explicitly +from a test step. + + +## Checklist + +Before committing test files: + +- [ ] Each test file has one clear goal with a verifiable outcome. +- [ ] Steps use spatial anchors and distinguishing features — no bare "click the button". +- [ ] Every step that does something verifiable includes an explicit verification. +- [ ] No credentials in any test file — only named references. +- [ ] Repeated sequences are in `procedures/`, not copy-pasted. +- [ ] Shared preconditions are in `setup.md`, not duplicated across tests. +- [ ] Shared cleanup is in `teardown.md`. diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx index a49493e..a70cd85 100644 --- a/content/docs/quickstart.mdx +++ b/content/docs/quickstart.mdx @@ -117,7 +117,7 @@ actually passed — the agent doesn't improvise. You have a working project. Here is where to go from here: - + Learn how to structure prompts so your runs stay reliable as your test suite grows — the four-file layout, `rules.md`, and how to avoid brittle tests. diff --git a/content/docs/support/troubleshooting.mdx b/content/docs/support/troubleshooting.mdx index ee352b8..bf4f335 100644 --- a/content/docs/support/troubleshooting.mdx +++ b/content/docs/support/troubleshooting.mdx @@ -92,7 +92,7 @@ specific: acting — for example, "zoom in on the toolbar area, then click the small red X icon". -See [Prompting best practices](/docs/using-askui-desktop/prompting-best-practices) +See [Prompting best practices](/docs/guides/prompting-best-practices) for a full guide on writing reliable element descriptions. ### Agent misinterprets a screen state diff --git a/content/docs/using-askui-desktop/agents-and-prompts.mdx b/content/docs/using-askui-desktop/agents-and-prompts.mdx index 0b9e966..1f5ae64 100644 --- a/content/docs/using-askui-desktop/agents-and-prompts.mdx +++ b/content/docs/using-askui-desktop/agents-and-prompts.mdx @@ -1,40 +1,20 @@ --- title: Agents & prompts -description: How AskUI Desktop assembles a testing agent from a Project's prompt files, with the real default prompts explained part by part. +description: The real default prompt files AskUI Desktop creates for a new Project — what each one contains and what to change. --- -When you run a test, AskUI Desktop assembles an autonomous testing agent from -your Project's `prompts/` folder. The agent reads the screen, acts via clicks -and keystrokes, verifies expected results, and writes a report. This page walks -through each prompt part using the **real defaults** a new Project ships with. +When you create a Project, AskUI Desktop scaffolds the `prompts/` folder with +sensible defaults. This page shows what each file contains out of the box and +what you are expected to customise. - -New to the structure? Start with -[How a Project is organized](/docs/using-askui-desktop/project-structure), then the -[Prompting best practices](/docs/using-askui-desktop/prompting-best-practices) for -the principles behind it. - +For the structural overview of what goes in each file and why, see +[What goes where](/docs/guides/prompting-best-practices). For writing guidance, +see [Writing a good system prompt](/docs/guides/system-prompt). -## What the agent is made of +## `system_capabilities.md` -The four prompt parts are composed into the agent at run start, then per-folder -`rules.md` / `setup.md` / `teardown.md` are layered on top for the tests in that -folder. - - - - - - - - - - -## `system_capabilities.md` — who the agent is - -Defines the agent's identity and the discipline it always follows. You rarely -edit this. The default establishes an autonomous tester that acts through -screenshots and input, and — critically — that **does not improvise**: +Defines the agent's identity and error-handling discipline. You rarely edit +this — the defaults are designed to keep runs honest: > **Error handling.** You have a maximum of **2 attempts per step**. If a step > does not succeed after 2 attempts, stop immediately. Do not try a third @@ -44,20 +24,19 @@ screenshots and input, and — critically — that **does not improvise**: > **Infrastructure errors.** Tool errors that indicate infrastructure failures > (connection lost, session expired, RPC errors) are fundamentally different > from test failures. Write the report with status **BROKEN** and call the -> `exception_tool` to abort — retrying cannot fix broken infrastructure. +> `exception_tool` to abort. -It also sets two conventions the agent relies on: +Two built-in conventions the agent relies on: - **Credentials** are never embedded in a test. When a step references "the QA credentials", the agent reads them from a local credentials file at run time. - **Scratchpad** — the agent can persist information across steps with - `scratchpad_write_tool` / `scratchpad_read_tool`, but only when explicitly - prompted to. + `scratchpad_write_tool` / `scratchpad_read_tool`, but only when a test + explicitly instructs it to. -## `device_information.md` — the machine +## `device_information.md` -Facts about the machine under test. Swap this file to retarget a run. The -default is a placeholder you fill in: +Facts about the machine under test. The default is a placeholder you fill in: ```markdown You are controlling a desktop computer. @@ -68,10 +47,12 @@ You are controlling a desktop computer. * Always verify the current screen state before performing interactions. ``` -## `ui_information.md` — your application +Swap this file when retargeting a Project at a different machine. -Where the agent learns **your** app: its areas, how to read state, and its -quirks. This is the file you invest the most in. +## `ui_information.md` + +Where the agent learns your application. The default ships empty — this is the +file you invest the most in: ```markdown ## Navigation @@ -86,10 +67,9 @@ session expired — sign in again." or dismissed before continuing." ``` -## `report_format.md` — how it reports +## `report_format.md` -The structure and status vocabulary of the report the agent writes after each -case. The default statuses: +The structure and status vocabulary of the report the agent writes. Default statuses: | Status | Meaning | | --- | --- | @@ -99,18 +79,15 @@ case. The default statuses: | `WARN` | Passed with a caveat (slow response, minor visual deviation). | | `BROKEN` | Could not execute — crash or infrastructure failure. | -The overall status is the worst of its steps. See -[Reading a run report](/docs/using-askui-desktop/run-report) to see one rendered. - -## Per-folder behaviour +The overall test status is the worst status of its steps. See +[Reading a run report](/docs/using-askui-desktop/run-report). -Don't edit `system_capabilities.md` to change one suite. Instead drop a -`rules.md` into the test folder — every test inside picks it up automatically: +## Per-folder files - Execution rules for this folder: interaction style, error-handling policy, - and the credential convention. Cascades with folder nesting. + Execution rules for this folder — patches the system prompt for this suite + only. Cascades with folder nesting. Runs **before** every test in the folder — outer folders first. @@ -119,9 +96,3 @@ Don't edit `system_capabilities.md` to change one suite. Instead drop a Runs **after** every test in the folder — innermost folder first. - - -The full UI walkthrough (editing these files inside AskUI Desktop with -screenshots) lands with the desktop-app screenshots pass. The structure and -defaults above are stable. - diff --git a/content/docs/using-askui-desktop/meta.json b/content/docs/using-askui-desktop/meta.json index fa1cef5..2db559b 100644 --- a/content/docs/using-askui-desktop/meta.json +++ b/content/docs/using-askui-desktop/meta.json @@ -1 +1 @@ -{ "title": "Using AskUI Desktop", "pages": ["project-structure", "agents-and-prompts", "model-providers", "prompting-best-practices", "system-prompt", "run-report", "cli"] } +{ "title": "Using AskUI Desktop", "pages": ["project-structure", "agents-and-prompts", "model-providers", "run-report", "cli"] } diff --git a/content/docs/using-askui-desktop/project-structure.mdx b/content/docs/using-askui-desktop/project-structure.mdx index 4ca8b64..0808c3b 100644 --- a/content/docs/using-askui-desktop/project-structure.mdx +++ b/content/docs/using-askui-desktop/project-structure.mdx @@ -40,7 +40,7 @@ the placeholders rather than starting from a blank page. - [Agents & prompts](/docs/using-askui-desktop/agents-and-prompts) — the prompt parts in detail. -- [Prompting best practices](/docs/using-askui-desktop/prompting-best-practices) — +- [Prompting best practices](/docs/guides/prompting-best-practices) — how to structure them well. - [Reading a run report](/docs/using-askui-desktop/run-report) — what a run produces. diff --git a/content/docs/using-askui-desktop/prompting-best-practices.mdx b/content/docs/using-askui-desktop/prompting-best-practices.mdx deleted file mode 100644 index 285bdeb..0000000 --- a/content/docs/using-askui-desktop/prompting-best-practices.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Prompting best practices -description: How to structure a Project's prompts so AskUI Desktop runs are reliable, reusable, and debuggable. ---- - -Good test runs come from well-structured prompts — not longer ones. AskUI -Desktop splits a Project's prompting into a few small files, each with one -job. This page explains **why** that structure exists and how to use it. - - -Separate **what the agent can do** from **the machine it runs on**, from -**your application's quirks**, from **how it reports** — and tune behaviour in -per-folder `rules.md`, never by editing the system prompt. - - - -For the deeper theory — the five-part structure, the criteria for judging each -part, and a complete worked example — see -[Engineering a good system prompt](/docs/using-askui-desktop/system-prompt). - - -## 1. Split the prompt into four parts - -Every Project gets a `prompts/` folder with four files. Each changes at a -different rate and is reused across every test in the Project — keeping them -separate is what makes prompts stable and debuggable. - - - - - - - - - - - - - Who the agent is and the rules it always follows. Stable — you rarely edit - this. Defines the agent as an autonomous tester that acts via screenshots, - clicks, and typing, plus strict error-handling discipline (below). - - - Facts about the machine under test: OS version, how many displays and - which one to use, that coordinates start at `(0,0)` top-left. Swap this - file to retarget a run at a different machine. - - - **Where the agent learns *your* app** — primary areas, navigation, state - indicators (e.g. "green dot top-right = signed in"), and dialog quirks. - This is the file you invest the most in. - - - The report the agent writes: Markdown structure plus the status vocabulary - — `PASSED`, `FAILED`, `SKIPPED`, `WARN`, `BROKEN`. - - - -**Why split, not one big prompt?** Each part has a different lifecycle. -`system_capabilities` is essentially constant. `device_information` changes -per machine. `ui_information` grows as you learn the app. `report_format` is -shared org-wide. Keeping them apart means a change to one never risks the -others, and when a run misbehaves you know exactly which file to inspect. - -## 2. Tune behaviour in `rules.md`, per folder — not in the system prompt - -Each test folder can carry conventional files that the runner picks up -**automatically** for every test inside it: - -- `rules.md` — execution rules for this folder (interaction style, error - handling, credential policy). -- `setup.md` — runs **before** every test in the folder (outer folders first). -- `teardown.md` — runs **after** every test (innermost folder first). - -This cascades with folder nesting, so shared behaviour lives at the top and -specific overrides live deeper — without ever touching the system prompt. - - -If a suite needs different behaviour, add a `rules.md` in its folder. Editing -`system_capabilities.md` changes behaviour for *every* test in the Project. - - -## 3. Never put credentials in tests - -Test files are shared and version-controlled — secrets must not be. Reference -them by name and let the agent read them at run time: - -```markdown -# In a test step -Sign in using the QA credentials. -``` - -The agent resolves "the QA credentials" by reading a local credentials file -with its file tools at execution time. Real credentials never appear in -`tests/*.md` or the prompts. - -## 4. Be strict about errors — no retry loops - -The default `system_capabilities` enforces discipline that keeps runs honest -and fast: - -- **Max 2 attempts per step.** No third try, no creative workarounds, no - navigating back to retry a sequence. -- **`FAILED` vs `BROKEN` are different.** A step whose result doesn't match the - expectation is `FAILED`. An *infrastructure* error (connection lost, session - expired, RPC error) is `BROKEN` — the agent writes the report and calls the - `exception_tool` to abort, because no further test can pass on broken - infrastructure. - - -This is why your run reports are trustworthy: a green run means the steps -actually passed, not that the agent improvised its way to "done". - - -## 5. Reuse sequences with procedures - -Common multi-step sequences (signing in, seeding data) live once in -`procedures/` — e.g. `procedures/login_to_ui.md` — and are invoked from a test -step instead of being copy-pasted. Fix the login flow in one place and every -test that uses it updates. - -## See it end to end - -Here's a real run produced by a Project structured this way — prompts on the -left of the app, the executed steps and screenshots on the right: - - - -## Checklist - -Before you commit a Project's prompts, confirm: - -- [ ] `prompts/` has all four parts, each scoped to its one job. -- [ ] App-specific knowledge lives in `ui_information.md`, not the system prompt. -- [ ] Folder behaviour is tuned in `rules.md` / `setup.md` / `teardown.md`. -- [ ] No credentials in any `tests/` or `prompts/` file — keep them in a local - file the agent reads at run time. -- [ ] `report_format.md` uses the standard status vocabulary. -- [ ] Repeated sequences are extracted into `procedures/`. diff --git a/content/docs/using-askui-desktop/system-prompt.mdx b/content/docs/using-askui-desktop/system-prompt.mdx deleted file mode 100644 index 940d0d6..0000000 --- a/content/docs/using-askui-desktop/system-prompt.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Engineering a good system prompt -description: The five parts of a strong AskUI system prompt, the criteria to judge each part, and a complete worked example. ---- - -System prompts are one of your biggest levers on agent reliability. If there -are test cases where the agent consistently fails, engineering the system -prompt is often the fix. Our recommendation: a prompt structured as **XML**, -composed of **five parts** — System Capabilities, Device Information, UI -Information, Report Format, and (optionally) Additional Rules. A consistent, -detailed, contradiction-free prompt lets the agent reason, plan, and act more -reliably. - - -In AskUI Desktop these five parts are the files in your Project's `prompts/` -folder plus per-folder `rules.md`. This page is the *why* and *how to write -each part well*; [Prompting best practices](/docs/using-askui-desktop/prompting-best-practices) -covers how they live in the Project, and [Agents & prompts](/docs/using-askui-desktop/agents-and-prompts) -shows the real defaults. - - -## Why system prompts matter - -A system prompt is one of the most important control surfaces in modern AI -engineering. Rather than fine-tuning model weights, it effectively reprograms -the model for the duration of a run — shaping how it produces every subsequent -token under a new set of constraints, priorities, and abilities. - -Simple tasks (drafting an email, describing an image) need little or no system -prompt. But an AskUI agent must plan and execute **multi-step interactions on -UIs it may never have seen**, across devices with completely different input -models (scroll vs. swipe), correctly identifying interaction affordances. A -good system prompt is how you induce the instructions and knowledge the agent -needs to do that. - -## The five parts - - - - What the agent should do, how it should behave, and how it unblocks itself. - **Stick to the AskUI default here** — small changes can cause unexpected - behaviour. Edit with care. - - - The device under test: desktop, Android phone, iPhone, in-car HMI? Windows, - Linux, macOS, iOS, Android? Any device-specific constraints? Defaults exist - for Desktop and Android. - - - The most important part you own. Nobody knows your UI better than you — - pass it as much as possible (below). - - - How the agent should report after a run — Markdown, JSON, or plain text. - Be explicit about structure. If you want no report, say so here. - - - -### 3 · UI Information — what to include - -This is where you teach the agent *your* application. Explain: - -- **How interactions work** on your interface. -- **Where relevant functions are located.** -- **Which interaction patterns are non-standard.** -- **Where first-time users commonly get lost.** - -Crucially, also call out **common pitfalls and what *not* to do** when -operating your UI. - -### 5 · Additional Rules (optional) - -Patches for specific cases the agent regularly struggles with. For example, if -it consistently fails to click your *Save* button, describe in detail where it -is, what it looks like, and what to do when asked to click it. Include: - -- how the agent can **identify** the stuck situation, -- what it **should do**, and -- what it **should not do**. - -Think of this as patching a single bug in your program. - -## Best practices for every part - - - - Stick to clear English throughout — the prompt, test cases, all inputs. - Other languages or mixed languages degrade performance. - - - Contradicting rules inevitably produce undefined behaviour. - - - Wrap each part in an XML tag and use bullet-point lists within each part. - - - If you feel you're being far too detailed, you're doing it right. Only you - know your UI — pass all relevant information. - - - -## A complete example - -A minimal system prompt with all five parts, for a web-search agent: - -```xml - -* You are an autonomous AI agent that operates User Interfaces such as apps, websites, or software. -* Your primary goal is to execute tasks efficiently and reliably while - maintaining system stability. -* Operate independently and make informed decisions without requiring - user input. -* When you cannot find something (application window, ui element etc.) on - the currently selected/active display/screen, check the other available - displays by listing them and checking which one is currently active and - then going through the other displays one by one until you find it or - you have checked all of them. -* When using your function calls, they take a while to run and send back - to you. Where possible/feasible, try to chain multiple of these calls - all into one function calls request. - - -Here are some details on the device you will be operating: -* Device Type: Personal Computer -* Operating System: macOS -* Internet Access: Available - - -* When asked to perform web tasks try to open the browser (firefox, - chrome, safari, ...) if not already open. Often you can find the - browser icons in the toolbars of the operating systems. -* When viewing a page it can be helpful to zoom out/in so that you can - see everything on the page. Either that, or make sure you scroll - down/up to see everything before deciding something isn't available. -* Uses single-page navigation with URL updates - - -* Provide a clear and concise summary of actions taken -* Use Markdown formatting for better readability -* Include any relevant observations or findings -* Highlight any issues or errors encountered - - -* If asked to open a browser window, tab or website, always make sure that you open a new window. If you cannot see a window you just opened, it might have appeared on another screen than you are currently looking at -**DO NEVER:** - - Complete a Purchase without explicit user confirmation - - submit any payment information - - delete any items from saved lists - -``` - -## Summary - -The system prompt is among the most powerful tools for improving your agent's -performance. Use the five-part structure to make sure you give the agent all -relevant information, and review each part against the criteria above to assert -prompt quality. - - -Once your prompt is solid, run it from the [CLI](/docs/using-askui-desktop/cli) to -evaluate it across your test suite, and read the -[run report](/docs/using-askui-desktop/run-report) to see where to tighten it. - From f2295dad137da442159bcf8cc072c09737e085f2 Mon Sep 17 00:00:00 2001 From: philipph-askui Date: Thu, 9 Jul 2026 21:48:23 +0200 Subject: [PATCH 5/7] docs: expand run report page and refine using-askui-desktop pages - run-report: add full coverage of markdown reports, summary report, and HTML report; demote live run viewer to a brief section - agents-and-prompts: clarify scratchpad use case, rename per-folder to per-suite, use suite terminology consistently - project-structure: tighten description, note subsuites as subfolders - model-providers: remove trailing Next cards section Co-Authored-By: Claude Sonnet 4.6 --- .../agents-and-prompts.mdx | 16 +- .../using-askui-desktop/model-providers.mdx | 8 +- .../using-askui-desktop/project-structure.mdx | 11 +- .../docs/using-askui-desktop/run-report.mdx | 165 ++++++++++++++++-- 4 files changed, 161 insertions(+), 39 deletions(-) diff --git a/content/docs/using-askui-desktop/agents-and-prompts.mdx b/content/docs/using-askui-desktop/agents-and-prompts.mdx index 1f5ae64..d446513 100644 --- a/content/docs/using-askui-desktop/agents-and-prompts.mdx +++ b/content/docs/using-askui-desktop/agents-and-prompts.mdx @@ -32,7 +32,7 @@ Two built-in conventions the agent relies on: credentials", the agent reads them from a local credentials file at run time. - **Scratchpad** — the agent can persist information across steps with `scratchpad_write_tool` / `scratchpad_read_tool`, but only when a test - explicitly instructs it to. + explicitly instructs it to. This might be necessary if you need to persist information across tests. ## `device_information.md` @@ -51,8 +51,8 @@ Swap this file when retargeting a Project at a different machine. ## `ui_information.md` -Where the agent learns your application. The default ships empty — this is the -file you invest the most in: +Where the agent learns your application. The default ships empty — **this is the +file you invest the most in**: ```markdown ## Navigation @@ -82,17 +82,17 @@ The structure and status vocabulary of the report the agent writes. Default stat The overall test status is the worst status of its steps. See [Reading a run report](/docs/using-askui-desktop/run-report). -## Per-folder files +## Per-Suite files - Execution rules for this folder — patches the system prompt for this suite - only. Cascades with folder nesting. + Execution rules for this suite — patches the system prompt for this suite + only. Cascades with suite nesting. - Runs **before** every test in the folder — outer folders first. + Runs **before** every test in the suite — parent suites first. - Runs **after** every test in the folder — innermost folder first. + Runs **after** every test in the suite — innermost suites first. diff --git a/content/docs/using-askui-desktop/model-providers.mdx b/content/docs/using-askui-desktop/model-providers.mdx index ad876ef..d595b3a 100644 --- a/content/docs/using-askui-desktop/model-providers.mdx +++ b/content/docs/using-askui-desktop/model-providers.mdx @@ -102,10 +102,4 @@ Run a test as usual. The agent now uses your provider. In **Settings → Model Provider**, choose **Remove key**. This reverts to the AskUI hub default and forgets the stored key. (In License mode there is no hub -default, so you replace the provider rather than removing it.) - -## Next - - - - +default, so you replace the provider rather than removing it.) \ No newline at end of file diff --git a/content/docs/using-askui-desktop/project-structure.mdx b/content/docs/using-askui-desktop/project-structure.mdx index 0808c3b..b40198e 100644 --- a/content/docs/using-askui-desktop/project-structure.mdx +++ b/content/docs/using-askui-desktop/project-structure.mdx @@ -1,6 +1,6 @@ --- title: How a Project is organized -description: The folder structure of an AskUI Desktop Project and how tests, plans, prompts, procedures and utils fit together. +description: The structure of an AskUI Desktop Project and how tests, plans, prompts, procedures and utils fit together. --- A **Project** is the unit of work in AskUI Desktop. Everything for a body of @@ -24,15 +24,14 @@ testing lives in one Project folder, split into a few well-known areas. - **Tests** decompose into **suites → cases → steps**. A step describes an action and its expected result. Cases may carry a **precondition** and - **postcondition**; suites may carry **setup** and **teardown**. -- A **step** can invoke a **procedure** (a reusable sequence) or a **util** (a + **postcondition**; suites may carry **setup** and **teardown**. Suites can have subsuites saved as subfolders. +- A **step** can invoke one or more **procedures** (a reusable sequence), or **utils** (a tool, MCP server, skill, or CLI command). -- **Plans** select what runs — e.g. a `smoke` plan that runs a subset of +- **Plans** select what runs, e.g. a `smoke` plan that runs a subset of suites for a quick check. -Start from the scaffold: a new Project comes pre-seeded with the four prompt -parts, an example login test, and a `smoke` plan. Fill in +Start from the scaffold: a new Project comes pre-seeded with all necessary parts. we recommend filling in the placeholders rather than starting from a blank page. diff --git a/content/docs/using-askui-desktop/run-report.mdx b/content/docs/using-askui-desktop/run-report.mdx index 3d00083..7d53be2 100644 --- a/content/docs/using-askui-desktop/run-report.mdx +++ b/content/docs/using-askui-desktop/run-report.mdx @@ -1,29 +1,158 @@ --- title: Reading a run report -description: How to read the report AskUI Desktop produces after a test run, including the embedded interactive run viewer. +description: The three report artifacts a run produces — per-test Markdown reports, a cross-run summary, and a portable HTML log — and how to read each one. --- -Every run produces a report: a per-step record of what the agent did, what it -expected, what it observed, and a screenshot of each step. You can open the -interactive report right here. +Every run writes its output into a timestamped workspace folder under +`agent_workspace/`. Three types of artifact are produced: - +``` +agent_workspace/ +└── 2025-11-12_14-30-00/ ← one folder per run + ├── summary_report.md ← run-level table + ├── conversation.html ← portable HTML log + ├── conversation.json ← raw data (used by the app) + └── login_test/ ← one folder per test + ├── login_test_report.md + ├── step_1.png + └── step_2.png +``` -## Status vocabulary +The default workspace path is `/agent_workspace/`. +You can override it with `--workspace` when running from the CLI. + +--- + +## Markdown report + +Each test gets its own subdirectory with a `_report.md` and a +`step_.png` screenshot for every step. The agent writes this report as it +executes — it is the primary record of what the agent did, what it expected, +and what it actually observed. + +```markdown +# Test Case Report: login_test + +**Test Case ID:** login_test +**Date:** 2025-11-12 +**Status:** PASSED + +## Summary + +The agent successfully logged in using the QA credentials and verified +the dashboard was shown. + +## Preconditions + +1. Application is running and the login page is visible. + +## Test Steps + +1. **Navigate to the login page** — Status: **PASSED** + - **Agent Interpretation:** Opened browser and navigated to the login URL. + - **Expected:** Login form visible. + - **Actual:** Login form visible with username and password fields. + - ![Step 1](step_1.png) + +2. **Enter QA credentials and submit** — Status: **PASSED** + - **Agent Interpretation:** Filled the form using the QA credentials file. + - **Expected:** Dashboard page shown after successful sign-in. + - **Actual:** Dashboard loaded with the welcome banner. + - ![Step 2](step_2.png) + +## Postconditions + +1. User is signed in and the dashboard is visible. + +## Issues + +No issues encountered. + +## Conclusion + +All steps passed. The login flow works as expected with the current QA credentials. +``` + +Each step carries its own status. The **overall status** of the test is derived +from the worst step status — see [Status vocabulary](#status-vocabulary) below. + +--- + +## Summary report + +`summary_report.md` in the run folder contains one Markdown table across all +tests in the run, with status and execution time per test. -Each step — and the run overall — carries one status: +```markdown +# Run Summary -- **PASSED** — actual result matches expected. -- **FAILED** — step executed but the result didn't match. -- **SKIPPED** — intentionally not executed (e.g. precondition not met). -- **WARN** — passed, but with a caveat (slow response, minor visual deviation). -- **BROKEN** — could not execute due to a crash or infrastructure failure. +| ID | Name | Status | Duration | +|---|---|---|---| +| login_test | login_test | PASSED | 1m 12s | +| settings_test | settings_test | PASSED | 0m 48s | +| checkout_test | checkout_test | FAILED | 2m 03s | -The overall status is the worst of its steps: `BROKEN` if any step broke, else -`FAILED` if any failed, else `WARN`, else `SKIPPED` if all skipped, otherwise -`PASSED`. +**Total: 3 · Passed: 2 · Failed: 1 · Broken: 0** +``` - -Report artifacts (the Markdown report and `step_N.png` screenshots) are written -into a per-test subdirectory, so a run's evidence stays together. +Tests that a plan selected but the run never reached are listed as `BROKEN` +so nothing goes missing silently. The Dashboard and Runs pages in AskUI Desktop +derive their pass/fail counters from this table. + + +`WARN` counts as passed (tracked separately in the warning total). `SKIPPED` +tests never executed and are excluded from the total. `BROKEN` tests without +an execution time in the summary (tests that never started) are also excluded +from the total — they show in the table but don't affect the pass rate. + +--- + +## HTML report + +`conversation.html` is a self-contained, portable file that captures the full +agent conversation — every message, tool call, and screenshot — in a single +file you can open in any browser, send to a colleague, or attach to a bug +report without any extra tooling. + + + +The HTML report and the raw `conversation.json` are written when the run +completes (or is cancelled — partial reports are preserved). In CI, upload +the whole workspace folder as a build artifact so the HTML report stays +attached to the run even when tests fail: + +```yaml title=".github/workflows/ui-tests.yml" +- uses: actions/upload-artifact@v4 + if: always() + with: + name: askui-run + path: ./run-artifacts +``` + +--- + +## Live run viewer + +While a run is in progress, AskUI Desktop shows the agent conversation in +real time on the **Runs** page — the same data that is later persisted to +`conversation.html`, but streaming as each step completes. Use it to watch +the agent act and catch unexpected behaviour early. + +--- + +## Status vocabulary + +Each step — and the test overall — carries one status: + +| Status | Meaning | +| --- | --- | +| `PASSED` | Actual result matches expected. | +| `FAILED` | Step executed but the result didn't match. | +| `SKIPPED` | Intentionally not executed (e.g. precondition not met). | +| `WARN` | Passed, but with a caveat (slow response, minor visual deviation). | +| `BROKEN` | Could not execute — crash or infrastructure failure. | + +The overall test status is the worst of its steps: `BROKEN` if any step broke, +else `FAILED` if any failed, else `WARN`, else `SKIPPED` if all skipped, +otherwise `PASSED`. From 0f39d8d407ee55cd05abb9d00d34b719d4b1b03f Mon Sep 17 00:00:00 2001 From: philipph-askui Date: Thu, 9 Jul 2026 21:59:02 +0200 Subject: [PATCH 6/7] docs: convert coming-soon list to cards, refine system-prompt guide - guides/index: convert Coming soon bullet list to Cards - guides/system-prompt: soften error-discipline framing, add naming conventions bullet to UI information, retitle report format section Co-Authored-By: Claude Sonnet 4.6 --- content/docs/guides/index.mdx | 18 ++++++++++++++---- content/docs/guides/system-prompt.mdx | 11 ++++++----- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx index 389efce..71428bb 100644 --- a/content/docs/guides/index.mdx +++ b/content/docs/guides/index.mdx @@ -22,7 +22,17 @@ description: Best-practice guides for authoring reliable AskUI tests — with mo ## Coming soon -- **Video tutorials** — end-to-end walkthroughs of common testing scenarios -- **CI/CD patterns** — how to wire AskUI into GitHub Actions, GitLab CI, and Jenkins -- **Multi-device fleet setup** — running the same suite across many machines in parallel -- **Flaky test debugging** — how to read a failing report and pinpoint the root cause + + + End-to-end walkthroughs of common testing scenarios. + + + How to wire AskUI into GitHub Actions, GitLab CI, and Jenkins. + + + Running the same suite across many machines in parallel. + + + How to read a failing report and pinpoint the root cause. + + diff --git a/content/docs/guides/system-prompt.mdx b/content/docs/guides/system-prompt.mdx index b8398c7..cdff50b 100644 --- a/content/docs/guides/system-prompt.mdx +++ b/content/docs/guides/system-prompt.mdx @@ -36,13 +36,13 @@ reliably. The AskUI default is a good starting point — edit it with care, as small changes can cause unexpected behaviour across every test. -The most important thing to get right here is **error discipline**: +Two examples of things that go into this prompt part: -- **Max 2 attempts per step.** After two failures, the agent stops and marks +- **Error Handling.** After two failures, the agent stops and marks the step `FAILED`. No third try, no creative workarounds, no navigating back to retry. This keeps runs honest — a result of `PASSED` means the steps actually passed. -- **`FAILED` vs `BROKEN` are different.** A step whose result does not match +- **Infering test status.** A step whose result does not match the expectation is `FAILED` — a problem with the app under test. An infrastructure error (connection lost, session expired, RPC error) is `BROKEN` — the agent writes the report and calls `exception_tool` to abort, @@ -80,6 +80,7 @@ test. Include: surprise a first-time user. - **State indicators** — what "logged in", "loading", "error" look like visually so the agent can read the screen correctly. +- **Naming conventions** — how specific areas or views are called so that you can refer to these in the tests. - **Common pitfalls and what not to do** — if there is a destructive action that's easy to trigger accidentally, say so explicitly. @@ -88,9 +89,9 @@ overlay as a blank page, for example), add a description here. The agent has no built-in knowledge of your app — everything it needs to recognise must be written down. -### 4 · Report format — make output predictable +### 4 · Report format — tailor reports to your needs -`report_format.md` tells the agent how to structure its output. Be explicit: +`report_format.md` tells the agent how to structure its reports. Be explicit: Markdown or JSON, required sections, and the status vocabulary. Using the standard AskUI status vocabulary (`PASSED`, `FAILED`, `SKIPPED`, `WARN`, `BROKEN`) ensures run reports are readable by AskUI Desktop's report viewer. From 7a41b1e6533743441ca469cfb45fa0f75433ade0 Mon Sep 17 00:00:00 2001 From: philipph-askui Date: Fri, 10 Jul 2026 12:54:12 +0200 Subject: [PATCH 7/7] docs: promote Troubleshooting to top-level section with subpages - Create content/docs/troubleshooting/ with index + 8 subpages: connection-sessions, agent-behavior, performance-cost, agentos-service, proxy-ssl, run-failures, model-providers, licensing - Add troubleshooting to top-level meta.json nav - Remove troubleshooting from support/meta.json and delete the old support/troubleshooting.mdx - Update all inbound links across faq/, support/, agentos/, reference/ Co-Authored-By: Claude Sonnet 4.6 --- content/docs/agentos/installation/service.mdx | 4 +- content/docs/faq/index.mdx | 2 +- content/docs/faq/runs-reports-cost.mdx | 2 +- content/docs/faq/technical.mdx | 4 +- content/docs/meta.json | 2 +- .../docs/reference/environment-variables.mdx | 2 +- .../docs/reference/network-requirements.mdx | 2 +- content/docs/support/get-help.mdx | 4 +- content/docs/support/index.mdx | 2 +- content/docs/support/meta.json | 2 +- content/docs/support/troubleshooting.mdx | 303 ------------------ .../docs/troubleshooting/agent-behavior.mdx | 49 +++ .../docs/troubleshooting/agentos-service.mdx | 69 ++++ .../troubleshooting/connection-sessions.mdx | 56 ++++ content/docs/troubleshooting/index.mdx | 50 +++ content/docs/troubleshooting/licensing.mdx | 28 ++ content/docs/troubleshooting/meta.json | 1 + .../docs/troubleshooting/model-providers.mdx | 85 +++++ .../docs/troubleshooting/performance-cost.mdx | 31 ++ content/docs/troubleshooting/proxy-ssl.mdx | 60 ++++ content/docs/troubleshooting/run-failures.mdx | 32 ++ 21 files changed, 474 insertions(+), 316 deletions(-) delete mode 100644 content/docs/support/troubleshooting.mdx create mode 100644 content/docs/troubleshooting/agent-behavior.mdx create mode 100644 content/docs/troubleshooting/agentos-service.mdx create mode 100644 content/docs/troubleshooting/connection-sessions.mdx create mode 100644 content/docs/troubleshooting/index.mdx create mode 100644 content/docs/troubleshooting/licensing.mdx create mode 100644 content/docs/troubleshooting/meta.json create mode 100644 content/docs/troubleshooting/model-providers.mdx create mode 100644 content/docs/troubleshooting/performance-cost.mdx create mode 100644 content/docs/troubleshooting/proxy-ssl.mdx create mode 100644 content/docs/troubleshooting/run-failures.mdx diff --git a/content/docs/agentos/installation/service.mdx b/content/docs/agentos/installation/service.mdx index 8cd3452..19939ca 100644 --- a/content/docs/agentos/installation/service.mdx +++ b/content/docs/agentos/installation/service.mdx @@ -13,7 +13,7 @@ AgentOS is proprietary software, **free for non-commercial use**. For commercial - **Administrator rights** -To automate the login/lock screen (Secure Attention Sequence), a Group Policy setting must be enabled. See [Troubleshooting](/docs/support/troubleshooting#agent-cant-press-ctrlaltdel) for details. +To automate the login/lock screen (Secure Attention Sequence), a Group Policy setting must be enabled. See [Troubleshooting](/docs/troubleshooting/agentos-service#agent-cant-press-ctrlaltdel) for details. ## Installation @@ -40,7 +40,7 @@ The installer includes a **Service Configuration** screen: - **Connection Scope:** Use **Public (0.0.0.0)** if AgentOS needs to be reachable from another machine (e.g. a remote CI runner). Keep **Private (127.0.0.1)** for local use only. - **Log Level:** `Info` for production, `Debug` for troubleshooting. -- **Allow CTRL+ALT+DEL:** Enable to automate the Windows lock/login screen (requires Group Policy — see [Troubleshooting](/docs/support/troubleshooting#agent-cant-press-ctrlaltdel)). +- **Allow CTRL+ALT+DEL:** Enable to automate the Windows lock/login screen (requires Group Policy — see [Troubleshooting](/docs/troubleshooting/agentos-service#agent-cant-press-ctrlaltdel)). - **Allow control of administrative applications:** Enable only if you need to automate apps running as administrator. Click **Next**, then **Install**. diff --git a/content/docs/faq/index.mdx b/content/docs/faq/index.mdx index aa270d7..d7532e5 100644 --- a/content/docs/faq/index.mdx +++ b/content/docs/faq/index.mdx @@ -28,5 +28,5 @@ description: Frequently asked questions about AskUI — capabilities, runs, bill --- Experiencing a specific error or unexpected behavior? See -[Troubleshooting](/docs/support/troubleshooting) for step-by-step fixes, or +[Troubleshooting](/docs/troubleshooting) for step-by-step fixes, or [Get help](/docs/support/get-help) to contact the team. diff --git a/content/docs/faq/runs-reports-cost.mdx b/content/docs/faq/runs-reports-cost.mdx index 2e46a64..9550b80 100644 --- a/content/docs/faq/runs-reports-cost.mdx +++ b/content/docs/faq/runs-reports-cost.mdx @@ -12,7 +12,7 @@ description: Understanding run statuses and caching behavior. - **`BROKEN`** — the run could not complete a step due to an infrastructure or environment issue: AgentOS unreachable, step limit reached, model error, or network timeout. Investigate the environment, not the app. Check the - [Troubleshooting guide](/docs/support/troubleshooting) first. + [Troubleshooting guide](/docs/troubleshooting) first. - **`WARN`** — the step completed but something unexpected was noted. The run continues. diff --git a/content/docs/faq/technical.mdx b/content/docs/faq/technical.mdx index 50e5201..cae89d3 100644 --- a/content/docs/faq/technical.mdx +++ b/content/docs/faq/technical.mdx @@ -25,7 +25,7 @@ see [CI/CD integration](/docs/agentos/deployment/ci). Yes. Set the standard `HTTP_PROXY` / `HTTPS_PROXY` environment variables before running. For deep-packet-inspection proxies (e.g. Zscaler), see -[Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). +[Proxy and SSL troubleshooting](/docs/troubleshooting/proxy-ssl). For the list of domains to allowlist, see [Network requirements](/docs/reference/network-requirements). @@ -39,7 +39,7 @@ Key notes for IT: - Both IPv4 and IPv6 are supported; no non-standard ports are required. - If the network uses deep-packet inspection (e.g. Zscaler), the AskUI certificate chain must be trusted — see - [Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). + [Proxy and SSL troubleshooting](/docs/troubleshooting/proxy-ssl). - Contact [support@askui.com](mailto:support@askui.com) to request a one-pager formatted for IT firewall review. diff --git a/content/docs/meta.json b/content/docs/meta.json index 4244df7..0a5490a 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1 +1 @@ -{ "pages": ["index", "quickstart", "get-started", "using-askui-desktop", "agentos", "guides", "account-billing", "reference", "faq", "support", "legacy"] } +{ "pages": ["index", "quickstart", "get-started", "using-askui-desktop", "agentos", "guides", "account-billing", "reference", "faq", "troubleshooting", "support", "legacy"] } diff --git a/content/docs/reference/environment-variables.mdx b/content/docs/reference/environment-variables.mdx index cef23af..c286422 100644 --- a/content/docs/reference/environment-variables.mdx +++ b/content/docs/reference/environment-variables.mdx @@ -29,4 +29,4 @@ description: All environment variables recognised by AskUI Desktop, the CLI, and | Variable | Default | Description | |----------|---------|-------------| -| `ASKUI_HTTP_SSL_VERIFICATION` | `true` | Set to `false` to disable SSL certificate verification. Use only as a last resort in environments with deep-packet-inspection proxies. See [Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). | +| `ASKUI_HTTP_SSL_VERIFICATION` | `true` | Set to `false` to disable SSL certificate verification. Use only as a last resort in environments with deep-packet-inspection proxies. See [Proxy and SSL troubleshooting](/docs/troubleshooting/proxy-ssl). | diff --git a/content/docs/reference/network-requirements.mdx b/content/docs/reference/network-requirements.mdx index 557c443..98b4efd 100644 --- a/content/docs/reference/network-requirements.mdx +++ b/content/docs/reference/network-requirements.mdx @@ -42,7 +42,7 @@ $env:NO_PROXY="localhost,127.0.0.1" For deep-packet-inspection proxies (e.g. Zscaler) that inject custom SSL certificates, see -[Proxy and SSL troubleshooting](/docs/support/troubleshooting#proxy-and-ssl). +[Proxy and SSL troubleshooting](/docs/troubleshooting/proxy-ssl). ## Air-gapped and on-premise deployments diff --git a/content/docs/support/get-help.mdx b/content/docs/support/get-help.mdx index f3f743c..ac16d1a 100644 --- a/content/docs/support/get-help.mdx +++ b/content/docs/support/get-help.mdx @@ -16,7 +16,7 @@ directly at the problem. See [Reading a run report](/docs/using-askui-desktop/ru **Check the troubleshooting guide.** The most common AgentOS and connectivity -issues are documented in [Troubleshooting](/docs/support/troubleshooting). +issues are documented in [Troubleshooting](/docs/troubleshooting). @@ -41,7 +41,7 @@ A good bug report gets you a faster answer. Include: - **Actual behavior** — what actually happens, including any error messages - **The run report** — the `.md` file or a screenshot of the failing step - **AgentOS logs** (for AgentOS issues) — see - [Logs](/docs/support/troubleshooting#logs) + [Logs](/docs/troubleshooting#logs) ## Contact channels diff --git a/content/docs/support/index.mdx b/content/docs/support/index.mdx index 3d33ab6..ee25b42 100644 --- a/content/docs/support/index.mdx +++ b/content/docs/support/index.mdx @@ -12,7 +12,7 @@ description: Get help with AskUI — troubleshooting, FAQs, community, and conta How to report bugs, what to include, and where to reach the team and community. - + Step-by-step fixes for common AgentOS and connectivity issues. diff --git a/content/docs/support/meta.json b/content/docs/support/meta.json index 509495b..fd1c4d0 100644 --- a/content/docs/support/meta.json +++ b/content/docs/support/meta.json @@ -1 +1 @@ -{ "title": "Support", "pages": ["index", "troubleshooting", "get-help"] } +{ "title": "Support", "pages": ["index", "get-help"] } diff --git a/content/docs/support/troubleshooting.mdx b/content/docs/support/troubleshooting.mdx deleted file mode 100644 index bf4f335..0000000 --- a/content/docs/support/troubleshooting.mdx +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: Troubleshooting -description: Diagnose and fix common issues with AskUI Desktop, AgentOS, and runs. ---- - -## Logs - -The AskUI Core Service and the Remote Device Controller write to two separate locations. For troubleshooting, collect logs from **both**: - -**Remote Device Controller** (runs in the interactive user session): - -``` -%userprofile%\.askui\Logs -``` - -**AskUI Core Service** (runs as SYSTEM): - -``` -C:\Windows\System32\config\systemprofile\.askui\logs -``` - ---- - -## Connection & session issues - -### Connection error or session mismatch at run start - -Connection errors and session mismatches happen when AgentOS and Desktop have -lost sync — most often after a machine restart or sleep cycle. - -**Correct restart order for multi-machine setups:** -1. Restart AgentOS on the target machine(s) first. -2. Then reconnect from AskUI Desktop. - -If the error persists, use the **Restart** button on the Devices page in the -Desktop sidebar to force a clean session reset. If the problem recurs after -restarts, check whether the target machine received a new IP address from DHCP -— see the entry below. - -### Tests won't start after a reboot or power outage - -Work through this checklist: - -1. **Verify all services are running.** Open the Devices page in AskUI Desktop - and confirm every connected machine shows a green status. -2. **Check for IP address changes.** DHCP can reassign addresses after a - restart, breaking a stored connection. Use hostnames instead of static - IPs wherever possible. -3. **Look for stale configuration.** Old connection settings in your project - or workspace config may point to a previous address. Update or remove them - and re-add the device. - -### Run stops when RDP session is disconnected or screen is locked - -- **Remote Desktop (Windows) — session disconnect:** Disconnecting an RDP - session suspends the virtual display. AgentOS in Host Mode loses its view of - the screen and the run ends. Either keep the RDP session connected and the - window visible during the run, or run AgentOS as a **system service** so it - operates independently of the interactive session — see - [Running as a service](/docs/agentos/installation/service). -- **Remote Desktop (Windows) — window minimized:** Minimizing the RDP client - window (`mstsc`) simulates a display disconnect on the remote machine. The - Remote Device Controller loses access to the display and may return empty - screenshots or shut down. To prevent this, set a registry value on the - machine running the RDP client: - - Open `regedit`, navigate to - `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client`, and create a - `DWORD` value named `RemoteDesktop_SuppressWhenMinimized` with data `2`. - -- **Locked screen:** A locked session hides the display on both Windows and - macOS. Either keep the machine unlocked during unattended runs, or use a - virtual display tool that persists across lock events. - -For fully unattended CI scenarios, the recommended setup is AgentOS as an OS -service — see [CI/CD integration](/docs/agentos/deployment/ci). - ---- - -## Agent behavior - -### Agent clicks the wrong element or misses small buttons - -Vague element descriptions are the most common cause. Make descriptions -specific: - -- **Use spatial anchors:** "the button in the bottom-right corner, below the - Save dialog" is far more reliable than "the button". -- **Include distinguishing features:** label text, color, icon shape, or - position relative to a unique landmark on the screen. -- **For very small targets:** explicitly instruct the agent to zoom before - acting — for example, "zoom in on the toolbar area, then click the small - red X icon". - -See [Prompting best practices](/docs/guides/prompting-best-practices) -for a full guide on writing reliable element descriptions. - -### Agent misinterprets a screen state - -The agent has no built-in knowledge of your application's UI. Add that -knowledge to `ui_information.md` in your project's `prompts/` folder. -Describe screens the agent commonly confuses — loading overlays, login walls, -modal dialogs, error banners. Example: - -``` -A grey semi-transparent overlay with a spinner in the centre means the page -is loading. Wait for it to disappear completely before taking any action. -``` - -See [Agents and prompts](/docs/using-askui-desktop/agents-and-prompts) for the -full prompt structure. - -### Agent stops in the middle of a long test - -Each run has a step limit that prevents runaway executions. If a test hits -that limit, it ends with status `BROKEN`. - -To avoid this: -- **Extract procedures:** move repeated sequences (e.g. "log in") into - `procedures/` and call them by name from your tests. -- **Split large tests:** break a long end-to-end flow into smaller focused - test cases, each with its own clear goal. - -See [Project structure](/docs/using-askui-desktop/project-structure) for how -procedures and test files are organised. - ---- - -## Performance & cost - -### Run cost increased unexpectedly - -Common drivers: - -| Driver | What to check | -|--------|--------------| -| Stale screenshot cache | Cache holds old, large screenshots re-sent each step. Clear the cache after any UI change. | -| Oversized images or logs | Very large screen captures or log files raise the token count per step. | -| Retry loops | A failing step the agent retries many times multiplies cost. Look for high step counts on single actions in the run report. | - -Open the run report and check the token count per step — the costliest steps -are usually the ones to optimize. For a cross-run view, see the -[Usage dashboard](/docs/account-billing/usage-dashboard). - -### Run got slower or crashed during a very long execution - -Log and trace files grow continuously over a run. Very large files can exhaust -memory or significantly slow the host machine. - -Mitigations: -- Keep test cases short and focused — split a large suite into smaller cases, - each producing its own report. -- Archive or delete old run artifacts from the `reports/` folder in your - project periodically. -- If a run must be long, monitor disk and memory usage on the AgentOS host - and set up log rotation if your OS supports it. - ---- - -## AgentOS service issues (Windows) - -The steps in this section apply to AgentOS running as a **Windows system service**. For standalone mode on macOS or Linux, check the terminal output for errors. - -### Restart the AgentOS service - -Many issues are resolved by restarting the service. To restart it via Task Manager: - -1. Open **Task Manager** (`Ctrl+Shift+Esc`). -2. Switch to the **Services** tab (the puzzle-piece icon). -3. Search for **`AskuiCoreService`**. -4. Right-click the entry and choose **Restart**. - -### Agent can't press CTRL+ALT+DEL - -The login/lock screen cannot be automated unless the local security policy allows services to simulate a Secure Attention Sequence (SAS). To enable it: - -1. Open the **Group Policy Editor** (`gpedit.msc`). -2. Navigate to **Computer Configuration → Administrative Templates → Windows Components → Windows Logon Options**. -3. Set **Disable or enable software Secure Attention Sequence** to **Enabled**. - -Also verify that `SERVICE_ENABLE_SAS` is set to `1` (default) in the [Silent installer parameters](/docs/agentos/installation/silent/#parameters). - - -The service includes a `windows.forceSas` option that overrides group policies. This is **not recommended** as it may trigger system integrity checks. Configure the GPE policy instead. - - -### Agent can't interact with apps running as Administrator - -Windows prevents non-elevated processes from sending input to elevated (Run as Administrator) applications. If your agent can't click or type into an app running as Administrator, you need to start the Remote Device Controller in elevated mode. - -To enable elevated mode: - -- **Service Installer (GUI)**: Open **Windows Add/Remove Programs**, find AskUI AgentOS, click **Modify**, and enable the elevated execution engine option. Alternatively, reinstall AgentOS with the option enabled. -- **Silent Installer**: Set `SERVICE_EXECUTION_ENGINE_ELEVATED` to `1` — see [Silent installer parameters](/docs/agentos/installation/silent/#parameters). - - -Running the execution engine elevated grants it higher privileges. Only enable this when you need to automate applications that run as Administrator. - - -### `ipv4:127.0.0.1:23000 unavailable` in Standalone mode - -If the client fails to connect with an error like `ipv4:127.0.0.1:23000 unavailable` while running in **Standalone** runtime mode, autostart of the local AgentOS instance is likely disabled. - -Check the `ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART` environment variable — if it is set to `false`, the client will not start AgentOS automatically and there is nothing listening on port `23000`. Either unset the variable or set it to `true`: - - - - ```powershell - $env:ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART="true" - ``` - - - ```bash - export ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART=true - ``` - - - -This variable is intentionally set to `false` when connecting to a remote AgentOS instance — see [Remote Windows VM](/docs/agentos/deployment/ci/#remote-windows-vm). - -### Need to reinstall or remove - - -**Do not** stop or remove the service from Windows Services manually. Always **uninstall the full AskUI AgentOS application** via Windows Add/Remove Programs. This ensures proper cleanup so the client falls back to standalone mode. - - ---- - -## Proxy and SSL - -### Configure a proxy - -AskUI Desktop and the CLI respect the standard proxy environment variables. -Set them before launching: - - - - ```powershell - $env:HTTP_PROXY="http://proxy.example.com:8080" - $env:HTTPS_PROXY="http://proxy.example.com:8080" - $env:NO_PROXY="localhost,127.0.0.1" - ``` - - - ```bash - export HTTP_PROXY="http://proxy.example.com:8080" - export HTTPS_PROXY="http://proxy.example.com:8080" - export NO_PROXY="localhost,127.0.0.1" - ``` - - - -### Deep-packet-inspection proxies (Zscaler and similar) - -Some corporate proxies intercept HTTPS traffic and inject a custom root -certificate. This can cause SSL errors like: - -``` -SSL: CERTIFICATE_VERIFY_FAILED -``` - -**Solution:** Disable SSL verification as a temporary workaround while you -get the proxy certificate added to your system trust store: - - - - ```powershell - $env:ASKUI_HTTP_SSL_VERIFICATION="false" - ``` - - - ```bash - export ASKUI_HTTP_SSL_VERIFICATION=false - ``` - - - - -Disabling SSL verification reduces security. Re-enable it once your proxy -certificate is trusted by the OS certificate store. - - -The permanent fix is to add your proxy's root certificate to the system -certificate store. Contact your IT/network team for the certificate file and -import instructions for your OS. - ---- - -## Debugging run failures - -The fastest way to debug a failing run: - -1. Open the run report (`.md` file in your project's `reports/` folder or - inline in AskUI Desktop). -2. Find the first step with status `FAILED` or `BROKEN` — that is where to - focus. -3. Check the screenshot for that step. `FAILED` means the expected outcome - didn't match; `BROKEN` means an infrastructure problem (connection lost, - session expired) stopped the run. -4. For AgentOS issues, check the [logs](#logs) for more detail. - -If you cannot resolve the issue yourself, see [Get help](/docs/support/get-help) -for how to generate a diagnostic report and contact support. diff --git a/content/docs/troubleshooting/agent-behavior.mdx b/content/docs/troubleshooting/agent-behavior.mdx new file mode 100644 index 0000000..8265db6 --- /dev/null +++ b/content/docs/troubleshooting/agent-behavior.mdx @@ -0,0 +1,49 @@ +--- +title: Agent behavior +description: Fix wrong clicks, screen misinterpretation, and runs stopping mid-test. +--- + +### Agent clicks the wrong element or misses small buttons + +Vague element descriptions are the most common cause. Make descriptions +specific: + +- **Use spatial anchors:** "the button in the bottom-right corner, below the + Save dialog" is far more reliable than "the button". +- **Include distinguishing features:** label text, color, icon shape, or + position relative to a unique landmark on the screen. +- **For very small targets:** explicitly instruct the agent to zoom before + acting — for example, "zoom in on the toolbar area, then click the small + red X icon". + +See [Prompting best practices](/docs/guides/prompting-best-practices) +for a full guide on writing reliable element descriptions. + +### Agent misinterprets a screen state + +The agent has no built-in knowledge of your application's UI. Add that +knowledge to `ui_information.md` in your project's `prompts/` folder. +Describe screens the agent commonly confuses — loading overlays, login walls, +modal dialogs, error banners. Example: + +``` +A grey semi-transparent overlay with a spinner in the centre means the page +is loading. Wait for it to disappear completely before taking any action. +``` + +See [Agents and prompts](/docs/using-askui-desktop/agents-and-prompts) for the +full prompt structure. + +### Agent stops in the middle of a long test + +Each run has a step limit that prevents runaway executions. If a test hits +that limit, it ends with status `BROKEN`. + +To avoid this: +- **Extract procedures:** move repeated sequences (e.g. "log in") into + `procedures/` and call them by name from your tests. +- **Split large tests:** break a long end-to-end flow into smaller focused + test cases, each with its own clear goal. + +See [Project structure](/docs/using-askui-desktop/project-structure) for how +procedures and test files are organised. diff --git a/content/docs/troubleshooting/agentos-service.mdx b/content/docs/troubleshooting/agentos-service.mdx new file mode 100644 index 0000000..a1a73ff --- /dev/null +++ b/content/docs/troubleshooting/agentos-service.mdx @@ -0,0 +1,69 @@ +--- +title: AgentOS service issues (Windows) +description: Restart the service, fix CTRL+ALT+DEL, elevated apps, and port errors on Windows. +--- + +The steps on this page apply to AgentOS running as a **Windows system service**. For standalone mode on macOS or Linux, check the terminal output for errors. + +### Restart the AgentOS service + +Many issues are resolved by restarting the service. To restart it via Task Manager: + +1. Open **Task Manager** (`Ctrl+Shift+Esc`). +2. Switch to the **Services** tab (the puzzle-piece icon). +3. Search for **`AskuiCoreService`**. +4. Right-click the entry and choose **Restart**. + +### Agent can't press CTRL+ALT+DEL + +The login/lock screen cannot be automated unless the local security policy allows services to simulate a Secure Attention Sequence (SAS). To enable it: + +1. Open the **Group Policy Editor** (`gpedit.msc`). +2. Navigate to **Computer Configuration → Administrative Templates → Windows Components → Windows Logon Options**. +3. Set **Disable or enable software Secure Attention Sequence** to **Enabled**. + +Also verify that `SERVICE_ENABLE_SAS` is set to `1` (default) in the [Silent installer parameters](/docs/agentos/installation/silent/#parameters). + + +The service includes a `windows.forceSas` option that overrides group policies. This is **not recommended** as it may trigger system integrity checks. Configure the GPE policy instead. + + +### Agent can't interact with apps running as Administrator + +Windows prevents non-elevated processes from sending input to elevated (Run as Administrator) applications. If your agent can't click or type into an app running as Administrator, you need to start the Remote Device Controller in elevated mode. + +To enable elevated mode: + +- **Service Installer (GUI)**: Open **Windows Add/Remove Programs**, find AskUI AgentOS, click **Modify**, and enable the elevated execution engine option. Alternatively, reinstall AgentOS with the option enabled. +- **Silent Installer**: Set `SERVICE_EXECUTION_ENGINE_ELEVATED` to `1` — see [Silent installer parameters](/docs/agentos/installation/silent/#parameters). + + +Running the execution engine elevated grants it higher privileges. Only enable this when you need to automate applications that run as Administrator. + + +### `ipv4:127.0.0.1:23000 unavailable` in Standalone mode + +If the client fails to connect with an error like `ipv4:127.0.0.1:23000 unavailable` while running in **Standalone** runtime mode, autostart of the local AgentOS instance is likely disabled. + +Check the `ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART` environment variable — if it is set to `false`, the client will not start AgentOS automatically and there is nothing listening on port `23000`. Either unset the variable or set it to `true`: + + + + ```powershell + $env:ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART="true" + ``` + + + ```bash + export ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART=true + ``` + + + +This variable is intentionally set to `false` when connecting to a remote AgentOS instance — see [Remote Windows VM](/docs/agentos/deployment/ci/#remote-windows-vm). + +### Need to reinstall or remove + + +**Do not** stop or remove the service from Windows Services manually. Always **uninstall the full AskUI AgentOS application** via Windows Add/Remove Programs. This ensures proper cleanup so the client falls back to standalone mode. + diff --git a/content/docs/troubleshooting/connection-sessions.mdx b/content/docs/troubleshooting/connection-sessions.mdx new file mode 100644 index 0000000..4a52146 --- /dev/null +++ b/content/docs/troubleshooting/connection-sessions.mdx @@ -0,0 +1,56 @@ +--- +title: Connection & sessions +description: Fix session mismatches, post-reboot failures, and RDP or locked-screen issues. +--- + +### Connection error or session mismatch at run start + +Connection errors and session mismatches happen when AgentOS and Desktop have +lost sync — most often after a machine restart or sleep cycle. + +**Correct restart order for multi-machine setups:** +1. Restart AgentOS on the target machine(s) first. +2. Then reconnect from AskUI Desktop. + +If the error persists, use the **Restart** button on the Devices page in the +Desktop sidebar to force a clean session reset. If the problem recurs after +restarts, check whether the target machine received a new IP address from DHCP +— see the entry below. + +### Tests won't start after a reboot or power outage + +Work through this checklist: + +1. **Verify all services are running.** Open the Devices page in AskUI Desktop + and confirm every connected machine shows a green status. +2. **Check for IP address changes.** DHCP can reassign addresses after a + restart, breaking a stored connection. Use hostnames instead of static + IPs wherever possible. +3. **Look for stale configuration.** Old connection settings in your project + or workspace config may point to a previous address. Update or remove them + and re-add the device. + +### Run stops when RDP session is disconnected or screen is locked + +- **Remote Desktop (Windows) — session disconnect:** Disconnecting an RDP + session suspends the virtual display. AgentOS in Host Mode loses its view of + the screen and the run ends. Either keep the RDP session connected and the + window visible during the run, or run AgentOS as a **system service** so it + operates independently of the interactive session — see + [Running as a service](/docs/agentos/installation/service). +- **Remote Desktop (Windows) — window minimized:** Minimizing the RDP client + window (`mstsc`) simulates a display disconnect on the remote machine. The + Remote Device Controller loses access to the display and may return empty + screenshots or shut down. To prevent this, set a registry value on the + machine running the RDP client: + + Open `regedit`, navigate to + `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client`, and create a + `DWORD` value named `RemoteDesktop_SuppressWhenMinimized` with data `2`. + +- **Locked screen:** A locked session hides the display on both Windows and + macOS. Either keep the machine unlocked during unattended runs, or use a + virtual display tool that persists across lock events. + +For fully unattended CI scenarios, the recommended setup is AgentOS as an OS +service — see [CI/CD integration](/docs/agentos/deployment/ci). diff --git a/content/docs/troubleshooting/index.mdx b/content/docs/troubleshooting/index.mdx new file mode 100644 index 0000000..1c0de15 --- /dev/null +++ b/content/docs/troubleshooting/index.mdx @@ -0,0 +1,50 @@ +--- +title: Troubleshooting +description: Step-by-step fixes for common AskUI issues — connection, agent behavior, performance, model providers, and more. +--- + + + + Session mismatches, post-reboot failures, RDP and locked-screen issues. + + + Wrong clicks, screen misinterpretation, and runs stopping mid-test. + + + Unexpected cost increases and slow or crashing long runs. + + + Restarting the service, CTRL+ALT+DEL, elevated apps, and port errors. + + + Configuring a proxy and fixing SSL errors from deep-packet-inspection. + + + Debugging FAILED and BROKEN statuses, and runs that produce no results. + + + 429, 401, 403, 404, connection refused, and vision-model errors for BYOM. + + + Invalid or expired license keys. + + + +--- + +## Logs + +The AskUI Core Service and the Remote Device Controller write to two separate +locations. For most issues, collect logs from **both**: + +**Remote Device Controller** (runs in the interactive user session): + +``` +%userprofile%\.askui\Logs +``` + +**AskUI Core Service** (runs as SYSTEM): + +``` +C:\Windows\System32\config\systemprofile\.askui\logs +``` diff --git a/content/docs/troubleshooting/licensing.mdx b/content/docs/troubleshooting/licensing.mdx new file mode 100644 index 0000000..ce2b5dc --- /dev/null +++ b/content/docs/troubleshooting/licensing.mdx @@ -0,0 +1,28 @@ +--- +title: Licensing errors +description: Fix invalid or expired license key errors. +--- + +### "License key invalid" or "License not found" + +**What it means:** The license key you entered isn't recognised. + +**What to do:** +1. Double-check that you copied the full key — it's easy to miss characters at + the start or end. +2. Make sure you're using the key for the right workspace. A key issued for one + workspace won't work for another. +3. If the key came from a colleague, ask them to re-share it directly from + [hub.askui.com](https://hub.askui.com). +4. If none of the above helps, contact [support@askui.com](mailto:support@askui.com) + with the first and last four characters of the key so we can look it up. + +### "License expired" + +**What it means:** Your subscription or trial period has ended. + +**What to do:** +1. Log in to [hub.askui.com](https://hub.askui.com) to check your subscription + status. +2. To renew or upgrade, contact [sales@askui.com](mailto:sales@askui.com) or + use the renewal link in your original purchase email. diff --git a/content/docs/troubleshooting/meta.json b/content/docs/troubleshooting/meta.json new file mode 100644 index 0000000..f093eb9 --- /dev/null +++ b/content/docs/troubleshooting/meta.json @@ -0,0 +1 @@ +{ "title": "Troubleshooting", "pages": ["index", "connection-sessions", "agent-behavior", "performance-cost", "agentos-service", "proxy-ssl", "run-failures", "model-providers", "licensing"] } diff --git a/content/docs/troubleshooting/model-providers.mdx b/content/docs/troubleshooting/model-providers.mdx new file mode 100644 index 0000000..afc6c79 --- /dev/null +++ b/content/docs/troubleshooting/model-providers.mdx @@ -0,0 +1,85 @@ +--- +title: Model provider errors +description: Fix 429, 401, 403, 404, connection refused, and vision-model errors when using a custom model provider (BYOM). +--- + +These errors appear when AskUI Desktop tests your API credentials on save, or +during a run when the model provider rejects a request. They only apply when +you have configured a [custom model provider](/docs/using-askui-desktop/model-providers). + +### 429 Too Many Requests + +**What it means:** You've sent too many requests to the AI provider in a short +time. Their system is temporarily blocking new requests. + +Each provider (Anthropic, OpenAI, etc.) limits how many requests you can make +per minute. A test suite that runs many tests back-to-back can hit this limit +quickly. + +**What to do:** +1. Wait a few minutes, then try again — the limit resets automatically. +2. Check your quota in your provider's console: + - Anthropic: [console.anthropic.com](https://console.anthropic.com) → Usage + - OpenAI: [platform.openai.com](https://platform.openai.com) → Usage +3. If this happens regularly, upgrade to a higher usage tier with your provider. +4. Alternatively, switch back to the **AskUI hub** (Settings → Model Provider → + Remove key) — the hub handles rate limits automatically. + +### 401 Unauthorized + +**What it means:** The API key you entered is wrong, was typed incorrectly, or +has been revoked. + +**What to do:** +1. Go to **Settings → Model Provider** and check the key you entered. +2. Generate a fresh key in your provider's console and paste it in — don't type + it by hand. +3. Make sure you copied the full key. Keys are long strings and it's easy to + miss characters at the start or end. + +### 403 Forbidden + +**What it means:** Your API key is valid, but your account doesn't have +permission to use this model or feature. Some models (e.g. Claude Opus, GPT-4o) +require a paid plan or explicit access request. + +**What to do:** +1. Log in to your provider's console and check whether your plan includes API + access to the model you selected. +2. Try a different model that's included in your current plan, or switch back to + the AskUI hub. + +### 404 Not Found / Model not found + +**What it means:** The model ID you entered doesn't exist, or was typed +incorrectly. Model IDs are case-sensitive and must match exactly. + +**What to do:** +1. Go to **Settings → Model Provider** and check the **Model** field. +2. Copy the exact model ID from your provider's documentation: + - Anthropic: [docs.anthropic.com/models](https://docs.anthropic.com/en/docs/about-claude/models/overview) + - OpenAI: [platform.openai.com/docs/models](https://platform.openai.com/docs/models) + +### Connection refused / Could not connect to server + +**What it means:** AskUI Desktop tried to reach your model's endpoint but got +no response. Either the address is wrong or the server isn't running. + +Most common with self-hosted models (vLLM, Ollama, llama.cpp). + +**What to do:** +1. Make sure your local model server is running before starting a run. +2. Check the **Base URL** in **Settings → Model Provider** — it should look like + `http://localhost:8000/v1`. Confirm the port matches what your server uses. +3. If connecting to a remote server, check that it's reachable on your network + and no firewall is blocking the port. + +### The agent can't see the screen (text-only model) + +**What it means:** The model you configured is text-only. It can't process +screenshots, so the agent can't see the UI it's supposed to test. + +**What to do:** Switch to a **vision-capable** model: +- Anthropic: any Claude 3 or later model +- OpenAI: `gpt-4o`, `gpt-4-turbo` +- Self-hosted: Qwen-VL, LLaVA, InternVL, or similar vision models diff --git a/content/docs/troubleshooting/performance-cost.mdx b/content/docs/troubleshooting/performance-cost.mdx new file mode 100644 index 0000000..41b9b87 --- /dev/null +++ b/content/docs/troubleshooting/performance-cost.mdx @@ -0,0 +1,31 @@ +--- +title: Performance & cost +description: Diagnose unexpected cost increases and slow or crashing long runs. +--- + +### Run cost increased unexpectedly + +Common drivers: + +| Driver | What to check | +|--------|--------------| +| Stale screenshot cache | Cache holds old, large screenshots re-sent each step. Clear the cache after any UI change. | +| Oversized images or logs | Very large screen captures or log files raise the token count per step. | +| Retry loops | A failing step the agent retries many times multiplies cost. Look for high step counts on single actions in the run report. | + +Open the run report and check the token count per step — the costliest steps +are usually the ones to optimize. For a cross-run view, see the +[Usage dashboard](/docs/account-billing/usage-dashboard). + +### Run got slower or crashed during a very long execution + +Log and trace files grow continuously over a run. Very large files can exhaust +memory or significantly slow the host machine. + +Mitigations: +- Keep test cases short and focused — split a large suite into smaller cases, + each producing its own report. +- Archive or delete old run artifacts from the `reports/` folder in your + project periodically. +- If a run must be long, monitor disk and memory usage on the AgentOS host + and set up log rotation if your OS supports it. diff --git a/content/docs/troubleshooting/proxy-ssl.mdx b/content/docs/troubleshooting/proxy-ssl.mdx new file mode 100644 index 0000000..e532a88 --- /dev/null +++ b/content/docs/troubleshooting/proxy-ssl.mdx @@ -0,0 +1,60 @@ +--- +title: Proxy & SSL +description: Configure a proxy and fix SSL certificate errors from deep-packet-inspection proxies. +--- + +### Configure a proxy + +AskUI Desktop and the CLI respect the standard proxy environment variables. +Set them before launching: + + + + ```powershell + $env:HTTP_PROXY="http://proxy.example.com:8080" + $env:HTTPS_PROXY="http://proxy.example.com:8080" + $env:NO_PROXY="localhost,127.0.0.1" + ``` + + + ```bash + export HTTP_PROXY="http://proxy.example.com:8080" + export HTTPS_PROXY="http://proxy.example.com:8080" + export NO_PROXY="localhost,127.0.0.1" + ``` + + + +### Deep-packet-inspection proxies (Zscaler and similar) + +Some corporate proxies intercept HTTPS traffic and inject a custom root +certificate. This can cause SSL errors like: + +``` +SSL: CERTIFICATE_VERIFY_FAILED +``` + +**Solution:** Disable SSL verification as a temporary workaround while you +get the proxy certificate added to your system trust store: + + + + ```powershell + $env:ASKUI_HTTP_SSL_VERIFICATION="false" + ``` + + + ```bash + export ASKUI_HTTP_SSL_VERIFICATION=false + ``` + + + + +Disabling SSL verification reduces security. Re-enable it once your proxy +certificate is trusted by the OS certificate store. + + +The permanent fix is to add your proxy's root certificate to the system +certificate store. Contact your IT/network team for the certificate file and +import instructions for your OS. diff --git a/content/docs/troubleshooting/run-failures.mdx b/content/docs/troubleshooting/run-failures.mdx new file mode 100644 index 0000000..b1482a8 --- /dev/null +++ b/content/docs/troubleshooting/run-failures.mdx @@ -0,0 +1,32 @@ +--- +title: Run failures +description: Debug FAILED and BROKEN run statuses, and fix runs that produce no results. +--- + +### Debugging a failing run + +The fastest way to debug a failing run: + +1. Open the run report (the `.md` file in your project's workspace folder, or + inline in AskUI Desktop). +2. Find the first step with status `FAILED` or `BROKEN` — that is where to + focus. +3. Check the screenshot for that step. `FAILED` means the expected outcome + didn't match; `BROKEN` means an infrastructure problem (connection lost, + session expired) stopped the run. +4. For AgentOS issues, check the [logs](/docs/troubleshooting#logs) for more + detail. + +If you cannot resolve the issue yourself, see [Get help](/docs/support/get-help) +for how to generate a diagnostic report and contact support. + +### Run completes with 0 results ("No tests ran") + +The run started but found no test files to execute. + +1. Check that you're running from the correct **Project root** — the folder that + contains `tests/`, `prompts/`, etc. +2. Check that your test files are inside `tests/` and have a supported extension + (`.md`, `.txt`, `.pdf`, `.csv`, `.json`). +3. If you used `--plan`, check that the plan file exists in `plans/` and + references valid test paths.