modular-agent-designer 1.0.0

A declarative YAML workflow designer powered by Agno agents, teams, tools, and state.

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