Skip to main content

nagents

PyPI version Python versions CI codecov License: MIT Docs

nagents (pronounced "N-agents") is a lightweight LLM agent library with direct HTTP-based provider integration.

Rust harness migration

This repository also contains ngn (pronounced "engine"), the Rust harness, TUI and web host under ngn/. The Python nagents library remains under src/nagents/, with its existing interfaces and independently usable APIs. The two communicate through a private, versioned runtime protocol; Python does not own Rust tool execution or approvals.

The library, native application and adapter share one version and one GitHub release. The Rust client is not yet a feature-complete replacement for the Python client below; see the migration checklist.

Install native ngn

curl -fsSL https://github.com/abi-jey/nagents/releases/latest/download/install.sh | sh
ngn doctor

Self-contained (bundled Python, core, adapter and dependencies) for Linux x86_64 (glibc 2.39+) and macOS 11+ (Apple silicon or Intel). It never overwrites an existing Python ngn; see the native installer guide for options, configuration and updates.

Python library and client features

  • Multi-Provider Support: OpenAI, Anthropic Claude, and Google Gemini APIs
  • Streaming Events: Real-time text chunks, tool calls, and usage statistics
  • Tool Execution: Register Python functions as tools with automatic schema generation
  • Session Management: SQLite-based conversation persistence
  • Batch Processing: Process multiple requests efficiently
  • Python Harness Extensions: Custom context transforms, lifecycle hooks, and replaceable compaction algorithms
  • Optional Terminal Client: ngn provides interactive coding, approvals, sessions, and headless JSON events
  • Minimal Dependencies: Three direct dependencies: aiohttp, aiosqlite, and PyYAML; no mandatory provider SDK

Library Installation

Use a Python 3.12–3.15 virtual environment, or poetry add nagents in an existing Poetry project. Do not replace an existing environment:

python -m pip install nagents

Python ngn headless client

The Python ngn is a headless and web coding harness. Its full-screen terminal UI was removed; use the native ngn for an interactive terminal client. Published wheels also include ngn serve, the web extra, and built frontend assets, verified in v0.15.0. This README describes the current source checkout, which may include newer changes. See release availability when checking the commands and fixes in an installed distribution.

Keep the existing Poetry workflow from the repository root:

poetry install -E dev
poetry run ngn run --demo "Hello"

For a new local editable environment with uv, from the repository root:

uv venv --python 3.13
uv pip install --python .venv/bin/python -e .
uv run --no-project --python .venv/bin/python ngn run --demo "Hello"

Do not recreate an existing Poetry-managed .venv; keep using Poetry or choose a separate local environment. This uv workflow does not require uv sync, uv lock, or changes to the existing uv.lock. The explicit interpreter needs no activation. See ngn installation for optional activation and isolated uvx/uv tool alternatives.

The offline demo needs no API key, makes no model requests, skips Python plugins, and performs no workspace edits or shell commands. It does save demo conversations locally. Send demo approval to try a change preview or demo subagents to exercise three native async jobs without provider calls.

For a real model, select a named connection in providers.json, set its referenced environment variable, and run through the same environment, for example poetry run ngn run --provider-id my-connection --model MODEL_ID "your prompt". Use ngn run --json "your prompt" for headless integration, or ngn serve for the browser client. Non-interactive approvals fail closed. Use --agent to select a configured profile; assistant is the default. Delegation never exceeds the parent's permissions and defaults to depth two (root 0, child 1, grandchild 2).

For ChatGPT/Codex subscription access, select a named OpenAI connection with "auth": "chatgpt" or "auth": "codex" in providers.json. Use /login or ngn login chatgpt for the ChatGPT device flow. Device login must be enabled in your ChatGPT security/workspace settings. This uses a separate Codex Responses route, not a general-purpose OpenAI API key. ngn login also selects OpenRouter through a browser sign-in or stores API keys for OpenAI, Anthropic, Gemini, and custom OpenAI-compatible endpoints; keys are entered hidden or referenced with --api-key-env, and ngn login --status/ngn logout manage stored credentials. A saved login does not select the active connection; choose it in Provider connections or providers.json.

