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:
ngnprovides interactive coding, approvals, sessions, and headless JSON events - Minimal Dependencies: Only
aiohttpandaiosqliterequired
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.
HTTP Interfaces
The current checkout includes a web-only Agent Designer: a YAML-backed agent
canvas with per-agent providers, instructions, selected tools/MCPs, delegation,
chat, and persisted context/request inspection. See the
Agent Designer guide for configuration and terminal
execution with ngn --design.
These are separate applications, not interchangeable launch commands:
| Command | Purpose | Installation |
|---|---|---|
python -m nagents.server |
Legacy HTTP/SSE API server. The current source has no bundled chat UI. | Current checkout with [server]; see the legacy API server guide for token, bind, and deployment setup. |
ngn serve |
Local React client for the ngn coding harness, sharing its workspace sessions and approvals. 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 local 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 legacy server's authentication hardening and removal of its old UI are also
post-0.5.0 changes. Do not apply the current security guarantees to that older
wheel or an unverified container image. Both applications are trusted-operator
tools, not sandboxes or multi-user services.
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. |
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
- ngn Installation
- ngn Usage Guide
- ngn Configuration Reference
- ngn Local Web Client
- Legacy API Server
- Installation
- Quick Start
- Providers Guide
- Tools Guide
- API Reference
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for nagents 0.22.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nagents-0.22.1.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nagents-0.22.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / nagents-0.22.1.tar.gz
| Download URL | nagents-0.22.1.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a0747d2a7a9a43d8fe3f519fc4e56f37a4923e28925c698d6937ea37714fdeb
|
|
BLAKE2b-256 checksum How to use checksums |
345b3ce3fbb0a53f5ebd5d535f591931aeb43053877994ddc06c2d7c94d90650
|
| Upload date | |
|
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.
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 Oct 9, 2026.
Transparency logRelease files / nagents-0.22.1-py3-none-any.whl
| Download URL | nagents-0.22.1-py3-none-any.whl |
|---|---|
| Size | 800.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a4188c34fc9e19d9c955f6e85b29639d7b86bff5a0730f975250522231b0dd28
|
|
BLAKE2b-256 checksum How to use checksums |
1e00c6e61d2af2f6a8c0bb686a66670875b9e6cd6a0cd46534122a3dba53d492
|
| Upload date | |
|
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.
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 Oct 9, 2026.
Transparency log
