NVIDIA-NeMo/labs-OO-Agents

NVIDIA‑labs Object Oriented Agents (NOOA)

What it is – NOOA is a model‑agnostic Python framework for building AI agents. It lets you write an agent as a normal Python class: fields hold state, regular methods are deterministic code, and methods whose body is just ... are agentic – they are filled in at runtime by an LLM based on the method’s signature and docstring.

Why it matters – By treating the whole agent as a single object, NOOA removes the need for separate prompt, tool, and workflow specifications that many other frameworks require. This makes agents easier to test, version‑control, and refactor with ordinary Python tooling.

Key ideas

Idea	What it gives you
Agents are Python objects	State lives on the instance, type hints become contracts, and docstrings become prompts.
`...` bodies become LLM‑driven methods	At call time the framework sends the signature and docstring to a language model, receives generated Python code, validates it, and executes it.
Typed I/O & auto‑retry	Input and output types are enforced, and the runtime will automatically retry failed generations.
Live‑object arguments	Methods can receive references to other objects, so the model can manipulate existing state directly.
Built‑in tracing	Every LLM request, code execution, and method call is recorded as a span; a CLI viewer can display the trace in a browser.
Modular extras	Optional packages add a CLI (`nooa-cli`), a memory subsystem, an Agent Client Protocol (ACP) client, and benchmark tools.

Installation

# Using uv (recommended)
uv init my-agent-project && cd my-agent-project
uv add nooa               # core framework
# optional extras
uv add "nooa[cli,memory]"   # CLI + long‑term memory

Or with pip:

pip install nooa

For the benchmark and evaluation utilities you can install directly from the repo:

uv add "eval_pipeline @ git+https://github.com/NVIDIA-NeMo/labs-OO-Agents.git@main#subdirectory=util/eval_pipeline"

Quick‑start example

import asyncio
from nooa import Agent
from nooa.unifiedllm.registry import get_llm_client

# 1️⃣ Pick a model (any LiteLLM‑compatible endpoint)
llm = get_llm_client("claude-haiku-4-5")   # set ANTHROPIC_API_KEY beforehand

# 2️⃣ Define an agent – the `...` marks a generation method
class FeedbackAgent(Agent, llm=llm):
    """You are an agent that analyses customer feedback."""

    async def analyze_feedback(self, text: str) -> str:
        """Return a one‑sentence sentiment summary and key topics."""
        ...

# 3️⃣ Run it
async def main():
    agent = FeedbackAgent()
    out = await agent.analyze_feedback("Great product, but shipping was slow")
    print(out)

asyncio.run(main())

Running the script prints a short LLM‑generated analysis. Changing the method name, parameters, or docstring changes the prompt automatically.

Safety notes

NOOA is research software; generated code can perform arbitrary actions. The framework does static AST checks and module deny‑lists, but these are not a security boundary.
Run agents in an OS‑level sandbox (container, VM, or NVIDIA OpenShell) when they execute generated code.
The library provides clear error messages when a generation would produce a stream (unsupported) or violate the contract.

When you might use NOOA

Rapid prototyping of LLM‑driven assistants where you want the agent’s state and capabilities expressed in ordinary Python.
Building tool‑using agents – the generated code can import modules, call other objects, or use the built‑in MemoryManager for long‑term context.
Research on agent architectures – the framework is model‑agnostic and includes a benchmark suite (nooa-bench) and evaluation pipeline.
Integrating with existing codebases – because agents are just classes, you can drop them into any Python project and test them with pytest.

Documentation & resources

[Full docs](https://github.com/NVIDIA-NeMo/labs-OO-Agents/blob/main/docs/README.md) – concepts, API reference, safety guide.
[10‑minute tour] – a concise walkthrough of the core ideas.
[Notebook tutorials] – Colab‑friendly notebooks for hands‑on learning.
[Examples catalog] – ready‑to‑run scripts showing structured output, tool use, decision models, tracing, etc.
[Paper](https://arxiv.org/abs/2607.20709) – design rationale and benchmark results.
[Blog post] – overview of the six “agent harness capabilities”.

Contributing & licensing

Open‑source under Apache 2.0.
Development uses uv for environment management; see CONTRIBUTING.md for the workflow, pre‑commit hooks, and test commands.
Cite the work with the provided BibTeX entry if you use NOOA in research.

Bottom line: NOOA gives you a pure‑Python way to write LLM‑backed agents that feel like ordinary classes, with built‑in typing, tracing, and optional memory/CLI extensions. It’s aimed at developers who want the flexibility of code‑generated behavior without abandoning standard software engineering practices.