Skip to content

nagents

PyPI version Python versions CI License: MIT

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

  • Minimal Dependencies

    Only aiohttp and aiosqlite required. No heavy SDKs.

  • Multi-Provider

    OpenAI, Anthropic Claude, and Google Gemini with unified API.

  • Tool Execution

    Register Python functions as tools with automatic schema generation.

  • Session Persistence

    SQLite-based conversation history with session management.

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
  • HTTP Logging - Debug with full HTTP/SSE traffic logging
  • Tool Hallucination Handling - Graceful handling of unknown tool calls

Quick Start

main.py
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 session manager for conversation persistence
    session_manager = SessionManager(Path("sessions.db"))

    # Create an agent
    agent = Agent(
        provider=provider,
        session_manager=session_manager,
    )

    # 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())

Installation

pip install nagents

uv add nagents

poetry add nagents

Providers

nagents supports multiple LLM providers with a unified interface:

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.

OpenAI Compatible

The OPENAI_COMPATIBLE provider works with any OpenAI-compatible API including Azure OpenAI, local models (Ollama, vLLM), and other compatible services.

Next Steps

  • Getting Started

    Install nagents and create your first agent in minutes.

    Installation

  • User Guide

    Learn about providers, tools, sessions, and events.

    Providers

  • Examples

    See complete working examples with tools and sessions.

    Quick Start