agentprop 0.1.0a1

Graph optimization for multi-agent LLM workflows.

AgentProp

Graph optimization for multi-agent LLM workflows.

AgentProp models agents, tools, memories, documents, and verifiers as nodes in a directed weighted graph. It then uses propagation models, classical graph algorithms, optional GNN-style policies, and reinforcement learning to optimize:

• which agents receive full context first
• which edges are redundant or risky to prune
• where verifier agents should observe or intercept failures
• how much cost is saved versus broadcast routing
• how learned routing policies compare with graph-theoretic baselines

AgentProp is not an agent orchestrator. It is an analysis and optimization layer for workflows you already have, want to inspect, or want to study.

Status

AgentProp is usable as a public alpha framework. The graph backbone, CLI, reports, workflow templates, ML/RL baselines, MCP/coding-agent briefs, checkpoints, and experiment artifact registry are implemented and tested.

The main limitation is evidence depth: real routed LLM validation should be treated as directional until larger, repeated studies are published. The current library prioritizes reproducible artifacts and conservative claims.

Check the current rollout state:

agentprop readiness

Install

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Optional extras:

python -m pip install -e ".[dl]"  # torch-backed GNN experiments
python -m pip install -e ".[rl]"  # optional Gymnasium ecosystem compatibility

CUDA/GPU is not required for the current dependency-light alpha workflows. Modal/GPU becomes useful for larger torch sweeps and hyperparameter searches.

First Recipes

Analyze a workflow:

agentprop analyze benchmarks/workflows/planner_coder_tester_reviewer.json

Recommend seed agents for context routing:

agentprop optimize planner_coder_tester_reviewer --budget 2 --algorithm greedy

Use quality-aware routing when correctness-sensitive roles should be protected:

agentprop optimize planner_coder_tester_reviewer \
  --budget 2 \
  --algorithm quality-aware-greedy

Simulate propagation:

agentprop simulate chain --seeds node_0 --model zero-forcing

Prune toward a token-reduction target:

agentprop prune planner_coder_tester_reviewer --target-token-reduction 0.3

Write an HTML report:

agentprop report planner_coder_tester_reviewer --out reports/demo.html --format html

Generate a Codex or Claude Code brief:

agentprop agent-instructions planner_coder_tester_reviewer \
  --target codex \
  --out reports/codex_agent_brief.md

Experiment Recipes

Run the benchmark table and SVG plot:

PYTHONPATH=src:. python experiments/run_benchmark.py \
  --workflows planner_coder_tester_reviewer,chain,tree \
  --budget 2 \
  --trials 20 \
  --out-dir results/benchmark

Run a small ML/RL sweep:

PYTHONPATH=src:. python experiments/run_ml_rl_sweep.py \
  --config configs/sweeps/ml_rl_smoke.json \
  --artifact-root results/ml_rl_smoke

Dry-run the full recipe suite:

PYTHONPATH=src:. python experiments/run_experiment_suite.py \
  --config configs/experiment_suites/ml_core.json \
  --artifact-root results/ml_core \
  --dry-run

Preflight the real LLM case study without making LLM calls:

PYTHONPATH=src:. python experiments/run_case_study.py \
  --execution-mode llm \
  --preflight \
  --out-dir docs/results/case_study_001

Artifacts

AgentProp writes plain, inspectable artifacts:

• results.json / results.csv for benchmark and case-study rows
• summary.json for aggregate metrics
• traces.jsonl and outputs.jsonl for routed LLM execution traces
• verification_logs.jsonl when command verification is enabled
• registry.json for ML/RL checkpoints and metric artifacts
• *.svg plots for benchmark and case-study summaries
• Markdown, JSON, or HTML optimization reports

This recipe-first layout is intentional: every claim should point to a command and a saved artifact.

What Is Implemented

• Directed weighted AgentGraph with JSON, validation, NetworkX conversion, and Graphviz DOT export.
• Propagation models: Independent Cascade, Linear Threshold, Bootstrap Percolation, Randomized Zero Forcing, deterministic Zero Forcing, and learned trace-calibrated propagation.
• Classical baselines: random, degree, in-degree, out-degree, PageRank, betweenness, closeness, k-core, greedy, CELF, cost-aware greedy, and quality-aware greedy.
• Bottleneck, articulation, bridge, low-reliability, failure-sensitive, pruning, observability, and verifier-placement diagnostics.
• Role-critical routing with context-sensitivity scores, graded context allocation, calibrated compression ratios, risk annotations, and verifier-placement coupling.
• Workflow templates for agent-inspired workflows and synthetic graph families.
• Quality scorers for exact match, human labels, rubrics, and injected LLM-as-judge adapters.
• Dependency-light ML baselines, optional torch GNNs, Q-learning, REINFORCE, PPO, expanded workflow-control actions, a category-conditioned online bandit, checkpoints, and artifact registry.
• Framework interchange adapters and optional native hooks for LangGraph, CrewAI, and OpenAI Agents SDK.
• Claude Code/Codex instructions and a lightweight stdio MCP server.

Documentation

• Documentation index
• Tutorial
• Quality-aware routing
• Case-study protocol
• ML/DL/RL guide
• Coding-agent integration
• Framework integrations
• Contributing

Development

ruff check .
mypy src
pytest

CI runs the same gates on every push and pull request.