ApexDocsOpen Apex
Merchants & developers

Apex Operator and tool-led building

Apex Operator is the model-led experiment builder. It gives the model compact tools for inspecting pages, network traffic, state, selectors, artifacts, QA evidence, and persistence.

Simple terms

Operator is the AI builder. It uses browser, page, code, selector, network, screenshot, filesystem, and persistence tools to help build and QA experiments.

Apex Operator is the model-led experiment builder. It gives the model compact tools for inspecting pages, network traffic, state, selectors, artifacts, QA evidence, and persistence.

Routes

  • /tests/[id]/variations/[varId]
  • Operator logs overlay in the variation editor
  • /api/operator-chat-session
  • /api/operator-events
  • /api/operator-runs
  • /api/operator-evidence
  • /api/operator-network
  • /api/operator-screenshot

Implementation behavior

  • On installed stores, Operator browser tools can use an active on-site editor session to inspect and interact with the real merchant page instead of the proxy iframe.
  • The compact on-store dock can generate and save a treatment from live DOM context. Full tool-led QA, evidence review, and launch gating remain in the dashboard Operator workflow.
  • Operator sessions gather current experiment, variation, page, workspace, and store-profile context.
  • Tools let the model inspect DOM, network, console, page state, selectors, files, screenshots, artifacts, and saved preview state.
  • Operator writes structured changes to variation mutations or code workspaces instead of relying on one-off text suggestions.
  • External handoff now prefers the Apex CLI workflow: install @drip-apex/apex-cli, run apex login, check out canonical workspace files, dogfood with apex workspace dev, then publish with apex workspace publish.
  • The CLI uses the same canonical workspace file model as in-app Operator: src/index.js, src/index.scss, src/info.js, src/mutations.json, experiment.config.json, targeting.json, goals/*.json, segments/*.json, network/*.recipe.json, and dev-doc.md.
  • Logs preserve chat messages, tool calls, evidence, failure states, artifacts, and network details for review.
  • The product principle is general tool affordance first: avoid hardcoding one test type as the only supported workflow.

How to use it

  • Use Operator to inspect a target page, propose a variant, build it, and collect QA evidence.
  • Review every generated change before launch.
  • Open the in-editor logs overlay when a run fails, produces unexpected output, or needs auditability.
  • Give Operator specific constraints, but let it use general tools for page inspection and implementation.
  • For handoff runs, let the external agent inspect the live target URL and relevant storefront/domain context itself; screenshots are useful evidence, not a hard prerequisite.

When not to use it

  • Do not treat Operator output as automatically launch-safe.
  • Do not use it for deterministic one-click workflows that normal forms already handle faster.
  • Do not constrain Operator to one narrow playbook when a general page-inspection tool can solve the task better.

Implementation source

  • Core code lives under src/features/apex-operator.
  • APIs include /api/operator-chat-session, /api/operator-events, /api/operator-runs, /api/operator-evidence, /api/operator-network, and /api/operator-screenshot.
  • The variation editor mounts the Operator UI and uses saved tool results to persist mutations, code workspace changes, artifacts, and evidence.
  • External handoff uses @drip-apex/apex-cli with apex workspace checkout, apex workspace dev, and apex workspace publish against canonical workspace files shared with in-app Operator.

Data and API

  • APIs include /api/operator-chat-session, /api/operator-events, /api/operator-runs, /api/operator-evidence, /api/operator-network, and /api/operator-screenshot.
  • CLI workspace APIs include /api/v1/experiments/[id]/variations/[variationId]/workspace, file read/write routes, build, and revisions.
  • Models include operator sessions, events, artifacts, evidence, review records, and code workspace snapshots.
  • Uses store profile facts, assets, backlog context, experiment setup, and preview browser state.

Failure modes

  • Poor output usually means missing target URL, missing store context, or vague instruction.
  • Tool failure can come from blocked storefront access, auth-required pages, CSP, or preview host mismatch.
  • A disconnected on-site tab falls back to the dashboard preview transport; reopen Edit on store when real-origin verification is required.
  • Never assume generated code is launch-ready without QA and visual inspection.