NovaAgents

NovaAgents (novaagents) is a production-oriented agent harness for building stateful AI agents with managed sessions, context management, skills, subagents, and long-term memory.

Provenance: NovaAgents is derived from Deep Agents (LangChain). It keeps compatibility where practical, but it is an independent package with Nova-specific APIs and behavior.

Installation

Install from PyPI (recommended, once published):

pip install novaagents
# or
uv add novaagents

For local development, run from the repository root:

uv sync --all-groups

Optional extras:

pip install "novaagents[aws]"    # AWS Bedrock support
pip install "novaagents[video]"  # video/media helpers (av, pillow)

Quickstart

Use create_nova_agent for the Nova graph. create_deep_agent is a separate compatibility factory with the inherited behavior.

from novaagents import create_nova_agent
from langchain.chat_models import init_chat_model

model = init_chat_model("anthropic:claude-sonnet-4-6")

agent = create_nova_agent(
    model=model,
    system_prompt="You are a concise, reliable assistant.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Summarize this repository."}]}
)
print(result["messages"][-1].content)

Managed Sessions (Nova-specific)

NovaSession supervises local background tasks and serializes parent invocations. Pass it a compiled Nova graph:

import asyncio
from novaagents import NovaSession

async def main():
    # Use the agent constructed in the quickstart above.
    async with NovaSession(agent, thread_id="demo-001") as session:
        result = await session.ainvoke({
            "messages": [{"role": "user", "content": "List files in / and summarize the project."}],
        })
        print(result["messages"][-1].content)
        await session.wait_until_idle()

asyncio.run(main())

See MANAGED_SESSIONS.md for lifecycle, resume, and background-task behavior. Persistence across restarts requires a persistent checkpointer and the appropriate backend. Local background workers live only for the current process.

Nova Features

NovaAgents includes capabilities layered on the Deep Agents foundation:

• create_nova_agent: Nova graph assembly with Nova middleware defaults.
• NovaSession: local background task supervision and serialized conversation execution.
• Context & managed skills middleware: Nova-specific context loading/handling and skill behavior (see novaagents.middleware).
• Subagents / delegation: task decomposition via LangGraph subagent patterns.
• Filesystem & stateful workflows: tool-driven file operations and checkpointed agent state.
• Long-term memory patterns: memory-backed workflows depending on configured backend/tools.

Compatibility APIs from the upstream lineage may still exist; prefer Nova APIs for new integrations and verify behavior against this repository's tests/docs.

Development

# install dev/test deps (example)
uv sync --group test

# lint / type / test (requires deps)
make lint
make type
make test

See DEVELOPMENT.md for development and PUBLISHING.md for PyPI releases.

Security & Threat Model

See THREAT_MODEL.md. NovaAgents inherits the general agent/tool risk profile of Deep Agents-derived systems: treat tool outputs, files, web content, and model outputs as untrusted inputs to policy decisions; enforce least privilege and human approval for sensitive actions.

Changelog & License

• CHANGELOG.md
• LICENSE (MIT)

Upstream Attribution

NovaAgents is derived from the Deep Agents project by LangChain:

• Upstream source: https://github.com/langchain-ai/deepagents
• Upstream docs: https://docs.langchain.com/oss/python/deepagents/overview

Security

NovaAgents follows a "trust the LLM, enforce at the tool boundary" model: the agent can do anything its tools allow. Enforce boundaries via sandboxing, least-privilege tools, and human approval for sensitive actions (see THREAT_MODEL.md). Upstream Deep Agents security guidance: Deep Agents security policy.

Contributing

Contributions are welcome (features, fixes, docs, tests). Before opening changes, run available checks and record blocked validation honestly. If your work touches upstream-derived behavior, keep Nova-specific intent and compatibility clear; upstream project context: Deep Agents.