# Tutorials
Tutorials are the entry point for learning OpenRath. They are organized in the order you are likely to use the project: build a `Session`, understand where tools run, then move into the v1.2 numbered example ladder.

Each tutorial focuses on code snippets, key-line notes, and observed behavior. Together they cover the common path from basic API usage to Workflow customization.

## Core Learning Path
| Order | Page | What it covers |
| --- | --- | --- |
| 1 | [Session Basics](session_basics.md) | Create user and agent sessions, and understand `fork()`, `detach()`, and Backend placement. |
| 2 | [Local Sandbox Tools](local_sandbox_tools.md) | Open a local Backend directly and see how file, command, and code payloads run around a workspace. |
| 3 | [Session Loop Tool Calls](session_loop_tools.md) | Understand model tool calls, tool dispatch, `tool_result` chunks, and the next completion round. |
| 4 | [Custom FlowToolCall](custom_flow_tool.md) | Define your own tool schema and Python execution logic, then pass it into the Session loop. |
| 5 | [Runnable Examples](examples/index.md) | Move into the v1.2 01-10 learning ladder, including streaming, compression, memory, and provider variation. |

## Example Groups
| Group | Use it for | Entry |
| --- | --- | --- |
| Basics | See the smallest runnable paths through agents and lineage. | [01 Hello Agent](examples/01_hello_agent.md), [02 Session Lineage](examples/02_session_lineage.md) |
| Runtime & Tools | Check where tools execute and how tool calls are represented. | [03 Sandbox Backend](examples/03_sandbox_backend.md), [04 Built-in Tools](examples/04_tools_builtin.md), [05 Custom Tool](examples/05_custom_tool.md) |
| Integrations | Try MCP tools, streaming, compression, memory, and provider variation. | [06 MCP Tool](examples/06_mcp_tool.md), [07 Streaming](examples/07_streaming.md), [08 Compress](examples/08_compress.md), [09 Memory](examples/09_memory.md), [10 Provider Variation](examples/10_provider_variation.md) |

## Choose by Task
| Task | Start with |
| --- | --- |
| Understand OpenRath's state model | [Session Basics](session_basics.md) |
| Check which directory tools run in | [Local Sandbox Tools](local_sandbox_tools.md) |
| See how an agent calls tools across turns | [Session Loop Tool Calls](session_loop_tools.md) |
| Wrap an external API as a model-callable tool | [Custom FlowToolCall](custom_flow_tool.md) |
| Connect OpenSandbox | [03 Sandbox Backend](examples/03_sandbox_backend.md) |
| Try a streaming UI callback | [07 Streaming](examples/07_streaming.md) |
| Use an Anthropic model | [10 Provider Variation](examples/10_provider_variation.md) |
| Wrap an MCP server as tools | [06 MCP Tool](examples/06_mcp_tool.md) |
| Inspect session lineage | [02 Session Lineage](examples/02_session_lineage.md) |
| Try key-free local memory | [09 Memory](examples/09_memory.md) |

## How to Read
Each page uses the same structure:

1. Read the coverage table first to confirm what the page explains.
2. Follow the code steps to understand the API boundary.
3. Compare the key-line notes to see where state changes.
4. Run or rewrite the exercises to turn the example into your own code.
5. If behavior is unexpected, check the troubleshooting table first, then use Developer Notes for source-level details.

```{toctree}
---
maxdepth: 2
caption: Tutorials
---

session_basics
local_sandbox_tools
session_loop_tools
custom_flow_tool
examples/index
```