Modular Agent Designer

Build runnable agent workflows from YAML using Agno. Agno provides the agent runtime, teams, MCP tools, workflow container, and session-state foundation; this package adds a compact YAML graph DSL and CLI.

Install

uv sync
uv run mad --help

Optional remote A2A steps require:

uv sync --extra a2a

Quick Start

name: hello_world
framework: agno
models:
  local:
    provider: ollama
    model: gemma4:e4b
agents:
  greeter:
    model: local
    instruction: "Answer the user's request."
workflow:
  nodes: [greeter]
  entry: greeter
  edges: []

uv run mad validate examples/workflows/hello_world.yaml --skip-build
uv run mad run examples/workflows/hello_world.yaml --input '{"message":"hello"}'

For agent, delegated sub-agent, and tool input/output visibility during a run:

uv run mad run examples/workflows/sub_agent_example.yaml \
  --input '{"topic":"Compare RAG with fine-tuning."}' \
  --verbose

YAML Surface

models supports ollama, anthropic, openai, and google providers. Each is instantiated with its corresponding Agno model class.

tools supports:

Type	Meaning
`builtin`	Shipped callable tool
`python`	Dotted Python callable reference
`mcp_stdio`	Agno MCP toolkit over a local command
`mcp_sse`	Agno MCP toolkit over SSE
`mcp_http`	Agno MCP toolkit over streamable HTTP

agents entries support:

Type	Meaning
`agent` or omitted	Agno `Agent`; `sub_agents` produces an Agno `Team`
`node`	State-aware Python callable workflow step
`workflow`	Nested YAML workflow with input/output mappings
`a2a`	Remote A2A workflow step when the optional extra is installed

Selected entries in skills resolve a SKILL.md file and append those instructions to the Agno agent's instruction set.

Workflow Graph

The workflow block declares nodes, an entry, and edges. Edge features:

condition: exact/list matching, default, or safe eval.
switch/cases: loader sugar for conditional routes.
loop: bounded iteration with optional on_exhausted.
on_error: route agent execution failures.
to: "{{state...}}": dynamic destination with optional allowed_targets.
to: [a, b], parallel: true, join: c: concurrent fan-out and join.

Runtime output and loop/error metadata are stored in the Agno workflow's session_state, and custom steps can access the same state through WorkflowContext.

Project Layout

src/modular_agent_designer/workflow/agno_builder.py: workflow compiler/runtime.
src/modular_agent_designer/frameworks/agno_adapter.py: agent and team execution.
src/modular_agent_designer/tools/registry.py: callable and MCP tool resolution.
src/modular_agent_designer/config/schema.py: YAML schema and validation.
examples/workflows/: runnable definitions.

Development

uv run pytest
uv run mad validate examples/workflows/custom_routing_e2e.yaml --skip-build

Metadata

Release files for modular-agent-designer 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for modular-agent-designer 1.0.0
File	Size	Uploaded	Provenance
modular_agent_designer-1.0.0.tar.gz	294.8 kB	May 28, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for modular-agent-designer 1.0.0
File	Interpreter	ABI	Platform	Reset
modular_agent_designer-1.0.0-py3-none-any.whl 68.8 kB May 28, 2026 Without provenance	Python 3	none	any	Details

Total release size: 363.5 kB

Release files / modular_agent_designer-1.0.0.tar.gz

Download URL	modular_agent_designer-1.0.0.tar.gz
Size	294.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`0e55e544bddaedbf8489515103ffae4078bd5b8f10e2fb05a2618953bb5020ca`
BLAKE2b-256 checksum How to use checksums	`f2859f1796a30f4cfb675981988b526bd28b77de2eafdb5f98d334942d805503`
Upload date	May 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`

Release files / modular_agent_designer-1.0.0-py3-none-any.whl

Download URL	modular_agent_designer-1.0.0-py3-none-any.whl
Size	68.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`65128dbfd2a92fdd69338a7de9da7a6e2d4198ee21d5cb072e57f554cc201634`
BLAKE2b-256 checksum How to use checksums	`88068e1f2b1fdd5d14c8dd6e5ad9c455d691a9d8bb76f66678f6f3b8b16f1654`
Upload date	May 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.4`

Security for modular-agent-designer 1.0.0

Report project as malware

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.