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. The published v0.5.0 release includes the CLI and the tui extra. This README describes the current source checkout, which also contains changes after that release. See release availability before assuming a particular command or fix is 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, set the provider key outside TOML and launch through the same environment, for example poetry run ngn --auth api-key --model MODEL_ID or uv run --no-project --python .venv/bin/python ngn --auth api-key --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, start ngn without --demo and use /login, or run ngn login chatgpt (same as --device-auth). 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 the saved selection. See the guide for credential storage and --auth selection. Saved credentials are never sent to custom endpoints.

Configuration uses top-level TOML, not [ngn] sections. Priority is built-ins < saved ngn login selection < NGN_* environment defaults < global TOML < trusted project TOML < explicit TOML < CLI. The global file is ~/.config/ngn/config.toml (respecting XDG_CONFIG_HOME); workspace .ngn/config.toml 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.

Optional microphone dictation uses the voice extra, a separate transcription API-key reference, and explicit opt-in. Transcriptions become editable previews, not automatically sent prompts. ChatGPT subscription access does not cover the paid transcription API. See dictation.

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

These are separate applications, not interchangeable launch commands:

The new 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.

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:

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