mech.app
AI Agents

Agent Teams AI: Kanban Boards, Agent-to-Agent Messaging, and Peer Review for Multi-Agent Orchestration

How agent-teams-ai uses task boards, structured messaging, and peer review to coordinate autonomous agents without race conditions or cascading failures.

Source: github.com
Agent Teams AI: Kanban Boards, Agent-to-Agent Messaging, and Peer Review for Multi-Agent Orchestration

Most multi-agent frameworks treat coordination as an afterthought. They give you primitives for spawning agents and calling tools, then leave you to figure out how agents discover work, communicate results, and recover from failures. Agent Teams AI takes a different approach: it puts a kanban board at the center and treats agents as team members who pull tasks, message each other, and review each other’s output.

The result is a TypeScript orchestration framework that supports 200+ models across 75+ LLM providers (Claude, Codex, OpenCode, Cursor, GitHub Copilot, and many free models with no auth required). The repo has 1,740 stars and 303 forks, and the architecture exposes practical patterns for agent-to-agent communication that most frameworks ignore.

Coordination Model: Kanban as Shared State

Agent Teams AI uses a kanban board as the single source of truth for task state. Each task moves through columns (Backlog, In Progress, Review, Done), and agents pull work from the board rather than receiving direct assignments.

Key plumbing decisions:

  • Task ownership: When an agent claims a task, it writes a lock to the task record with a timestamp and agent ID. Other agents see the lock and skip that task.
  • State transitions: Agents can only move tasks forward (Backlog → In Progress → Review → Done). Moving backward (e.g., Review → In Progress) requires explicit human approval or a peer review rejection.
  • Visibility: All agents see the full board. There is no agent-specific queue or hidden state.

This design avoids the “who owns what” problem that plagues many multi-agent systems. If an agent crashes, its locked tasks become visible again after a timeout (default 5 minutes). Another agent can pick up the work without manual intervention.

Agent-to-Agent Messaging Protocol

Agents communicate through a structured message bus, not shared memory or direct RPC. Each message is a JSON object with a schema that includes sender, recipient, message type, and payload.

Message types:

  • task.request_help: Agent A asks Agent B for assistance with a subtask.
  • task.delegate: Agent A hands off an entire task to Agent B.
  • review.request: Agent A asks Agent B to review completed work.
  • review.approve / review.reject: Agent B responds with approval or rejection, including reasoning.
  • status.update: Agent broadcasts progress to all other agents (used for dependency tracking).

Example message structure:

{
  "id": "msg_abc123",
  "timestamp": "2026-07-28T00:12:34Z",
  "sender": "agent_coder_01",
  "recipient": "agent_reviewer_02",
  "type": "review.request",
  "payload": {
    "task_id": "task_456",
    "artifact_url": "file://output/feature.ts",
    "context": "Implemented user authentication flow",
    "review_criteria": ["security", "test_coverage", "api_contract"]
  }
}

Messages are persisted to a SQLite database (or PostgreSQL in production). Agents poll the message queue every 2 seconds by default. There is no WebSocket or event stream, which simplifies deployment but introduces latency.

Peer Review Mechanics

When an agent completes a task, it can request peer review before marking the task as Done. The review flow works like this:

  1. Agent A moves task to Review column and sends a review.request message to Agent B.
  2. Agent B reads the task description, examines the output artifact (code, document, API response), and evaluates against predefined criteria.
  3. Agent B sends either review.approve or review.reject with a reasoning field.
  4. If approved, Agent A moves task to Done. If rejected, Agent A moves task back to In Progress and logs the feedback.

Review criteria are configurable per task type:

Task TypeReview CriteriaReviewer Agent Type
Code generationSyntax, test coverage, securityCode reviewer
API designContract consistency, error handlingAPI reviewer
DocumentationClarity, completeness, examplesDoc reviewer
Data processingSchema validation, performance, accuracyData reviewer

If the reviewer agent crashes before responding, the review request times out after 10 minutes and the task returns to In Progress. The original agent can retry or request a different reviewer.

Disagreement handling: If Agent A disagrees with Agent B’s rejection, it can escalate to a human operator. The system does not support multi-round agent debates (yet). This is a deliberate simplification to avoid infinite loops.

Failure Modes and Recovery

Multi-agent systems fail in predictable ways. Agent Teams AI handles these scenarios:

