Agentic Accelerators¶

Location: inception_core/accelerators/

The accelerators layer provides two categories of reusable, runnable templates:

patterns_agentic/ — The 7 canonical AI agent design patterns, each as a standalone, executable Python file
patterns_solution/ — Enterprise security and integration reference patterns

Teams use these as starting points — copy, extend, and wire into your domain recipe without rebuilding from scratch.

Agentic Patterns (`patterns_agentic/`)¶

Pattern 1 — Augmented LLM (Foundation)¶

File: agent_with_augmented_llm.py

The base pattern every other pattern is built from. An LLM enhanced with three capabilities:

Retrieval — access relevant knowledge from vector stores or databases
Tools — execute actions, query APIs, run computations
Memory — retain context and state across turns

Retrieval ──┐
            ├──→ LLM (augmented) ──→ Memory
Tools ──────┘

When to use: Any agent that needs to know things it wasn't trained on, or take actions in external systems.

Pattern 2 — Prompt Chaining¶

File: agent_with_prompt_chaining.py

Decomposes a complex task into sequential LLM steps. Each call processes the output of the previous one. Quality gates (programmatic checks) can sit between steps and trigger retries or early termination.

Input → LLM₁ → Gate → LLM₂ → Output
                  ↓
                 Fail → retry / abort

When to use: Multi-stage document generation, structured data extraction pipelines, translation + review flows.

Pattern 3 — Routing¶

File: agent_with_routing.py

Classifies the input, then dispatches to a specialized handler with an optimized prompt for that category. Built with LangGraph conditional edges.

Input → Classifier → Route A → LLM_A → Output
                  → Route B → LLM_B → Output
                  → Route C → LLM_C → Output

When to use: Multi-intent chatbots, tiered support triage, domain-specific agent fleets where different inputs need different expertise.

Pattern 4 — Parallelization¶

File: agent_with_parallelization.py

Two sub-patterns:

Sectioning — split a large task into independent subtasks and run them concurrently
Voting — run the same task N times and merge results for confidence or quality

Input → ┌─ LLM₁ ─┐
        ├─ LLM₂ ─┤ → Merge → Output
        └─ LLM₃ ─┘

When to use: Long document summarization, parallel research on multiple topics, reliability-critical responses that benefit from consensus.

Pattern 5 — Orchestrator-Workers¶

File: agent_with_orchestrator_workers.py

A central orchestrator LLM dynamically decides what subtasks are needed, delegates to specialized worker agents, and synthesizes their results into a final response.

         Orchestrator
        /      |      \
  Worker₁  Worker₂  Worker₃
        \      |      /
         Synthesized output

When to use: Complex multi-step research tasks, code generation with review and test steps, any workflow where task decomposition should be dynamic rather than hardcoded.

Pattern 6 — Evaluator-Optimizer¶

File: agent_with_evaluator_optimizer.py

One LLM generates output; a second LLM evaluates it against quality criteria and provides structured feedback. The generator retries with the feedback until the criteria are met or max attempts reached.

Input → Generator → Evaluator → pass → Output
              ↑         |
              └─feedback─┘ (retry)

When to use: Content quality control, code correctness loops, structured data validation, anywhere you need iterative refinement.

Pattern 7 — Autonomous Agent¶

File: basic_agent.py

The LLM dynamically directs its own process — choosing which tools to call, planning steps, and reacting to tool results in a loop until the task is complete.

while not done:
    Input → LLM (decides) → Tools (execute) → feedback

Needs guardrails

This is the most powerful and hardest pattern to control. Always attach OCI Guardrails and human-in-the-loop approval for high-stakes tool execution.

Swarm — Peer-to-Peer Handoff¶

File: agent_swarm_pattern.py

A collaborative topology distinct from the 7 patterns above: instead of a central router or orchestrator deciding what happens next, every agent in the swarm can hand off control directly to any teammate. There is no dispatcher — the agents decide among themselves.

Fully connected (every agent can hand off to every other agent):

    Researcher <-> Reviewer
    Researcher <-> Architect
    Reviewer   <-> Architect
    Coder      <-> Researcher / Reviewer / Architect

Mechanics:

Each peer is a full create_oci_agent (ReAct), equipped with one transfer_to_<agent> tool per teammate.
Calling that tool returns a LangGraph Command(goto=<agent>, graph=Command.PARENT), which jumps control directly to the teammate's node in the parent swarm graph — no central node evaluates "who goes next."
All peers share the running message history and a common InMemoryStore/OracleStore for working memory, so any teammate can see what the others already found or decided.
Entry routing reads an active_agent field from state (defaulting to a designated entry peer on a new session) — the swarm graph itself never decides where to go next, only where the conversation currently is.

