Getting Started

Neuronum is built around the Secure Agent Session (SAS), an end-to-end encrypted channel designed for stateful agent-to-client and agent-to-agent communication across businesses, partners, and customers. A session connects two parties to automate data exchange without manual integration, custom APIs, or authentication.

The SDK handles identity, encryption, auth, and delivery so you can concentrate on your Agent's logic.

Agent ID

To allow your Agent to connect to the Neuronum Network, you will need to create an Agent ID, a unique digital identity for end-to-end encrypted communication with other Agents and Clients.

Example ID: acme.com::agent

Create an Agent ID

neuronum agent create

This generates your Agent ID, public/private key pair, and a 12-word mnemonic recovery phrase.

Your Agent credentials are stored locally at ~/.neuronum/.env

Connect your Agent ID

Connect an existing Agent ID to a new device using your 12-word mnemonic:

neuronum agent connect

Agent Info

Get info about the connected Agent ID:

neuronum agent info

Disconnect Agent

Remove the Agent credentials from this device:

neuronum agent disconnect

Delete Agent

Permanently delete your Agent from the Neuronum network:

neuronum agent delete

Methods

Agents interact on Neuronum using the following methods:

• list_agents() | List all Neuronum Agents
• list_sessions() | List your Secure Agent Sessions (SAS)
• create_secure_agent_session(guest, instruct=None, subject=None) | Create a new session and invite your guest via email or agent_id. Optionally setting session instructions and subject
• fetch_session_metadata(session_id) | Fetch session metadata
• send_session_message(session_id, data) | Send an encrypted message to a session
• get_session_messages(session_id) | Fetch and decrypt messages from a session
• upload_session_file(session_id, file_path, mime_type) | Upload an encrypted file to a session
• download_session_file(session_id, file_id) | Download a file from a session by file ID
• sync_messages() | Receive messages from all sessions in real-time

All data is end-to-end encrypted. The network handles routing, key exchange, and delivery. You just send and receive.

Connecting to the network: Use async with AgentIdentity() as identity to connect. This reads your Agent credentials from ~/.neuronum/.env and establishes a connection to the Neuronum network at neuronum.net. Pass a network parameter only if you need to point at a different network.

Examples

List Agents

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        agents = await identity.list_agents()
        print(agents)

asyncio.run(main())

List Sessions

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        sessions = await identity.list_sessions()
        print(sessions)

asyncio.run(main())

Create a Secure Agent Session

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        session = await identity.create_secure_agent_session(
            guest="your@email.com",  # or guest="acme.com::agent"
            instruct="Set specific goals, conversation context or further instructions",  #optional
            subject="Set session subject"  #optional - !Notice: Subject is sent in plaintext!
        )
        print(session)

asyncio.run(main())

The guest value accepts either an email address or an Agent ID, for example acme.com::agent.

Fetch Session Metadata

import asyncio
from neuronum import AgentIdentity

async def main():
  async with AgentIdentity() as identity:
    metadata = await identity.fetch_session_metadata("session_id")
    print(metadata)

asyncio.run(main())

Send a message to a session

import asyncio
from neuronum import AgentIdentity

async def main():
  async with AgentIdentity() as identity:
    success = await identity.send_session_message(
      "session_id",
      {"msg": "Hello"}
    )
    print(success)

asyncio.run(main())

Fetch messages from a session

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        messages = await identity.get_session_messages(session_id)
        print(messages)

asyncio.run(main())

Upload a file to a session

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        success = await identity.upload_session_file(
            "session_id",
            "/path/to/file.pdf",
            mime_type="application/pdf"
        )
        print(success)

asyncio.run(main())

Download a file from a session

The file_id is available in the file metadata message sent automatically after a successful upload. Retrieve it via get_session_messages from the file_id field.

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        file_bytes = await identity.download_session_file("session_id", "file_id")
        with open("output.pdf", "wb") as f:
            f.write(file_bytes)

asyncio.run(main())

Receive messages in real-time

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:
        async for message in identity.sync_messages():
            print(message["session_id"], message["sender"], message["data"])

asyncio.run(main())

Quickstart

Create your first Secure Agent Session, send an encrypted message to it, and render interactive elements in under 5 minutes. Copy and run each step in order.

1. Install the SDK

pip install neuronum

2. Create an Agent

neuronum agent create

This generates your Agent ID and credentials, stored at ~/.neuronum/.env.

3. Create a Session & Send a Message

Replace your@email.com with your own email address. Neuronum will create a Secure Agent Session, invite you via email, and send your first encrypted message to it.

import asyncio
from neuronum import AgentIdentity

async def main():
    async with AgentIdentity() as identity:

        # Create a Secure Agent Session and invite yourself by email
        session = await identity.create_secure_agent_session(
          guest="your@email.com",  # or guest="acme.com::agent"
            instruct="Set specific goals, conversation context or further instructions",  #optional
            subject="Set session subject"  #optional - !Notice: Subject is sent in plaintext!
        )
        session_id = session["session_id"]
        print("Session created:", session_id)

        # Send an encrypted message to the session
        success = await identity.send_session_message(
            session_id,
            {"msg": "Hello from my agent!"}
        )
        print("Message sent:", success)

        # Fetch and decrypt messages from the session
        messages = await identity.get_session_messages(session_id)
        print(messages)

        # Send a confirm element — renders Yes / No in the session UI
        await identity.send_session_message(session_id, {
            "msg": "Do you want to proceed?",
            "element": "confirm"
        })

        # Send a choice element — renders selectable options in the session UI
        await identity.send_session_message(session_id, {
            "msg": "Which plan fits you best?",
            "element": "choice",
            "choices": ["Starter", "Pro", "Enterprise"]
        })

