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 session API reuses the same config and credentials as the CLI. Run your script inside the checkout’s environment with uv run python your_script.py. Register adapters before the first turn (tools and investigation):

from bootstrap.process import EMBEDDED_PROFILE, configure_process

configure_process(EMBEDDED_PROFILE)

One API — chat and investigate

Every surface uses the same two verbs:

from bootstrap.process import EMBEDDED_PROFILE, configure_process
from core.agent_harness import AgentSession

configure_process(EMBEDDED_PROFILE)

session = AgentSession.start()
result = session.chat("why is checkout-api slow?")
if result.answered:
    print(result.primary_response_text)

report = session.investigate({"alert_name": "HighLatency", "severity": "warning"})
print(report.report)

Or the one-liner that wires the same boot step for you:

from bootstrap.embedded import start_embedded_session

session = start_embedded_session()

AgentSession.start() resolves the environment, opens a session, and attaches an agent with the standard ports — the same tools and prompts the interactive shell uses. It does not register adapters (core may not import bootstrap); call configure_process first or use start_embedded_session. investigate does not require an attached chat agent; it uses the payload runner installed by configure_process. Always check result.answered before trusting chat text: when a turn fails (for example the LLM provider is unreachable), the error message itself lands in result.primary_response_text.

Internal seams (not for hosts)

Chat hosts terminate at dispatch_chat_turn → run_turn. Investigation terminates at the installed payload runner (run_investigation_payload). Do not invent parallel public entrypoints.

A conversation

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

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

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

from core.agent_harness import AgentSession, SessionConfig

session = AgentSession.start(SessionConfig(session_id="abc123"))

Your own grounding context

The agent builds its prompts from the session by default. To ground it your own way — a different system prompt, your own retrieved context — pass a provider:

from core.agent_harness import AgentSession, SessionConfig

session = AgentSession.start(SessionConfig(prompts=my_provider))

Omit it and the built-in provider applies (core.agent_harness.DefaultPromptContextProvider). A custom provider must satisfy core.agent_harness.ports.PromptContextProvider. The same prompts= argument is accepted by build_default_headless_agent on the custom-ports path below.

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 (
    AgentSession,
    BufferOutputSink,
    SessionConfig,
    build_default_headless_agent,
)

session = AgentSession(SessionConfig())
startup = session.startup()
sink = BufferOutputSink()
agent = build_default_headless_agent(
    session=startup.session,
    output=sink,
    prompts=my_provider,  # optional — same port as SessionConfig.prompts
)
session.attach_agent(agent)

session.chat("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.

Your own tools

from tools.registry import register_external_tool_package
import my_agent_tools

register_external_tool_package(my_agent_tools)

Two gotchas:

Declare tools with surfaces=("action",) (or include "action"). The @tool default is ("investigation",) only — the chat/Python-API action loop will not see investigation-only tools.
Tools may live in the package’s __init__.py or in submodules; both are scanned after registration.

Overview

First steps

Prerequisites

One API — chat and investigate

Internal seams (not for hosts)

A conversation

Your own grounding context

Custom output and ports

Your own tools

​Prerequisites

​One API — chat and investigate

​Internal seams (not for hosts)

​A conversation

​Your own grounding context

​Custom output and ports

​Your own tools

Prerequisites

One API — chat and investigate

Internal seams (not for hosts)

A conversation

Your own grounding context

Custom output and ports

Your own tools