Docs · Quick Start · Notebook Tutorials · Examples · Paper · Blog
NVIDIA-labs Object Oriented Agents (NOOA) is a model-agnostic Python framework designed to support reliable AI agent development. Many agent frameworks represent prompts, tools, callbacks, and workflows as separate abstractions. NOOA offers an alternative object-oriented interface that brings these concepts together in a Python class. NOOA lets developers express an agent’s state, capabilities, prompts, and typed interfaces through a single Python class:
from nooa import Agent
# The agent is a Python object.
class SupportAgent(Agent):
"""You are a support agent."""
# State lives on the object. Fields are typed.
order_db: OrderDB
# Ordinary method. Just Python.
def is_refund_eligible(self, order: Order) -> bool:
return order.delivered and order.days_since_delivery <= 30
# Agentic method: the runtime hands this to an LLM.
async def triage(self, message: str, order: Order) -> Ticket:
"""Create a typed support ticket."""
...
What's happening here:
- Agents are Python objects. Fields are state, methods are capabilities, docstrings are prompts, type annotations are contracts.
... bodies are LLM-driven. A method with ... becomes an agentic loop; a real body stays deterministic Python.- Generation commits one result. Deterministic generators are supported, but generated streams need a separate stream contract and are rejected clearly.
- Code as action. The model acts by writing Python in a Jupyter-style REPL with access to
self, imports, and helpers — Python methods and type annotations supply the callable interfaces, reducing the need to write separate tool-schema definitions.
- Pythonic and agent-ready. Typed I/O with auto-retry, live-object arguments passed by reference, and model-callable context and event APIs — designed around agent-oriented Python workflows.
This design supports familiar Python testing, tracing, refactoring, and version-control workflows — just like the rest of your software. Read the paper for the design principles and evaluation results.
Want to see how the pieces compose? Take the 10-minute tour, from one thinking method through tools, typed contracts, deterministic orchestration, and object composition.
Installation
Add the core framework to a new (or existing) Python project with uv:
uv init my-agent-project
cd my-agent-project
uv add nooa
Windows: use WSL 2. Native Windows is not supported: import nooa and the nooa command stop with an error that points to WSL 2. Setting NOOA_SKIP_PLATFORM_CHECK=1 skips that check. The pure-Python core (agents, PredictStrategy, in-process CodeAct, in-memory storage) and nooa connect are tested on native Windows. Other features may work but are unsupported; those that need POSIX (shell tools, the CodeAct sandbox, file-backed SQLite storage, monitor()) stop with a PosixOnlyFeatureError.
The CLI, ACP, memory, and benchmark packages are separate distributions. Install
them by name, or pull them in as extras of the core package:
uv add nooa-cli # or: uv add "nooa[cli]"
uv add nooa-acp # or: uv add "nooa[acp]"
uv add nooa-memory # or: uv add "nooa[memory]"
uv add nooa-bench # or: uv add "nooa[bench]"
uv add "nooa[cli,memory]" # several at once
| Package | Extra | What it adds |
|---|
nooa-cli | nooa[cli] | the nooa command, trace-viewer command, eval runner |
nooa-acp | nooa[acp] | deprecated, replaced by nooa-atom (last release): coding agent for Agent Client Protocol hosts such as Zed — setup |
nooa-memory | nooa[memory] | long-term memory subsystem (MemoryManager) |
nooa-bench | nooa[bench] | BenchAgent and the Harbor benchmark runner |
For eval_pipeline, follow the Contributing instructions to clone
the repo and run uv sync --group dev. This installs it editable with the other
workspace packages.
# latest development state
uv add "nooa @ git+https://github.com/NVIDIA-NeMo/labs-OO-Agents.git@main"
# pinned to a release tag
uv add "nooa @ git+https://github.com/NVIDIA-NeMo/[email protected]"
This is the beginning of the README. Read the rest at the original. Read the full README ↗
