English · 简体中文

ADS Agent Bridge

Give AI agents a safe, local, and version-aware way to understand and operate Keysight ADS.

ADS Agent Bridge is an unofficial, local-first documentation and automation bridge for Keysight Advanced Design System (ADS). It turns the ADS installation already on your machine into a version-aware documentation source, a bounded runtime context, and a safely managed automation target for general-purpose Agents such as Codex or OpenCode.

The Agent may run on the ADS host or execute ads-agent there over SSH. Live bridge endpoints remain bound to loopback on the ADS host; the package does not open ADS directly to the network.

[!IMPORTANT] This project is a public alpha. Use disposable workspaces for first trials and review the reported capability gates before relying on automation results. Keysight and ADS are trademarks of Keysight Technologies. This project is not affiliated with or endorsed by Keysight.

What you can ask your Agent to do

The initial release is deliberately small, but it is not a dummy wrapper. Documentation, no-GUI automation, the installed DE/DDS plug-in, dialog supervision, and session lifecycle are separate, observable capability lanes. See the capability, mechanism, and evidence matrix for the exact support boundary behind every row.

The DE/DDS plug-in is a first-class part of the product

ads-agent setup installs the Bridge package and its recoverable ADS add-on. After ADS restarts, the add-on provides:

• DE schematic, layout, and symbol windows: Copy ADS Context in the right-click menu and under Tools > ADS Context;
• DE Folder/Library tree: Copy ADS Context for supported workspace, folder, library, cell, cellview, and multi-item selections;
• DDS: Copy ADS Context in the right-click menu and a DDS-owned top-level ADS Context menu, including an empty page selection.

DE and DDS use separate entrypoints and callback lifecycles. The copied handle contains bounded target and selection metadata, not a port, token, or mutation permission. The Agent must still resolve freshness and obtain workflow authorization before editing, simulating, opening, or closing anything. See the interaction contract.

From your selection to a checked result

You select the intended object in ADS, copy its bounded Context, and ask in normal engineering language. The Bridge resolves that exact target and reports which observable gates actually passed.

How it works

The package has three main execution lanes:

1. Knowledge: the public ads-kb-docs Skill routes questions through the CLI to the selected installation's private, version-scoped local index, which returns matched content and source evidence.
2. Live ADS: the Session Manager coordinates the packaged ADS Agent Bridge plug-in installed inside DE or DDS. Its loopback, token-authenticated endpoint verifies the exact workspace, process, display, slot, profile, and ownership identity.
3. No-GUI automation: the selected ADS Python runtime creates a disposable example, simulates it, and reads the dataset without opening an ADS window.

On Linux, ADS Python can still require an available X display for runtime initialization. For isolation, keep the real user HOME so ADS can see its per-user state, and isolate Bridge state with ADS_AGENT_HOME.

Evidence and comparison scope

Bridge uses three evidence labels:

• Validated means a maintained gate passed against a real ADS installation.
• Compared means the capability participated in a published, isolated comparison.
• Available (bounded) means the interface exists with an explicit stop rule; it does not claim general unattended correctness.

The public evidence now includes two deliberately narrow comparisons: one for the knowledge lane and one for a minimal no-GUI execution task. Neither compares installation, the DE/DDS plug-in, GUI session control, dialog handling, DDS UI readback, safe shutdown, or the complete product surfaces.

ADS 2027 knowledge-layer benchmark — not a full-product comparison

We ran the same three ADS knowledge tasks three times per arm with the same model, host, prompts, and strict output contract. Global Agent configuration, skills, memories, rules, and shell startup files were masked for every run.

Bridge used 10.4% fewer total tokens and closed all nine tasks, but it was not faster overall: median latency was 5.2% higher, and one geometry run produced a long mean-latency tail. In the Python DRC task, all three official-MCP answers used the unverified create_drc_job route; Bridge reported the verified boundary and safe fallback in all three runs.

This is a small engineering regression suite, not a claim of universal or full-product superiority: earlier pilots on these cases informed Bridge improvements. See the methodology and interpretation boundary and sanitized per-run data.

ADS 2027 headless execution microbenchmark

We also asked each released execution surface to create a disposable ADS 2027 workspace, run a minimal AC simulation without launching a GUI, read the dataset, and return a finite numeric sample. The Bridge arm used its public headless example / quickstart path; the official arm used start_local_session and execute_python. Direct ADS Python or simulator shell bypass was forbidden for both.

For this one task, Bridge used 43.4% fewer total tokens and had 21.5% lower median wall time. Total tokens include cached input; the uncached-input difference was a smaller 9.5%. This is a three-repetition microbenchmark, not a general performance ranking. See the execution methodology, calibration disclosure, and interpretation boundary and sanitized per-run data.

Quick start

Prerequisites:

• a locally licensed ADS installation;
• Python 3.10 or later for the ads-agent command;
• Windows or Linux.

Install and prove the local setup:

pipx install ads-agent-bridge
ads-agent doctor
ads-agent setup
ads-agent quickstart

Installing ads-agent-bridge also installs the small eda-bridge-runtime Python library automatically, so ads-agent runtime serve works without an extra Python package choice. On a separate Agent host, install and enable the Runtime MCP/plugin there as described by the EDA Bridge Runtime; the ADS host does not need the Agent-facing plugin.

