Metadata-Version: 2.4
Name: modular-agent-designer
Version: 1.0.0
Summary: A declarative YAML workflow designer powered by Agno agents, teams, tools, and state.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: agno>=1.4
Requires-Dist: click>=8
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic<3,>=2
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=14
Provides-Extra: a2a
Requires-Dist: a2a-sdk[http-server]>=1.0; extra == 'a2a'
Provides-Extra: dev
Requires-Dist: flake8>=7.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: telemetry
Requires-Dist: mlflow>=2.14.0; extra == 'telemetry'
Requires-Dist: openinference-instrumentation-agno; extra == 'telemetry'
Requires-Dist: opentelemetry-exporter-otlp; extra == 'telemetry'
Description-Content-Type: text/markdown

# Modular Agent Designer

Build runnable agent workflows from YAML using [Agno](https://docs.agno.com).
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

```bash
uv sync
uv run mad --help
```

Optional remote A2A steps require:

```bash
uv sync --extra a2a
```

## Quick Start

```yaml
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: []
```

```bash
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:

```bash
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

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