Skip to content

feat: add AGENT_BROWSER_CDP env var for --cdp flag#489

Open
bukacdan wants to merge 2 commits intovercel-labs:mainfrom
bukacdan:feat/cdp-env-var
Open

feat: add AGENT_BROWSER_CDP env var for --cdp flag#489
bukacdan wants to merge 2 commits intovercel-labs:mainfrom
bukacdan:feat/cdp-env-var

Conversation

@bukacdan
Copy link

Problem

When agent-browser is used programmatically by an AI agent (e.g., inside an agentic loop that drives a
browser), connecting to an existing browser via CDP currently requires one of two approaches:

  1. Pass --cdp on every command -- the agent must remember to include --cdp 9222 (or a WebSocket URL)
    on every single agent-browser invocation throughout its session. In practice, agents can and do forget
    flags between calls, leading to commands silently launching a new browser instead of controlling the intended
    one.

  2. Run agent-browser connect at the start -- this persists the CDP endpoint in the session, but it
    relies on the agent executing the right setup command first and maintaining the same session for every
    subsequent call. If the session is lost or the connect step is skipped, the same silent-failure mode occurs.

Both approaches are fragile in agentic contexts because they depend on the agent's behavioral consistency
across many invocations -- something that is inherently unreliable.

Solution

Add AGENT_BROWSER_CDP environment variable support, following the established AGENT_BROWSER_* convention
already used by --proxy (AGENT_BROWSER_PROXY), --provider (AGENT_BROWSER_PROVIDER), --auto-connect
(AGENT_BROWSER_AUTO_CONNECT), and others.

When AGENT_BROWSER_CDP is set, every agent-browser command automatically uses the specified CDP endpoint
without requiring any flags. The CLI --cdp flag still takes precedence when both are present, preserving
full backward compatibility.

# Set once in the agent's environment
export AGENT_BROWSER_CDP=9222

# Every command connects to the right browser, no flags needed
agent-browser snapshot
agent-browser click @e1
agent-browser fill @e2 "hello"

This makes CDP connections deterministic and reliable regardless of the agent's behavior -- the environment
is set by the orchestrator, and individual commands cannot "forget" it.

Changes

Functional (1 line):
- cli/src/flags.rs -- read AGENT_BROWSER_CDP env var as fallback for the cdp field, identical to the pattern
used by every other env-backed flag

Documentation (4 files):
- cli/src/output.rs -- --help text and environment variable listing
- README.md -- options table and CDP Mode section
- skills/agent-browser/SKILL.md -- AI agent skill reference
- docs/src/app/cdp-mode/page.mdx -- docs site CDP Mode page

Compatibility

- Fully backward compatible; no existing behavior changes
- --cdp flag overrides the env var (CLI args are parsed after env var defaults, matching the existing
pattern)
- Existing conflict checks (--cdp + --extension, --cdp + --auto-connect) work unchanged since they test
flags.cdp.is_some() regardless of source
- All 162 existing tests pass

@vercel
Copy link
Contributor

vercel bot commented Feb 17, 2026

@bukacdan is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

bukacdan and others added 2 commits February 18, 2026 20:04
Read AGENT_BROWSER_CDP env var as a fallback for the --cdp CLI flag,
matching the pattern used by other flags (--proxy, --provider, etc.).
CLI --cdp still takes precedence when both are set.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update --help output, README, SKILL.md, and docs site to mention the
new AGENT_BROWSER_CDP env var alongside the --cdp flag.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bukacdan bukacdan reopened this Feb 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant