nagents

A lightweight LLM agent framework with direct HTTP-based provider integration.

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: Only aiohttp and aiosqlite required

Library Installation

pip install nagents

ngn Terminal Client

ngn is an optional terminal and headless coding harness, available in published distributions with the tui extra. 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 -E tui
poetry run ngn --demo

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 '.[tui]'
uv run --no-project --python .venv/bin/python ngn --demo

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, headless-only installation, 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 dialog 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 launch through the same environment, for example poetry run ngn --provider-id my-connection --model MODEL_ID. With the environment activated, use ngn run --json "your prompt" for headless integration. Non-interactive approvals fail closed.

Type / for selectable commands from the harness, skills, and trusted plugins. Shift+Enter inserts a newline; Tab cycles agent profiles. Input queues while work is active, or use --submit-mode interrupt. The default terminal theme inherits terminal colors; try --theme graphite, ocean, or ember, and disable motion with --no-animations. Build-capable delegation uses the built-in agent profile by default, 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 TUI uses the same harness as the headless client; Textual remains an optional dependency. See the ngn usage guide, custom Python behavior example, and upstream research.

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-4o-mini",
    )

    # 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 supports three provider types:

Provider	Type	Models
OpenAI	`ProviderType.OPENAI_COMPATIBLE`	gpt-4o, gpt-4o-mini, etc.
Anthropic	`ProviderType.ANTHROPIC`	claude-3-5-sonnet, claude-3-opus, etc.
Google	`ProviderType.GEMINI_NATIVE`	gemini-2.0-flash, gemini-1.5-pro, etc.

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.24.1

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.24.1
File	Size	Uploaded	Provenance
nagents-0.24.1.tar.gz	2.2 MB	Oct 18, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for nagents 0.24.1
File	Interpreter	ABI	Platform	Reset
nagents-0.24.1-py3-none-any.whl 1.2 MB Oct 18, 2026 With provenance	Python 3	none	any	Details

Total release size: 3.4 MB

Release files / nagents-0.24.1.tar.gz

Download URL	nagents-0.24.1.tar.gz
Size	2.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`f010f57a902124a59f902b05e714d9f9cfdaa68ec1115a14af08b446489aa244`
BLAKE2b-256 checksum How to use checksums	`d6ceb566289841d8f3a4ceac2e3737e97a33882f9dcb2e641b1d756abcc59714`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/abi-jey/nagents
Publishing commit: github.com/abi-jey/nagents/tree/0da88351806c5d7c53393f57a5e7255abd9a7544

Workflow

Publishing configuration: github.com/abi-jey/nagents/blob/0da88351806c5d7c53393f57a5e7255abd9a7544/.github/workflows/ci.yml
Publishing logs: github.com/abi-jey/nagents/actions/runs/39124638059/attempts/1

Artifact

Subject: nagents-0.24.1.tar.gz
SHA-256 checksum: f010f57a902124a59f902b05e714d9f9cfdaa68ec1115a14af08b446489aa244 Verifying attestations

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

Download URL	nagents-0.24.1-py3-none-any.whl
Size	1.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`f9a9be38a4f0361468ac1229fef372530d6ba3d9782c0d05c230808f53b13e80`
BLAKE2b-256 checksum How to use checksums	`021b03b967e7ef9354c8c3df00f4a933b7650bee7f26721554cce40c85cf8723`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/abi-jey/nagents
Publishing commit: github.com/abi-jey/nagents/tree/0da88351806c5d7c53393f57a5e7255abd9a7544

Workflow

Publishing configuration: github.com/abi-jey/nagents/blob/0da88351806c5d7c53393f57a5e7255abd9a7544/.github/workflows/ci.yml
Publishing logs: github.com/abi-jey/nagents/actions/runs/39124638059/attempts/1

Artifact

Subject: nagents-0.24.1-py3-none-any.whl
SHA-256 checksum: f9a9be38a4f0361468ac1229fef372530d6ba3d9782c0d05c230808f53b13e80 Verifying attestations

Security for nagents 0.24.1

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for nagents-0.24.1.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/abi-jey/nagents
Publishing commit: github.com/abi-jey/nagents/tree/0da88351806c5d7c53393f57a5e7255abd9a7544

Workflow

Publishing configuration: github.com/abi-jey/nagents/blob/0da88351806c5d7c53393f57a5e7255abd9a7544/.github/workflows/ci.yml
Publishing logs: github.com/abi-jey/nagents/actions/runs/39124638059/attempts/1

Artifact

Subject: nagents-0.24.1.tar.gz
SHA-256 checksum: f010f57a902124a59f902b05e714d9f9cfdaa68ec1115a14af08b446489aa244 Verifying attestations

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.