0.1.4

AgyQueue: Non-Blocking Asynchronous Task Execution for AI Agents

AgyQueue is a lightweight, non-blocking asynchronous task execution framework built for AI agents. It allows agents to offload long-running operations—such as code generation, compilation, testing, and validation—to background workers while keeping client conversation threads responsive.

---

🚀 Core Capabilities

1. Asynchronous Task Offloading: Agents submit tasks via MCP tool calls or REST API requests and immediately receive a task_id, returning execution control back to the user chat session.
2. Resilience & Reconnection: Task status is saved in a persistent database store, allowing clients to query progress or fetch final outputs even after network drops or worker crashes.
3. Interactive Console UI: Built-in dark mode dashboard that visualizes enqueued runs, progress bars, vertical event history timelines (e.g. WorkflowExecutionStarted, WorkflowTaskScheduled), and aggregated markdown reports.
4. Well-Architected Architecture:
   • Threaded Connection Pooling: Uses ThreadedConnectionPool for PostgreSQL backend tasks, preventing socket exhaust under high concurrent query volumes.
   • Graceful Shutdown: Catches SIGTERM / SIGINT signals, allowing workers to finish their active task run cleanly before eviction.
   • Workspace Isolation: Spawns copy-on-write scratch worktree folders for subprocess executions, ensuring zero file-system cross-interference.
5. Configurable Multi-Channel Notifications: Real-time push notifications over Slack webhook and SMTP Email when tasks hit terminal states.
6. Model Context Protocol (MCP) Support: Serves as a standard stdio/sse MCP server compatible with Cursor, Claude Desktop, Claude Code, and Copilot CLI.

---

🛠️ Architecture

AgyQueue supports both hybrid cloud-agnostic execution flows and fully-managed Google Cloud configurations:

1. Cloud-Agnostic Core Flow

2. Google Cloud Native Production Deployment

Google Cloud & Google AI Managed Services Mapping

When migrating from local development/fallback to production cloud scaling, AgyQueue integrates natively with Google Cloud managed services:

---

📦 Installation & Setup

Install as Python Package (Local Development)

You can install AgyQueue locally in editable mode for development and testing:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env

Install from PyPI

Once published, users can install AgyQueue directly from PyPI:

pip install agyqueue

---

🏁 Quick Start

1. Run Standalone Dev Demo

Spins up a local server, enqueues an SRE compliance check and FastAPI code generator workflow, executes it in isolated directories, and outputs the final report:

python examples/demo.py

2. Open the Web Console Dashboard

Start the standalone SSE server and background worker:

# Terminal 1: Start Server
export AGYQUEUE_TRANSPORT=sse
python -m agyqueue.mcp_server

# Terminal 2: Start Worker
python -m agyqueue.worker

Navigate to http://localhost:8000/dashboard to submit runs, inspect progress, and view timeline event history logs.

---

📁 Examples & Client Integrations

The examples/ folder contains detailed client scripts for every connection method:

• Antigravity 2.0 SDK: examples/antigravity_agent_sdk.py shows how to bind tools to a google.antigravity agent.
• Google ADK Agents: examples/google_adk_agent.py demonstrates tool binding in the google.adk.agents framework.
• StdIO MCP Client: examples/mcp_stdio_client.py connects programmatically via stdin/stdout subprocesses.
• SSE MCP Client: examples/mcp_sse_client.py connects over network Server-Sent Events.
• Direct REST SDK: examples/rest_client_sdk_demo.py performs calls using the lightweight AgyQueueClient Python client.

---

🔌 Connecting to Agentic Frameworks

1. Google Agent Development Kit (ADK) & Agent Engine

The Google ADK allows Python-defined agents to be deployed to Agent Engine (Vertex AI Reasoning Engine). Import and register AgyQueue's functional tools directly:

from google.adk.agents import Agent
from agyqueue.client import submit_async_task, check_task_progress, get_task_output, cancel_running_task

# Define the coordinator agent
orchestrator_agent = Agent(
    name="deployment_coordinator",
    model="gemini-3.5-flash",
    instruction=(
        "You coordinate SRE compliance checks and API code generation workloads. "
        "Use submit_async_task to spawn background jobs. Do not wait for jobs in a loop. "
        "Return the task_id to the user/orchestrator so that progress can be tracked asynchronously."
    ),
    tools=[
        submit_async_task,
        check_task_progress,
        get_task_output,
        cancel_running_task
    ]
)

2. Registering with Agent Registry as MCP Server

To register AgyQueue with your Google Cloud Agent Registry as an MCP server, run the following:

agents-cli publish gemini-enterprise \
  --name "agyqueue" \
  --description "A pluggable, non-blocking asynchronous task queue and MCP server for AI Agents." \
  --url "https://<your-agyqueue-server-url>/sse" \
  --type "mcp"

For the Gemini CLI / Antigravity CLI (agy), you can install this repository directly as a fully compatible local/remote extension by running:

agy plugin install .agents

(The repository is configured as a native Gemini extension via gemini-extension.json and .agents/ metadata).

---

💻 Local IDE & AI CLI Integration (MCP)

