====== Agent Task Queue ======

//Vytvořeno: **12.11.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/block/agent-task-queue|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 [[ai:lokalni-ai:runtimy:gpu-broker|gpu-broker]]. Ten střídá LLM, obrázkové a video modely na jedné GPU.

===== Problém, který řeší =====

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.

===== Jak funguje =====

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ář.

==== Proč MCP, a ne CLI wrapper ====

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.

==== MCP nástroje ====

^ Nástroj ^ Účel ^
| ''run_task'' | Zařadí příkaz do fronty a spustí ho. |
| ''task_status'' | Vrátí nový výstup nebo změnu stavu, nejpozději po 30 s jako heartbeat. |
| ''cancel_task'' | Ukončí běžící nebo čekající úlohu. |
| ''clear_task_logs'' | Smaže všechny soubory s výstupem úloh. |

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

Parametry ''run_task'':

^ Parametr ^ Povinný ^ Popis ^
| ''command'' | ano | Příkaz pro shell. |
| ''working_directory'' | ano | Absolutní cesta, odkud se příkaz spustí. |
| ''queue_name'' | ne | Název fronty, výchozí ''global''. |
| ''timeout_seconds'' | ne | Maximální doba **běhu**, výchozí 1200 s. Čekání ve frontě se nepočítá. |
| ''env_vars'' | ne | Proměnné prostředí ve tvaru ''KEY=val,KEY2=val2''. |
| ''wait_seconds'' | ne | Počáteční čekání před vrácením identifikátoru úlohy (0–30, výchozí 30). |

==== Úspora tokenů a ochrana proti zombie procesům ====

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čí.

===== Instalace =====

Server se spouští přes [[https://docs.astral.sh/uv/guides/tools/|uvx]] přímo z PyPI, bez klonování a virtuálního prostředí. Obecná konfigurace pro MCP klienta:

<code json>
{
  "mcpServers": {
    "agent-task-queue": {
      "command": "uvx",
      "args": ["agent-task-queue@latest"]
    }
  }
}
</code>

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.

==== Claude Code ====

Podle [[https://github.com/block/agent-task-queue/blob/main/examples/claude-code/SETUP.md|návodu pro Claude Code]] jsou potřeba tři kroky.

1. Přidání MCP serveru:

<code bash>
claude mcp add agent-task-queue -- uvx agent-task-queue@latest
</code>

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

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

**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'':

<code markdown>
## 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.
</code>

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

===== Konfigurace serveru =====

^ Přepínač ^ Výchozí hodnota ^ Popis ^
| ''%%--%%data-dir'' | ''/tmp/agent-task-queue'' | Adresář pro databázi a logy. |
| ''%%--%%max-log-size'' | 5 | Velikost metrického logu v MB před rotací. |
| ''%%--%%max-output-files'' | 50 | Počet uchovávaných souborů s výstupem úloh. |
| ''%%--%%tail-lines'' | 50 | Počet řádků výstupu vrácených při chybě. |
| ''%%--%%lock-timeout'' | 120 | Minuty, po kterých se uvolní zaseknutý zámek. |
| ''%%--%%queue-capacity'' | žádná | Opakovatelné ''scope=capacity'' pro hierarchické fronty. |

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.

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

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 =====

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ů.

<code bash>
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
</code>

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

===== Omezení =====

  * 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ě.

===== Související články =====

  * [[ai:lokalni-ai:runtimy:gpu-broker|gpu-broker]] – fronta a střídání modelů na jedné GPU.
  * [[ai:mcp:uvod|MCP – Model Context Protocol]]

===== Zdroje =====

  * [[https://github.com/block/agent-task-queue|Agent Task Queue – repozitář a dokumentace]]
  * [[https://github.com/block/agent-task-queue/blob/main/examples/claude-code/SETUP.md|Agent Task Queue – nastavení pro Claude Code]]
  * [[https://pypi.org/project/agent-task-queue/|agent-task-queue na PyPI]]
  * [[https://docs.astral.sh/uv/guides/tools/|uv – spouštění nástrojů přes uvx]]