setup discovers installed ADS versions instead of hard-coding one release. It also installs two small, mutually routing public Skills: ads-agent-bridge for setup and bounded operation, and ads-kb-docs for documentation lookup. An existing complete ads-kb-docs from the full ADS Agent Kit is preserved. quickstart passes only after documentation indexing and query, add-on registration, disposable workspace creation, circuit simulation, and dataset readback all pass.

Launch a real workspace only after that gate succeeds:

ads-agent --pretty launch --workspace /path/to/MyWorkspace_wrk
ads-agent --pretty status
ads-agent disconnect                 # ADS keeps running
ads-agent shutdown                   # native exit for an agent-owned session

On Linux, bind GUI work to the intended display:

ads-agent --pretty launch --workspace /path/to/MyWorkspace_wrk --display :4

curl -fsSLO https://github.com/cottman99/ads-agent-bridge/releases/download/v0.1.0a37/install.sh
sh install.sh

Invoke-WebRequest https://github.com/cottman99/ads-agent-bridge/releases/download/v0.1.0a37/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

Remote use over SSH

SSH is the recommended current remote boundary. Run the public CLI on the ADS host instead of exposing the embedded Bridge port:

ssh ads-host 'ads-agent doctor'
ssh ads-host 'ads-agent --pretty status'
ssh ads-host 'ads-agent --pretty launch --workspace /path/to/MyWorkspace_wrk --display :4'

This keeps session files, random tokens, process ownership, workspaces, and ADS itself on the same host. For one-off administration these commands remain the smallest route. For repeated Agent operations, use the automatically installed Runtime integration to keep one SSH stdio process alive:

ads-agent runtime serve

The generic Runtime performs the protocol handshake, records purpose and observed timings in its append-only ledger, and avoids starting SSH once per operation. It never exposes the embedded Bridge port or token.

The Runtime Skill, MCP server, and connection registry belong on the Agent host. ads-agent runtime serve, the ADS plug-in, and ADS itself belong on the ADS host. If the Agent and ADS share a machine, register the same service as a local connection rather than bypassing Runtime. Adapter capabilities identify this service as an eda-worker with a synchronous Run model.

When no workspace exists, the ADS Skill establishes the typed workspace.create operation even without a live ADS plug-in session; capability discovery remains available only when the contract is unknown or stale. The operation creates a non-overwriting minimal workspace and returns an opaque rich EDA_CONTEXT; session.launch, session.status, and session.shutdown then provide the bounded GUI lifecycle without putting the remote path in the context token.

For a safe schematic edit, design.apply accepts only an ads.design-plan/v1 object containing registered instance and wire operations. It copies a closed source workspace to staging, applies one ADS database transaction, saves and closes, freshly reopens the copied design, checks exact instance/parameter/netlist assertions, verifies the source Bundle hash is unchanged, and only then atomically commits the output workspace. It rejects raw Python/AEL, unknown fields, stale expected_before state, and overwrite.

For an existing, generated Momentum simulation-input directory, momentum.run_generated provides the same bounded Runtime path to a real S-parameter result. It fingerprints and preserves the source, solves only a new sibling copy with the explicitly selected ADS installation, checks the complete finite N-port CITI matrix, and promotes the output only after all checks pass. A timeout stops the wrapper and its solver process tree. This operation deliberately starts after EM setup/input generation; it does not invent substrate, ports, mesh, or sweep settings for a blank layout.

Safety and privacy

• Documentation, indexes, workspaces, session tokens, and automation results remain local unless the user deliberately moves them.
• Bridge endpoints listen on loopback and use a random token per session.
• Reusing a session requires the selected ADS instance and exact workspace to match; the Bridge does not silently switch workspaces.
• Context handles identify a target but do not authorize editing or simulation.
• Structured design.apply plans modify only a non-overwriting output copy and must pass fresh-reopen assertions before promotion.
• Dialog actions are bound to a fresh process/window fingerprint instead of a product title or fixed screen coordinate.
• shutdown refuses unverified or user-owned sessions and never force-kills ADS or silently discards modified work.
• Arbitrary embedded Python and dynamic AEL calls stay disabled unless both the ADS process and the client explicitly opt into unsafe mode.

See the dialog automation contract, context interaction contract, and execution context contract for the exact boundaries.

Version support

No version is fixed into the public Docs Skill. Multiple installed versions can be discovered and selected explicitly.

Five public examples

ads-agent --pretty examples list

The current catalog covers:

1. ADS discovery and explicit version selection;
2. no-GUI minimal-AC simulation and dataset readback;
3. read-only live DE workspace context;
4. bounded DDS dataset readback into a new native DDS file;
5. a fixed read-only AEL workspace call showing the hybrid boundary.

Every runner names its prerequisites, state changes, evidence, and stop rule. See EXAMPLES.md for exact commands.

Current boundaries

The project does not claim blank-layout Momentum setup authoring or a completed RFPro, FEM, SIPro, or PIPro workflow. Its bounded Momentum capability begins with already-generated simulation inputs. Remote ADS operations use the generic Runtime over persistent SSH stdio; raw port forwarding is not supported. Other solver workflows still require their own runtime and solver-side acceptance evidence before promotion.

Documentation

• CLI and installation reference
• Capability, mechanism, and evidence matrix
• ADS 2027 headless AC execution benchmark
• Examples and acceptance gates
• Release contract
• Session and dialog automation
• DE/DDS context interaction
• Execution context contract
• Changelog

To remove the ADS integration while preserving unrelated add-ons:

ads-agent addon uninstall

Development

See CONTRIBUTING.md. Public claims are accepted only when the corresponding test, runtime observation, or validation gate has passed.