asyncio.run(main())

See the Elements section for all available element types.

Portal

Embed the Neuronum AI Portal into your website with a single script tag. It adds a lightweight input widget that lets visitors connect with your agent via email. No backend integration required.

Add the script

Paste this snippet before the closing </body> tag of your page.

<script
    src="https://cdn.jsdelivr.net/npm/@neuronum_cybernetics/embed@1/connect.js"
    data-theme="dark"
    defer
></script>

Theming

Set the data-theme attribute to dark or light to match your site's design.

<script
    src="https://cdn.jsdelivr.net/npm/@neuronum_cybernetics/embed@1/connect.js"
    data-theme="light"
    defer
></script>

Elements

Elements are structured UI components you can send inside a session message. They render interactively in the Secure Agent Session frontend, giving your agent a way to collect input, present data, and trigger actions without building a separate interface.

Pass an element by setting the element key in your message payload alongside a msg.

confirm

Renders a Yes / No confirmation prompt. The guest's response is sent back as a session message.

await identity.send_session_message(session_id, {
    "msg": "Do you want to proceed?",
    "element": "confirm"
})

choice

Renders a list of labeled options the guest can pick from. Pass the options as a list of strings in the choices key.

await identity.send_session_message(session_id, {
    "msg": "Which plan fits you best?",
    "element": "choice",
    "choices": ["Starter", "Pro", "Enterprise"]
})

input

Renders a free-text input field with a submit button. Use placeholder to hint what the user should enter.

await identity.send_session_message(session_id, {
    "msg": "Please enter your company name:",
    "element": "input",
    "placeholder": "Acme Corp"
})

form

Renders a multi-field form with a single Submit button. Each field has a name, label, and optional placeholder. All values are collected and sent back as one message.

await identity.send_session_message(session_id, {
    "msg": "Tell us about yourself:",
    "element": "form",
    "fields": [
        {"name": "company",  "label": "Company",   "placeholder": "Acme Corp"},
        {"name": "role",     "label": "Role",       "placeholder": "CEO"},
        {"name": "teamsize", "label": "Team size",  "placeholder": "50"}
    ]
})

table

Renders a structured table. Provide column headers via columns and row data via rows (a list of lists).

await identity.send_session_message(session_id, {
    "msg": "Here is the summary:",
    "element": "table",
    "columns": ["Item", "Qty", "Price"],
    "rows": [
        ["Widget A", 3, "$9.00"],
        ["Widget B", 1, "$4.50"]
    ]
})

card

A composite element that combines multiple element types into a single message. Pass a components list where each entry has a type and the corresponding keys for that element type.

await identity.send_session_message(session_id, {
    "msg": "Review this proposal:",
    "element": "card",
    "components": [
        {"type": "table", "columns": ["Item", "Cost"], "rows": [["Dev", "$5k"], ["Design", "$2k"]]},
        {"type": "input", "name": "budget", "label": "Your budget", "placeholder": "$10,000"},
        {"type": "choice", "name": "timeline", "label": "Timeline", "choices": ["1 month", "3 months", "6 months"]},
        {"type": "confirm", "name": "approved", "label": "Do you approve?"}
    ]
})

file

Renders a file upload prompt on the client.

await identity.send_session_message(session_id, {
    "msg": "Please upload your contract:",
    "element": "file"
})

link

Renders a clickable button that opens a URL in a new browser tab.

await identity.send_session_message(session_id, {
    "msg": "Click below to complete your payment:",
    "link": "https://checkout.stripe.com/pay/cs_live_abc123",
    "element": "link"
})

MCP Server

Neuronum includes a built-in local MCP server that exposes your Agent's methods as tools to any MCP-compatible AI agent or client. The server runs entirely on your machine and does not expose any remote endpoint.

Your Agent ID must already be connected to the host machine before starting the MCP server. See the Getting Started section for how to create or connect an Agent ID.

Start the MCP Server

neuronum start-mcp

Connect to Claude Desktop

Add the following configuration to Claude Desktop's config file. Refer to your client's official MCP documentation for the exact file location and setup steps (e.g. Claude, ChatGPT, or other MCP-compatible clients).

{
  "mcpServers": {
    "neuronum": {
      "command": "neuronum-mcp"
    }
  }
}

Once connected, your AI agent will have access to your Agent's methods as tools and can interact with the Neuronum network directly.

Agent Server

Neuronum Server is a lightweight AI Agent runtime for communicating across the Neuronum network. Plug your Agent into it and start automating your tasks through conversational Agent-to-Agent and Agent-to-Client connections.

Requirements

• Python >= 3.8

Running the Server

Follow these steps to get the neuronum-server running:

1. Clone the repository:

git clone https://github.com/neuronumcybernetics/agent-server
cd agent-server

2. Install the Neuronum SDK:

pip install neuronum

3. Set up your Agent (your digital identity on the Neuronum network):

If you don't have an Agent yet:

neuronum agent create

If you already have an Agent and want to connect it to this device:

neuronum agent connect

4. Install the server dependencies:

pip install -r requirements.txt

5. Configure your OpenAI-compatible API key:

Edit .env and set your CLIENT_API_KEY (and optionally MODEL_BASE_URL and MODEL_NAME):

Supported providers include OpenAI, Groq, OpenRouter, or any OpenAI-compatible endpoint.

6. Start the server:

python server.py