Oracle Generative AI Agentic Harness · Locus, the locus-sdk package
Multi-agent workflows built for production · Built inside Oracle · Open source (UPL-1.0)
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.
Tools, memory, RAG, observability, guardrails, admit() in front of every consequential action. Pipelines, fan-out,
orchestrator, swarm, handoff, graphs, debate, A2A. OCI Generative AI on day 0, Dedicated AI Clusters, Oracle Database 26ai.
Documentation · Quickstart · Multi-agent shapes · OCI GenAI models · The admission gate · Notebooks
pip install "locus-sdk[oci,oracledb]"
export OCI_PROFILE=DEFAULT # a profile in ~/.oci/config with Generative AI accessfrom locus.agent import Agent
agent = Agent(model="oci:openai.gpt-5.5")
print(agent.run_sync("What is the capital of France?").text)
# → ParisLocus runs on Python 3.11 to 3.14. Swap oci:openai.gpt-5.5 for openai:gpt-5.5,
anthropic:claude-sonnet-5-5 or openrouter:x-ai/grok-4.7, each reading its key from the
environment; the call stays the same. With an OCI profile in ~/.oci/config, the notebooks in
examples/ run against OCI Generative AI with no further setup.
→ Quickstart · Notebook 02 — Basic agent · Notebook 03 — Agent with tools
Every shape runs the same Agent, emits the same events, and checkpoints to the same backends.
Pick the shape; the agents do not change.
| Shape | What it is | Where |
|---|---|---|
| Pipelines | SequentialPipeline, ParallelPipeline, LoopAgent: chain, fan out, revise until a reviewer clears |
Composition |
| Orchestrator and specialists | One coordinator delegates to typed specialists with their own tools and merges the results | Orchestrator |
| Swarm | Peers hand work to each other on their own judgment, shared scratchpad, hard stop | Swarm |
| Handoff | Tiered escalation with typed context, L1 to L2 to L3 | Handoff |
| StateGraph and functional API | Nodes, edges, reducers, Send fan-out (a node scatters work to parallel workers), interrupts for a person, checkpointed state |
StateGraph |
| Debate and critic loops | Two debaters and a judge; a skeptical reviewer that rejects unproven claims before they ship | Notebook 26 |
| Cognitive router | Typed GoalFrame from the task, one of eight protocols, compiled onto real agents; a request too risky for its shape is held for approval, not refused |
Notebook 29 |
| Agent-to-agent (A2A) and DeepAgent | Cross-process agents as spec-compliant peers; plan, explore, validate, report with grounding | A2A · DeepAgent |
import asyncio
from locus.agent import Agent
from locus.agent.composition import SequentialPipeline
model = "oci:openai.gpt-5.5"
diagnose = Agent(model=model, tools=[query_metrics, search_logs], system_prompt="Find what changed.")
mitigate = Agent(model=model, tools=[scale_up, rollback], system_prompt="Fix it, smallest step.")
brief = Agent(model=model, system_prompt="Write the status update.")
war_room = SequentialPipeline(agents=[diagnose, mitigate, brief])
result = asyncio.run(war_room.run("checkout p99 hit 4.2s: fix and brief"))
print(result.final_output)The cognitive router picks the shape from the task: a Router extracts a typed GoalFrame,
selects one of the eight registered protocols and compiles it onto real agents (Notebook 29
builds one):
result = await router.dispatch("Diagnose the checkout API slowdown.")
print(result.protocol_id) # "specialist_fanout"→ Multi-agent overview · Notebook 19 — Composition · Notebook 22 — Orchestrator · Notebook 29 — Cognitive router
OCI Generative AI and Oracle Database are built into the runtime: same Agent, same events, same
admission gate.
| Primitive | What it gives you |
|---|---|
| OCI Generative AI | model="oci:…" picks the transport from the model id: the OpenAI-compatible V1 endpoint for the OpenAI, Meta, xAI, Mistral and Google families, the OCI SDK for Cohere and for Dedicated AI Cluster endpoints; the Responses transport is opt-in through OCIResponsesModel. A model OCI adds is a new string, with no Locus release needed (day 0). Auth from your OCI profile, a session token, or instance / resource principals. |
| Dedicated AI Clusters | model="oci:ocid1.generativeaiendpoint…" targets your own Dedicated AI Cluster (DAC) endpoint. |
| 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. pip install "locus-sdk[oci-sandbox]". |
| OCI tools | use_oci() / 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(N, FLOAT32) columns, VECTOR_DISTANCE, HNSW / IVF, hybrid search; OracleInDBChunker and OracleInDBEmbeddings so text never leaves the database; OracleADBLoader to ingest from ADB tables. |
| 26ai checkpoints and history | oracle_checkpointer for durable threads, OracleCheckpointSaver for versioned history and time travel; OCIBucketBackend on Object Storage as the alternative. |
| 26ai long-term memory | OracleStore for cross-thread memory and OracleAgentMemoryManager over Oracle's official oracleagentmemory client. |
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()])→ OCI GenAI models · Dedicated AI Clusters · Oracle Database 26ai · OCI GenAI Sandboxes · Notebook 01 — OCI transports · Notebook 38 — Oracle 26ai RAG · Notebook 42 — Oracle 26ai checkpointer · Notebook 44 — Oracle agent memory
| Layer | What it gives you |
|---|---|
| The coding harness | The toolset a coding agent works with (read, write, edit, grep, a shell), written once against a workspace protocol and run unchanged on the host, inside an OCI GenAI Sandbox in your tenancy or inside NVIDIA OpenShell; one wrap gates every call. pip install "locus-sdk[oci-sandbox]" adds the sandbox client. |
| Tools and MCP | @tool on any function; arguments coerced to the declared types whatever the model sends; @tool(idempotent=True) dedupes on (name, args); MCPClient consumes Model Context Protocol (MCP) servers and LocusMCPServer exposes yours. |
| Memory | Checkpoint backends for Oracle Database 26ai (with its versioned saver), OCI Object Storage, PostgreSQL, MySQL, Redis, OpenSearch, S3-compatible object stores, HTTP, a local file, in-memory; OracleStore, Oracle agent memory, the portable LLMMemoryManager for long-term memory. |
| RAG | Six vector stores (Oracle 26ai, pgvector, Qdrant, Chroma, OpenSearch, in-memory); OCI, in-database, OpenAI and Cohere embeddings; OCI Cohere, local and Cohere rerankers; retriever.as_tool(). |
| Grounded reasoning | Grounding-Stratified Adaptive Replanning (GSAR) partitions every claim as grounded, ungrounded, contradicted or complementary against typed evidence; below threshold the agent regenerates, replans or abstains. Reflexion, when enabled, scores every turn: the agent assesses its own progress from the tool results and adjusts. |
| Guardrails and the admission gate | Input, output and tool-call guardrails, steering (LLM-as-judge), trace hygiene, and admit() / approve(): allow, hold for a human, or deny, on a hash-chained audit trail. |
| Observability and streaming | Opt-in EventBus; one run_context() streams typed events from every layer; Server-Sent Events (SSE) and token streaming; OpenTelemetry hook. |
| Server and deploy | locus serve / AgentServer (FastAPI, bearer auth, POST /invoke, POST /stream, threads); a multi-stage Dockerfile for OCI Kubernetes Engine (OKE) or any container host; the box runner (python -m locus.runner) runs one agent's loop inside an NVIDIA OpenShell sandbox for a Locus gateway. |
| Skills, playbooks, evaluation, testing | Progressive-disclosure skills, enforced playbooks, EvalCase / EvalRunner / EvalReport regression suites; locus.testing model doubles (ScriptedModel, FunctionModel) and AgentTestClient for deterministic tests with no API key. |
| Model providers | oci:, openai:, anthropic: native; gemini:, openrouter:, together:, runpod:, groq:, ollama:, vllm: and 11 more OpenAI-compatible routes; failover chains, credential pooling, prompt-cache breakpoints. |
Every backend is an optional extra — install only what you use: pip install "locus-sdk[oci,oracledb]"
for the Oracle stack, [oci-sandbox] for OCI GenAI Sandboxes, [openshell] for NVIDIA OpenShell,
[server] for AgentServer, [mcp] for MCP, [qdrant,s3,rerank-local] and the other extras in
pyproject.toml as needed. 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.").text)
backend.close() # the sandbox is stopped and deletedA prompt rule is advisory; admit() is structural: the gate wraps the tool, so the side-effecting
call runs only after it clears a ControlPolicy you wrote, whatever the model asks for.
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 intactpip install locus-sdk && python -m locus.rogue
# an interactive challenge: talk the agent into wipe_database and watch the gate hold
# 🛡️ wipe_database → deny: labels ['irreversible'] are denied by policy; …
# FINAL SCORE · dangerous attempts: 1 · 💥 BREACHES: 0 · audit chain intact: ✓Put the same gate around an agent loop you already have, whatever it is built on, or build on the full runtime.
→ How the admission gate works · First controlled action · Notebook 71 — Payment refund gate
The notebooks are numbered in reading order: start here (01–11), multi-agent shapes (12–32),
Oracle Cloud and Database 26ai (33–45), the harness (46–59), observability, streaming and
serving (60–67), control layer and security (68–76) and real-world workflows (77–80) live in
examples/; the security-operations notebooks (81–89) ship with the
opt-in locus-sdk-security package, installed from
the repository at the matching tag. Notebooks 01–80 run against OCI Generative AI with an OCI
profile, or the bundled mock model without one; 81–89 run on the mock model, or on OpenAI or
Anthropic through LOCUS_MODEL_PROVIDER.
git clone https://github.com/oracle/locus.git
cd locus && pip install -e ".[oci,oracledb]"
python examples/notebook_01_oci_transports.py # the three OCI GenAI transports
python examples/notebook_02_basic_agent.py # your first agent
python examples/notebook_19_composition.py # pipelines
python examples/notebook_29_cognitive_router.py # the cognitive router
python examples/notebook_38_oracle_26ai_rag.py # RAG on Oracle Database 26aiTo serve an agent, AgentServer wraps it as a FastAPI app (pip install "locus-sdk[server]") and
the repo ships a multi-stage Dockerfile:
import os
from locus.server import AgentServer
AgentServer(agent=my_agent, api_key=os.environ["API_KEY"]).run(host="0.0.0.0", port=8080)OpenAI Codex builds on Locus. The repository ships a Codex
skill, .agents/skills/locus/, that
teaches it the SDK: Agent and @tool, the admission gate, the multi-agent shapes, memory and RAG,
the coding harness, the providers, and how to test an agent offline. locus codex puts the skill
where Codex looks and starts Codex with the sandbox settings it needs:
pip install "locus-sdk[oci]"
locus codex run "Build a support agent with an order lookup and a gated refund tool, with tests"In a clone, codex/PROMPT.md drives
Codex through a first agent with a typed tool, an admission gate allowing, holding and denying, and
the rogue-agent challenge, on OCI Generative AI, OpenAI, Anthropic or offline;
codex/SPEC.md is written for a person
to follow by hand as well:
git clone https://github.com/oracle/locus.git && cd locus
codex -s workspace-write -c sandbox_workspace_write.network_access=true "$(cat codex/PROMPT.md)"Codex itself can run on OCI Generative AI:
examples/codex-on-oci/ is a
loopback gateway that signs Codex's calls with your OCI profile, so neither Codex nor the agent it
builds needs an account outside Oracle Cloud.
codex/scenarios/ is a series of twelve
tasks Codex builds from the skill alone, each with an automatic check, and the runner that executes
them: the proof that the skill produces correct applications, and the way a change to the SDK or to
the skill is tried before a release.
src/locus/
├── agent/ Agent runtime, config, Sequential / Parallel / Loop pipelines
├── multiagent/ Orchestrator, Swarm, Handoff, StateGraph, Functional
├── router/ Cognitive router — GoalFrame, ProtocolRegistry, PolicyGate, CognitiveCompiler
├── a2a/ Cross-process Agent-to-Agent protocol
├── deepagent/ create_deepagent + create_research_workflow + node primitives
├── core/ AgentState, Message, events, termination algebra, Send
├── models/ Provider registry + OCI GenAI (V1 / SDK / Responses), OpenAI, Anthropic
├── memory/ BaseCheckpointer + backends (Oracle 26ai, OCI Object Storage, …), stores, memory managers
├── rag/ Embeddings + 6 vector stores (Oracle 26ai, …) + rerankers + loaders + chunkers
├── tools/ @tool decorator, registry, builtins, executors, OCI tools
├── harness/ Coding harness: workspace tools over LocalBackend, OCISandboxBackend, OpenShellBackend; build_harness(wrap=…)
├── reasoning/ Reflexion, Grounding, Causal, GSAR
├── control/ Admission gate, policy, audit trail, grounded findings, verification
├── decision/ Typed decisions (choice, yes/no, score) with probabilities
├── hooks/ Logging, telemetry, retry, guardrails, steering
├── observability/ EventBus, run_context, agent yield bridge, EV_* constants
├── skills/ AgentSkills.io filesystem-first capability disclosure
├── playbooks/ Declarative step plans + PlaybookEnforcer
├── providers/ Multi-modal: web search, web fetch, image, speech
├── server/ FastAPI AgentServer with thread persistence
├── evaluation/ EvalCase + EvalRunner + EvalReport
├── integrations/ MCP (client + server)
├── durable/ Durable execution for agent runs (Temporal, DBOS)
├── streaming/ Stream handlers: console, SSE, structured
├── voice/ Realtime speech-to-speech sessions; tool calls go through the gate
├── runner/ Box runner (`python -m locus.runner`): one agent's loop in an NVIDIA OpenShell sandbox
├── cli.py The `locus` command line: run, resume, approvals, audit verify, serve
├── testing.py Model doubles (ScriptedModel, FunctionModel) and AgentTestClient
└── rogue/ The rogue-agent challenge (`python -m locus.rogue`)
The docs site lives in docs/ (mkdocs.yml, theme in overrides/, build
hooks in hooks/) and publishes to locusagents.ai. The opt-in security
package lives in packages/locus-sdk-security/; it is
not on PyPI and installs from the repository at the matching tag (see its
README).
git clone https://github.com/oracle/locus.git
cd locus && pip install -e ".[dev,sdk]"
hatch run check # ruff format-check, ruff lint, mypy, unit tests under the coverage gate
hatch run test # unit tests on the active Python (CI runs them on 3.11–3.14)
pre-commit installSee CONTRIBUTING.md. Contributions need the Oracle Contributor Agreement; every PR runs format, lint, mypy, unit tests and the OCA check. Questions and bug reports go to GitHub Issues; CHANGELOG.md lists what changed in each release. Please consult the security guide for vulnerability disclosure.
Locus's GSAR layer is based on the method described in F. A. Kamelhar, GSAR: Typed Grounding for Hallucination Detection and Recovery in Multi-Agent LLMs (PDF), arXiv:2604.23366, 2026. The paper is separate from this project; if you use the method, cite it directly:
@article{kamelhar2026gsar,
author = {Kamelhar, Federico A.},
title = {GSAR: Typed Grounding for Hallucination Detection and Recovery in Multi-Agent LLMs},
journal = {arXiv preprint arXiv:2604.23366},
year = {2026},
url = {https://arxiv.org/abs/2604.23366},
}Copyright (c) 2025, 2026 Oracle and/or its affiliates.
Released under the Universal Permissive License v1.0 — see LICENSE and
THIRD_PARTY_LICENSES.txt. Releases 1.0.0 – 2.28.0 were
published as tulip-agents under the Apache License 2.0 while the project was developed
outside Oracle; they remain available under that license from their tags. See
PROVENANCE.md.