Agent Harness

Harness (a13n-harness) is the embeddable execution SDK behind Harness UI and Service. It builds reusable agents, runs them with current tools and Environments, streams observations, and returns state for continuation. Start with the offline quickstart; the Python import is a13n_harness.

Capability composition

Build an AgentSpec with only the behavior your application needs. For example, to expose Environment tools and working state:

from a13n_harness import AgentSpec, HarnessBuilder
from a13n_harness.capabilities import WorkingStateCapability
from a13n_harness.environment import DynamicEnvironmentCapability, DynamicEnvironmentConfiguration

executable = HarnessBuilder().build(
    AgentSpec(model="openai-responses:gpt-5"),
    output_type=str,
    capabilities=(
        DynamicEnvironmentCapability(DynamicEnvironmentConfiguration()),
        WorkingStateCapability(),
    ),
)

Supply a Host-owned EnvironmentSource to each run(..., environment=...), or use environments={...} for named mounts. Harness invokes the source’s readiness preparation on first use, then opens and closes fresh fixed-target executions; your application selects their configuration, current state, access policy, and when to destroy a backing target. See Environments and Capabilities.

Async subagent results

For Host-owned async execution, configure SubagentCapability(async_enabled=True, operator=operator). Final results arrive automatically, including after the parent turn ends. The parent can continue other work and end its turn when only background work remains.

Your Host implements delivery and wake eligibility; Harness does not schedule delivery. Retrieved results include the child's execution identity. Hosts can use a13n_harness.execution_identity.format_execution_header for matching delivered results and messages. See the delegation contract.

Browser tools

Connect to an existing Chromium instance through a trusted CDP endpoint. The application prepares Chromium and its profile; Harness does not install or launch a browser. cdp-use is included in the normal Python dependencies.

from a13n_harness import AgentSpec, HarnessBuilder, RunBindings
from a13n_harness.capabilities import BrowserUseCapability
from a13n_harness.capabilities.browser.scope import CdpBrowserBackend


async def inspect_page(cdp_url: str) -> str:
    executable = HarnessBuilder().build(
        AgentSpec(model="openai-responses:gpt-5"),
        capabilities=(BrowserUseCapability(),),
        output_type=str,
    )
    async with CdpBrowserBackend.connect(cdp_url) as browser:
        result = await executable.run(
            "Navigate to https://example.com and describe the page.",
            bindings=RunBindings.embedded(browser_backend=browser),
        )
        return result.output_or_raise()

The context manager creates an owned tab scope, closes its tabs on exit, and disconnects its CDP client while leaving the browser process and unrelated tabs alive. The endpoint can be an HTTP(S) CDP base URL or WS(S) debugger URL. Keep CDP private: it grants broad browser control.

For a long-lived Host, connect once with Chromium.connect(cdp_url) from a13n_harness.capabilities.browser.cdp, create independent CdpBrowserBackend(runtime) scopes, and open a tab with await scope.tabs("new"). The default tab_access="owned" exposes only that scope's tabs and popups. Use CdpBrowserBackend(runtime, tab_access="global") to list and operate all actual browser tabs, including user tabs and other scopes' tabs. Global listing and selection borrow existing pages; newly created tabs remain owned by their creator. Each binding has independent logical selection, and close() only cleans up its owned targets in either mode.

Reuse a backend across Runs, supplying fresh authorization through each Run binding. await scope.attach(target_id) validates an exact surviving page during Host-directed reattachment, claiming it in owned mode or borrowing it in global mode. Both modes share the profile's login/storage state. When another binding uses the same Page, previous element and screenshot references expire; observe again before acting.

Before human input, await scope.pause() for every scope on the controlled browser and prevent new scope admission. After revoking viewer input, call scope.resume(). Pending tools return a fresh-observation instruction without replaying their original action. scope.retire() revokes access; await scope.close() also closes owned tabs; await runtime.close() disconnects without destroying Chromium. Run completion performs none of these Host lifecycle operations.

