Python API

Use this when your Python code runs on the same machine as OpenSRE and you want agent answers without shelling out to the CLI. To call OpenSRE over the network instead, use the HTTP API.

Prerequisites

The standalone CLI installer does not expose an importable package, so embed from a source checkout:

git clone https://github.com/Tracer-Cloud/opensre.git
cd opensre && make install

Configure a provider once (opensre onboard) — the harness reuses the same config and credentials as the CLI. Run your script inside the checkout’s environment with uv run python your_script.py.

One turn

from core.agent_harness import AgentHarness

harness = AgentHarness.start()
result = harness.dispatch_message("why is checkout-api slow?")
if result.answered:
    print(result.primary_response_text)

AgentHarness.start() resolves the environment, opens a session, and attaches an agent with the standard ports — the same tools and prompts the interactive shell uses. Always check result.answered before trusting the text: when a turn fails (for example the LLM provider is unreachable), the error message itself lands in result.primary_response_text.

A conversation

Each dispatch_message call is one turn in the same session, so follow-ups see earlier context:

harness.dispatch_message("list unresolved Sentry issues from the last 24 hours")
result = harness.dispatch_message("which of those affect checkout?")

To resume a previous session instead of starting a new one, pass its ID:

from core.agent_harness import AgentHarness, HarnessConfig

harness = AgentHarness.start(HarnessConfig(session_id="abc123"))

Custom output and ports

start() buffers all output. To capture tool progress yourself — stream to a websocket, collect for a report — build the agent explicitly and pass your own sink:

from core.agent_harness import (
    AgentHarness,
    BufferOutputSink,
    HarnessConfig,
    build_default_headless_agent,
)

harness = AgentHarness(HarnessConfig())
startup = harness.startup()
sink = BufferOutputSink()
agent = build_default_headless_agent(session=startup.session, output=sink)
harness.attach_agent(agent)

harness.dispatch_message("summarize open incidents")
print(sink.lines)      # rendered output lines
print(sink.streamed)   # streamed answer chunks

Any object implementing the OutputSink protocol (core.agent_harness.ports.OutputSink: print, render_response_header, render_error, stream) works in place of BufferOutputSink. build_default_headless_agent also accepts a custom logger, prompt surface, and tool observers — see its docstring for the full port list.

Overview

First steps

Prerequisites

One turn

A conversation

Custom output and ports

​Prerequisites

​One turn

​A conversation

​Custom output and ports

Prerequisites

One turn

A conversation

Custom output and ports