> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evo-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A Agent

> Integrate external agents that implement the Agent-to-Agent protocol as native agents in the platform

## Overview

The **A2A Agent** enables the integration of external agents that implement the Agent-to-Agent (A2A) protocol as native agents within the Evo AI platform. Using the ADK base agent, these external agents can be used anywhere in the system as if they were local agents.

This functionality is fundamental for creating hybrid ecosystems, where externally developed or hosted agents in other systems can seamlessly participate in complex workflows alongside native platform agents.

<Note>
  **Based on A2A Protocol**: Implementation following the [Agent-to-Agent protocol](https://google.github.io/A2A/specification/) developed by Google for agent interoperability.
</Note>

## Key Features

<CardGroup cols={2}>
  <Card title="Transparent Integration" icon="plug">
    External agents function as natives in workflows and sub-agents
  </Card>

  <Card title="Standard Protocol" icon="network-wired">
    Uses A2A protocol for standardized and interoperable communication
  </Card>

  <Card title="ADK Base Agent" icon="cube">
    Implemented on top of the ADK base agent for maximum compatibility
  </Card>

  <Card title="Total Flexibility" icon="arrow-right-arrow-left">
    Agents can be on any infrastructure or technology
  </Card>
</CardGroup>

## When to Use A2A Agent

<AccordionGroup>
  <Accordion icon="check" title="Ideal Scenarios">
    **✅ Use A2A Agent when:**

    * **External agents**: Integrating agents developed outside the platform
    * **Legacy systems**: Connecting existing systems via A2A protocol
    * **External specialization**: Using specialized third-party agents
    * **Distributed infrastructure**: Agents in different clouds or datacenters
    * **Specific technologies**: Agents in Python, Node.js, or other languages

    **Practical examples:**

    * Python data analysis agent hosted externally
    * Legacy recommendation system exposed via A2A
    * Specialized image processing agent
    * Third-party translation service
    * Document validation agent in specific infrastructure
  </Accordion>

  <Accordion icon="x" title="When NOT to use">
    **❌ Avoid A2A Agent when:**

    * **Simple agents**: Functionality can be implemented natively
    * **Critical latency**: Network communication adds overhead
    * **Sensitive data**: Requires local processing for security
    * **Total control**: Need complete control over execution
    * **Initial development**: Better to start with native agents
  </Accordion>
</AccordionGroup>

## Creating an A2A Agent

### Step by Step on the Platform

<AccordionGroup>
  <Accordion icon="robot" title="1. Start creation">
    1. On the Evo AI main screen, click **"New Agent"**
    2. In the **"Type"** field, select **"A2A Agent"**
    3. You'll see specific fields for A2A configuration

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/a2a_agent_creation.png" alt="Creating A2A Agent" />
  </Accordion>

  <Accordion icon="gear" title="2. Configure basic information">
    **Name:** A2A agent name on the platform

    ```
    Example: python_data_analyzer
    ```

    **Description:** Summary of external agent capabilities

    ```
    Example: Agent specialized in complex data analysis 
    using advanced Python libraries, hosted externally
    ```

    **Goal:** Agent's objective and responsibilities

    ```
    Example: Perform advanced statistical analysis and machine learning 
    on large datasets, providing insights and visualizations
    ```
  </Accordion>

  <Accordion icon="network-wired" title="3. Configure A2A connection">
    **Endpoint URL:** URL of the external agent implementing A2A

    ```
    Example: https://data-analyzer.mycompany.com/api/v1/a2a
    ```

    **Agent ID:** Agent identifier in the external system

    ```
    Example: data-analyzer-v2
    ```

    **Authentication:** Authentication method

    ```
    Options:
    - API Key (x-api-key header)
    - Bearer Token (Authorization header)
    - Basic Auth (username/password)
    - Custom Headers
    ```

    **API Key/Token:** Credentials for authentication

    ```
    Example: sk-1234567890abcdef...
    ```

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/a2a_agent_connection.png" alt="Configuring A2A Connection" />
  </Accordion>

  <Accordion icon="file" title="4. Define agent interface">
    **Instructions:** How to use the A2A agent in the platform context

    ```markdown theme={null}
    # External Python Data Analyzer

    This agent performs advanced data analysis using Python.

    ## Capabilities:
    - Descriptive and inferential statistical analysis
    - Machine learning (classification, regression, clustering)
    - Interactive visualizations and reports
    - Large dataset processing (>1GB)

    ## How to use:
    Send data in JSON or CSV format along with specific instructions:
    - Desired analysis type
    - Specific parameters
    - Preferred output format

    ## Input example:
    {
      "data": "base64_encoded_csv_data",
      "analysis_type": "regression",
      "target_column": "sales",
      "features": ["price", "marketing_spend", "season"]
    }

    ## Limitations:
    - Maximum timeout: 10 minutes
    - Maximum data size: 100MB
    - Supported formats: CSV, JSON, Parquet
    ```
  </Accordion>

  <Accordion icon="gear" title="5. Advanced configurations">
    **Timeout:** Time limit for calls to external agent

    ```
    Recommended: 300-600 seconds (depending on complexity)
    ```

    **Retry Policy:** Retry policy in case of failure

    ```
    Options:
    - No Retry (for critical operations)
    - Retry Once (default)
    - Retry with Backoff (for temporary failures)
    ```

    **Health Check:** External agent health verification

    ```
    - Health Check URL: /health
    - Check Interval: 60 seconds
    - Failure Threshold: 3 consecutive failures
    ```

    **Circuit Breaker:** Protection against cascading failures

    ```
    - Failure Rate Threshold: 50%
    - Recovery Time: 30 seconds
    - Half-Open Requests: 3
    ```

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/a2a_agent_advanced.png" alt="Advanced A2A Configurations" />
  </Accordion>
</AccordionGroup>

## Practical Examples

### 1. Python Data Analysis Agent

<AccordionGroup>
  <Accordion icon="chart-bar" title="Agent Configuration">
    **Scenario:** Integrate external Python data analysis system

    **Platform configuration:**

    **Basic Information:**

    * **Name:** `python_data_analyzer`
    * **Description:** `Python agent for advanced data analysis and ML`
    * **Goal:** `Provide insights through statistical analysis and machine learning`

    **A2A Connection:**

    * **Endpoint:** `https://analytics.company.com/api/v1/a2a/data-analyzer`
    * **Agent ID:** `data-analyzer-prod`
    * **Auth Method:** `API Key`
    * **API Key:** `da_prod_key_abc123...`

    **Advanced Settings:**

    * **Timeout:** `600 seconds` (analysis can be time-consuming)
    * **Retry Policy:** `Retry with Backoff`
    * **Health Check:** `Enabled` (`/health` endpoint)

    **Usage Instructions:**

    ```markdown theme={null}
    # Python Data Analyzer

    Send data and analysis specifications:

    ## Input Format:
    {
      "dataset": "base64_csv_data",
      "analysis": {
        "type": "regression|classification|clustering|descriptive",
        "target": "column_name",
        "features": ["col1", "col2", "col3"],
        "parameters": {...}
      }
    }

    ## Output Format:
    {
      "results": {...},
      "visualizations": ["base64_plot1", "base64_plot2"],
      "insights": ["insight1", "insight2"],
      "model_metrics": {...}
    }
    ```
  </Accordion>
</AccordionGroup>

### 2. Legacy Recommendation System

<AccordionGroup>
  <Accordion icon="star" title="Agent Configuration">
    **Scenario:** Integrate existing recommendation system via A2A

    **Platform configuration:**

    **Basic Information:**

    * **Name:** `legacy_recommender`
    * **Description:** `Legacy recommendation system integrated via A2A`
    * **Goal:** `Provide personalized recommendations based on history`

    **A2A Connection:**

    * **Endpoint:** `https://recommender.legacy-system.com/a2a`
    * **Agent ID:** `recommender-v1`
    * **Auth Method:** `Bearer Token`
    * **Token:** `Bearer eyJhbGciOiJIUzI1NiIs...`

    **Usage Instructions:**

    ```markdown theme={null}
    # Legacy Recommendation System

    ## Input:
    {
      "user_id": "12345",
      "context": {
        "category": "electronics",
        "price_range": [100, 500],
        "previous_purchases": [...]
      },
      "num_recommendations": 10
    }

    ## Output:
    {
      "recommendations": [
        {
          "item_id": "item123",
          "score": 0.95,
          "reason": "Based on similar purchases"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### 3. Image Processing Agent

<AccordionGroup>
  <Accordion icon="image" title="Agent Configuration">
    **Scenario:** Integrate specialized image processing service

    **Platform configuration:**

    **Basic Information:**

    * **Name:** `image_processor`
    * **Description:** `Agent specialized in image analysis and processing`
    * **Goal:** `Extract information, detect objects and process images`

    **A2A Connection:**

    * **Endpoint:** `https://vision-api.imageservice.com/a2a`
    * **Agent ID:** `vision-processor`
    * **Auth Method:** `Custom Headers`
    * **Headers:** `X-API-Key: img_key_xyz789...`

    **Usage Instructions:**

    ```markdown theme={null}
    # Image Processor

    ## Capabilities:
    - Object detection
    - Text extraction (OCR)
    - Image classification
    - Face recognition
    - Image enhancement

    ## Input:
    {
      "image": "base64_encoded_image",
      "operations": ["detect_objects", "extract_text"],
      "options": {
        "confidence_threshold": 0.8,
        "max_objects": 10
      }
    }

    ## Output:
    {
      "objects": [...],
      "text": "extracted text",
      "metadata": {...}
    }
    ```
  </Accordion>
</AccordionGroup>

## Workflow Integration

### Using A2A Agents in Sub-Agents

<AccordionGroup>
  <Accordion icon="sitemap" title="In Sequential Agents">
    **Example: Product Analysis Pipeline**

    ```markdown theme={null}
    Pipeline with A2A Agent:

    1. **Data Collector** (Native)
       - Collects product information

    2. **Image Analyzer** (A2A Agent)
       - Processes product images
       - Extracts visual features

    3. **Sentiment Analyzer** (Native)
       - Analyzes reviews and comments

    4. **Report Generator** (Native)
       - Combines all analyses
    ```
  </Accordion>

  <Accordion icon="arrow-right-arrow-left" title="In Parallel Agents">
    **Example: Complete User Analysis**

    ```markdown theme={null}
    Parallel analyses:

    - **Email Verifier** (Native)
    - **Credit Analyzer** (External A2A Agent)
    - **Document Verifier** (Specialized A2A Agent)
    - **Background Checker** (Native)

    All execute simultaneously and results are aggregated.
    ```
  </Accordion>

  <Accordion icon="recycle" title="In Loop Agents">
    **Example: Campaign Optimization**

    ```markdown theme={null}
    Iterative loop:

    1. **Parameter Generator** (Native)
    2. **Performance Simulator** (Python A2A Agent)
    3. **Results Analyzer** (Native)
    4. **Convergence Decider** (Native)

    The Python A2A Agent uses specialized libraries for simulation.
    ```
  </Accordion>
</AccordionGroup>

## Monitoring and Debugging

### Tracking A2A Agents

<AccordionGroup>
  <Accordion icon="chart-line" title="Monitoring Dashboard">
    **Specific metrics for A2A Agents:**

    * **Network latency**: Communication time with external agent
    * **Success rate**: Percentage of successful calls
    * **Health status**: External agent health status
    * **Circuit breaker**: Circuit breaker state
    * **Retry attempts**: Number of attempts per call

    **Real-time visualization:**

    ```
    A2A Agent: python_data_analyzer

    Status: 🟢 Healthy
    Endpoint: https://analytics.company.com/...

    Last 24h Metrics:
    ├── Success Rate: 98.5%
    ├── Avg Latency: 2.3s
    ├── Total Calls: 1,247
    ├── Failed Calls: 19
    └── Circuit Breaker: CLOSED

    Recent Activity:
    ├── 14:32 - Analysis completed (3.2s)
    ├── 14:30 - Analysis started
    ├── 14:28 - Health check OK
    └── 14:25 - Analysis completed (1.8s)
    ```
  </Accordion>

  <Accordion icon="bug" title="Problem Debugging">
    **Common issues with A2A Agents:**

    **1. Connection Timeout**

    ```
    Symptom: Calls frequently exceed time limit
    Cause: Slow external agent or unstable network
    Solution: Increase timeout or optimize external agent
    ```

    **2. Authentication Failures**

    ```
    Symptom: 401/403 error in calls
    Cause: Invalid or expired credentials
    Solution: Check and update API keys/tokens
    ```

    **3. Active Circuit Breaker**

    ```
    Symptom: Calls automatically rejected
    Cause: High failure rate activated circuit breaker
    Solution: Check external agent health
    ```

    **4. Incompatible Data Format**

    ```
    Symptom: External agent returns format error
    Cause: Sent data doesn't follow A2A protocol
    Solution: Validate input/output format
    ```
  </Accordion>
</AccordionGroup>

## Advanced Configurations

### Performance Optimization

<AccordionGroup>
  <Accordion icon="rocket" title="Latency Reduction">
    **Strategies to optimize performance:**

    **Connection Pooling:**

    ```markdown theme={null}
    - Reuse HTTP connections
    - Configure appropriate keep-alive
    - Limit number of simultaneous connections
    ```

    **Intelligent Caching:**

    ```markdown theme={null}
    - Cache deterministic results
    - Use TTL based on data nature
    - Invalidate cache when necessary
    ```

    **Compression:**

    ```markdown theme={null}
    - Enable gzip/deflate compression
    - Compress large payloads
    - Use binary formats when appropriate
    ```
  </Accordion>

  <Accordion icon="shield" title="Resilience and Reliability">
    **Configurations for maximum robustness:**

    **Circuit Breaker Settings:**

    ```markdown theme={null}
    - Failure Threshold: 50% (adjust according to SLA)
    - Recovery Time: 30s (time to try again)
    - Half-Open Requests: 3 (tests during recovery)
    ```

    **Retry Configuration:**

    ```markdown theme={null}
    - Max Retries: 3
    - Backoff Strategy: Exponential
    - Initial Delay: 1s
    - Max Delay: 30s
    ```

    **Health Check:**

    ```markdown theme={null}
    - Check Interval: 60s
    - Timeout: 10s
    - Failure Threshold: 3 consecutive failures
    ```
  </Accordion>

  <Accordion icon="lock" title="Security">
    **Security configurations:**

    **Authentication:**

    ```markdown theme={null}
    - Always use HTTPS
    - Rotate API keys regularly
    - Implement rate limiting
    ```

    **Data Protection:**

    ```markdown theme={null}
    - Encrypt sensitive data
    - Use TLS 1.3 or higher
    - Validate SSL certificates
    ```

    **Access Control:**

    ```markdown theme={null}
    - Whitelist IPs when possible
    - Use tokens with limited scope
    - Monitor access attempts
    ```
  </Accordion>

  <Accordion icon="database" title="Output Key - State Sharing">
    **`Output Key` field in the interface:**

    The Output Key allows the A2A Agent to save the external agent's response to a specific variable in the shared state, making it available to other agents or subsequent processes.

    **How it works:**

    * Configure the `Output Key` field with a descriptive name
    * The external agent's response will be automatically saved to that variable
    * Other agents can access it using placeholders `{{output_key_name}}`
    * Works in workflows, loops, and multi-agent systems

    **Configuration examples:**

    ```markdown theme={null}
    Output Key: "external_analysis"
    → Saves response in state.external_analysis

    Output Key: "ai_processed_data"
    → Saves response in state.ai_processed_data

    Output Key: "validation_result"
    → Saves response in state.validation_result
    ```

    **Usage in other agents:**

    ```markdown theme={null}
    # In subsequent agent instructions:
    "Analyze the request: {{user_input}} and base it on the external analysis: {{external_analysis}}"
    "Use the processed data: {{ai_processed_data}}"
    "Consider the validation: {{validation_result}}"
    ```

    **A2A data handling:**

    ```markdown theme={null}
    # The A2A Agent automatically:
    - Extracts the result from JSON-RPC 2.0 protocol
    - Converts to usable format
    - Saves to state with specified key
    - Handles errors and timeouts appropriately
    ```

    **Best practices:**

    * Use snake\_case: `external_system_response`, `validated_data`
    * Be specific: `sentiment_analysis_api` instead of `analysis`
    * Document expected external response format
    * Consider error handling in state
    * Use names that identify external origin
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion icon="lightbulb" title="Integration Design">
    **Principles for effective integration:**

    * **Idempotency**: Operations should be safe for retry
    * **Appropriate timeouts**: Balance between performance and reliability
    * **Error handling**: Handle failures gracefully
    * **Monitoring**: Constantly monitor health and performance
    * **Documentation**: Clearly document interface and limitations
  </Accordion>

  <Accordion icon="network-wired" title="A2A Protocol">
    **Correct protocol implementation:**

    * **JSON-RPC 2.0**: Follow specification rigorously
    * **Message IDs**: Use unique UUIDs for tracking
    * **Error codes**: Implement standardized error codes
    * **Streaming**: Support SSE for long operations
    * **Context**: Maintain context between calls when necessary
  </Accordion>

  <Accordion icon="shield-check" title="Operation and Maintenance">
    **Ensuring stable operation:**

    * **Health checks**: Implement health endpoints
    * **Logging**: Log all interactions
    * **Metrics**: Collect performance metrics
    * **Alerting**: Configure alerts for issues
    * **Versioning**: Manage API versions carefully
  </Accordion>
</AccordionGroup>

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Legacy Systems" icon="server">
    **Gradual Modernization:**

    * Integration of existing systems
    * Incremental migration to new architecture
    * Preservation of previous investments
  </Card>

  <Card title="External Specialization" icon="star">
    **Specialized Agents:**

    * Advanced data analysis
    * Image/video processing
    * Specialized machine learning
  </Card>

  <Card title="Distributed Infrastructure" icon="cloud">
    **Multi-Cloud/Hybrid:**

    * Agents in different clouds
    * Edge computing
    * Compliance and data residency
  </Card>

  <Card title="Third Parties" icon="handshake">
    **Third-Party Services:**

    * Partner APIs
    * Specialized SaaS services
    * Vendor integrations
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="A2A Protocol" icon="network-wired" href="/a2a-protocol">
    Understand the Agent-to-Agent protocol in detail
  </Card>

  <Card title="LLM Agent" icon="brain" href="/agents/llm">
    Learn about native intelligent agents
  </Card>

  <Card title="Configurations" icon="gear" href="/configurations/index">
    Explore advanced agent configurations
  </Card>

  <Card title="Workflow Agents" icon="sitemap" href="/agents/sequential">
    Use A2A Agents in complex workflows
  </Card>
</CardGroup>

***

The A2A Agent is essential for creating hybrid ecosystems and integrating external agents. Use it to leverage existing systems and external specialization while maintaining the flexibility of the Evo AI platform.