Agent Harness Bridge

agent-harness-bridge gives applications one small, submit-tool-oriented API for three different agent runtimes:

• OpenAI Agents SDK, including OpenAI-compatible endpoints such as Volcengine Ark
• Claude Agent SDK
• DeepSeek Harness (dsh)

It deliberately does not hide backend lifecycle differences. Each adapter owns its native session continuation, MCP transport, timeout, cleanup and recovery logic, while applications keep their prompts, domain tools and submit validation.

Install

Install only the runtime you need, or all validated adapters:

pip install 'agent-harness-bridge[openai]==0.2.0'
pip install 'agent-harness-bridge[claude]==0.2.0'
pip install 'agent-harness-bridge[deepseek]==0.2.0'
pip install 'agent-harness-bridge[all]==0.2.0'

The dsh adapter also imports deepseek_harness. DeepSeek's current SDK depends on a platform-specific runtime wheel, so the bridge does not force that wheel onto every installation. Install the SDK using the method supported by the target host. On older-glibc clusters, load polyfill-glibc/0.1 before using its runtime or point DSH_BIN at a validated source build.

Configuration

Harness and model selection are independent:

HARNESS=openai MODEL=doubao-seed-2-1-turbo-260628 python your_workflow.py
HARNESS=openai MODEL=doubao-seed-2-1-pro-260628 python your_workflow.py
HARNESS=deepseek MODEL=doubao-seed-2-1-turbo-260628 python your_workflow.py
HARNESS=claude MODEL=claude-sonnet-5 python your_workflow.py

The default remains OpenAI Agents SDK with doubao-seed-2-1-turbo-260628. Model identifiers are intentionally open strings rather than a hard-coded catalog.

Logging

Every bridge line (== [label] agent: tool(...), retries, usage limits, run summaries) goes through the harness_bridge logger family at INFO. Configure it once in your CLI entry point, together with your own logger families, so one stream carries one style of output:

from harness_bridge import configure_logging

configure_logging("myapp")            # harness_bridge + myapp -> stdout, "%(message)s"
configure_logging("myapp", stream=sys.stderr, level="DEBUG")

Records are flushed one by one, so Slurm and tee logs stay live. If nobody configured logging before run_agent runs, the bridge attaches the same default handler itself (ensure_logging), which keeps the pre-0.2 behaviour of printing to stdout. Loggers keep propagating to the root logger, so pytest's caplog still sees the records.

Contract

Applications provide ToolSpec objects and designate one successful submit tool as the completion condition:

from harness_bridge import ToolSpec, run_agent

async def submit(args):
    return {
        "content": [{"type": "text", "text": "accepted"}],
        "_submitted": args,
    }

result = await run_agent(
    tools=[ToolSpec("submit_answer", "Submit the checked answer", {"answer": str}, submit)],
    submit_tool="submit_answer",
    prompt="Check the evidence and submit the answer.",
    cwd="/absolute/read-only/workdir",
)

Tool handlers return an MCP-shaped result containing text or image content, an optional is_error, and an optional private _submitted value captured by the host after successful validation. A handler that raises is reported to the model as an error result under every backend; it never aborts the run.

run_agent() validates the tool table before importing any SDK: the submit tool must be present, tool names must be unique, allowed_builtin must be a subset of read, glob, grep, tasks, and application tools may not reuse the name of a requested builtin.

allowed_builtin selects Claude Code's own Read/Glob/Grep/Task tools under HARNESS=claude. The OpenAI and dsh adapters serve same-named, cwd-confined host tools implemented in pure Python (Grep needs no rg on the host), so prompts stay portable across backends.

backend_capabilities() exposes runtime facts that callers can check before a run. Unsupported built-in capabilities fail closed.

Design boundary

The bridge owns only runtime concerns. Domain workflows should continue to own:

• prompts and scientific or business policy
• tool handler implementations
• submit validation
• output files and resume manifests

Backend-specific defenses remain adapter-local. In particular, OpenAI Responses continuation and context reset, Claude SDK teardown and permissions, and dsh MCP startup/watchdog/SSE recovery are not reduced to a lowest-common- denominator loop.