Standard for creating technical documentation in this repository. Use this when writing new documentation in docs/ to ensure consistent hierarchy and formatting.

2026-02-022

mermaid-diagrams

FullFran/Hybrid-RAG-example

Expert guidance on creating accurate, visually polished Mermaid diagrams for architecture documentation.

2026-02-022

mongodb

FullFran/Hybrid-RAG-example

Expert guidance on MongoDB implementation for RAG, including aggregation pipelines and search patterns.

2026-02-022

pydantic-ai

FullFran/Hybrid-RAG-example

Expert guidance on building agents and tools with Pydantic AI.

2026-02-022

name	ai-orchestration-patterns
description	Apply AI orchestration patterns (routing, tool use, ReAct, fallbacks) to design reliable agent flows.
license	MIT
metadata	{"author":"OpenCode","version":"1.0"}

AI Orchestration Patterns

When to use

Designing agent flows, tool calling, or multi-step reasoning.
Adding fallbacks, routing, or safety checks for LLM behavior.
Improving observability and determinism of agent outcomes.

Core guidance

Separate decisioning from execution (planner vs. tool runner).
Prefer explicit tool schemas and clear system instructions.
Add guardrails: timeouts, max steps, and safe fallbacks.
Log decisions with enough context for debugging.

Do

Keep tool routing in services (not endpoints).
Define tool schemas close to the agent logic in src/services/.
Add conservative fallbacks when tool support is missing.

Don't

Let LLMs call tools without validation of arguments.
Mix orchestration logic into src/endpoints/.
Skip logging of tool calls, queries, and chosen paths.

Anti-patterns seen

Hidden state in scratchpads without logging.
Tool selection coupled to provider-specific formats.
Unlimited loops without max_steps or timeouts.

Repo anchors

src/services/agent_service.py
src/services/rag_service.py
src/services/context_builder.py

References

https://the-amazing-gentleman-programming-book.vercel.app/es/book/Chapter19_AI-Orchestration-Patterns