Getting started
Install Nodex and create an agent
Nodex should feel copy-paste simple. Install the package, scaffold an agent, then run it in dev mode while you edit.
quickstart
$ pip install nodex-ai
$ nodex new research-agent
$ cd research-agent
$ nodex dev agent:app --input '{"query":"AI trends"}'nodex run for one-shot execution.Install
Python 3.11 and one package
Start from a virtual environment, install Nodex, then add any LLM provider package your agent needs.
Tip
Provider packages stay separate so Nodex does not force one model vendor. Use
google-generativeai, openai, anthropic, or any other.
install
$ python --version
Python 3.11+
$ python -m venv .venv
$ source .venv/bin/activate # Windows: .venv\Scripts\activate
$ pip install nodex-ai
$ # Add your LLM provider separately:
$ pip install google-generativeaiHello world
The smallest useful Nodex agent
Two nodes, one state key, one run call. This is all you need to get Nodex working.
from nodex import Agent
app = Agent(name="first-agent")
@app.node(next="writer", retry=2)
def research(state):
return {"notes": f"Research: {state.get('query')}"}
@app.node(next="end")
def writer(state):
return {"final": state.get("notes", "").upper()}
app.run({"query": "LangGraph boilerplate"})Run it and you'll see a trace like this in your terminal:
output
> nodex running - first-agent
--------------------------------------------------
OK research -> 0.001s | tokens: 0 | $0.0000
OK writer -> 0.001s | tokens: 0 | $0.0000
--------------------------------------------------
OK Completed | 0.002s | $0.0000 | 2 nodes | 0 failed | tokens: 0Troubleshooting
Common first-run issues
| No nodes registered | Create an Agent and decorate at least one function with @app.node before calling app.run(). |
|---|---|
| Node returned empty output | Every node must return a non-empty dictionary. return {} or return None raises NodexStateError. |
| Invalid JSON input | CLI --input must be valid JSON, e.g. --input '{"query":"hello"}'. |
| Provider key missing | Nodex does not choose an LLM provider. Set the API key required by your model package (e.g. GOOGLE_API_KEY). |
| nodex command not found | Make sure your virtual environment is activated and you installed nodex-ai inside it. |
Next