A2A Multi-Agent Dynamic Coordination POC

This repository demonstrates an advanced Agent-to-Agent (A2A) ecosystem featuring Autonomous DAG Orchestration, Dynamic Discovery, and Integrated MCP Tool-Calling. The POC orchestrates complex, parallel workflows across specialized agents to solve multi-step goals.

🚀 Key Features

• Parallel DAG Orchestration: The core orchestrator (run_poc_flow.py) uses a Planner Agent to decompose user queries into a Directed Acyclic Graph (DAG), enabling concurrent execution of independent tasks.
• A2A v1.0 Production Security: Support for Digital Signatures (RS256) for Agent Cards and Bearer Token Authentication for secure agent-to-agent communication.
• Distributed Observability: Integrated OpenTelemetry tracing for every agent task, capturing performance spans and error metadata.
• Dynamic LangGraph Control: A stateful, cyclic orchestration model (run_langgraph_flow.py) for complex, self-correcting agent workflows.
• Robust Redis Registry: A persistent discovery service with TTL-based lifecycle management and automatic in-memory fallback.
• Production-Ready Agent Cards: Rich metadata including Input/Output Schemas, Operational Constraints (Latency/Rate Limits), and explicit Ownership.
• Multi-Format Visual Artifacts: Integrated AntV MCP and cairosvg for dual-format (SVG + PNG) charting with isolated, approach-specific naming.
• Data-Grounded Pipeline: agents process real-world security audit data from external text files for high-fidelity reporting.

---

🏗️ Architecture

The system architecture follows a modular, agent-centric design optimized for parallel execution and dynamic tool integration. We support two orchestration models:

1. Standard DAG Orchestration (Original)

A one-shot, forward-only execution model where the Planner generates a plan and the Orchestrator executes it in waves.

graph TD
    User([User/Client]) --> Orchestrator[Parallel DAG Orchestrator]
    
    subgraph "Orchestration Layer"
        Orchestrator --> Registry[Dynamic Registry Server]
        Orchestrator --> Planner[Planner Agent]
        Planner -- "Generates DAG" --> Orchestrator
    end

    subgraph "Parallel Execution Pool"
        Orchestrator -- Task A --> Report[Report Agent]
        Orchestrator -- Task B --> Validator[Validator Agent]
        Orchestrator -- Task C --> Chart[Charting Agent]
    end

    subgraph "Tooling Layer (MCP)"
        Chart --> AntV[AntV Charting MCP]
        Validator --> QualityGate[LLM Quality Check]
    end

    Report --> Return[Context Aggregation]
    Validator --> Return
    Chart --> Return
    Return --> Orchestrator
    Orchestrator -->|Synthesized Result| User

Loading

2. Dynamic LangGraph Orchestration (Recommended)

A stateful, cyclic orchestration model that enables complex control flows, recursive planning, and feedback loops.

graph TD
    User([User/Client]) --> State([Shared Agent State])
    State --> Planner[Planner Node]
    Planner -- "Generates DAG Plan" --> State
    State --> Controller{Controller Node}
    Controller -- "Parallel Dispatch" --> Executor[Executor Node]
    Executor -- "Report Agent" --> State
    Executor -- "Validator Agent" --> State
    Executor -- "Charting Agent" --> State
    State -- "State Updated" --> Controller
    Controller -- "Task Pool Empty" --> End([Final Synthesis])
    End --> User

Loading

---

📁 Repository Structure

.
├── src/a2a_toolkit/           # Core A2A integration library
│   ├── registry.py            # Local registry client (Redis + In-Memory)
│   ├── types.py               # ProfessionalAgentCard & Schema definitions
│   ├── llm_manager.py         # Standardized LLM interface (Ollama)
│   └── server_adapter.py      # A2A Protocol adapter (Extended)
├── examples/
│   ├── data/                  # External data sources (Security Audits)
│   ├── output/                # Generated artifacts (SVG, PNG, Log Trees)
│   ├── config/                # A2A Configuration & Redis settings
│   ├── servers/               # Collection of specialized agents
│   │   ├── registry_server.py # Central Discovery Service (Redis-ready)
│   │   ├── poc_planner_server.py # DAG-based Planning Agent
│   │   ├── poc_report_server.py  # Data Extraction Agent
│   │   ├── poc_validator_server.py # Quality Gate Agent
│   │   └── poc_chart_server.py    # MCP-enabled Charting Agent (Multi-format)
│   ├── run_poc_flow.py        # Main Parallel DAG Orchestrator
│   └── run_langgraph_flow.py  # Dynamic LangGraph Orchestrator
└── README.md

---

🏛️ Professional Infrastructure

1. Robust Redis Registry

The registry server is Redis-ready. It attempts to connect to a local Redis instance for persistent agent state and TTL-based lifecycle management. If Redis is unavailable, it automatically reverts to a safe In-Memory mode, ensuring system uptime.

