Agent Task Planner

Optimal, re-planning task selection for AI agents. Give it candidate actions with a value and a cost, a budget, and optional conflicts and prerequisites. It returns the provably best plan and, as things happen, the single best next action. It works as a Claude Code plugin, as an MCP server for any MCP-capable agent, or as a Python library.

Why this algorithm: it won a pre-registered benchmark against QAOA, Grover Adaptive Search, simulated annealing and LP-guided sampling (research report). CP-SAT found the optimum of every test instance in under 1 ms. Re-planning after every event added 14–28 % utility over a fixed plan, and quantum methods did not beat classical ones at any size tested.

Install

Claude Code (one step, Claude Code ≥ 2.1.275):

/plugin install agent-task-planner --marketplace maxkyliu/agent-task-planner

or in two steps:

/plugin marketplace add maxkyliu/agent-task-planner
/plugin install agent-task-planner@agent-task-planner

Requires uv on your PATH; the plugin's MCP server runs with uv run, which installs its Python dependencies on first start.

Any MCP client (Claude Desktop, other agents), stdio server:

{
  "mcpServers": {
    "task-planner": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/maxkyliu/agent-task-planner", "agent-task-planner-mcp"]
    }
  }
}

Python:

uv add git+https://github.com/maxkyliu/agent-task-planner

from agent_task_planner.planner import PlanRequest, select_tasks

plan = select_tasks(
    PlanRequest.model_validate(
        {
            "budget": 10,
            "tasks": [
                {"id": "retrieve", "utility": 5, "cost": 4},
                {"id": "verify", "utility": 3, "cost": 3},
                {"id": "deep_dive", "utility": 4, "cost": 5},
            ],
            "conflicts": [["retrieve", "deep_dive"]],
            "prerequisites": [{"task": "verify", "requires": "retrieve"}],
        }
    )
)
print(plan.execution_order, plan.total_utility, plan.optimal)  # ['retrieve', 'verify'] 8 True

Related MCP server: agent-reasoning-mcp

Tools

The rules:

• Integers only: utilities, costs and budgets are non-negative integers, so scale fractions (for example ×100).

• Conflicts are pairs that cannot both run.

• Prerequisites mean "B only after A succeeded".

• Fallback: if CP-SAT hits its time limit, the best plan found is returned with optimal: false. If CP-SAT finds nothing in time, a feasible greedy plan is returned instead.

The research behind it

The planner comes out of an 8-week, pre-registered study comparing classical and quantum methods for budgeted agent task selection at 4–24 tasks. Full report: docs/research-report.pdf.

Development

uv sync
uv run pytest            # unit, property (vs brute force) and MCP stdio tests
uv run ruff check . && uv run mypy
claude plugin validate .

License

MIT