Agent Task Queue

Vytvořeno: 12.11.2026 | Aktualizováno: 12.11.2026 21:48

Agent Task Queue je MCP server od firmy Block pro lokální řazení úloh AI agentů do fronty. Brání tomu, aby více agentů na jednom stroji současně spouštělo drahé operace, jako jsou buildy, testy nebo docker build, a přetížilo tak CPU, RAM a disk.

Podobný problém řeší na úrovni grafické karty projekt gpu-broker. Ten střídá LLM, obrázkové a video modely na jedné GPU.

Každý agent spouští drahé příkazy samostatně a o ostatních neví. Když běží současně, podle README:

• se pětiminutový build protáhne na 30 a více minut,
• dochází paměť a disk je přetížený,
• stroj přestane reagovat,
• agenti se nemají jak mezi sebou domluvit.

V ukázce z README spustí dva agenti stejný Android build s odstupem dvou sekund. Druhý agent počká ve frontě. Jeho build pak trvá 32,6 s místo 192,6 s, protože Gradle využije cache z prvního buildu.

Agent nespouští drahý příkaz přes Bash, ale přes MCP nástroj run_task. Server příkaz zařadí do fronty v SQLite (/tmp/agent-task-queue/queue.db) a spustí ho jako podproces, až na něj přijde řada.

• Globální fronta. Ve výchozím stavu sdílejí všechna volání run_task jednu frontu global.
• Vlastní fronty. Parametr queue_name odděluje nezávislé úlohy. Například fronty android a web mohou běžet paralelně.
• FIFO. V rámci jedné fronty platí pořadí podle příchodu. Bez další konfigurace má každá fronta kapacitu 1.
• Hierarchické fronty. Názvy s lomítkem (gradle/emu-5557) spolu s přepínačem --queue-capacity umožní paralelismus se sdíleným stropem.

Fronta funguje jen mezi procesy, které používají stejný datový adresář (--data-dir nebo proměnná TASK_QUEUE_DATA_DIR). Agenti v oddělených kontejnerech by proto potřebovali sdílený adresář.

První verze byla souborová fronta obalující příkazy v shellu. Měla zásadní vadu: AI nástroje mají v shellu timeout 30–120 s. Když příkaz čekal ve frontě déle, agent to vzdal, přestože by úloha nakonec proběhla.

MCP server vlastní příkaz nezávisle na jednom volání nástroje. run_task vrátí krátké příkazy rovnou s výsledkem. U delších vrátí nejpozději do 30 s identifikátor úlohy. Agent se pak ptá přes task_status a dostává průběžný výstup. Mezi těmito voláními může přijmout pokyny od uživatele.

Přerušení volání run_task nebo task_status příkaz nezastaví. Zastaví ho jen cancel_task.

Parametry run_task:

Plný výstup se ukládá do souborů output/task_<id>.log a task_<id>.raw.log. Při úspěchu agent dostane jediný řádek s cestou k logu. Při chybě dostane posledních 50 řádků výstupu.

Když agent spadne během úlohy, další úloha zjistí mrtvý rodičovský proces, zabije osiřelý build a uvolní zámek. Úlohy běžící déle než 120 minut server ukončí.

Server se spouští přes uvx přímo z PyPI, bez klonování a virtuálního prostředí. Obecná konfigurace pro MCP klienta:

{
  "mcpServers": {
    "agent-task-queue": {
      "command": "uvx",
      "args": ["agent-task-queue@latest"]
    }
  }
}

README obsahuje návody pro Amp, Claude Code, Claude Desktop, Cline, Codex, Copilot / VS Code, Cursor, Firebender a Windsurf. Podporované platformy jsou macOS a Linux.

Podle návodu pro Claude Code jsou potřeba tři kroky.

1. Přidání MCP serveru:

claude mcp add agent-task-queue -- uvx agent-task-queue@latest

2. Úprava settings.json a settings.local.json (globálních i projektových). Přidá se oprávnění ke čtení logů:

{
  "permissions": {
    "allow": [
      "Read(/tmp/agent-task-queue/*)"
    ]
  }
}

Pozor: Je nutné odebrat povolovací pravidla jako Bash(./gradlew:*), Bash(docker build:*), Bash(pytest:*), Bash(npm run build:*) nebo Bash(make:*). Pokud zůstanou, agent spustí příkaz rovnou přes Bash a frontu úplně obejde.

3. Doplnění instrukce do ~/.claude/CLAUDE.md:

## Build Queue
 
For expensive operations, ALWAYS use the `run_task` MCP tool instead of Bash.
 
**Commands that MUST use run_task:**
- gradle, bazel, make, cmake, mvn, cargo build, go build
- docker build, docker-compose, kubectl, helm
- npm/yarn/pnpm build, pytest, jest, mocha
 
**Usage:**
- command: The full shell command
- working_directory: Absolute path to project root
- env_vars: Optional like "KEY=value,KEY2=value2"
 
NEVER run these via Bash. Always use run_task MCP tool.

Po úpravě je potřeba Claude Code restartovat. Amp, Copilot a Windsurf podle README preferují MCP nástroje samy a další nastavení nepotřebují.

Přepínače se předávají v poli args konfigurace MCP. Příklad hierarchických front: sdílený Gradle smí běžet nejvýš dvakrát, každý emulátor jen jednou.

uvx agent-task-queue@latest \
  --queue-capacity=gradle=2 \
  --queue-capacity=gradle/emu-5557=1 \
  --queue-capacity=gradle/emu-5559=1

Kapacity se neukládají do queue.db. Pokud stejný datový adresář sdílí více serverů nebo volání tq, musí všechny používat stejné přepínače --queue-capacity.

CLI tq zařadí do stejné fronty i příkazy spuštěné ručně. Build spuštěný člověkem pak nebude soupeřit s buildy agentů.

uv tool install agent-task-queue    # nainstaluje MCP server i tq
 
tq ./gradlew assembleDebug          # spuštění přes frontu
tq -q android ./gradlew test        # konkrétní fronta
tq -t 600 npm test                  # vlastní timeout v sekundách
tq -C /path/to/project make         # pracovní adresář
 
tq list                             # aktuální fronta
tq logs -n 50                       # posledních 50 událostí
tq clear                            # vyčištění zaseknutých úloh

Pro sledování fronty existuje volitelná desktopová aplikace (Compose Multiplatform) a plugin pro IntelliJ. Obě čtou stejnou SQLite databázi.

• Fronta funguje jen tehdy, když agent opravdu zvolí run_task. Příkaz spuštěný přímo přes Bash frontu obejde.
• FIFO je zaručené jen v rámci jedné fronty, ne mezi sourozeneckými frontami se společným rodičem.
• Kapacita fronty platí po celou dobu běhu příkazu. Sdílenou přípravu buildu je proto vhodné oddělit od kroků, které běží paralelně.

• gpu-broker – fronta a střídání modelů na jedné GPU.
• MCP – Model Context Protocol

• Agent Task Queue – repozitář a dokumentace
• Agent Task Queue – nastavení pro Claude Code
• agent-task-queue na PyPI
• uv – spouštění nástrojů přes uvx