When to use: Multi-intent conversational surfaces where a single entry point (concierge/triage) needs to hand off fluidly between specialists, without hardcoding a fixed sequence — e.g. a banking assistant that moves between general Q&A, product questions, and a structured application flow within one session. See Meridian Bank for the production implementation: a 3-peer swarm (concierge / products / loan_application) where the third peer is deliberately not an LLM agent at all — it wraps a deterministic pipeline instead, so the platform's zero-LLM-discretion decision boundary (no model ever approves or declines a loan) survives inside a pattern that's otherwise fully agent-driven.

Non-obvious gotcha: InjectedState only sees the local graph

A tool inside a swarm peer's own create_oci_agent only ever sees that peer's narrow {"messages": [...]} state schema via Annotated[dict, InjectedState] — never the outer swarm's extra state fields (session id, an authenticated user's id, etc.), even though they were present in what the swarm passed into that node as input. If a peer's tool needs that context (e.g. a handoff tool's own audit log), set a module-level "turn context" from a thin per-node wrapper immediately before invoking the peer's compiled graph, rather than relying on injection. See meridian_swarm.py's _turn_context for the working pattern.

Human-in-the-Loop¶

File: human_in_loop.py

Demonstrates pausing agent execution for human approval before a sensitive tool call (e.g. sending an email) executes — the tool call is intercepted and requires an explicit confirmation step rather than firing immediately. Pair this with any Pattern 7 (Autonomous Agent) or swarm peer that can take an irreversible action.

Structured Output¶

File: agent_with_structured_output.py

Reference examples of with_structured_output(PydanticModel) against several schema shapes (nested models, enums, optional fields, lists) — the same mechanism metro/evals uses for its scorer verdicts and every recipe in this repo uses for entity extraction (e.g. normalizing free text or OCR output onto a fixed domain model).

Code Interpretation¶

File: agent_with_code_interpreter.py

Code interpreter tools let an agent write and execute code — usually Python — in a controlled, sandboxed environment, so it can compute, transform data, and produce real output instead of guessing at it in free text. This pattern wires the run_python sandbox tool (inception_core/libs/src/tools/python_scratchpad.py) into a short-term-memory ReAct agent (Pattern 1 shape).

Mechanics:

Reads are unrestricted; writes are confined to output/ under the tool's configured base directory — open() is monkey-patched to reject any resolved write path that falls outside it.
stdout/stderr are captured and returned alongside a result variable if the executed code sets one.
Every file created during execution is tracked and returned in files / file_urls / file_links.

Six turns exercise it end-to-end: arithmetic, an in-sandbox file write, a rejected out-of-sandbox write, a line chart, geometric shapes, and a labeled coordinate "map" with routes — all rendered to PNG.

When to use: Any agent task that needs real computation, data transformation, or chart/image generation rather than an LLM guessing at output — financial calculations, quick data visualizations, format conversions.

Note: The sandbox should have all the required python libraries for visualization pre-installed.

Memory Patterns¶

Short-Term Memory (agent_with_st_memory.py) — Thread-based in-memory checkpointing using LangGraph's built-in MemorySaver. Conversations persist within a process session.

Long-Term Memory (agent_with_lt_memory.py) — Oracle ADB-backed OracleDBSaver checkpointer. Conversations survive process restarts. Resume any session by thread ID.

Memory Store (agent_with_memory_store.py) — Oracle ADB-backed OracleStore virtual filesystem. Supports:

File read/write with hierarchical namespacing
Keyword and vector similarity search
Multi-agent shared access — every agent in the fleet sees the same store
Skills storage backend — skills are versioned files, lazy-loaded on demand

Memory-Aware Deep Research Agent¶

The flagship pattern — a batteries-included harness combining all of the above:

Component	Implementation
Core reasoning	LangGraph state machine
LLM inference	OCI GenAI (Cohere / LLaMA)
Tracing	LangFuse callback handler
Thread memory	`OracleDBSaver` checkpointer
Shared memory	`OracleStore` virtual filesystem
Skills	Lazy-loaded from memory store
Subagent fleet	Parallel agents sharing the store

Configuration:

