Getting Started

Install the package, run a zero-key quickstart, then point at a real model.

Install

pip install neuroagent-ai                 # core + all LLM providers (httpx-based, no vendor SDKs)

pip install "neuroagent-ai[rag]"          # + document loaders (PDF/DOCX) for retrieval
pip install "neuroagent-ai[sql]"          # + SQLAlchemy for Postgres/MySQL/etc. database agents
pip install "neuroagent-ai[redis]"        # + Redis memory backend
pip install "neuroagent-ai[security]"     # + secret encryption (cryptography/Fernet)
pip install "neuroagent-ai[server]"       # + FastAPI/uvicorn for agent.serve()
pip install "neuroagent-ai[all]"          # everything

Lean by design. OpenAI, Anthropic, Gemini, and Groq all work on the base install — they talk to REST APIs over httpx, no vendor SDK required. Missing an extra raises a clear MissingDependencyError telling you exactly what to pip install.

Requires Python 3.10+.

Quickstart (60 seconds, no API key)

Every example below runs offline with the built-in echo provider — it echoes your prompt, no key, no network — so you can explore the API instantly.

from neuroagent import Agent, tool

@tool
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

agent = Agent(provider="echo", tools=[add])
response = agent.run("Please add 2 and 3")

print(response.content)              # the answer text
print(response.usage.total_tokens)   # token accounting
print(response.steps)                # provider/tool iterations

To use a real model, set the provider and an API key:

import os
os.environ["OPENAI_API_KEY"] = "sk-..."

agent = Agent(provider="openai", model="gpt-4.1", tools=[add])
print(agent.run("What is 2 + 3? Use the tool.").content)

Configuration

Pass options directly, or set environment variables. Precedence is explicit kwargs > env vars > defaults.

from neuroagent import Agent, Settings

# Per-agent
agent = Agent(
    provider="anthropic",
    model="claude-opus-4-8",
    api_key="sk-ant-...",       # or rely on the env var below
    system_prompt="You are a concise financial analyst.",
    temperature=0.2,
    max_tokens=1024,
    max_steps=8,                # cap on tool-calling iterations
)

# Global defaults via env (prefix NEUROAGENT_) or a .env file
#   NEUROAGENT_DEFAULT_PROVIDER=anthropic
#   NEUROAGENT_DEFAULT_MODEL=claude-opus-4-8
settings = Settings(default_provider="openai", default_model="gpt-4.1")
agent = Agent(settings=settings)   # provider/model resolved from settings

Provider API keys are read from standard environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY), GROQ_API_KEY.

NextCore Concepts →