Configuration uses JSON with separate config.json and providers.json files. Priority is built-ins < NGN_* environment defaults < global JSON < trusted project JSON < explicit JSON < CLI. The global file is ~/.config/ngn/config.json (respecting XDG_CONFIG_HOME); workspace .ngn/config.json needs --trust-project, or explicit selection with --config. Any explicitly selected config file is trusted. See the full schema and recipes for types, defaults, ranges, profile replacement, relative paths, and LiteLLM endpoints.

Python plugins can change how the agent builds context, compacts history, and executes tools. The headless and web clients share the same harness. See the ngn usage guide, custom Python behavior example, and upstream research.

Python web client and HTTP API

ngn serve runs the React client and HTTP API for the ngn coding harness, sharing its workspace sessions, tools, and approvals. It is also the Docker image's default command. Install nagents[web] for a published wheel with built frontend assets, or build an editable checkout. See the web client guide.

The frontend source lives in src/nagents/web-ui/; its Vite build goes to src/nagents/web/static/. Plain ngn serve uses the bundled assets without building or reloading. Use ngn serve --dev in an editable checkout to build stale assets and reload after frontend or Python edits. Source build/check commands are in Contributing. For the runtime image's no-config startup, mounted YAML and Kubernetes Secret or environment-variable examples, see the container configuration guide.

The web client is a trusted-operator tool, not a sandbox or multi-user service.

Quick Start

import asyncio
from pathlib import Path
from nagents import Agent, Provider, ProviderType, SessionManager


async def main():
    # Create a provider
    provider = Provider(
        provider_type=ProviderType.OPENAI_COMPATIBLE,
        api_key="your-api-key",
        model="gpt-6-luna",
    )

    # Create an agent
    agent = Agent(
        provider=provider,
        session_manager=SessionManager(Path("sessions.db")),
        streaming=True,
    )

    # Run a conversation
    async for event in agent.run("Hello, how are you?"):
        if hasattr(event, "chunk"):
            print(event.chunk, end="")

    await agent.close()


asyncio.run(main())

Providers

nagents integrates with OpenAI, Anthropic, Google Gemini and OpenAI-compatible services. Select an exact model ID offered by your account and endpoint; example IDs are not a current catalog or an entitlement guarantee.

Provider documentation Library type
OpenAI ProviderType.OPENAI_COMPATIBLE
Anthropic ProviderType.ANTHROPIC
Google Gemini ProviderType.GEMINI_NATIVE

For OpenAI-compatible connections, await provider.get_model_list() discovers the endpoint's catalog; see model discovery and provider-specific limits.

With Tools

def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Weather in {city}: Sunny, 22°C"


agent = Agent(
    provider=provider,
    session_manager=SessionManager(Path("sessions.db")),
    tools=[get_weather],
)

async for event in agent.run("What's the weather in Paris?"):
    ...

With Session Persistence

from pathlib import Path
from nagents import SessionManager

session_manager = SessionManager(Path("sessions.db"))

agent = Agent(
    provider=provider,
    session_manager=session_manager,
)

# Use a specific session ID for conversation continuity
async for event in agent.run("Remember my name is Alice", session_id="user-123"):
    ...

Documentation

License

MIT

Metadata

Release files for nagents 0.100.43

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nagents 0.100.43
File Size Uploaded Provenance Actions
nagents-0.100.43.tar.gz 2.6 MB With provenance Details for nagents-0.100.43.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nagents 0.100.43
File Interpreter ABI Platform Actions
nagents-0.100.43-py3-none-any.whl Python 3 none any Details for nagents-0.100.43-py3-none-any.whl

Total release size: 4.0 MB

Release files / nagents-0.100.43.tar.gz

Download URL nagents-0.100.43.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
17bb9c5b5241946844f596b059d28a32736a810e7132c50fe88fad89b3936911
BLAKE2b-256 checksum
How to use checksums
a70f0d9c8ce80c6d463209e78090f45f5caa2e99e71dfc5bc5524e2e527f23f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / nagents-0.100.43-py3-none-any.whl

Download URL nagents-0.100.43-py3-none-any.whl
Size 1.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
ccdb6f70d46483aa1a5b71103e615684aefc06d0c92d1184c34d6a6c3cac72c1
BLAKE2b-256 checksum
How to use checksums
6c476cde8eaa5c6daa304a1604fb895c37f45e25d2ae039463e9d8866e079014
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for nagents 0.100.43

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nagents-0.100.43.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.100.43 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page