Tutorials¶
Tutorials walk you through building complete agents from scratch. Unlike guides — which explain SCRAPI's individual features — tutorials give you a finished, working agent at the end, with real code, real evaluations, and the full context of why each decision was made.
What you'll build¶
The current tutorial builds Bella Notte — a restaurant reservation agent for a fine-dining Italian restaurant. By the end, you'll have a complete agent that:
- Collects party size, preferred date, and other reservation details through natural conversation.
- Checks availability via a simulated API and presents time options.
- Handles multi-slot input ("table for 2 on Friday under Garcia") with all three setter tools firing in one turn.
- Books the reservation and returns a confirmation number.
- Recovers gracefully from invalid input (party size out of range, past dates, unavailable times).
- Has a full eval suite — 20+ golden evals and 5+ scenario evals — covering the happy path, error recovery, conversational detours, and multi-slot batching.
The agent implements the Slot Filling Pattern end-to-end. Reading that pattern page before starting the tutorial is recommended but not required.
Prerequisites¶
- Python 3.10 or later
- A Google Cloud project with CX Agent Studio enabled
- A CX Agent Studio app created in the UI (you'll get its app ID from
cxas apps list) - SCRAPI installed:
pip install cxas-scrapi - SCRAPI authenticated:
gcloud auth application-default login
Learning path¶
Work through the tutorial in order — each step builds on the previous one.
| Step | What you'll do |
|---|---|
| 1 — Project setup | Create gecx-config.json, understand the folder structure |
| 2 — Agent instruction | Write the XML-tagged instruction with the slot filling protocol |
| 3 — Slot DAG | Define the 7 slots and 2 tasks |
| 4 — Setter tools | Write set_party_size.py and the other setter tools |
| 5 — The callback | Write before_model_callback with DAG evaluation and preemption |
| 6 — Variables | Declare the sm variable in your app |
| 7 — Evaluations | Write one golden eval and one scenario eval |
| 8 — Run and iterate | Run evals, read results, and fix failures |
What you'll learn¶
After completing the tutorial, you'll understand:
- How the Slot Filling Pattern splits work between the LLM (language) and Python (state, control flow).
- Why tool docstrings must be short and what happens when they're verbose.
- How
before_model_callbackevaluates the DAG and preempts the LLM when a task fires. - How golden evals check exact tool calls and scenario evals check overall behavior.
- The 7 stabilization gotchas — and how the tutorial's design avoids each one.
After the tutorial¶
Once you've built Bella Notte, the natural next steps are:
- Read the full Slot Filling Pattern for the complete set of advanced features: conditional slots, retry configuration, readback stall detection, and config validation.
- Explore Dynamic Prompting to see how to adapt the agent's instruction based on conversation phase.
- Add Self-Healing Errors to the booking tool so the agent has explicit recovery instructions for API failures.