Choosing Among Desktop, CLI, SDK, and Managed Agents for the Same Job

Antigravity 2.0 has several surfaces: desktop, CLI, SDK, and the Managed Agents API. Which one should run a given task? Here is a framework for choosing the surface from the nature of the work.

Antigravity²⁴² Antigravity 2.0⁴ architecture¹⁵ workflow design²

✦ Premium Article

When Antigravity 2.0 changed from a single editor into a platform with five surfaces, my first hesitation was not about any new feature but about a question: which surface should this job run on? Work it interactively on the desktop, fire it from the CLI, embed it in an app through the SDK, or throw it at the cloud via the Managed Agents API? Even for the same task — "fix a component" — the right surface shifts with the context.

As an indie developer running four sites in parallel, I first tried to do everything on the desktop and ran out of hands. Only once I started choosing the surface by the nature of the work did things settle. Here I lay out that choice as a decision framework.

First, the plain character of the four surfaces

Setting aside the enterprise Cloud path, the four surfaces an indie developer touches each suit a different shape of work.

Surface	Plain character	Best-fit work
Desktop	Interactive; supervise parallel agents by eye	Exploratory building; work that needs judgment
CLI	Non-interactive; embeds in scripts	Routine processing, CI, nightly batch
SDK	Embeds an agent in your own app	Resident processing as a product feature
Managed Agents API	Spins up an isolated environment in one call	Heavy, risky, or to-be-isolated work

The point is that these are about fit, not rank. Desktop is not above and the API below. Apply the nature of the work and the fitting surface falls out on its own.

Measure the work on four axes

When choosing a surface, I measure the work on four axes.

Interactivity

Does a human need to decide mid-flight? If so, desktop. If the steps are fully fixed, you can push it toward the CLI or API. Force-automating work whose direction changes as you go just multiplies redos.

Scheduling

Do you want it to run unattended at a set time? Then put the CLI on cron, or use the SDK's scheduled execution. Desktop assumes a human in front of it, so it does not suit unattended operation.

Isolation

Do you want to contain the blast radius of a failure? Work that handles untrusted input or tries destructive operations goes to the isolated environment of the Managed Agents API. There is no need to run it in your local workspace.

Integration depth

Do you want the processing resident as part of your own product? If you are building a feature where an agent acts on user input, it is the SDK, full stop. The CLI and desktop cannot be built into a product.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦A four-axis frame for choosing a surface: interactivity, scheduling, isolation, integration depth

✦A small router that returns a surface from task attributes, plus minimal CLI and SDK launch examples

✦The cross-surface trap I hit running all four in indie development, and how I now choose

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Turn the decision into code

Once the axes are set, the choice is mechanical to write — a small router that takes the nature of a task and returns a surface.

from dataclasses import dataclass
from enum import Enum
 
class Surface(Enum):
    DESKTOP = "desktop"
    CLI = "cli"
    SDK = "sdk"
    MANAGED = "managed_api"
 
@dataclass
class Task:
    needs_human_judgment: bool   # judgment needed mid-flight?
    scheduled: bool              # run unattended on a clock?
    needs_isolation: bool        # contain failure blast radius?
    embed_in_product: bool       # resident inside the product?
 
def choose_surface(t: Task) -> Surface:
    if t.embed_in_product:
        return Surface.SDK            # integration depth wins first
    if t.needs_isolation:
        return Surface.MANAGED        # risky/heavy work to isolation
    if t.scheduled:
        return Surface.CLI            # unattended clock runs
    if t.needs_human_judgment:
        return Surface.DESKTOP        # talk it through
    return Surface.CLI               # default to the lightweight CLI

The order matters. Integration depth and isolation come first because those two are requirements no other surface can substitute for. Interactivity and scheduling come later and, being mutually exclusive, get sorted last. Reverse this order and you end up accidentally running to-be-isolated work on the desktop.

Minimal CLI and SDK launches

The actual calls are short. The CLI runs in non-interactive mode.

# routine work, non-interactive (from CI or cron)
antigravity run \
  --headless \
  --task "pass lint and type checks; on failure, summarize the diff" \
  --output json > result.json

The SDK launches an agent from your own code.

from antigravity import AgentClient
 
client = AgentClient()
 
def handle_user_request(prompt: str) -> str:
    # launch an agent as a resident product feature
    run = client.start(task=prompt, tools=["read_file", "run_tests"])
    return run.wait().summary

Both are a few lines; as long as you pick the surface correctly, the implementation is light. The hard part is not the code but that first "which surface" call.

The cross-surface trap

Once I ran all four in production, the trap was that state is separated per surface. Try to continue on the CLI a job you carried halfway on the desktop, and the context is not shared, so you start over from scratch.

My workaround is, for any work that will cross surfaces, to write state outside the surface — into repo files or a ticket.

1. Cross-surface work always leaves progress in a file/ticket
2. Build each surface to resume by reading that file
3. Never let state live only inside a surface

With that in place, the hand-off flows: settle the design on the desktop, run the routine parts through the CLI, and finally isolate the heavy tests on the Managed API. Not trapping state inside a surface is, I find, the single biggest knack of running multiple surfaces.

How I choose

Finally, my personal priority order when in doubt.

Question	If yes
A feature resident in the product?	SDK
Heavy work you want to isolate on failure?	Managed Agents API
Run unattended on a clock?	CLI
Judgment needed as you go?	Desktop

Apply top to bottom and take the first surface that turns up "yes." Since making this a habit, the time I spend hesitating over the surface has all but disappeared. I would personally recommend dropping the urge to hold everything on the desktop and splitting surfaces by the nature of the work. I hope it gives you a foothold if Antigravity 2.0's widened set of surfaces feels like more than you can hold.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.