Oracle Generative AI Multi-Agent Reasoning Orchestrator SDK
Multi-agent workflows built for production.¶
One Agent class, eight ways to combine agents, Oracle Cloud underneath. Around the model, the agentic harness; around the code an agent writes, an OCI GenAI Sandbox in your tenancy.
- The agentic harness. Tools, memory, RAG, observability, guardrails. Durable threads, typed events, claims checked against evidence.
admit()in front of every consequential action: allow, hold for a person, deny, on a hash-chained audit trail. - The coding harness, sandboxed. Read, write, edit, search, a shell, on the host or inside an OCI GenAI Sandbox: isolated Linux, created in seconds, expiring on its own. Every call gated, every command recorded.
- Eight multi-agent shapes. Pipelines, fan-out, orchestrator, swarm, handoff, graphs, debate, A2A, each running the same
Agent. A cognitive router picks one from the task. - Oracle Cloud, native. OCI Generative AI on day 0, Dedicated AI Clusters, Oracle Database 26ai for vectors, threads, memory.
Quickstart Multi-agent shapes GitHub
Built inside Oracle · Open source (UPL-1.0)
from locus.agent import Agent
from locus.agent.composition import (
SequentialPipeline,
)
model = "oci:openai.gpt-5.5" # OCI, day 0
diagnose = Agent(
model=model,
tools=[query_metrics, search_logs],
system_prompt="Find what changed.",
)
mitigate = Agent(
model=model,
tools=[scale_up, rollback], # admit()
system_prompt="Fix it, smallest step.",
)
brief = Agent(
model=model,
system_prompt="Write the update.",
)
war_room = SequentialPipeline(
agents=[diagnose, mitigate, brief],
)
result = await war_room.run(
"checkout p99 hit 4.2s: fix and brief"
)
print(result.final_output)
Your first agent¶
Pick a provider above; the call does not change. With an OCI profile in
~/.oci/config, every notebook runs against OCI Generative AI with no further
setup.
The Agent → · Notebook 02 — Basic agent → · Notebook 03 — Agent with tools →
Build it with Codex¶
OpenAI Codex builds on the SDK. The
repository ships a Codex skill that teaches it the SDK: the Agent and its
tools, the admission gate, the multi-agent shapes, memory and RAG on Oracle
Database 26ai, the coding harness, the model providers, offline tests with
model doubles. locus codex puts the skill where Codex looks and starts
Codex with the sandbox settings it needs. Codex itself can run on OCI
Generative AI through a loopback gateway in the repository, so neither Codex
nor the agent it builds needs an account outside Oracle Cloud.
pip install "locus-sdk[oci]"
locus codex run "Build a support agent with an order lookup and a gated refund tool, with tests"
A scenario series proves it: twelve tasks Codex builds from the skill alone,
from a gated refund with its audit trail to an agent served over HTTP, each
with an automatic check. In a clone, codex/PROMPT.md walks Codex through a
first agent with a typed tool, an admission gate allowing, holding and
denying, and the rogue-agent challenge, each step with a checkpoint a person
can follow by hand.
Build it with Codex → ·
The Codex skill → ·
Codex on OCI Generative AI → ·
The scenarios → ·
codex/ in the repository →
What are you building?¶
Each tab shows one workload in a few lines and links to the notebook that runs the full example.
A support agent credits customer accounts to resolve tickets; admit()
runs before each write, so a credit over the policy's limit is held for a
human and every decision, allowed or held, lands on the audit trail,
whatever the prompt asked for.
from locus.agent import Agent
from locus.tools import tool
from locus.control import Action, AuditTrail, ControlPolicy, gate_tool
@tool
async def apply_credit(account: str, usd: float) -> str:
"""Credit a customer account."""
return await billing.credit(account, usd)
policy = ControlPolicy(require_human_over_usd=50, require_verification_score=0)
gated = gate_tool( # no finding to verify here; the amount decides
apply_credit, policy=policy, trail=AuditTrail(),
action=lambda name, a: Action(name, a["account"], cost_usd=a["usd"]))
agent = Agent(model="oci:openai.gpt-5.5", tools=[gated])
print(agent.run_sync("SUP-7782: apply a $500 retention credit.").text)
An on-call runbook as a StateGraph: triage grades the page, three
investigators fan out in parallel, a synthesizer names the likely cause,
and on a critical grade the run halts at interrupt(), so the mitigation
agent is not reached until a human resumes it with Command(resume=...).
from locus.agent import Agent
from locus.core import Command, interrupt
from locus.multiagent.graph import StateGraph
agent = Agent(model="oci:openai.gpt-5.5", system_prompt="Propose one mitigation.")
async def page_human(state): # critical only; a human answers yes or no
return {"approved": interrupt(state["hypothesis"]) == "yes"}
async def mitigate(state):
return {"mitigation": (await agent.arun(state["hypothesis"])).message}
def severity_gate(state): # info and warn mitigate on their own
return "page_human" if state["severity"] == "critical" else "auto_mitigate"
g = StateGraph(name="incident-runbook") # earlier nodes as in the notebook
g.add_node("page_human", page_human).add_node("auto_mitigate", mitigate)
g.add_edge("page_human", "auto_mitigate")
g.add_conditional_edges("synthesize", severity_gate)
run = await g.execute({"symptom": "checkout p99 latency 8x, 12% 503s"})
if run.interrupt: # paused at page_human until a human answers
run = await g.execute(Command(resume="yes", update=run.final_state))
Reviewers read a vendor data-processing agreement, a gate rule pauses for
human counsel while any blocker is open and re-reviews the redline, and
the sign-off is a ContractDecision: the SDK validates it against the
schema, feeds validation errors back to the model for repair, and
otherwise returns parsed=None with the parse error, never an
unvalidated record.
from pydantic import BaseModel, Field
from locus.agent import Agent
class ContractDecision(BaseModel):
open_blockers: list[str]
decision: str = Field(description="signed | rejected | abandoned")
def negotiation_gate(state: dict) -> str: # "negotiate" pauses for counsel
return "negotiate" if state["open_blockers"] else "sign_off"
legal = Agent(model="oci:openai.gpt-5.5", system_prompt="List blockers.")
dpo = Agent(model="oci:openai.gpt-5.5", output_schema=ContractDecision)
findings = (await legal.arun(f"DPA clauses:\n{clauses}")).message
decision = (await dpo.arun(f"Findings:\n{findings}")).parsed
One Agent, every shape¶
Every shape runs the same Agent, emits the same events, and checkpoints to
the same backends. Pick the shape; the agents do not change.
-
SequentialPipeline,ParallelPipeline,LoopAgent: chain, fan out, or revise until a reviewer clears. Three lines each. -
One coordinator delegates to typed specialists with their own tools, and merges what comes back.
-
Peers that hand work to each other on their own judgement, with a shared scratchpad and a hard stop.
-
Tiered escalation with typed context: L1 to L2 to L3, nothing lost in between.
-
Nodes, edges, reducers,
Sendfan-out, interrupts for a human, and checkpointed state. -
Two debaters and a judge, or a skeptical reviewer that rejects unproven claims before they ship.
-
Describe the task; the router extracts a typed
GoalFrame, picks one of eight protocols and compiles it onto real agents. -
Cross-process agents as spec-compliant peers: expose yours, call theirs, same tool contract.
-
DeepAgent and research workflows
Plan, explore, validate, report, with per-turn grounding and a post-hoc grounding evaluation.
result = await router.dispatch("Diagnose the checkout API slowdown.")
print(result.protocol_id) # "specialist_fanout"
print(result.text) # findings from 3 parallel probes
Multi-agent overview → · Notebook 19 — Composition → · Notebook 22 — Orchestrator → · Notebook 29 — Cognitive router →
Oracle Cloud, native¶
OCI Generative AI and Oracle Database are built into the runtime: same Agent,
same events, same admission gate.
-
model="oci:…"picks the transport from the model id: V1 for OpenAI, Meta, xAI, Google; SDK for Cohere; the Responses transport is opt-in throughOCIResponsesModel. -
oci:ocid1.generativeaiendpoint…as the model string targets your own Dedicated AI Cluster endpoint, with the compartment and auth resolved from your profile. -
use_oci()anddescribe_oci()put the OCI control plane behind tools, so an agent can list, inspect and act on your tenancy. -
OracleVectorStoreon nativeVECTORcolumns, hybrid search, plus in-database chunking and embeddings so text never leaves the database. -
Oracle Database 26ai checkpoints and history
oracle_checkpointerfor durable threads,OracleCheckpointSaverfor versioned history and time travel, OCI Object Storage as the alternative. -
Oracle Database 26ai long-term memory
OracleStorefor cross-thread memory andOracleAgentMemoryManagerover Oracle's official agent-memory client. -
OCISandboxBackendruns the coding harness inside an isolated, expiring Linux workspace in your tenancy: the model's shell commands and file edits never touch the host, and every call still clears the gate.
OCI Generative AI first: oci: reaches the whole catalog (OpenAI, Google, Meta,
xAI, Cohere) and your Dedicated AI Clusters, so a new model is a new string, not
new code. Everything else that speaks the OpenAI API plugs in behind a prefix,
hosted or self-hosted.
One model string, any provider
from locus.agent import Agent
from locus.rag import OCIEmbeddings, OracleVectorStore, RAGRetriever
Agent(model="oci:openai.gpt-5.5") # V1 transport
Agent(model="oci:cohere.command-a-03-2025") # SDK transport, auto-routed
Agent(model="oci:ocid1.generativeaiendpoint.oc1...") # your Dedicated AI Cluster
retriever = RAGRetriever( # Oracle Database 26ai
embedder=OCIEmbeddings(model_id="cohere.embed-v4.0"),
store=OracleVectorStore(dsn="mydb_low", user="locus_app", password="…",
wallet_location="~/.oci/wallets/mydb", dimension=1536),
)
agent = Agent(model="oci:openai.gpt-5.5", tools=[retriever.as_tool()])
Oracle Database 26ai, every primitive → · Which OCI models work → · Configure any provider → · Dedicated AI Clusters → · Oracle Database 26ai notebooks →
The harness¶
-
Read, write, edit, grep and a shell over one workspace protocol, run on the host, in an OCI GenAI Sandbox or in NVIDIA OpenShell; one
wrapgates every call. -
@toolon any function, typed arguments coerced from whatever the model sends, idempotent execution, Model Context Protocol (MCP) servers in or out. -
Four layers: working memory, the thread (checkpoint backends from local files to Oracle Database 26ai), long-term memory across threads, and knowledge through RAG (six vector stores, rerankers,
retriever.as_tool()). All four on Oracle Database 26ai. -
Grounding, guardrails, admission gate
Grounding-Stratified Adaptive Replanning (GSAR) checks every claim against evidence; guardrails and steering catch the rest;
admit()holds or denies consequential actions. -
One
run_context()streams typed events from every layer; Server-Sent Events (SSE) and token streaming for the UI. -
locus serveputs an agent behind FastAPI with bearer auth and thread persistence; a multi-stageDockerfilefor OCI Kubernetes Engine (OKE) or any container host. -
Progressive-disclosure skills, enforced playbooks, and regression suites with
EvalRunnerso behaviour does not drift.
A coding agent in an OCI GenAI Sandbox is one backend away from the same harness that runs on your laptop:
from locus.agent import Agent
from locus.control import ControlPolicy, gate_tool
from locus.harness import OCISandboxBackend, build_harness
backend = OCISandboxBackend.create("ocid1.generativeaiproject.oc1...", expiration="PT1H")
policy = ControlPolicy(
require_verification_score=0.0, require_human_for=frozenset({"workspace.exec"})
)
harness = build_harness(
backend, wrap=lambda tool, spec: gate_tool(tool, policy=policy, action=spec)
)
agent = Agent(
model="oci:openai.gpt-5.5", tools=harness.tools, system_prompt=harness.prompt_fragment
)
print(agent.run_sync("Add pytest tests for calc/ and run them.").message)
backend.close() # the sandbox is stopped and deleted
The coding harness → · OCI GenAI Sandboxes → · NVIDIA OpenShell →
Control, when you need it¶
The admission gate is one call around the agent you already have, or built in:
from locus.control import governed_agent
agent = governed_agent(model="oci:openai.gpt-5.5", tools=[...])
print(agent.run_sync("Refund order 8812 if the return was received.").text)
assert agent.audit_trail.verify() # the chain is intact
pip install locus-sdk && python -m locus.rogue
# 🛡️ wipe_database → deny: labels ['irreversible'] are denied by policy
# FINAL SCORE · dangerous attempts: 1 · BREACHES: 0 · audit chain intact: ✓
How the admission gate works → · First controlled action → · Notebook 71 — Payment refund gate →
Where next¶
All notebooks → · Build it with Codex → · Capabilities → · API reference → · Deploy →