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	Create user and agent sessions, and understand fork(), detach(), and Backend placement.
2	Local Sandbox Tools	Open a local Backend directly and see how file, command, and code payloads run around a workspace.
3	Session Loop Tool Calls	Understand model tool calls, tool dispatch, tool_result chunks, and the next completion round.
4	Custom FlowToolCall	Define your own tool schema and Python execution logic, then pass it into the Session loop.
5	Runnable Examples	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, 02 Session Lineage
Runtime & Tools	Check where tools execute and how tool calls are represented.	03 Sandbox Backend, 04 Built-in Tools, 05 Custom Tool
Integrations	Try MCP tools, streaming, compression, memory, and provider variation.	06 MCP Tool, 07 Streaming, 08 Compress, 09 Memory, 10 Provider Variation

Choose by Task

Task	Start with
Understand OpenRath’s state model	Session Basics
Check which directory tools run in	Local Sandbox Tools
See how an agent calls tools across turns	Session Loop Tool Calls
Wrap an external API as a model-callable tool	Custom FlowToolCall
Connect OpenSandbox	03 Sandbox Backend
Try a streaming UI callback	07 Streaming
Use an Anthropic model	10 Provider Variation
Wrap an MCP server as tools	06 MCP Tool
Inspect session lineage	02 Session Lineage
Try key-free local memory	09 Memory

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.

Tutorials

• Session Basics
  • Coverage
  • Step 1: Create Agent and User Sessions
  • Step 2: Understand the Chunk Table
  • Step 3: Preserve Origin with Fork
  • Step 4: Create a New Starting Point with Detach
  • Step 5: Set the Local Backend Target
  • Step 6: Open and Close the Sandbox Handle
  • Step 7: Fork Shares an Open Handle
  • Troubleshooting
  • Exercises
  • Summary
• Local Sandbox Tools
  • Coverage
  • Step 1: Open the Local Backend
  • Step 2: Write and Read a File
  • Step 3: Run a Shell Command
  • Step 4: Run Python Code
  • Step 5: Close the Sandbox
  • Troubleshooting
  • Exercises
  • Summary
• Session Loop Tool Calls
  • Coverage
  • Step 1: Prepare Agent and User Sessions
  • Step 2: Run the Loop
  • Step 3: Understand One Tool Round
  • Step 4: Inspect the Chunk Table
  • Step 5: Confirm Sandbox Sharing
  • Troubleshooting
  • Exercises
  • Summary
• Custom FlowToolCall
  • Coverage
  • Step 1: Define the Input Schema
  • Step 2: Subclass FlowToolCall
  • Step 3: Pass It into the Session Loop
  • Step 4: Read the Result
  • Step 5: Let the Tool Access the Sandbox
  • Troubleshooting
  • Exercises
  • Summary
• Runnable Examples
  • Ladder
  • Setup