# OCI credentials
OCI_CONFIG_FILE=~/.oci/config
CONFIG_PROFILE=DEFAULT
OCI_REGION=us-chicago-1
OCI_COMPARTMENT_ID=ocid1.compartment...

# LLM
OCI_GENAI_ENDPOINT=https://inference.generativeai...
OCI_GENAI_MODEL_ID=cohere.command-r-plus
OCI_EMBEDDING_MODEL=cohere.embed-english-v3.0

# Oracle ADB
ADB_USER=ADMIN
ADB_PASSWORD=<secret>
ADB_DSN=mydb_high
ADB_WALLET_LOCATION=./wallet
ADB_WALLET_PASSWORD=<secret>

# LangFuse
LANGFUSE_SECRET_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_BASE_URL=https://langfuse.your-domain.com

Solution Patterns (`patterns_solution/`)¶

Five reference implementations, each demonstrating one token_factory.TokenFactory target_tool end-to-end — from a browser login, through a per-request token exchange, to the downstream system (Oracle Database with VPD row-level security, OCI Object Storage, or OIC/EBS). Plus a client-credentials pattern for Oracle Fusion AI Agents that isn't token_factory-based, a zero-dependency IDCS browser-login package for any recipe's UI gateway (idcs_browser_login/), and a reusable multi-tool chat agent pattern for a recipe's conversational entry point (reference_chatbot/).

See Solution Patterns for the full architecture, token flow, and code for each.

Running pattern examples¶

From the inception_core/accelerators/patterns_agentic/ directory:

# Activate your environment
source .venv/bin/activate

# Run any pattern
python -m src.agent_with_augmented_llm
python -m src.agent_with_routing
python -m src.agent_with_orchestrator_workers
python -m src.agent_with_lt_memory
python -m src.agent_with_code_interpreter

# Run the full test suite
bash tests/test_run.sh

Most examples require .env to be populated with OCI credentials. agent_with_lt_memory.py (OracleDBSaver) and agent_with_memory_store.py (OracleStore) additionally require Oracle ADB connectivity via the AVD_* variables in .env (user, password, DSN, wallet location/password).

Which pattern should I use?¶

Not sure which of the 7 patterns fits your problem? Use this decision guide:

Your task looks like...	Start with
Single-turn Q&A with tool use	Pattern 1 — Augmented LLM
Multi-step document generation or transformation	Pattern 2 — Prompt Chaining
Different input types need different specialists	Pattern 3 — Routing
Independent subtasks that can run at the same time	Pattern 4 — Parallelization
Complex, unpredictable task that needs dynamic planning	Pattern 5 — Orchestrator-Workers
Output quality is the goal; correctness must be verified	Pattern 6 — Evaluator-Optimizer
Open-ended research or tool-use with no fixed steps	Pattern 7 — Autonomous Agent
Multi-intent conversation that needs fluid handoff between specialists, no fixed sequence	Swarm — Peer-to-Peer Handoff
Any pattern that needs to survive a process restart	Add Pattern — Long-Term Memory
Multiple agents sharing knowledge	Add Pattern — Memory Store
Needs real computation, data transforms, or chart/image generation	Add Pattern — Code Interpretation

Anti-patterns (what not to do)¶

Situation	Don't do this	Do this instead
Building on OCI Wayflow (Oracle's managed workflow service)	Plug in LangGraph memory primitives — state management is incompatible	Use Wayflow-native state management, or move off Wayflow to LangGraph entirely
Integrating with Oracle Fusion Studio / Enterprise AI Projects	Build a custom LangGraph agent that reimplements its logic	Use the `async_invoke_fusion_agents` pattern to call Fusion Studio agents from LangGraph
Sharing credentials across agents	Use a shared service account in every agent	Use IAM identity propagation — each agent call carries the end user's own token
Deploying Pattern 7 (Autonomous Agent) without safety controls	Ship without a guardrail policy	Always attach `OCIGuardrails` handler and enable HITL for any tool that mutates data
Hardcoding model IDs in agent files	`model = "cohere.command-r-plus"` scattered everywhere	Import `LLMFactory.get_chat_model()` — change the model in one env var
Swarm peers that each own their own checkpointer	Independently-invoked compiled graphs sharing one raw `thread_id` on the same `OracleDBSaver` storage — they silently collide on checkpoint storage	Namespace the inner pipeline's own thread ids (e.g. `f"loan-intake::{session_id}"`) distinctly from the outer swarm's own `session_id`, so unrelated compiled graphs never share a `(thread_id, checkpoint_ns)` key