The model receives eleven tools: browser_observe, browser_read, browser_navigate, browser_act, browser_wait, browser_tabs, browser_files, browser_dialog, browser_screenshot, browser_js, and browser_cdp. Select a subset with BrowserUseCapability(enabled_tools=frozenset({...})).

A typical task navigates, observes a focused region, acts on an eN reference or a unique semantic locator, and reads or waits to verify the outcome. browser_act takes one action at a time, including fill/type, click/hover, key chords, check, native select, and scroll. For example, its arguments can be:

{"action": {"kind": "fill", "target": {"kind": "locator", "role": "textbox", "name": "Email"}, "text": "ada@example.com"}}

Observation filters and pagination keep large pages manageable; reading text, links, tables, or forms preserves the existing refs. Both support same-process and out-of-process frames. State values distinguish disabled, readonly, checked, selected, and expanded controls; password values are redacted. Inspect dispatch separately from verification: input delivery alone does not establish that a form submitted or a purchase succeeded.

Screenshots return JPEG content plus an sN identifier and CSS dimensions. For visual-only controls, click or hover accepts normalized coordinates in the latest viewport/clip screenshot; the reference is consumed once and checked for stale page/viewport state. Prefer semantic targets for moving content. Full-page screenshots are for observation. Use browser_files for Host-path uploads and accessible tracked download status, and browser_dialog for JavaScript prompts.

Use browser_js(expression) for task-specific page JavaScript and JSON extraction. It awaits Promises in the selected page's main world. browser_cdp(method, params) sends supported page-domain commands through that page's session; its description lists the domains and exclusions. Browser/target administration and file transfer retain their existing owners. Both tools expire element/screenshot references and can leave page effects after errors, timeout or cancellation. Human control drains tool requests, not installed timers or listeners. Custom backends implement js and cdp to provide these tools. With CodeActCapability() enabled, the same browser tools are callable from restricted Python without another mode or runtime; see Compose Browser Tools.

Browser access is outside the Agent Environment's sandbox and cannot enforce restrictive allowed_hosts. The Host must authorize the captured Run rather than relying on its Thread's defaults. See the browser contract.

Run the opt-in native fixtures with an already installed Chromium executable:

uv run --package a13n-harness --group test pytest \
  packages/a13n-harness/tests/test_browser_cdp_native.py \
  packages/a13n-harness/tests/test_browser_workflows_native.py \
  --browser-executable=/path/to/chromium

The fixtures use disposable profiles and a basic password store to avoid desktop keyring prompts. If the test environment requires disabling Chromium's sandbox, explicitly add --browser-no-sandbox; it is never selected automatically for root.

Model construction

Pass a native model directly through HarnessBuilder.build(model=...), or select one in AgentSpec.model. a13n_harness.infer_model() constructs a model from supported aliases and caller-owned provider factories. create_model_http_client() builds a caller-owned httpx2 client for provider requests. Configure credentials and close owned clients in your application. See Models and Model authentication.

Execution boundary and filters

Harness prepares images for the selected Model without changing saved history or original files. Configure HarnessModelCharacteristics.image_input with ImageInputPolicy, or set image_input=None to disable preparation. See Context.

Recognized provider-history repairs are on by default; configure them through SelfHealingModelCapability or disable automatic installation with HarnessBuilder(self_healing_enabled=False). For long Threads, opt into proactive history compaction. Context recovery is enabled by default and first tries normal compaction after native context-window overflow. Add other Capabilities for policy, memory, or delegation.

A completed Run returns a HarnessState with a stable thread_id. Pass it as previous_state to continue the Thread; each new Run receives a fresh run_id. The Host persists accepted state and reconstructs credentials and other current authority on resume. State and resume covers serialization and interrupted calls.

Runnable examples and guides

• Agent application: offline streaming turns, checkpointing, and restart recovery.
• Environment Providers: construction, re-entry, and lifecycle.
• Plugins and extensions: packaged middleware, Capabilities, and Environment integrations.
• MCP tools: an in-process server and an offline Model, followed by Host-owned clients and per-Run headers.
• Harness guide: the public API by task.

Versioning

Harness and a13n-stream-protocol publish together at one exact version. Harness UI releases independently. The Harness specification owns the accepted contracts.