MindRoot Python SDK

A simple Python client for interacting with the MindRoot API. This SDK provides programmatic access to run tasks with MindRoot AI agents.

Agent Definition Requirements

Note that for the results field to be filled in, the Agent you reference MUST have the task_result command enabled from the chat plugin section under Available Commands (/admin | Agents | select agent from drop down).

API Key Generation

Go to /admin | MindRoot API Keys in your MindRoot installation.

Installation

You can install the package from PyPI:

pip install mrsdk

This is the recommended installation method for most users.

Alternatively, you can install directly from GitHub:

pip install git+https://github.com/mindroot/mindroot-python-sdk.git

Or install from a local copy:

pip install -e .

Quick Start

frommrsdkimportMindRootClient# Initialize client with your API key and MindRoot URLclient=MindRootClient(
api_key="your_api_key_here",
base_url="http://localhost:8010"
)
# Or use environment variable# export MINDROOT_API_KEY=your_api_key_here# client = MindRootClient(base_url="http://localhost:8010")# Run a task with an agentresult=client.run_task(
agent_name="Assistant",
instructions="What is the square root of 256? Show your work."
)
# Print the resultprint(result["results"])

Advanced Usage

Getting the Full Trace

result=client.run_task(
agent_name="Assistant",
base_url="http://localhost:8010",
instructions="Please write a program to calculate the first 10 prime numbers.",
include_trace=True
)
# Print the resultprint(result["results"])
# Print the full trace of commands executed by the agentimportjsonforcmdinresult["full_results"]:
print(json.dumps(cmd, indent=2))

Handling Errors

frommrsdkimportMindRootClient, MindRootErrorclient=MindRootClient(base_url="http://localhost:8010")
try:
result=client.run_task("Assistant", "Complex task instructions here")
print(result["results"])
exceptMindRootErrorase:
print(f"Error from MindRoot API: {e}")
exceptExceptionase:
print(f"Unexpected error: {e}")

Changing the Base URL

# For connecting to a custom MindRoot instanceclient=MindRootClient(
api_key="your_api_key_here",
base_url="https://mindroot.your-company.com", # Always requiredtimeout=600# Increase timeout for complex tasks (in seconds)
)

Executing Tool Commands via HTTP

The SDK provides an execute_command method that runs any tool command via HTTP using an existing session's context. This calls the POST /cmd/{log_id} route on the MindRoot server (defined in src/mindroot/coreplugins/chat/router.py). It lets you run commands like read, write, run_python, etc. against a live chat session identified by its log_id.

HTTP Route Reference

POST /cmd/{log_id} — execute a command using an existing session's context:

curl -X POST http://localhost:PORT/cmd/{log_id} \
-H "Authorization: Bearer <api_key>" \
-H "Content-Type: application/json" \
-d '{"command": "read", "args": {"fname": "/path/to/file"}}'

Using execute_command in Python

frommrsdkimportMindRootClientclient=MindRootClient(
api_key="your_api_key_here",
base_url="http://localhost:8010"
)
try:
result=client.execute_command("abc123", "read", {"fname": "/path/to/file"})
print(result)
exceptExceptionase:
print(f"Error: {e}")

Command-line Interface

The package includes a simple command-line interface for quick testing:

# Set your API keyexport MINDROOT_API_KEY=your_api_key_here
# Run the example script (specify the MindRoot server URL)
python -m mrsdk.cli "What is the square root of 256? Show your work." --url http://localhost:8010
# Include full trace in the output
python -m mrsdk.cli "Calculate the first 10 prime numbers." --url http://localhost:8010 --trace
# Specify a different agent
python -m mrsdk.cli "Translate this to French: Hello, world!" --agent Translator

API Reference

MindRootClient

client=MindRootClient(api_key=None, base_url="http://localhost:8010", timeout=300)

Parameters:

