agents-sdk-mutta
A CLI scaffolding tool for OpenAI Agents SDK projects following the Mutta conventions.
Think of it like django-admin but for building multi-agent AI services with the OpenAI Agents SDK.
Why Mutta?
Building production-ready multi-agent systems requires consistent patterns. Mutta provides:
- Opinionated Structure - No decision fatigue. One way to organize agents, tools, and services.
- Manager Pattern - Every service has a manager that orchestrates agents in predictable, linear workflows.
- AI-First Rules - Installs
.mdcconvention rules that AI coding assistants (Cursor, Claude, GitHub Copilot) understand. - Instant Scaffolding - Go from zero to a working agent service in seconds.
Quick Start
Installation
pip install agents-sdk-mutta
Initialize a Project
mutta startproject
This creates:
agents_sdk/- Your agents directory with a README.cursor/rules/- Convention rules for AI assistants (or.claude/rules/,.github/rules/)
Create a Service
mutta startservice research
This generates a complete service structure:
agents_sdk/research_agents/
|-- __init__.py
|-- manager.py # Orchestrates the workflow
|-- tools.py # Shared tools for agents
|-- utilities.py # Helper functions
+-- agents/
|-- __init__.py
+-- example_agent.py # Template to get started
Commands
| Command | Description |
|---|---|
mutta startproject |
Initialize project with agents_sdk/ folder and AI rules |
mutta startservice <name> |
Scaffold a new agent service |
mutta --help |
Show all available commands |
Options
# Initialize in a specific directory
mutta startproject --path /path/to/project
# Verbose output when creating services
mutta startservice my_service --verbose
The Mutta Conventions
1. Manager Pattern
Every service has a Manager class that orchestrates agents in a linear, predictable flow:
class ResearchManager:
async def run(self, query: str) -> ResearchReport:
# Step 1: Plan the research
plan = await Runner.run(planner_agent, query)
# Step 2: Execute research
findings = await Runner.run(researcher_agent, plan.output)
# Step 3: Synthesize report
report = await Runner.run(writer_agent, findings.output)
return report.final_output
2. One Agent Per File
Each agent lives in its own file with a clear structure:
# agents/planner_agent.py
PLANNER_INSTRUCTIONS = """
You are a research planning specialist...
"""
class PlanOutput(BaseModel):
steps: list[str]
focus_areas: list[str]
planner_agent = Agent(
name="PlannerAgent",
instructions=PLANNER_INSTRUCTIONS,
model="gpt-5",
output_type=PlanOutput
)
3. Pydantic Everything
All inputs and outputs use Pydantic models. Never use Dict[str, Any]:
# Good
class SearchResult(BaseModel):
title: str
url: str
snippet: str
# Bad - Never do this
results: Dict[str, Any]
4. GPT-5 Series Models
Use GPT-5 models with appropriate reasoning levels:
| Use Case | Model | Reasoning |
|---|---|---|
| Complex planning | gpt-5 |
high |
| Standard tasks | gpt-5 |
medium |
| Simple extraction | gpt-5-mini |
low |
Installed Rules
When you run mutta startproject, these convention files are installed:
| File | Description |
|---|---|
openai-agents-sdk.mdc |
SDK overview, primitives, and concepts |
agent_services.mdc |
Service building conventions (the core rules) |
agent-additional.mdc |
Advanced patterns: streaming, LiteLLM, parallel execution |
mutta-cli.mdc |
How to use this CLI tool |
These rules are read by AI coding assistants to help you write code that follows Mutta conventions.
Example: Building a Research Service
# 1. Initialize the project
mutta startproject
# 2. Create the research service
mutta startservice research
# 3. Edit the generated files
code agents_sdk/research_agents/
Then use your service:
from agents_sdk.research_agents import ResearchManager
manager = ResearchManager()
report = await manager.run("What are the latest trends in quantum computing?")
print(report.summary)
Development
# Clone the repository
git clone https://github.com/maestromaximo/agent-sdk-mutta.git
cd agent-sdk-mutta
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
Requirements
- Python 3.10+
- Works with any project using the OpenAI Agents SDK
License
This project is licensed under the PolyForm Noncommercial License 1.0.0.
- Free for personal use, research, education, and non-commercial projects
- Commercial use requires a separate license agreement
See LICENSE for the full text.
Author
Alejandro Garcia Polo
- GitHub: @maestromaximo
- Email: alejandrogarcia2423@hotmail.com
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Metadata
Release files for agents-sdk-mutta 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agents_sdk_mutta-0.1.1.tar.gz | 30.4 kB | Without provenance | Details for agents_sdk_mutta-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_sdk_mutta-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agents_sdk_mutta-0.1.1-py3-none-any.whl |
Total release size: 68.4 kB
Release files / agents_sdk_mutta-0.1.1.tar.gz
| Download URL | agents_sdk_mutta-0.1.1.tar.gz |
|---|---|
| Size | 30.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f926a134fe783d9ab71e5cd787bae26bed5c1235ea425e643a171da01d60ea02
|
|
BLAKE2b-256 checksum How to use checksums |
6d2017163c506f8b249b1016c27607fb466e28dbc32626ff34247080fe776d76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.0
|
Release files / agents_sdk_mutta-0.1.1-py3-none-any.whl
| Download URL | agents_sdk_mutta-0.1.1-py3-none-any.whl |
|---|---|
| Size | 38.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
537229648d5631a53fad61c4a06fe1dc7d2f71afbd8fadf505239cdd9dcaaf51
|
|
BLAKE2b-256 checksum How to use checksums |
03ccb1505acb2287e9a93e41c2a5b8b7b1cc7144e3fcbd21117fe940f3b0a753
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.0
|
Security for agents-sdk-mutta 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.