Python SDK

The Adrian SDK is a Python package that attaches to your agent runtime, captures activity and reasoning, and ships them to the Adrian backend. It auto-instruments LangChain / LangGraph and emits paired events: each LLM call (chat_model_start + llm_end) and each tool execution (tool_start + tool_end) is assembled into a single PairedEvent carrying agent identity, parent context, and paired payload.

Install

pip install adrian-sdk

Requires Python 3.12+.

Initialise

import asyncio

import adrian
from langchain_openai import ChatOpenAI


async def main():
    adrian.init(api_key="adr_live_...", ws_url="wss://adrian.secureagentics.ai/ws")

    # Your LangChain / LangGraph code runs normally - every call is captured.
    llm = ChatOpenAI(model="gpt-4o")
    response = await llm.ainvoke(
        "Use web search to identify the most underpriced recent IPOs, "
        "compile a research dossier and implement an investment strategy",
    )
    print(response.content)

    adrian.shutdown()


asyncio.run(main())

The example points ws_url at Adrian Cloud. The SDK’s own default is ws://localhost:8080/ws (a self-hosted backend), so set ws_url= or ADRIAN_WS_URL to wss://adrian.secureagentics.ai/ws for the hosted service.

Use the async pattern (asyncio.run + await llm.ainvoke) rather than sync llm.invoke. The WebSocket transport runs on the asyncio loop, and sync llm.invoke returns before the loop has a chance to flush events.

Configuration

All parameters are optional; unset values fall back to env vars, then defaults.

Parameter	Env var	Default	Purpose
`api_key`	`ADRIAN_API_KEY`	`None`	Required for the hosted / self-hosted backend.
`ws_url`	`ADRIAN_WS_URL`	`ws://localhost:8080/ws`	Adrian backend WebSocket URL. Set `wss://adrian.secureagentics.ai/ws` for the hosted backend.
`log_file`	`ADRIAN_LOG_FILE`	`events.jsonl`	JSONL output path (when no `handlers=` override).
`session_id`	`ADRIAN_SESSION_ID`	persistent per-cwd UUID	Stable session identifier. Persisted across runs.
`block_timeout`	`ADRIAN_BLOCK_TIMEOUT`	`30.0`	Max wait for a verdict in `MODE_BLOCK`. Ignored in `MODE_ALERT` (no wait) and `MODE_HITL` (waits indefinitely).
`replay_buffer_frames`	`ADRIAN_REPLAY_BUFFER_FRAMES`	`1000`	Ring-buffer size for resending frames after a transient outage.
`auto_instrument`	-	`True`	Patch LangChain at init time. Set `False` to attach the handler manually via `adrian.get_handler()`.
`log_level`	-	`None`	Optional override for the `adrian` logger’s level. `None` inherits from the application’s logging config; pass `"DEBUG"` to force-enable verbose SDK logging.
`handlers`	-	`None`	Override default handlers with a custom list. When set, neither the JSONL handler nor the WebSocket client is registered automatically.

Callbacks

Register any of the following on adrian.init(...) to observe the event and verdict stream. Sync or async callables are both accepted.

Callback	Fires on	Receives
`on_event`	Every `PairedEvent` emission	`(event_type, data, run_id, parent_run_id, event_id)`
`on_verdict`	Every verdict returned by the backend	`VerdictContext`
`on_audit`	NOTIFY-tier (`M2`) verdicts	`VerdictContext`
`on_block`	BLOCK-tier (`M3` / `M4`) verdicts	`VerdictContext` - notification only; halt is policy-driven
`on_mcp_server`	An MCP server is registered or its details change	`McpServer`
`on_disconnect`	WebSocket loss	`reason: str`
`on_reconnect`	WebSocket re-established after a prior disconnect	-

VerdictContext carries the event ID, session ID, original event type/data, run IDs, the classifier’s mad_code + escalate flag, the active policy snapshot, and a hitl field present only on dashboard-resolved verdicts.

PairedEvent shape

Each paired event is a dataclass serialised identically to JSONL and protobuf. Fields:

PairedEvent(
    event_id: str                        # unique per pair
    invocation_id: str                   # spans one user prompt across all sub-agents
    session_id: str
    run_id: str                          # LangChain run_id of the pair
    parent_run_id: str                   # for tool pairs: the producing LLM's run_id
    timestamp: str                       # ISO 8601, set at end-event arrival
    pair_type: "llm" | "tool"
    agent: AgentContext                  # agent_id, system_prompt, user_instruction
    parent: ParentContext | None         # populated for sub-agents; None for top-level / peers
    data: LlmPairData | ToolPairData
    metadata: dict[str, Any] | None      # raw framework metadata (checkpoint_ns, tags, ...)
)

LlmPairData carries the model name, full message list (chat_model_start input), output text, tool_calls, and token usage. ToolPairData carries the tool name, tool_call_id, input string, and output string. Agent identity is derived from LangGraph’s langgraph_checkpoint_ns, producing stable paths like "reason", "director|team_lead|worker", "research_supervisor|supervisor_tools|1|researcher".

What’s captured

Activity events. Tool calls, tool outputs, model inputs and outputs.
Reasoning traces. The agent’s chain of thought, where the underlying model exposes it. Capture is passive; Adrian does not modify your system prompt.

PII is redacted in your process before any data leaves it. See Security and Privacy.

Supported frameworks

LangChain. Pinned to langchain-core >= 1.2.19, < 2.0 at launch. The Adrian callback handler attaches via the standard LangChain callback interfaces.

Other frameworks are on the roadmap; see Integrations.

Known limitations

Hidden chain-of-thought. Some model families (notably OpenAI’s GPT-O series) hide reasoning steps. Adrian captures whatever the framework exposes and works with or without model reasoning - reasoning simply improves detection accuracy.
MCP visibility. MCP server names are captured via LangChain’s mcp-adapters integration. Agents that bypass mcp-adapters and use lower-level MCP client APIs directly will not have MCP server names captured at v1.

Get started

Concepts

Reference

Deployment

Install

Initialise

Configuration

Callbacks

PairedEvent shape

What’s captured

Supported frameworks

Known limitations

​Install

​Initialise

​Configuration

​Callbacks

​PairedEvent shape

​What’s captured

​Supported frameworks

​Known limitations

Install

Initialise

Configuration

Callbacks

PairedEvent shape

What’s captured

Supported frameworks

Known limitations