# Developer Notes
Developer Notes explain OpenRath's core components and runtime boundaries. They are written for developers who want to extend OpenRath, read the source, write custom workflows, or connect a new backend.

This page maps the main component pages to the relevant source files and tests.

## Component map
| Component | Covers | Entry point |
| --- | --- | --- |
| `Session` | Context table, backend placement, session graph. | [Session](session.md) |
| `Sandbox` | Backend registration, sandbox lifecycle, local/OpenSandbox behavior. | [Sandbox](sandbox.md) |
| `Tool` | `FlowToolCall`, backend payloads, tool result chunks, streams. | [Tool](tool.md) |
| `AgentParam` | Agent-side system session and provider options. | [Agent Param](agent_param.md) |
| `Workflow` | Composable agent workflow modules. | [Workflow](workflow.md) |
| `LLM` | Provider registry, OpenAI-compatible and Anthropic clients, streaming, retry, budget, and executor replacement points. | [LLM](llm.md) |
| `Memory` | Local and OpenViking memory stores, memory ops, and Agent recall/commit behavior. | [Memory](memory.md) |
| `Async runtime` | Lazy sessions, resource-keyed tool dispatch, and private runtime boundaries. | [Async Runtime](async_runtime.md) |

## Reading order
| Goal | Suggested order |
| --- | --- |
| Understand the runtime path | `Session` -> `Sandbox` -> `Tool` |
| Write a single agent | `AgentParam` -> `Workflow` -> `LLM` |
| Write a multi-agent workflow | `Workflow` -> `AgentParam` -> `Session` |
| Write a custom tool | `Tool` -> `Sandbox` -> `Session` |
| Connect a new model gateway | `LLM` -> `AgentParam` |
| Add long-term agent state | `Memory` -> `Workflow` -> `Session` |
| Reason about lazy results | `Async Runtime` -> `Session` -> `Tool` |

## Source and tests
| Component | Main source | Main tests |
| --- | --- | --- |
| `Session` | `src/rath/session/session.py`, `loop.py`, `compress.py`, `graph/` | `tests/session/`, `tests/integration/test_session_loop_real.py`, `tests/integration/test_session_compress_real.py` |
| `Sandbox` | `src/rath/backend/abc.py`, `local.py`, `opensandbox.py` | `tests/backends/`, `tests/conformance/`, `tests/unit/test_registry.py` |
| `Tool` | `src/rath/flow/tool/`, `src/rath/backend/tool_types.py` | `tests/session/test_tool_registry.py`, `tests/flow/test_flow_tool_user_subclass.py`, `tests/unit/test_flow_tool.py` |
| `AgentParam` | `src/rath/flow/agent_param.py`, `src/rath/flow/agent.py` | `tests/flow/test_workflow_agent.py`, `tests/test_import.py` |
| `Workflow` | `src/rath/flow/workflow.py`, `agent.py`, `compressor.py` | `tests/flow/test_workflow_agent.py` |
| `LLM` | `src/rath/llm/`, `src/rath/session/provider_builtin.py` | `tests/llm/`, `tests/session/test_llm_message_wire.py` |
| `Memory` | `src/rath/memory/`, `src/rath/flow/memory_inject.py` | `tests/memory/`, `tests/flow/test_agent_memory_*` |
| `Async runtime` | `src/rath/_async/`, `src/rath/session/session.py` lazy materialization hooks | `tests/session/test_lazy_session.py`, `tests/concurrency/`, `tests/bench/` |

Developer Notes describe behavior that exists in the current source. Roadmap notes, troubleshooting, and full application tutorials are tracked separately.

```{toctree}
---
maxdepth: 2
caption: Developer Notes
---

session
sandbox
tool
agent_param
workflow
llm
memory
async_runtime
```