---
id: npmai-agents
version: "1.0.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# npmai-agents — Production-grade autonomous AI agent framework with 1,371 tools across 100 classes and a 5-role LLM pipeline — built on the NPMAI ECOSYSTEM.

License: permissive · Maintenance: active · Downloads: 236.3K/mo

## What it is and what it does

npmai_agents is an autonomous AI agent framework that breaks down plain-English tasks into a structured 5-stage pipeline: Planner (breaks down the task), Tool Manager (selects relevant tools), Coder (generates execution code), Auditor (security review), and Verifier (validates results). The core innovation is pre-compiled tool knowledge — each of the 1,371 tools across 100 classes ships with structured metadata that the pipeline reads on-demand, eliminating hallucination on API shapes and method signatures.

You can run tasks via CLI (`npmai run "your task"`) or programmatically by importing AgentBrain and other classes. The framework supports 12 LLM providers including free NPMAI-hosted models, OpenAI, Groq, Anthropic, Gemini, and local Ollama. By default all roles use free NPMAI models with zero setup; you can override any role's provider and model per-call. Tool dependencies auto-install at runtime unless you pre-install the full extra (`pip install npmai_agents[full]`), keeping the base install lightweight.

Use it for:

- Automate multi-step business workflows (e.g., scrape data, analyze it, generate reports, email results) without writing orchestration code
- Build desktop automation tasks that interact with files, APIs, and local tools using natural language instead of shell scripts
- Prototype and iterate on agentic AI solutions using free LLM models before committing to paid providers
- Execute security-audited code generation tasks where the Auditor role reviews generated code before execution
- Integrate with external services (Stripe, GitHub, Slack) via pre-built tool classes without managing API client libraries individually

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Autonomous AI agent framework that executes plain-English tasks through a 5-role LLM pipeline, with access to 1,371 tools across 100 classes and support for 12 LLM providers including free NPMAI models, OpenAI, Groq, Anthropic, and Gemini.

Yes, if you want to experiment with autonomous AI agents or automate complex multi-step tasks. The framework is actively maintained, has low install friction, carries no license restrictions, and offers genuine value through its pre-compiled tool registry and free LLM tier. Start with the minimal install and upgrade to `[full]` only if you need all 1,371 tools available immediately. Verify that the specific tools and LLM providers you need are stable and well-documented before committing to production use.

## Install

pip install npmai-agents
uv add npmai-agents
poetry add npmai-agents

## Installing npmai-agents

Before you install: Low friction install with pure Python wheel distribution. Active maintenance with recent release (38 days ago) and ongoing commits. Five runtime dependencies (npmai, requests, cryptography, typer, rich) are all stable, widely-used libraries with minimal transitive overhead.

License in practice: MIT license is permissive — you can use this in commercial projects, modify it freely, and distribute it with minimal restrictions. No copyleft obligations or patent clauses.

Quickstart:

pip install npmai_agents

from npmai_agents import AgentBrain

# Run a task through the 5-role pipeline
agent = AgentBrain()
result = agent.run("Analyze my sales.csv and create a revenue report")

Requires Python 3.9 or later. LLM provider credentials (API keys) must be saved via CLI for non-NPMAI providers; NPMAI free tier requires no setup.

Verify before relying:

- Whether the 1,371 tools and 100 classes are all functional and well-maintained in the current release
- Real-world latency and reliability of the 5-role pipeline on complex multi-step tasks
- How tool dependency auto-installation at runtime handles version conflicts or missing system libraries
- Whether the framework handles long-running tasks and recovery from transient LLM provider failures

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 236.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

autonomous ai agent framework, llm multi-agent orchestration, task automation with ai, local tool registry for agents, free llm agent pipeline, desktop automation ai, agentic ai framework python, multi-agent-orchestration, autonomous-ai, free-llm

[View on SkillFed](https://skillfed.io/packages/npmai-agents) · [View on PyPI](https://pypi.org/project/npmai-agents/)