MODULE 05 / 08

Autonomous Executive Agent: Fault-Tolerant Action Layer

Master the Action layer—build a fault-tolerant LangGraph agent that plans parallel tools, retries flaky APIs, interrupts for human approval, and resumes from crash-surviving checkpoints for high-stakes bookings and scheduling.

LangGraph state machines + checkpointers for long-running agency: QLoRA tool calling, parallel tools, HITL interrupts, and Postgres lineage.

LangGraphPEFTTavily APIPostgreSQLFastAPI

YOU'LL BUILD

A Hotel Booking Assistant

Production goals

G01Implement persistent agency that survives server crashes via checkpointed state.
G02Manage high-stakes tool calling with human-in-the-loop interrupts before reservation.
G03Execute multi-step booking/scheduling workflows with parallel tools and fault-tolerant retries.

You'll master techniques:

T01QLoRA fine-tuning for high-precision tool calling.
T02Parallel tool execution for complex multi-step tasks.
T03Adapter-based training for JSON reliability.
T04Interrupt-driven workflows (Human-in-the-loop).
T05Fault-tolerant retry logic for API failures.

Autonomous Executive Agent: Fault-Tolerant Action Layer

The Project Kit

The Action-Layer Agent Graph

A modular Python codebase structured for high-stakes booking and scheduling:

LangGraph Orchestration: Intent → parallel tools → HITL → reserve state machine with thread_id checkpoints after every node.
Parallel Tool Fan-Out: Hotel search, calendar checks, travel policy validation, and Tavily destination research via ThreadPoolExecutor.
HITL Interrupts: High-stakes bookings pause for human approval before reservation; resume from the same checkpointed thread.
Fault-Tolerant Retries: Transient API failures are retried with audit-logged status instead of silent agent loops.
QLoRA / PEFT Contracts: Tool-calling SFT hooks and runtime JSON schema guards for reliable structured outputs.

The Full-Stack Serving Layer

An entire system to book, approve, and recover agency state:

FastAPI Microservice: / /health /metadata /simulate POST /book POST /approve GET /checkpoint/{thread_id} with CORS and App Runner-ready Docker Compose.
MakCorps + Local Inventory: Free hotel API when credentials are set; local inventory fallback so demos and smoke tests always run.
Tavily Research: Live destination briefs when TAVILY_API_KEY is set; offline brief otherwise.
Postgres-Ready Lineage: Booking events to PostgreSQL with JSONL fallback for crash-surviving audit trails.
Deploy Scripts: UV + Docker Compose helpers without rebuilding the image for every booking request.

1curl -X POST http://127.0.0.1:8000/book -H "Content-Type: application/json" -d '{"user_id":"exec-001","destination":"Tokyo","check_in":"2026-07-10","check_out":"2026-07-12","guests":1,"budget_per_night":300,"require_human_confirmation":true}'

Portfolio-Ready Documentation

README.md + TUTORIAL.md / TUTORIAL_FULL.md: System architecture + agency pipeline diagrams and production goals designed for GitHub showcase.
Smoke Tests: Compile + route checks that assert HITL interrupt and approved booking completion.

1uv run bash scripts/test.sh

Tutorial Summary

Tutorial: Building a Fault-Tolerant Booking Agent What We'll Build - The System Architecture Production Goals What You'll Master Booking Request Source Layout Intent Resolver Parallel Tool Execution Third-Party Hotel API

How to get MakCorps free credentials

How to get a Tavily API key

Tool-Calling Reliability Human-In-The-Loop FastAPI Service Full run (API + optional live tools + QLoRA)Smoke Test

Tutorial: Building a Fault-Tolerant Booking Agent

What We'll Build - The System Architecture

In this project, we'll implement an autonomous executive agent that handles high-stakes multi-step tasks like hotel booking and scheduling. The agent resolves user intent, plans tool calls, executes hotel search and policy checks, interrupts for human approval, and resumes from checkpoints.

