Skip to content

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

pip install "locus-sdk[oci,oracledb]"

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

from locus.agent import Agent

agent = Agent(model="oci:openai.gpt-5.5")
print(agent.run_sync("What is the capital of France?").text)
# → Paris
from locus.agent import Agent

agent = Agent(model="openai:gpt-4o")
print(agent.run_sync("What is the capital of France?").text)
# → Paris
from locus.agent import Agent

agent = Agent(model="anthropic:claude-sonnet-5-5")
print(agent.run_sync("What is the capital of France?").text)
# → Paris
from locus.agent import Agent

agent = Agent(model="ollama:qwen3")
print(agent.run_sync("What is the capital of France?").text)
# → Paris

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.

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.

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)

Notebook 73 — Support account gate →

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))

Notebook 77 — Incident response runbook →

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

Notebook 79 — Contract review →

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.

  • Pipelines


    SequentialPipeline, ParallelPipeline, LoopAgent: chain, fan out, or revise until a reviewer clears. Three lines each.

  • Orchestrator and specialists


    One coordinator delegates to typed specialists with their own tools, and merges what comes back.

  • Swarm


    Peers that hand work to each other on their own judgement, with a shared scratchpad and a hard stop.

  • Handoff


    Tiered escalation with typed context: L1 to L2 to L3, nothing lost in between.

  • StateGraph and functional API


    Nodes, edges, reducers, Send fan-out, interrupts for a human, and checkpointed state.

  • Debate and critic loops


    Two debaters and a judge, or a skeptical reviewer that rejects unproven claims before they ship.

  • Cognitive router


    Describe the task; the router extracts a typed GoalFrame, picks one of eight protocols and compiles it onto real agents.

  • Agent-to-agent (A2A) protocol


    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

Oracle Cloud, native

OCI Generative AI and Oracle Database are built into the runtime: same Agent, same events, same admission gate.

  • OCI Generative AI


    model="oci:…" picks the transport from the model id: V1 for OpenAI, Meta, xAI, Google; SDK for Cohere; the Responses transport is opt-in through OCIResponsesModel.

  • Dedicated AI Clusters


    oci:ocid1.generativeaiendpoint… as the model string targets your own Dedicated AI Cluster endpoint, with the compartment and auth resolved from your profile.

  • OCI tools


    use_oci() and describe_oci() put the OCI control plane behind tools, so an agent can list, inspect and act on your tenancy.

  • Oracle Database 26ai RAG


    OracleVectorStore on native VECTOR columns, hybrid search, plus in-database chunking and embeddings so text never leaves the database.

  • Oracle Database 26ai checkpoints and history


    oracle_checkpointer for durable threads, OracleCheckpointSaver for versioned history and time travel, OCI Object Storage as the alternative.

  • Oracle Database 26ai long-term memory


    OracleStore for cross-thread memory and OracleAgentMemoryManager over Oracle's official agent-memory client.

  • OCI GenAI Sandboxes


    OCISandboxBackend runs 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

oci:openai:anthropic:gemini:openrouter:together:runpod:groq:mistral:xai:deepseek:fireworks:cerebras:perplexity:nvidia:litellm:ollama:vllm:llamacpp:lmstudio:openai-compatible:
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()])

The harness

  • The coding 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 wrap gates every call.

  • Tools and MCP


    @tool on any function, typed arguments coerced from whatever the model sends, idempotent execution, Model Context Protocol (MCP) servers in or out.

  • Memory and RAG


    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.

  • Observability and streaming


    One run_context() streams typed events from every layer; Server-Sent Events (SSE) and token streaming for the UI.

  • Server and deploy


    locus serve puts an agent behind FastAPI with bearer auth and thread persistence; a multi-stage Dockerfile for OCI Kubernetes Engine (OKE) or any container host.

  • Skills, playbooks, evaluation


    Progressive-disclosure skills, enforced playbooks, and regression suites with EvalRunner so 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: ✓

Where next