Agent crash mid-task:

  • Task lock expires after 5 minutes.
  • Another agent can claim the task and restart from the last checkpoint.
  • Partial work (e.g., half-written code) is saved to the artifact store and tagged with the original agent ID.

Dependency chain failure:

  • If Task B depends on Task A and Agent X fails on Task A, Task B remains in Backlog with a blocked status.
  • Agents skip blocked tasks until the dependency resolves.
  • No automatic retry. A human must reassign Task A or unblock Task B manually.

Message delivery failure:

  • Messages are stored in the database before being marked as sent.
  • If an agent crashes before reading a message, the message remains unread.
  • Agents poll for unread messages on startup, so no messages are lost.

Review deadlock:

  • If Agent B never responds to a review request, the timeout mechanism (10 minutes) kicks in.
  • Agent A can request a different reviewer or escalate to a human.

Race conditions on task claiming:

  • Two agents might try to claim the same task simultaneously.
  • The database uses a unique constraint on (task_id, agent_id) to prevent double-locking.
  • The second agent receives a constraint violation error and moves to the next task.

Tool Boundaries and Capability Discovery

Agents declare their capabilities in a manifest file. When a task enters the Backlog, agents evaluate whether they can handle it based on required capabilities.

Example capability manifest:

{
  "agent_id": "agent_coder_01",
  "capabilities": [
    "code.typescript",
    "code.python",
    "test.unit",
    "git.commit"
  ],
  "tools": [
    "typescript_compiler",
    "pytest",
    "git_cli"
  ],
  "max_concurrent_tasks": 3
}

Tasks include a required_capabilities field. Agents skip tasks that require capabilities they don’t have. This prevents a Python-only agent from claiming a Rust task.

Delegation logic: If an agent starts a task and realizes it needs a capability it lacks (e.g., database access), it sends a task.delegate message to an agent with that capability. The original agent remains the task owner but waits for the delegate to complete the subtask.

Deployment Shape

Agent Teams AI ships as an Electron desktop app with a built-in orchestration server. The server runs locally and manages the kanban board, message queue, and agent lifecycle.

Architecture components:

  • Frontend: Electron + React for the kanban board UI.
  • Backend: Node.js + Express for the orchestration API.
  • Database: SQLite for local deployments, PostgreSQL for multi-user setups.
  • Agent runtime: Each agent runs in a separate Node.js worker thread.
  • LLM integration: Unified API client that wraps 75+ providers (OpenAI, Anthropic, Cohere, local models via Ollama, etc.).

Scaling considerations:

  • Single-machine deployments support up to 10 concurrent agents before CPU becomes a bottleneck.
  • Multi-machine deployments require PostgreSQL and a shared file system for artifacts.
  • No built-in load balancer. You must run multiple instances behind nginx or similar.

Observability and Debugging

The system logs every state transition, message, and tool call to the database. The UI includes:

  • Task timeline: Shows which agent worked on a task, when, and what actions they took.
  • Message log: Full history of agent-to-agent messages with timestamps and payloads.
  • Token usage dashboard: Tracks LLM API calls, token counts, and estimated costs per agent.
  • Agent health monitor: Shows which agents are active, idle, or crashed.

No distributed tracing: The system does not integrate with OpenTelemetry or similar. If you need cross-service traces, you must instrument the code yourself.

Technical Verdict

Use Agent Teams AI when:

  • You need a visual interface for multi-agent coordination and want to avoid building a custom dashboard.
  • Your agents perform long-running tasks (minutes to hours) where polling-based messaging is acceptable.
  • You want built-in peer review and delegation without writing orchestration logic from scratch.
  • You need to support multiple LLM providers without vendor lock-in.

Avoid it when:

  • You need sub-second agent-to-agent communication (the polling interval introduces latency).
  • Your agents must coordinate across multiple machines or data centers (the architecture assumes a single orchestration server).
  • You require formal verification of agent behavior or provable safety properties (the system has no formal model).
  • You need fine-grained access control or multi-tenancy (all agents see the full board).

The kanban-as-state and peer-review patterns are the most interesting contributions. They turn coordination into a visible, debuggable process instead of hidden message passing. The trade-off is latency and limited scalability, but for desktop-scale automation or small team workflows, the simplicity wins.