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.

Based on A2A Protocol: Implementation following the Agent-to-Agent protocol developed by Google for agent interoperability.

Key Features

Transparent Integration

External agents function as natives in workflows and sub-agents

Standard Protocol

Uses A2A protocol for standardized and interoperable communication

ADK Base Agent

Implemented on top of the ADK base agent for maximum compatibility

Total Flexibility

Agents can be on any infrastructure or technology

When to Use A2A Agent

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

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

Creating an A2A Agent

Step by Step on the Platform

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

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

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

4. Define agent interface

Instructions: How to use the A2A agent in the platform context

# 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

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

Practical Examples

1. Python Data Analysis Agent

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:

# 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": {...}
}

2. Legacy Recommendation System

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:

# 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"
    }
  ]
}

3. Image Processing Agent

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:

# 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": {...}
}

Workflow Integration

Using A2A Agents in Sub-Agents

In Sequential Agents

Example: Product Analysis Pipeline

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

In Parallel Agents

Example: Complete User Analysis

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.

In Loop Agents

Example: Campaign Optimization

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.

Monitoring and Debugging

Tracking A2A Agents

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)

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

Advanced Configurations

Performance Optimization

Latency Reduction

Strategies to optimize performance:

Connection Pooling:

- Reuse HTTP connections
- Configure appropriate keep-alive
- Limit number of simultaneous connections

Intelligent Caching:

- Cache deterministic results
- Use TTL based on data nature
- Invalidate cache when necessary

Compression:

- Enable gzip/deflate compression
- Compress large payloads
- Use binary formats when appropriate

Resilience and Reliability

Configurations for maximum robustness:

Circuit Breaker Settings:

- Failure Threshold: 50% (adjust according to SLA)
- Recovery Time: 30s (time to try again)
- Half-Open Requests: 3 (tests during recovery)

Retry Configuration:

- Max Retries: 3
- Backoff Strategy: Exponential
- Initial Delay: 1s
- Max Delay: 30s

Health Check:

- Check Interval: 60s
- Timeout: 10s
- Failure Threshold: 3 consecutive failures

Security

Security configurations:

Authentication:

- Always use HTTPS
- Rotate API keys regularly
- Implement rate limiting

Data Protection:

- Encrypt sensitive data
- Use TLS 1.3 or higher
- Validate SSL certificates

Access Control:

- Whitelist IPs when possible
- Use tokens with limited scope
- Monitor access attempts

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:

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:

# 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:

# 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

Best Practices

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

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

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

Common Use Cases

Legacy Systems

Gradual Modernization:

• Integration of existing systems
• Incremental migration to new architecture
• Preservation of previous investments

External Specialization

Specialized Agents:

• Advanced data analysis
• Image/video processing
• Specialized machine learning

Distributed Infrastructure

Multi-Cloud/Hybrid:

• Agents in different clouds
• Edge computing
• Compliance and data residency

Third Parties

Third-Party Services:

• Partner APIs
• Specialized SaaS services
• Vendor integrations

Next Steps

A2A Protocol

Understand the Agent-to-Agent protocol in detail

LLM Agent

Learn about native intelligent agents

Configurations

Explore advanced agent configurations

Workflow Agents

Use A2A Agents in complex workflows

---

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.