NeuronAgent Overview

What NeuronAgent Is

NeuronAgent is an AI agent runtime service that provides:

• REST API and WebSocket — Create and manage agents, sessions, and messages over HTTP (default port 8080) and stream responses in real time over WebSocket.
• Persistent memory — Long-term memory backed by vector search (HNSW in NeuronDB) so agents can store and retrieve context across conversations.
• Tool execution — 18+ built-in tools (SQL, HTTP, code, shell, browser, memory, RAG, etc.) plus custom tool registration; agents choose tools via LLM decisions.
• Workflow engine — DAG-based workflows with agent, tool, HTTP, SQL, approval, and conditional steps; human-in-the-loop (HITL) with notifications.
• Multi-agent collaboration — Workspaces, agent-to-agent messaging, task delegation, and hierarchical agent structures.

NeuronAgent depends on NeuronDB (PostgreSQL with the NeuronDB extension). It uses the same database for agent state, sessions, messages, memory embeddings, and workflow state. It does not replace NeuronDB; it adds an agent runtime layer on top of it.

Key Capabilities

Quick Start

1. Prerequisites: PostgreSQL 16+ with NeuronDB extension, port 8080 available, API key for authentication.

2. Start the service (e.g. with Docker from the neurondb repo root):

   Copy
   docker compose up -d neurondb
   docker compose up -d neuronagent

3. Health check:

   Copy
   curl -sS http://localhost:8080/health
   # {"status":"ok"}

4. Create an agent and send a message (see API Reference):

   Copy
   export API_KEY="your_api_key"
   # Create agent
   curl -X POST http://localhost:8080/api/v1/agents \
     -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
     -d '{"name":"my-agent","system_prompt":"You are helpful.","model_name":"gpt-4","enabled_tools":[]}'
   # Create session (use agent id from response)
   curl -X POST http://localhost:8080/api/v1/sessions \
     -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
     -d '{"agent_id":"<agent_id>"}'
   # Send message (use session id from response)
   curl -X POST "http://localhost:8080/api/v1/sessions/<session_id>/messages" \
     -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
     -d '{"content":"Hello, what can you do?"}'

Full setup (database, config, Docker) is in the README.

Documentation Map

Machine-readable API: OpenAPI 3.0 spec at src/openapi/openapi.yaml (or /openapi.yaml when the server is running).

Docker Service Variants

Where to Go Next

• First-time setup: README Quick Start and Configuration.
• Deep dive on capabilities: Features.
• How the system is built: Architecture.
• Calling the API: API Reference and API (full).
• Problems: Troubleshooting.

For the official NeuronDB docs site: https://www.neurondb.ai/docs/neuronagent.