fsq-agent 0.1.0a1

An evidence-first agent harness for replayable, verifiable AI UI automation.

Quick Start • Why FSQ • Platforms • Documentation • Contributing

Why FSQ?

Other AI agents say "I'm done." FSQ shows you the proof.

See It in Action

┌──────────────────────────────────────────────────────────────────────┐
│ $ cd /path/to/workspaces/web-demo                                   │
│ $ fsq case create --platform web                                    │
│     --goal "Search for FSQ on Bing"                                │
├──────────────────────────────────────────────────────────────────────┤
│  ► Planning: 3 key actions identified                                │
│  ► Step 1: startBrowser          📸 screenshot + UI snapshot         │
│  ► Step 2: navigateTo bing.com   📸 screenshot + UI snapshot         │
│  ► Step 3: typeText "FSQ"        📸 screenshot + UI snapshot         │
│  ► Step 4: pressKey Enter        📸 screenshot + UI snapshot         │
│  ► Verification: PASSED ✅ (evidence-based)                          │
│  ► Recording manifest → .fsq/runs/web/<run-id>/recording.json       │
│  ► Replayable YAML → .fsq/runs/web/<run-id>/recorded.fsq.yaml       │
└──────────────────────────────────────────────────────────────────────┘

What Can FSQ Do?

The Dual Loop: AI explores → evidence proves it worked → strict YAML locks it down → replay catches regressions.

Quick Start

1. Install

pip install fsq-agent

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --extra dev

The default installation includes the Python dependencies for Android, Web, Windows, and macOS. FSQ does not use platform extras. Applications, browsers, devices, and host services such as Appium remain system prerequisites.

2. Initialize a Workspace

mkdir web-demo && cd web-demo
fsq init --platform web --browser-channel chrome

init uses the exact current directory as the Workspace root and derives the Workspace name from that directory. It initializes one platform per invocation. To configure another platform in the same Workspace, run init again from the same directory:

cd /path/to/workspaces/web-demo

# Initialize Web. The executable path is optional when one matching browser is discoverable.
fsq init \
  --platform web \
  --browser-channel chrome

# Add Android to the same registered workspace.
fsq init \
  --platform android \
  --app-id com.example.app

Platform target options are:

Repeating an equal platform configuration returns unchanged. If its target or private environment mapping differs, pass --update-existing to replace only that platform's target and --env NAME=VALUE entries. Use fsq --output json init ... or --output jsonl for machine output. init checks readiness but never installs Driver/Runtime packages or system prerequisites.

Run fsq doctor from the exact Workspace root to inspect configured-platform readiness. Commands do not search parent directories or migrate legacy .fsq/config.yaml and .fsq-agent-workspace layouts.

3. Configure a Provider

Configure and inspect the user-level Provider from any directory:

fsq providers configure github_copilot
fsq providers status

Provider configuration is stored under ~/.fsq and shared with the Control Plane UI. Azure OpenAI can be configured with fsq providers configure azure_openai.

4. Create and Test Cases

cd /path/to/workspaces/web-demo

# AI-driven exploration with evidence and a Run-local candidate Case
fsq case create --platform web \
  --goal "Open https://www.bing.com, search for 'FSQ automation', verify results appear."

# Deterministic execution of an existing Case
fsq case test --platform web path/to/case.fsq.yaml

# Execute once, then ask AI to analyze the persisted execution facts
fsq case test --platform web --suggest path/to/case.fsq.yaml

Every execution writes evidence and reports under .fsq/runs/<platform>/<run-id>/. Suggestions and candidate Cases are Run-local and never overwrite the source Case or cases/<platform>. Inspect history with fsq runs list, fsq runs show RUN_ID, and fsq runs logs RUN_ID. fsq runs show RUN_ID --open builds and opens an offline static HTML report.

Control Plane

Launch the local browser Control Plane for multi-platform workspace management, platform readiness, target and case discovery, Explore runs, Strict Replay, and live evidence:

fsq ui

It listens on 127.0.0.1:8879 and opens a browser by default. Use --host, --port, and --no-open-browser to override those defaults. A wheel installation includes the compiled frontend and needs no Node.js runtime. From a source checkout, run npm ci && npm run build before starting the Control Plane.

Supported Platforms

All platforms share the same HarnessInterface, evidence model, and FSQ YAML format. A registered workspace may configure one or more platforms independently:

<workspace-root>/
  .fsq/config/config.<platform>.yaml
  cases/<platform>/
  knowledge/<platform>/
  .fsq/runs/<platform>/

Workspace commands use the exact current directory as the registered Workspace root. fsq doctor checks all configured platforms; fsq case create/test select a platform; fsq runs queries Workspace history across all platforms unless filtered. fsq ui starts the browser Control Plane and uses its own Workspace selection.

target:
  browser_executable_path: /usr/bin/google-chrome

target:
  app_id: com.example.app

cd /path/to/workspaces/my-workspace
fsq case create --platform android --goal "Open the app"

target:
  app_path: C:\Program Files\MyApp\app.exe
  window_title_re: .*MyApp.*

target:
  bundle_id: com.example.app

How It Works

The Dual Loop in a nutshell:

• Dynamic (AI) → LLM agent explores → evidence captured at every step → replayable YAML generated
• Strict (Replay) → replays YAML deterministically (no LLM) → evidence captured → pass/fail

Compared To...

Documentation

Contributing

We welcome contributions! FSQ is designed to be extended.

git clone https://github.com/microsoft/FSQ.git && cd FSQ
uv sync --extra dev
npm ci && npm run build
uv run python -m pytest

Ways to contribute:

See CONTRIBUTING.md for the full guide and contributor growth path. Project decisions and role progression follow GOVERNANCE.md.

License

MIT — Copyright (c) Microsoft Corporation.

_{Built with ❤️ by the FSQ team at Microsoft}