2. High-Fidelity Agent Specifications

Each agent exposes a Professional Agent Card containing:

• Input/Output Schemas: Formal JSON Schema definitions of expected data.
• Operational Constraints: Maximum latency tokens and rate limits.
• Observability: Configuration for structured logging and OpenTelemetry tracing.

3. Integrated Multi-Format Charting

The Chart Agent coordinates with the AntV MCP Server and uses cairosvg to produce visual risk distributions in both vector (SVG) and broadly compatible raster (PNG) formats.

---

🛠️ Quick Start

1. Prerequisites

• Python 3.11+: Managed via uv (recommended).
• Node.js v20+: Required for AntV Charting MCP.
• Redis: Optional but recommended for persistent agent discovery.
• Ollama: Required for local LLM inference.
  • Pull required models:

    ollama pull gemma3:270m      # Reasoner & Classifier
    ollama pull qwen3:0.6b       # Vision/Multimodal
    ollama pull functiongemma:270m # Tool-calling

• System Libraries (for CairoSVG):
  • Linux: sudo apt-get install libcairo2
  • macOS: brew install cairo

2. Startup Sequence

Launch the ecosystem in the following order using separate terminals:

# 1. Start the Dynamic Registry (Port 9500)
# This acts as the central discovery node.
uv run python examples/servers/registry_server.py

# 2. Start the Specialized Agents
# These will automatically register themselves with the Registry.
uv run python examples/servers/poc_planner_server.py
uv run python examples/servers/poc_report_server.py
uv run python examples/servers/poc_validator_server.py
uv run python examples/servers/poc_chart_server.py

3. Run the End-to-End Flow

Execute the parallel orchestration using the standard DAG scheduler:

uv run python examples/run_poc_flow.py

4. Dynamic LangGraph Orchestration

Experience stateful, dynamic orchestration using the LangGraph engine:

uv run python examples/run_langgraph_flow.py

This version supports recursive planning, persistent state, and advanced error handling.

---

⚙️ Configuration Guide (a2a_config.json)

The system uses a centralized configuration file at examples/config/a2a_config.json.

1. servers

Maps agent roles to their registration/access URLs.

• planner: The DAG planning agent.
• validator: The quality gate agent.
• report: The data extraction and synthesis agent.
• mm: The multimodal/vision agent.
• local-multiagent: Alias for the central registry server.

2. settings.models

Defines which Ollama models to use for specific tasks:

• classifier: Identifying user intent.
• reasoner: Logical analysis and planning.
• vision: Image/PDF processing.
• tool_caller: Specialized model for generating tool calls.

3. settings.ports

Explicitly defines the ports for each server. Ensure these match your environment and are not blocked by firewalls.

• router: 9500 (Registry/Router)
• planner_server: 9011
• validator_server: 9012
• mm_server: 9013
• report_server: 9017
• chart_server: 9018

4. settings.redis

Persistent storage configuration for the agent registry.

• enabled: Set to true to use Redis; false falls back to In-Memory storage.
• host / port / db: Standard Redis connection parameters.
• agent_ttl: registration expiry time (seconds).

5. settings.mcp_servers

Configurations for Model Context Protocol bridges:

• mcp-atlassian: Tools for Confluence/Jira.
  • env: Must contain CONFLUENCE_URL, CONFLUENCE_USERNAME, and CONFLUENCE_API_TOKEN.
• mcp-server-chart: AntV visualization tools.
  • command: Absolute path to your node binary.
  • args: Path to the compiled index.js of the chart server.

---

🛠️ Detailed Setup

1. Python Environment

We recommend uv for seamless dependency management.

uv sync  # Installs all dependencies from pyproject.toml

2. Redis Setup (Optional)

To enable persistent registration, start a Redis server:

docker run -d --name redis-a2a -p 6379:6379 redis

Then set "enabled": true in a2a_config.json under settings.redis.

3. MCP Server Configuration

AntV Charting

Ensure you have the chart server installed in node_modules:

npm install @antv/mcp-server-chart

Verify the path in a2a_config.json matches your local installation.

Atlassian Integration

Generate an API Token from Atlassian Account Settings and add it to the env section of mcp-atlassian in a2a_config.json.

4. Troubleshooting

• Cairo Library Error: If cairosvg fails with OSError: no library called "cairo", ensure you have installed the libcairo2 library (Linux) or cairo via homebrew (macOS).
• Redis Connection Refused: Ensure the Redis server is running and the port in a2a_config.json matches (default 6379). The system will automatically fall back to In-Memory mode if Redis is unreachable.
• Model Not Found: If Ollama errors with "model not found", run ollama pull <model_name> for the models defined in settings.models.
• Node Path: If the Chart Agent fails to start the MCP server, double-check that the command in settings.mcp_servers.mcp-server-chart is the absolute path to your node executable.