-- base_url (str, required): Base URL of the MindRoot API server (e.g., http://localhost:8010).

• timeout (int): Request timeout in seconds. Default is 300 (5 minutes).

Methods

run_task

result=client.run_task(agent_name, instructions, include_trace=False)

Parameters:

• agent_name (str): Name of the agent to run the task.
• instructions (str): Instructions or prompt for the agent.
• include_trace (bool): Whether to include the full trace of commands in the result. Default is False.

Returns:

A dictionary containing the task results:

• If include_trace is False, returns only the final textual result.
• If include_trace is True, returns a dict with 'results', 'full_results', and 'log_id' keys.

Raises:

• MindRootError: If the API returns an error or if the request fails.
• requests.RequestException: For network-related errors.

License

MIT

Advanced Usage: Agent Management

The SDK provides programmatic access to manage agents (list, get, create, update, delete). These calls require an API key with admin privileges. All agents and personas are stored in the local scope.

Listing Agents

agents=client.list_agents()
foragentinagents:
print(agent["name"], "-", agent.get("description", ""))

Getting Agent Details

# Get agent config (without persona data)agent=client.get_agent("Assistant")
# Get full agent data with the persona data embeddedagent=client.get_agent("Assistant", include_persona=True)
print(agent["persona"])

Creating an Agent

The persona argument is optional. If omitted, it defaults to "Assistant". You can pass either a persona name string (to reference an existing persona) or a persona data dict (to create the persona at the same time).

# Create an agent using the default 'Assistant' personaclient.create_agent(
agent_data={
"name": "MyAgent",
"description": "A custom agent",
"instructions": "Be helpful and concise.",
"commands": ["task_result"],
},
)
# Create an agent with a new persona (written at the same time)client.create_agent(
agent_data={
"name": "MyAgent",
"description": "A custom agent",
"instructions": "Be helpful and concise.",
"commands": ["task_result"],
},
persona={
"name": "MyPersona",
"description": "You are a friendly assistant.",
"speech_patterns": "Warm and concise.",
},
)
# Create an agent with a new persona that includes an avatar imageclient.create_agent(
agent_data={
"name": "MyAgent",
"description": "A custom agent",
"instructions": "Be helpful and concise.",
"commands": ["task_result"],
},
persona={
"name": "MyPersona",
"description": "You are a friendly assistant.",
},
avatar="/path/to/avatar.png",
)

Updating an Agent

When updating, if persona is provided it will be created/updated at the same time. If omitted, the agent's existing persona is left unchanged.

# Update agent fieldsclient.update_agent(
"MyAgent",
agent_data={
"description": "An updated description",
"instructions": "New instructions.",
},
)
# Update agent and its persona data togetherclient.update_agent(
"MyAgent",
agent_data={"description": "Updated"},
persona={
"name": "MyPersona",
"description": "Updated persona description.",
},
avatar="/path/to/new_avatar.png",
)

Deleting an Agent

client.delete_agent("MyAgent")

Agent Management API Reference

client.list_agents()
client.get_agent(name, include_persona=False)
client.create_agent(agent_data, persona=None, avatar=None, overwrite=False)
client.update_agent(name, agent_data, persona=None, avatar=None)
client.delete_agent(name)

Parameters:

• persona (str | dict | None): Persona name string, persona data dict, or None.
  • If a dict, the persona is created/updated at the same time and must include a "name" field.
  • If None on create, defaults to "Assistant".
• avatar (str | None): Optional path to an image file used as the persona's avatar. Only used when persona is a dict.
• overwrite (bool): If True and an agent with the same name already exists, it will be overwritten. Default is False (raises if it exists).

Raises:

• MindRootError: If the API returns an error or if the request fails.

Advanced Usage: Persona Management

The SDK also provides programmatic access to manage personas (list, get, create, update). These calls require an API key with admin privileges. All personas are stored in the local scope.

Listing Personas

personas=client.list_personas()
forpersonainpersonas:
print(persona["name"])

Getting a Persona

persona=client.get_persona("Assistant")
print(persona)

Creating a Persona

# Create a persona with just dataclient.create_persona(
persona_data={
"name": "MyPersona",
"description": "You are a friendly assistant.",
"speech_patterns": "Warm and concise.",
},
)
# Create a persona with an avatar imageclient.create_persona(
persona_data={
"name": "MyPersona",
"description": "You are a friendly assistant.",
},
avatar="/path/to/avatar.png",
)

Updating a Persona

client.update_persona(
"MyPersona",
persona_data={
"name": "MyPersona",
"description": "Updated persona description.",
},
)

Persona Management API Reference

client.list_personas()
client.get_persona(name)
client.create_persona(persona_data, avatar=None, faceref=None)
client.update_persona(name, persona_data, avatar=None, faceref=None)

Parameters:

• persona_data (dict): Persona configuration. Must include a "name" field.
• avatar (str | None): Optional path to an image file used as the persona's avatar.
• faceref (str | None): Optional path to an image file used as the persona's face reference.

Raises:

• MindRootError: If the API returns an error or if the request fails.