Docs Logo
Neuronum Client API

About Neuronum Client API

Manage and call your Agent with the Neuronum Client API using different message types

Requirements

Connect To Neuronum

Installation

Create and activate a virtual environment:

Bash 
python3 -m venv ~/neuronum-venv
source ~/neuronum-venv/bin/activate

Install the Neuronum SDK:

Bash 
pip install neuronum==2026.01.0.dev1

Note: Always activate this virtual environment (source ~/neuronum-venv/bin/activate) before running any neuronum commands.

Create a Neuronum Cell (secure Identity)

Bash 
neuronum create-cell

Connect your Cell

Bash 
neuronum connect-cell

Neuronum Client API Usage

Manage and call your Agent with "kybercell" (official Neuronum Client) or build your own custom Client using the Neuronum Client API.

Core Methods

Python 
# Target Cell ID
cell_id = "id::cell"

# Core Methods
cell.activate_tx(cell_id, data)  # Send request and wait for response
cell.stream(cell_id, data)       # Send request via WebSocket (no response)
cell.sync()                      # Receive incoming requests
cell.tx_response(transmitter_id, data, public_key)  # Send response to a request

Example 1: Send a Prompt to Your Agent

The agent will answer questions using its knowledge base and can execute tools conversationally when needed.

Python 
import asyncio
from neuronum import Cell

async def main():
    async with Cell() as cell:
        cell_id = "id::cell"  # Target cell to communicate with

        prompt_data = {
            "type": "prompt",
            "prompt": "Explain what a black hole is in one sentence"
        }
        tx_response = await cell.activate_tx(cell_id, prompt_data)
        print(tx_response)

if __name__ == '__main__':
    asyncio.run(main())

Example 2: Action Approval Flow

When the agent suggests a tool action, it returns an action_id. The client can then approve or decline the action.

Python 
# Approve a pending action
approve_data = {
    "type": "approve",
    "action_id": 123  # ID returned from prompt response
}
tx_response = await cell.activate_tx(cell_id, approve_data)
print(tx_response)

# Decline a pending action
decline_data = {
    "type": "decline",
    "action_id": 123
}
tx_response = await cell.activate_tx(cell_id, decline_data)
print(tx_response)

Example 3: Knowledge Management

Python 
# Add knowledge to agent's database
upload_knowledge_data = {
    "type": "upload_knowledge",
    "knowledge_topic": "Company Policy",
    "knowledge_data": "Our company operates from 9 AM to 5 PM Monday through Friday."
}
tx_response = await cell.activate_tx(cell_id, upload_knowledge_data)

# Update existing knowledge
update_knowledge_data = {
    "type": "update_knowledge",
    "knowledge_id": "abc123...",  # SHA256 hash ID from previous add
    "knowledge_data": "Updated: Company operates 8 AM to 6 PM Monday through Friday."
}
tx_response = await cell.activate_tx(cell_id, update_knowledge_data)

# Fetch all knowledge
get_knowledge_data = {"type": "get_knowledge"}
knowledge_list = await cell.activate_tx(cell_id, get_knowledge_data)
print(knowledge_list)
# Returns: [{"knowledge_id": "...", "topic": "...", "content": "..."}, ...]

# Delete knowledge
delete_knowledge_data = {
    "type": "delete_knowledge",
    "knowledge_id": "abc123..."
}
tx_response = await cell.activate_tx(cell_id, delete_knowledge_data)

Example 4: Icebreaker (Welcome Message)

Python 
# Get the icebreaker/welcome message
get_icebreaker_data = {"type": "get_icebreaker"}
icebreaker = await cell.activate_tx(cell_id, get_icebreaker_data)
print(icebreaker)

# Update the icebreaker message
update_icebreaker_data = {
    "type": "update_icebreaker",
    "icebreaker": "Welcome! How can I help you today?"
}
tx_response = await cell.activate_tx(cell_id, update_icebreaker_data)

Example 5: Tool Management

Python 
# List all available tools on Neuronum network
available_tools = await cell.list_tools()
print(available_tools)
# Returns list of tools with metadata: [{"tool_id": "...", "name": "...", "description": "..."}, ...]

# Get all installed tools on your agent
get_tools_data = {"type": "get_tools"}
tools_info = await cell.activate_tx(cell_id, get_tools_data)
print(tools_info)
# Returns: {"tools": {"tool_id": {config_data}, ...}}

# Install a tool (requires tool to be published)
# Use stream() instead of activate_tx() to listen for agent restart
install_tool_data = {
    "type": "install_tool",
    "tool_id": "019ac60e-cccc-7af5-b087-f6fcf1ba1299",
    "variables": {"API_TOKEN": "your-token"}  # Optional: tool variables
}
await cell.stream(cell_id, install_tool_data)
# Agent will restart and send "ping" when ready

# Delete a tool
delete_tool_data = {
    "type": "delete_tool",
    "tool_id": "019ac60e-cccc-7af5-b087-f6fcf1ba1299"
}
await cell.stream(cell_id, delete_tool_data)
# Agent will restart after deletion

Example 6: Actions Audit Log

Python 
# Get all actions (audit log)
get_actions_data = {"type": "get_actions"}
actions = await cell.activate_tx(cell_id, get_actions_data)
print(actions)
# Returns list of actions with status, tool info, timestamps, etc.

Example 7: Agent Status

Python 
# Check if agent is running
status_data = {"type": "get_agent_status"}
status = await cell.activate_tx(cell_id, status_data)
print(status)  # Returns: {"json": "running"}

Example 8: Receiving Requests (Server-side)

Listen for incoming requests using sync() and send encrypted responses back to clients.

Python 
# Listen for incoming requests using sync()
async for transmitter in cell.sync():
    data = transmitter.get("data", {})
    message_type = data.get("type")

    # Send encrypted response back to the client
    await cell.tx_response(
        transmitter_id=transmitter.get("transmitter_id"),
        data={"json": "Response message"},
        client_public_key_str=data.get("public_key", "")
    )

Need Help? For more information, visit the GitHub repository or contact us.