Neuronum SDK
About
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.
Requirements
- Python >= 3.8
Installation
Set up and activate a virtual environment:
python3 -m venv ~/neuronum-venv
source ~/neuronum-venv/bin/activate
Install the Neuronum SDK:
pip install neuronum
Note: Always activate this virtual environment (
source ~/neuronum-venv/bin/activate) before running anyneuronumcommands.
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 your Agent ID:
neuronum agent create
# Prompts you to select a Network (default: neuronum.net), enter a Company Name, Business Email, and verify your Email.
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 to a Server:
neuronum agent connect
# Prompts you to enter your 12-word Agent Identity Recovery Phrase.
Get Info about the connected Agent ID:
neuronum agent info
# Displays the Agent ID, Operator (Company), Verification Status, and the path where keys are stored.
Disconnect your Agent ID from the Server:
neuronum agent disconnect
Delete your Agent ID permanently:
neuronum agent delete
Methods
Agents interact on Neuronum using the following methods:
| Method | Description |
|---|---|
list_agents() |
List all Neuronum Agents |
list_sessions() |
List your Secure Agent Sessions (SAS) |
create_secure_agent_session(guest, instruct=None, subject=None, tools=None) |
Create a session and optionally provide instructions, a subject, and encrypted API tool definitions |
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.
Quick 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
tools = [
{
"name": "jsonplaceholder_get_post",
"description": "Look up a post by its ID.",
"url": "https://jsonplaceholder.typicode.com/posts/{post_id}",
"method": "GET",
"parameters": {
"type": "object",
"properties": {
"post_id": {
"type": "string",
"description": "The ID of the post to look up.",
}
},
"required": ["post_id"],
},
}
]
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!
tools=tools,
)
print(session)
asyncio.run(main())
Tool definitions use JSON Schema for parameters. The SDK encrypts the tool list before sending it; fetch_session_metadata() decrypts it when reading session metadata. Include credentials under auth (for example, {"bearer": "YOUR_TOOL_API_TOKEN"}) rather than in the tool URL.
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())
Elements
Elements are UI components rendered on the client's frontend. Pass an element key in any send_session_message call to trigger them.
| Element | Description |
|---|---|
confirm |
Renders Accept / Decline buttons |
choice |
Renders a set of option buttons |
input |
Renders a single text input field |
form |
Renders a multi-field form |
table |
Renders a data table |
card |
Renders a composite card combining multiple elements |
file |
Renders a file upload prompt |
link |
Renders a clickable button that opens a URL in a new browser tab |
Confirm
await identity.send_session_message(session_id, {
"msg": "Do you accept the session terms?",
"element": "confirm"
})
Choice
await identity.send_session_message(session_id, {
"msg": "Which report format do you prefer?",
"element": "choice",
"choices": ["PDF", "CSV", "JSON"]
})
Input
await identity.send_session_message(session_id, {
"msg": "Please enter your company name:",
"element": "input",
"placeholder": "e.g. Acme Corp"
})
Form
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
await identity.send_session_message(session_id, {
"msg": "Your Order Summary:",
"element": "table",
"columns": ["Item", "Qty", "Price"],
"rows": [
["Widget A", 3, "9,00€"],
["Widget B", 1, "4,50€"],
["Widget C", 2, "1,50€"]
]
})
Card
A card combines multiple elements into a single message.
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 identity.
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 visit our website:",
"link": "https://example.com",
"element": "link"
})
Neuronum MCP Server
neuronum neuronum start-mcp
Full Documentation
Visit the Neuronum Documentation for the complete SDK reference.
1 maintainer
Metadata
1 maintainer
Release files for neuronum 2026.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| neuronum-2026.10.0.tar.gz | 23.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| neuronum-2026.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 45.1 kB
Release files / neuronum-2026.10.0.tar.gz
| Download URL | neuronum-2026.10.0.tar.gz |
|---|---|
| Size | 23.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ae3f8bc1b3b0c5e584917071ce69cab938a645751cc5dca8a9c6a6bf20a4b2bb
|
|
BLAKE2b-256 checksum How to use checksums |
6a21241f50983ca1ee517df1a385e7b90f53b319a30f4346f9697c13702f33c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / neuronum-2026.10.0-py3-none-any.whl
| Download URL | neuronum-2026.10.0-py3-none-any.whl |
|---|---|
| Size | 21.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e88be5a4d336b7dff8f9a55b0d44c929d0548f313ca4baeaa5aed82d21f922b5
|
|
BLAKE2b-256 checksum How to use checksums |
6dc037797e155289665889828b5920716d99566ffddebff062e98efab2583d77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
