Kodosumi is a Python framework for running AI agent workflows in production. It combines Ray Serve for distributed execution, a built-in Admin Panel for monitoring, and Masumi blockchain integration for paid agent services.
Screenshots (click to expand)
Agent Services
Analytics Dashboard
Masumi Payment Dashboard
Timeline
Expose Management
pip install kodosumi# app.py
import kodosumi.core as core
from kodosumi.core import forms as F
app = core.ServeAPI()
@app.enter(
path="/",
model=F.Model(
F.InputText(label="Question", name="question"),
F.Submit("Run"),
),
summary="My First Agent",
tags=["Demo"],
)
async def enter(request, inputs: dict):
return core.Launch(request, "app:run_agent", inputs=inputs)
async def run_agent(inputs: dict, tracer: core.Tracer):
question = inputs.get("question", "")
await tracer.result({"answer": f"You asked: {question}"})
return {"answer": f"You asked: {question}"}# Start Ray (required once)
ray start --head
# Start Kodosumi admin panel
koco serve
# In another terminal, deploy your agent
serve run app:app --host 0.0.0.0 --port 8001Open http://localhost:3370 to see your agent in the Admin Panel.
Agents are managed through the Expose system in the Admin Panel:
- Create an Expose entry with your agent's config (YAML)
- Click Boot to deploy all configured agents to Ray Serve
- Monitor executions in the Timeline and Analytics dashboards
- Distributed Execution - Scale from laptop to cluster with Ray Serve
- Admin Panel - Monitor agents, view timelines, track errors
- Payment Dashboard - Revenue tracking and failure analysis for Masumi-integrated agents
- Forms & Validation - Declarative input forms with client-side validation
- File Upload/Download - Chunked file transfer for agent I/O
- Human-in-the-Loop - Lock/lease pattern for interactive agent workflows
- MIP-003 Protocol - Standard API for agent discovery and job management (Sumi endpoints)
- Blockchain Payments - Masumi/Cardano integration for paid agent services
+------------------+
| Admin Panel | Litestar (port 3370)
| - Dashboard | Monitoring, Expose, Analytics
| - Masumi | Payment tracking
+--------+---------+
|
+--------+---------+
| Ray Serve | Distributed execution
| +-----+ +-----+|
| |App 1| |App 2|| Your agent endpoints
| +-----+ +-----+|
+--------+---------+
|
+--------+---------+
| Spooler | Event collection
| SQLite per job | Execution logs
+------------------+
| Command | Description |
|---|---|
koco serve |
Start admin panel (development) |
koco serve --reload |
Start with auto-reload |
koco start |
Start admin panel + spooler (production) |
koco spool --start |
Start spooler independently |
koco spool --status |
Check spooler status |
All settings via environment variables with KODO_ prefix or .env file:
KODO_APP_SERVER=http://localhost:3370 # Admin panel URL
KODO_RAY_SERVER=localhost:6379 # Ray cluster address
KODO_EXEC_DIR=./data/execution # Execution data directory
KODO_ADMIN_EMAIL=admin@example.com # Default admin credentials
KODO_ADMIN_PASSWORD=adminSee Configuration Reference for all options.
See the kodosumi-examples repository for complete examples:
- simple - Minimal agent with text input
- form - Advanced forms with validation
- upload - File upload/download
- hitl - Human-in-the-loop with locks
- prime - Multi-step workflow
Full documentation at docs.kodosumi.io:
# Clone and install in development mode
git clone https://github.com/masumi-network/kodosumi.git
cd kodosumi
python -m venv .venv
source .venv/bin/activate
pip install -e ".[tests]"
# Run tests
pytest tests/
# Start development server
ray start --head
koco serve --reload