Tutorials¶

55 runnable examples/tutorial_NN_*.py files in the repo. Every one runs end-to-end against the bundled MockModel (no creds required) and upgrades to live OCI / OpenAI / Anthropic / Ollama by setting one env var.

Run any tutorial directly:

git clone https://github.com/oracle-samples/locus.git
cd locus && pip install -e .
python examples/tutorial_01_basic_agent.py

Foundations¶

The agent loop, tools, state, memory, hooks, streaming.

#	Tutorial
1	Basic agent
2	Agent with tools
3	Conversation memory
4	Streaming events
5	Lifecycle hooks
21	SSE streaming
27	Hooks (advanced)
28	Agent server (FastAPI)
37	Termination conditions

Graphs & composition¶

StateGraph, conditional edges, reducers, retries, the functional API.

#	Tutorial
6	Basic graph
7	Conditional routing
8	State reducers
9	Human-in-the-loop
10	Command + advanced patterns
25	Composition (Sequential / Parallel / Loop)
35	Graph (advanced) — retries, subgraphs
36	Functional API (`@task`, `@entrypoint`)

Multi-agent¶

In-process patterns plus A2A, DeepAgent, and real-world crew workflows.

#	Tutorial	Shape
11	Swarm	Peer-to-peer shared context
16	Agent handoff	Sequential escalation
17	Orchestrator pattern	Coordinator + parallel specialists
18	Specialist agents	Named domain experts
34	A2A protocol (cross-process)	HTTP + SSE mesh
41	DeepAgent — research factory	Reflexion + grounding + subagents
42	Map-reduce code review	`Send` fan-out / reduce
43	Supervisor + critic loop	Refinement loop with cycles
44	Adversarial debate + judge	Typed `Verdict` via `output_schema`
45	Multi-agent + human-in-the-loop	3 HITL patterns in one file

Reasoning¶

Reflexion, Grounding, Causal, GSAR (typed grounding).

#	Tutorial
13	Structured output (Pydantic)
14	Reasoning patterns
39	GSAR — typed grounding

RAG¶

#	Tutorial
22	RAG basics
23	RAG providers (vector stores, embeddings)
24	RAG agents

Skills, playbooks & plugins¶

#	Tutorial
12	MCP integration
15	Playbooks
31	Plugins
32	Skills
33	Steering (LLM-as-policy hook)

Production¶

Structured output, guardrails, checkpointers, multi-modal, DAC.

#	Tutorial
19	Guardrails / security basics
20	Checkpoint backends
26	Evaluation
29	Model providers
30	Guardrails (advanced)
38	Multi-modal providers (web, images, audio)
40	OCI Dedicated AI Cluster (DAC)

Real-world workflows¶

End-to-end use cases — incident response, contract review, audio chat.

#	Tutorial
46	On-call incident response
47	Tiered approval workflow
48	Contract review + negotiation
49	Voice output (TTS)
50	Voice in → voice out (gpt-audio)

Cognitive router & observability¶

Cognitive router + opt-in EventBus telemetry.

#	Tutorial
51	Cognitive router
52	Observability basics — opt-in SSE telemetry
53	Agent yield bridge + token usage
54	EventBus subscriber patterns
55	Full event catalogue tour