You'll build a hotel booking assistant using LangGraph, PEFT, Tavily API, PostgreSQL, and FastAPI production patterns.

Kernel Labs | Kuriko IWAI | kuriko-iwai.com

Figure A. Booking Assistant system architecture — travelers and ops hit an API gateway / LB; FastAPI App Runner runs /book and /approve; LangGraph agents resolve intent, plan parallel tools, retry failures, interrupt for human confirmation, and persist checkpoints with PostgreSQL lineage.

Kernel Labs | Kuriko IWAI | kuriko-iwai.com

Figure B. Agency pipeline — booking request → FastAPI → intent → parallel tools → HITL + reservation → checkpointed result.

Production Goals

Implementing persistent agency that survives server crashes.
Managing high-stakes tool calling with human-in-the-loop.

What You'll Master

QLoRA fine-tuning for high-precision tool calling.
Parallel tool execution for complex multi-step tasks.
Adapter-based training for JSON reliability.
Interrupt-driven workflows (Human-in-the-loop).
Fault-tolerant retry logic for API failures.

Booking Request

The API accepts a structured booking request:

1{
2  "user_id": "exec-001",
3  "destination": "Tokyo",
4  "check_in": "2026-07-10",
5  "check_out": "2026-07-12",
6  "guests": 1,
7  "budget_per_night": 300,
8  "preferences": ["wifi", "breakfast"],
9  "require_human_confirmation": true
10}
11

The local engine converts this request into a BookingRequest and executes the state machine.

The orchestration loop in src/agency/workflow.py is the core of the module. build_langgraph_workflow() defines the production LangGraph StateGraph (intent → parallel tools → HITL → reserve); the runtime still checkpoints after every node so agency survives process crashes:

1_ = build_langgraph_workflow()
2for node_name, node in NODE_ORDER:
3    state = node(state)
4    state = checkpoint(state, node_name, store)
5    if state.get("status") in {"interrupted", "failed"}:
6        break
7

Shipping AI Systems?

I help teams design and deploy scalable ML / RAG / LLM pipelines and MLOps infrastructure.

Or explore:

Dive deeper 👉 Research Archive
Learn by building 👉 AI Engineering Masterclass
Try it live 👉 Playground

Source Layout

Code is grouped by responsibility:

1module_5/
2├── app.py                 FastAPI routes: /book, /approve, /checkpoint
3├── scripts/test.sh        Smoke test (routes + HITL + approval)
4└── src/
5    ├── main.py            Public entrypoint + re-exports
6    ├── models.py          BookingRequest, ToolCall, BookingResult, state
7    ├── metadata.py        Course metadata + technique / stack coverage
8    ├── _utils/            Logging helpers
9    ├── agency/            LangGraph action layer
10    │   ├── agents.py      Intent → parallel tools → retry → HITL → reserve
11    │   └── workflow.py    StateGraph + run_booking_agent + checkpoints
12    ├── persistence/       Crash survival
13    │   ├── checkpointing.py   JSON thread checkpoints
14    │   └── lineage.py         PostgreSQL events (JSONL fallback)
15    └── tools/             External APIs + PEFT contracts
16        ├── hotel_api.py       MakCorps free API + local inventory
17        ├── tavily_tools.py    Destination research (live or offline)
18        └── tool_training.py   QLoRA / PEFT + JSON tool-call validation
19

Intent Resolver

The intent resolver checks required fields and assigns a risk level. Ambiguous requests produce an interrupt instead of unsafe tool execution.

Parallel Tool Execution

The planner schedules hotel search, calendar / scheduling checks, travel policy validation, and Tavily destination research. The implementation fans these tools out with ThreadPoolExecutor, then validates each JSON-like tool result before the workflow continues.

Implemented in src/agency/agents.py (+ src/tools/tavily_tools.py):