To make it incredibly easy for anyone cloning or using this repository, we have provided pre-configured JSON snippets and integration files for all major AI-based development platforms inside the mcp-configs/ directory.

🚀 Direct Integration Files

• Claude Code CLI: Add the server config in mcp-configs/claude_code_config.json to your ~/.config/claude-code/mcp.json.
• Claude Desktop: Copy the snippet in mcp-configs/claude_desktop_config.json to your claude_desktop_config.json.
• Cursor IDE: Add a new MCP server in Cursor Settings under Features -> MCP using the parameters specified in mcp-configs/cursor_config.json.
• Windsurf IDE: Add the server config in mcp-configs/windsurf_config.json to your ~/.codeium/windsurf/mcp_config.json.
• VS Code (Cline / Roo Code / Copilot / Codex / others): Append the server config in mcp-configs/copilot_config.json to your cline_mcp_settings.json or Copilot MCP configuration.

🛠️ Configuration Quick-Reference

Claude Desktop Configuration

Add the following to your claude_desktop_config.json (located in ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "agyqueue": {
      "command": "python",
      "args": ["-m", "agyqueue.mcp_server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/your/agyqueue/repo",
        "AGYQUEUE_TRANSPORT": "stdio",
        "AGYQUEUE_DB_PATH": "/absolute/path/to/your/agyqueue/repo/agyqueue.db"
      }
    }
  }
}

Gemini CLI & Antigravity CLI Configuration

To configure AgyQueue as an MCP server inside your global Gemini/Antigravity CLI settings (located at ~/.gemini/GEMINI.md or user preferences), append the server config under the "mcpServers" dictionary:

Option A: Local StdIO Execution

{
  "mcpServers": {
    "agyqueue": {
      "command": "python",
      "args": ["-m", "agyqueue.mcp_server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/your/agyqueue/repo",
        "AGYQUEUE_TRANSPORT": "stdio",
        "AGYQUEUE_DB_PATH": "/absolute/path/to/your/agyqueue/repo/agyqueue.db"
      }
    }
  }
}

Option B: Remote SSE (Server-Sent Events) Service

{
  "mcpServers": {
    "agyqueue": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client-sse",
        "https://<your-agyqueue-server-url>/sse"
      ]
    }
  }
}

Cursor Configuration

1. Open Cursor Settings -> Features -> MCP.
2. Click + Add New MCP Server.
3. Configure:
   • Name: AgyQueue
   • Type: command
   • Command: PYTHONPATH=. .venv/bin/python -m agyqueue.mcp_server (relative to your repo path).

VS Code Configuration (Cline / Roo Code / Copilot / Codex)

Append the AgyQueue stdio server configuration to your MCP settings file:

{
  "mcpServers": {
    "agyqueue": {
      "command": "python",
      "args": ["-m", "agyqueue.mcp_server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/your/agyqueue/repo",
        "AGYQUEUE_TRANSPORT": "stdio",
        "AGYQUEUE_DB_PATH": "/absolute/path/to/your/agyqueue/repo/agyqueue.db"
      }
    }
  }
}

Claude Code CLI Integration

Add AgyQueue as a local tool under the "mcpServers" dictionary in ~/.config/claude-code/mcp.json using the SSE endpoint:

{
  "mcpServers": {
    "agyqueue": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client-sse",
        "https://<your-agyqueue-server-url>/sse"
      ]
    }
  }
}

---

🌳 Multi-Agent Tree-Based Orchestration Pattern

AgyQueue natively supports parent-child task aggregation. When an orchestrator agent splits a large request into parallel child workloads, it submits the subtasks with a parent_id parameter:

1. Task Submission:
   • The orchestrator spawns subagents by submitting child tasks referencing the parent ID.
   • The parent task status transitions to WAITING.
2. Worker Isolation:
   • Background workers pick up and execute child tasks in isolated workspaces (git_worktree or copy-on-write temp folders) in parallel.
3. Automatic Resumption:
   • As soon as the final sibling completes, the worker recognizes that all siblings are done and automatically re-queues the parent task.
   • The orchestrator wakes up, reads the logs of all completed subtasks, aggregates the results, and marks the parent task as COMPLETED.

---

🐳 Docker Compose Deployment (Redis + SSE Mode)

To run the complete system with Redis queues and PostgreSQL stores:

1. Build and Run:

   docker compose up --build
   

2. Verify over SSE:

   python examples/mcp_sse_client.py
   

---

☁️ Cloud Deployment (Cloud Run & GKE)

For Google Cloud production environments, configuration templates are located in deployment/:

• Cloud Run: Serverless container setups with Memorystore Redis and Cloud SQL PostgreSQL.
• GKE: Scalable Kubernetes microservices with Horizontal Pod Autoscalers (HPA).

---

---

🚀 Publishing to PyPI

Step 1: Install Build Tools

pip install --upgrade build twine

Step 2: Build the Distribution Package

python -m build

Step 3: Upload to PyPI

Run twine to securely publish to PyPI under your profile:

python -m twine upload dist/*

Once uploaded, anyone can install and run the AgyQueue CLI globally:

pip install agyqueue