---

🔬 Example Scenario: Multi-Phase Security Audit

The system handles complex, multi-step requests like:

"Conduct a multi-phase security audit of the 'A2A Gateway'. 1) Have 'report' extract vulnerability trends from security_audit_data.txt. 2) Parallelly have 'validator' check trends and 'chart' create a risk visual. 3) Finally, have 'report' synthesize the final executive summary."

1. Orchestrator fetches the Planner to create a multi-layered DAG.
2. Planner identifies the sequential and parallel dependencies.
3. Waves/Nodes are executed according to the plan.
4. Final Result is synthesized with both a text summary and visual artifacts (SVG & PNG).

---

📜 Metadata & Protocols

This POC implements the A2A Protocol v1.0, adhering to the core A2A Design Principles:

A2A Design Principles

1. Embrace agentic capabilities: Enables agents to collaborate in natural, unstructured modalities without limiting them to standard tools.
2. Build on existing standards: Uses established standards like HTTP, SSE, and JSON-RPC for seamless IT stack integration.
3. Secure by default: Supports enterprise-grade authentication with parity to OpenAPI's authentication schemes (e.g., Bearer tokens).
4. Support for long-running tasks: Handles everything from quick executions to multi-day deep research with real-time state updates.
5. Modality agnostic: Beyond standard text, A2A natively supports various modalities like audio and video streaming.

A2A Core Concepts

• Artifacts: Represent tangible outputs generated by remote agents during task processing, incrementally streamable and identified by artifactId.
• Tasks & Messages: Agents can respond immediately with a Message or handle long-running operations via a Task.
• Context (contextId): A server-generated identifier used to logically group multiple related Task objects across a series of interactions.
• Transport and Format: Uses HTTP(S) as the transport layer with JSON-RPC 2.0 as the standardized payload format.
• Extensions: Agents can formally extend the protocol via their Agent Cards defining custom capabilities across four scopes: Data-only, Profile, Method (Extended Skills), and State Machine extensions.

Task Lifecycle & Follow-ups

Our agent coordination architecture inherently complies with A2A's task progression principles:

• Task Immutability: All executed tasks are terminal and immutable. Any subagent refinement explicitly generates a distinct task sharing the parent contextId.
• Parallel Follow-ups: The DAG orchestrator inherently supports branching concurrent requests triggered from identical dependencies.
• Artifact Referencing: Multi-agent sessions seamlessly persist state by resolving downstream inputs via referenceTaskIds.

Streaming & Asynchronous Operations

To support diverse execution environments and long-running autonomous workflows:

• Server-Sent Events (SSE): Real-time incremental results and intermediate task state transitions are streamed back to the orchestrator utilizing text/event-stream.
• Push Notifications (Webhooks): For disconnected runtimes or multi-day executions, agents accept an embedded PushNotificationConfig to ping external webhooks strictly upon critical state transformations.

A2A ❤️ MCP Integration

This architecture demonstrates exactly how A2A and the Model Context Protocol (MCP) act as complementary standards:

• A2A Protocol (Agentic Domain): Governs communication between autonomous peers. Used by the DAG Orchestrator to delegate broad, ambiguous goals to the independent Charting Agent.
• MCP (Tooling Domain): Governs isolated tool usage. Used internally by the Charting Agent to invoke discrete stateless functions on the external AntV Charting MCP server.

Agent Discovery Strategies

The A2A protocol standardizes how agents discover each other's Agent Cards. This POC implements two of the three primary strategies:

• Well-Known URI: Hosting a card at /.well-known/agent-card.json (supported by the standard protocol for public domains).
• Curated Registries: Implemented via our Redis Registry Server for dynamic, catalog-based discovery within the ecosystem.
• Direct Configuration: Implemented via a2a_config.json for static local routing and private discovery scenarios.

Professional Agent Implementation

The POC features professional Agent Cards with:

• Digital Signatures (RS256): Cryptographic proof of identity and metadata integrity.
• Authentication Schemes: Support for Bearer-token based service-to-service security.
• Observability Spans: OpenTelemetry-compliant tracing for task lifecycles.
• Input/Output Schemas for reliable data exchange.
• Operational Constraints for predictable performance (SLAs).
• Persistent Redis Storage for resilient discovery.

API Management & Governance

For robust enterprise deployment, A2A implementations should interface with standard API Management solutions. This POC aligns with these governance pillars:

• Centralized Policy Enforcement: Enforced via our Authentication Schemes (Bearer Tokens) and Operational Constraints (rate-limits/latency SLAs).
• Analytics and Reporting: Realized through our integrated OpenTelemetry Spans for performance metrics and trace reporting.
• Developer Portals & Discovery: Supported via our standard Professional Agent Cards and Redis Registry Server for seamless agent discovery and onboarding.

---

Developed for professional multi-agent ecosystem demonstrations.