1plan_parallel_tools
2execute_parallel_tools
3retry_tool_call
4research_destination_with_tavily
5

Third-Party Hotel API

The hotel search tool calls MakCorps free Hotel API when MAKCORPS_USERNAME + MAKCORPS_PASSWORD (or MAKCORPS_JWT) are configured. If credentials are absent, the app uses local inventory so smoke tests and demos still run.

Implemented in src/tools/hotel_api.py:

1search_hotels_via_makcorps
2search_hotels_with_best_provider
3search_hotels_locally
4

1HOTEL_PROVIDER=auto
2MAKCORPS_USERNAME=...
3MAKCORPS_PASSWORD=...
4

◼ How to get MakCorps free credentials

Sign up (no card): https://api.makcorps.com/register
Auth docs: https://docs.hotelapi.co/jwt-token-api — POST /auth with username/password → access_token
Free city search docs: https://docs.hotelapi.co/free-hotel-api — GET /free/{city} with Authorization: JWT <token>
Put username/password (or the JWT) in .env. Leave blank to stay on local inventory.

Note: the free endpoint returns sample/random future rates (no check-in/out params) — enough for agent tool-calling demos; local inventory remains the default for smoke tests.

◼ How to get a Tavily API key

Open https://app.tavily.com/onboarding/connect
Sign in and generate an API key → TAVILY_API_KEY in .env
Without the key, src/tools/tavily_tools.py returns an offline brief.

Tool-Calling Reliability

The tutorial techniques are explicit source hooks:

1QLoRA fine-tuning: src/tools/tool_training.py → run_qlora_tool_calling_sft
2PEFT JSON recipe: src/tools/tool_training.py → build_peft_json_reliability_recipe
3JSON reliability: src/tools/tool_training.py → validate_tool_call_json
4Parallel tools: src/agency/agents.py
5Human interrupt: src/agency/agents.py
6Retry logic: src/agency/agents.py
7LangGraph graph: src/agency/workflow.py
8PostgreSQL lineage: src/persistence/lineage.py
9

Human-In-The-Loop

If the booking is high stakes, the agent returns an interrupted state. Checkpoints and optional PostgreSQL lineage (DATABASE_URL) record the pause. The user can approve through /approve, and the agent resumes with the same thread_id.

Shipping AI Systems?

I help teams design and deploy scalable ML / RAG / LLM pipelines and MLOps infrastructure.

Or explore:

Dive deeper 👉 Research Archive
Learn by building 👉 AI Engineering Masterclass
Try it live 👉 Playground

FastAPI Service

The serving layer exposes:

1GET  /health
2GET  /metadata
3GET  /simulate
4GET  /checkpoint/{thread_id}
5POST /book
6POST /approve
7

Full run (API + optional live tools + QLoRA)

MAKCORPS_API_KEY is not used. Use MAKCORPS_USERNAME + MAKCORPS_PASSWORD, or MAKCORPS_JWT. Leave blank for local hotel inventory.

1cd module_5
2
3# 1) Env
4cp -n .env.sample .env
5# optional live hotels:  MAKCORPS_USERNAME=...  MAKCORPS_PASSWORD=...
6# optional live Tavily:  TAVILY_API_KEY=tvly-...
7
8# 2) App deps + QLoRA group (torch / transformers / bitsandbytes / datasets)
9uv sync --group qlora
10
11# 3) Smoke (local inventory OK without MakCorps)
12uv run bash scripts/test.sh
13
14# 4) API
15uv run python app.py
16# other terminal:
17curl "http://127.0.0.1:8000/simulate"
18
19# 5) CLI booking agent
20uv run python src/main.py
21
22# 6) QLoRA draft train (GPU recommended; needs HF access for the base model)
23export QLORA_BASE_MODEL=meta-llama/Meta-Llama-3-8B-Instruct   # or a smaller public model
24export QLORA_MAX_STEPS=20
25uv run python -m src.tools.tool_training
26# or:
27uv run python -c "from src.tools.tool_training import run_qlora_tool_calling_sft; print(run_qlora_tool_calling_sft(max_steps=20))"
28

