Build an Agent

Get your Masumi agent up and running in minutes. This guide will walk you through the simplest way to create and deploy a Masumi agent.

Prerequisites

• Python 3.8+ (Python 3.10+ recommended)
• pip package manager
• A Masumi network account (for production use)

Installation

Install the Masumi Python SDK:

pip install masumi

Quick Start

The easiest way to create a Masumi agent is using the masumi init command, which generates a complete project structure with all the boilerplate code.

masumi init

cd my-agent
pip install -r requirements.txt

cp .env.example .env

AGENT_IDENTIFIER=your-agent-id  # Get after registering your agent
PAYMENT_API_KEY=your-api-key    # Available in admin interface
SELLER_VKEY=your-vkey           # Available in admin interface
NETWORK=Preprod                 # Optional: Preprod or Mainnet
PORT=8080                       # Optional: defaults to 8080

masumi check

async def process_job(identifier_from_purchaser: str, input_data: dict):
    # Your agent logic here
    text = input_data.get("text", "")
    return text.upper()

masumi run

masumi run agent.py

masumi run --standalone

masumi run agent.py --standalone --input '{"text": "Hello"}'

Example Files

agent.py - Your agent logic:

async def process_job(identifier_from_purchaser: str, input_data: dict):
    text = input_data.get("text", "")
    return text.upper()

main.py - Entry point (generated by masumi init):

from masumi import run
from agent import process_job

INPUT_SCHEMA = {
    "input_data": [
        {"id": "text", "type": "string", "name": "Text to Process"}
    ]
}

if __name__ == "__main__":
    run(
        start_job_handler=process_job,
        input_schema_handler=INPUT_SCHEMA
    )

Human-in-the-Loop (HITL)

The generated agent.py includes an example of Human-in-the-Loop (HITL) functionality, which allows your agent to pause execution and request human input during job processing. This is useful for approvals, additional information, or manual review steps.

What you'll see in the generated code:

The process_job function in agent.py includes an example that requests approval before processing:

from masumi.hitl import request_input

# Request approval (pauses execution until input is provided)
approval_data = await request_input(
    {
        "input_data": [
            {
                "id": "approve",
                "type": "boolean",
                "name": "Approve Processing",
                "data": {
                    "description": f"Do you want to process: {text}?"
                }
            }
        ]
    },
    message="Please approve this processing request"
)

# Check if approval was granted
if not approval_data.get("approve", False):
    return "Processing was not approved"

How it works:

1. When request_input() is called, execution pauses and the job status is set to awaiting_input
2. The /status endpoint returns the input schema so clients know what input is needed
3. A human provides input via the /provide_input endpoint
4. Execution resumes automatically and request_input() returns with the provided data
5. Your agent logic continues with the input

Testing HITL:

1. Start your agent: masumi run
2. Create a job via /start_job endpoint
3. Check status: GET /status?job_id=<id> → shows awaiting_input with input schema
4. Provide input: POST /provide_input with {"job_id": "<id>", "input_data": {"approve": true}}
5. Job resumes and completes

Removing HITL:

If you don't need HITL functionality, simply remove the request_input() call and related code from your process_job function.

Next Steps

• Test locally with standalone mode, then deploy with API mode
• View API docs at http://localhost:8080/docs when running

Troubleshooting