Adapter artifacts write to artifacts/booking-tool-json-qlora/.

Docker alternative for the API only:

1docker-compose up --build
2

Smoke Test

Run:

1uv run bash scripts/test.sh
2

This compiles the Python files, verifies API routes, checks a human approval interrupt, and confirms that an approved booking completes.

The Project Kit

The Action-Layer Agent Graph

A modular Python codebase structured for high-stakes booking and scheduling:

LangGraph Orchestration: Intent → parallel tools → HITL → reserve state machine with thread_id checkpoints after every node.
Parallel Tool Fan-Out: Hotel search, calendar checks, travel policy validation, and Tavily destination research via ThreadPoolExecutor.
HITL Interrupts: High-stakes bookings pause for human approval before reservation; resume from the same checkpointed thread.
Fault-Tolerant Retries: Transient API failures are retried with audit-logged status instead of silent agent loops.
QLoRA / PEFT Contracts: Tool-calling SFT hooks and runtime JSON schema guards for reliable structured outputs.

The Full-Stack Serving Layer

An entire system to book, approve, and recover agency state:

FastAPI Microservice: / /health /metadata /simulate POST /book POST /approve GET /checkpoint/{thread_id} with CORS and App Runner-ready Docker Compose.
MakCorps + Local Inventory: Free hotel API when credentials are set; local inventory fallback so demos and smoke tests always run.
Tavily Research: Live destination briefs when TAVILY_API_KEY is set; offline brief otherwise.
Postgres-Ready Lineage: Booking events to PostgreSQL with JSONL fallback for crash-surviving audit trails.
Deploy Scripts: UV + Docker Compose helpers without rebuilding the image for every booking request.

1curl -X POST http://127.0.0.1:8000/book -H "Content-Type: application/json" -d '{"user_id":"exec-001","destination":"Tokyo","check_in":"2026-07-10","check_out":"2026-07-12","guests":1,"budget_per_night":300,"require_human_confirmation":true}'

Portfolio-Ready Documentation

README.md + TUTORIAL.md / TUTORIAL_FULL.md: System architecture + agency pipeline diagrams and production goals designed for GitHub showcase.
Smoke Tests: Compile + route checks that assert HITL interrupt and approved booking completion.

1uv run bash scripts/test.sh

Autonomous Executive Agent: Fault-Tolerant Action Layer

Production goals

You'll master techniques:

The Project Kit

The Action-Layer Agent Graph

The Full-Stack Serving Layer

Portfolio-Ready Documentation

Tutorial Summary

Table of Contents

Tutorial: Building a Fault-Tolerant Booking Agent

What We'll Build - The System Architecture

Production Goals

What You'll Master

Booking Request

Shipping AI Systems?

Source Layout

Intent Resolver

Parallel Tool Execution

Third-Party Hotel API

◼ How to get MakCorps free credentials

◼ How to get a Tavily API key

Tool-Calling Reliability

Human-In-The-Loop

Shipping AI Systems?

FastAPI Service

Full run (API + optional live tools + QLoRA)

Smoke Test

The Project Kit

The Action-Layer Agent Graph

The Full-Stack Serving Layer

Portfolio-Ready Documentation

Table of Contents

Tutorial: Building a Fault-Tolerant Booking Agent

What We'll Build - The System Architecture

Production Goals

What You'll Master

Booking Request

Shipping AI Systems?

Source Layout

Intent Resolver

Parallel Tool Execution

Third-Party Hotel API

◼ How to get MakCorps free credentials

◼ How to get a Tavily API key

Tool-Calling Reliability

Human-In-The-Loop

Shipping AI Systems?

FastAPI Service

Full run (API + optional live tools + QLoRA)

Smoke Test