A2A Client Plugin for Dify

Connect your Dify agents to any external agents using the standardized Agent-to-Agent (A2A) protocol v0.3.0.

🌟 Overview

The A2A Client plugin enables Dify agents to communicate and collaborate with external agents that implement the A2A (Agent-to-Agent) protocol. This opens up a world of possibilities by allowing your Dify workflows to delegate specialized tasks to domain-expert agents, regardless of which platform they run on.

What is the A2A Protocol?

The Agent-to-Agent (A2A) protocol is an open standard for enabling different AI agents to communicate with each other. Think of it as a universal translator that allows agents from different platforms to work together seamlessly.

Key Benefits:

🌐 Universal Compatibility - Connect Dify to agents on any platform that supports A2A
🔧 Specialization - Delegate tasks to agents with specific domain expertise
🚀 Scalability - Build agent ecosystems that can grow and evolve
📖 Open Standard - Based on JSON-RPC 2.0, not proprietary to any vendor

Why This Plugin Matters

Without the A2A protocol, each agent platform operates in isolation. With this plugin, your Dify agents can:

Access specialized knowledge - Connect to domain-expert agents (sales, research, analytics)
Leverage external tools - Use capabilities that don't exist in Dify
Build agent networks - Create complex workflows spanning multiple platforms
Collaborate asynchronously - Submit long-running tasks and check results later

⚠️ Prerequisites

Community Edition Users:

This plugin is not yet published to the Dify Marketplace and requires disabling signature verification for installation.

Requirements:

Dify Community Edition v1.0.0 or higher
Access to set environment variables (Docker, Kubernetes, bare metal, etc.)
Admin access to modify deployment configuration

Cloud Edition Users:

This plugin cannot currently be installed on Dify Cloud. We plan to submit to the Marketplace in the future.

🏗️ How It Works

Architecture

Communication Patterns

The plugin supports both synchronous and asynchronous communication:

Synchronous (message/send):

Send a request → Wait for response → Get immediate result
Best for: Quick queries, fact-checking, simple delegations

Asynchronous (message/stream + tasks/get):

Submit a task → Receive taskId → Continue working → Check status later
Best for: Complex analysis, long-running operations, resource-intensive tasks
Uses Server-Sent Events (SSE) to stream progress updates

JSON-RPC 2.0 Protocol

All communication uses JSON-RPC 2.0 messages with proper A2A Message objects:

✨ Features

This plugin provides 5 powerful tools for A2A communication:

1. 📋 List Agents

What it does: Shows all agents you've configured in the registry.

When to use:

Discover which agents are available
Show users their agent options
Debug configuration issues

Returns: JSON array of agent names and descriptions

2. 🔍 Get Agent Capabilities

What it does: Fetches the "agent card" from a remote agent, showing what it can do.

How it works:

Queries (or fallback to )
Returns metadata: name, description, capabilities, skills, API endpoints

When to use:

Before calling an unfamiliar agent
To understand what parameters an agent accepts
For dynamic UI generation based on agent capabilities

Returns: Agent card JSON with full capability information

3. 💬 Call Agent (Synchronous)

What it does: Sends a message to an agent and waits for the complete response.

Technical details:

Uses JSON-RPC method
Blocks until agent responds (timeout: 60 seconds)
Best for quick operations

When to use:

Simple queries that return quickly (< 60 seconds)
When you need an immediate answer
For interactive workflows where users are waiting

Example use case:

4. 📤 Submit Task (Asynchronous)

What it does: Submits a long-running task and returns immediately with a taskId.

Technical details:

Uses JSON-RPC method with SSE
Extracts taskId from first Server-Sent Event
Closes stream immediately (true async behavior)
Does NOT wait for completion

When to use:

Complex analysis that takes minutes/hours
Resource-intensive operations
When you want to continue working while agent processes
Batch operations

Example use case:

Returns: TaskId string (e.g., )

5. ✅ Get Task Status

What it does: Checks the status of a previously submitted asynchronous task.

Technical details:

Uses JSON-RPC method
Returns current state: , , , ,

When to use:

After submitting an async task
To poll for completion
To retrieve final results when done

Example workflow:

Returns: Task status object with state, progress, and results (when complete)

📥 Installation

From Dify Marketplace (Coming Soon)

This plugin is pending submission to the Dify Marketplace. Once approved, it will be available for one-click installation.

For Community Edition (Self-Hosted)

Step 1: Enable Unsigned Plugin Installation

Set the following environment variable in your deployment:

Deployment-Specific Instructions:

Docker Compose:
Add to your file or :

Restart:

Kubernetes:
Add to your ConfigMap or deployment environment:

Apply changes:

Bare Metal / Other:
Export environment variable before starting Dify:

⚠️ Security Note: This setting allows ANY unsigned plugin to be installed. Use cautiously and only install plugins you trust. Review the source code before installation.

Step 2: Download Plugin

Download from:

Step 3: Install Plugin

In Dify, click "Plugins" (top-right corner)
Click "Install Plugin → Install via Local File"
Select the file
Click Install

Step 4: Configure Agent Registry

See Configuration section below

⚙️ Configuration

Agent Registry Setup

The plugin stores up to 5 agent configurations using individual credential fields:

For Each Agent (1-5):

Field	Required	Description	Example
Name	Yes	Unique identifier for this agent
Base URL	Yes	A2A protocol endpoint
Auth Type	Yes	Authentication method	, , , or
API Key/Token	Conditional	Required if auth type is not
Description	No	Human-readable description

Authentication Types Explained:

None - No authentication required (public endpoints)
Bearer Token - Standard OAuth 2.0 bearer token authentication
API Key - Custom API key in Authorization header
Basic Auth - Username:password in base64 (format: )

Example Configuration:

Important Notes:

⚠️ Security: API keys are stored securely in Dify's credential system and never exposed to end users.

⚠️ Agent Endpoint Requirements: Remote agents must implement A2A protocol v0.3.0 for compatibility.

🚀 Usage

Basic Workflow

List available agents to see your configured agents
Get agent capabilities to understand what an agent can do
Call agent (sync) for quick queries OR Submit task (async) for long operations
Get task status to check on async tasks

Example: Synchronous Agent Call

Scenario: You need product pricing information.

User asks: "What's the price for Enterprise plan?"
Your Dify workflow uses Call Agent tool:
- Agent Name:
- Instruction:
Sales agent responds immediately with pricing details
Workflow shows response to user

Example: Asynchronous Task Workflow

Scenario: You need deep market analysis that takes 10 minutes.

User asks: "Analyze competitor pricing trends for Q4 2024"
Your Dify workflow uses Submit Task tool:
- Agent Name:
- Instruction:
Plugin returns taskId:
Workflow tells user: "Analysis started, taskId: abc-123-def"
User continues conversation or leaves
Later, workflow uses Get Task Status:
- Agent Name:
- Task ID:
Status shows with full analysis results
Workflow presents results to user

Tool Usage Tips

When to use List Agents:

At the start of a conversation to show available capabilities
When users ask "what can you do?"
For debugging: verify agents are configured correctly

When to use Get Agent Capabilities:

Before first interaction with a new agent
To discover agent-specific parameters
For dynamic workflows that adapt to agent capabilities

When to use Call Agent (Sync):

Simple questions with quick answers
Interactive conversations where user is waiting
Operations under 60 seconds
When you need the answer to continue

When to use Submit Task (Async):

Complex analysis (> 1 minute)
Report generation
Batch processing
When user doesn't need immediate results

When to use Get Task Status:

After submitting async tasks
In polling workflows (check every 30-60 seconds)
To retrieve final results
To handle errors/failures gracefully

🔧 A2A Protocol Compliance

This plugin implements A2A Protocol v0.3.0, which includes:

Supported Methods:

Method	Purpose	Implementation
	Synchronous request/response	✅ Call Agent tool
	Asynchronous task with SSE	✅ Submit Task tool
	Task status retrieval	✅ Get Task Status tool
	Cancel running task	⏳ Future enhancement
	Resume SSE stream	⏳ Future enhancement

Protocol Features:

✅ JSON-RPC 2.0 over HTTP/HTTPS
✅ Proper Message objects with , , ,
✅ Agent discovery via
✅ Multiple auth types (none, bearer, API key, basic)
✅ Server-Sent Events (SSE) for async streaming
✅ Error handling with standard JSON-RPC error codes

Agent Card Support:

Agents can advertise their capabilities via agent cards:

🛠️ Technical Details

Message Format

All messages follow A2A spec with proper structure:

SSE (Server-Sent Events)

Async tasks use SSE streaming for progress updates:

The Submit Task tool extracts the taskId from the first event and immediately closes the stream for true async behavior.

Error Handling

JSON-RPC error responses:

Common error codes:

- Parse error
- Invalid request
- Method not found
- Invalid params
- Internal error

🐛 Troubleshooting

"Agents Registry is not configured"

Problem: No agents are configured in the plugin settings.

Solution:

Go to plugin configuration
Fill in at least Agent 1 fields (Name, URL, Auth Type)
If using auth, provide API key

"Plugin verification has been enabled, and the plugin you want to install has a bad signature"

Problem: Signature verification is blocking unsigned plugin installation.

Solution for Community Edition:

Set environment variable:
Restart your Dify deployment:
- Docker:
- Kubernetes:
- Bare metal: Restart Dify service
Try installation again

For Cloud Edition:
This plugin cannot be installed on Dify Cloud until it's published to the Marketplace.

"Agent 'xyz' not found in registry"

Problem: The agent name doesn't match any configured agent.

Solution:

Use List Agents tool to see available names
Verify spelling matches exactly (case-sensitive)
Check agent is actually configured

"A2A Error: Missing or invalid params.id"

Problem: Task ID is malformed or missing.

Solution:

Verify you're using the exact taskId returned from Submit Task
Don't modify or truncate the taskId
Check taskId format:

"Network Error: Connection timeout"

Problem: Agent endpoint is unreachable or slow.

Solution:

Verify base URL is correct
Check agent server is running
Test connectivity:
Check firewall/network settings
For sync calls: operation may exceed 60s timeout (use async instead)

"A2A Error: Unauthorized" or "403 Forbidden"

Problem: Authentication failed.

Solution:

Verify API key is correct
Check auth type matches agent's requirements
For basic auth, ensure format is
Confirm agent endpoint expects the auth method you selected

Agent returns unexpected results

Problem: Agent response doesn't match expectations.

Solution:

Use Get Agent Capabilities to see what agent actually does
Check agent's documentation for expected input format
Verify agent implements A2A protocol v0.3.0
Review instruction clarity and specificity

💻 Development

Repository

Source code: https://github.com/flyryan/dify-a2a-plugin

Local Development

See CLAUDE.md for detailed development instructions, including:

Plugin structure and architecture
Building and testing locally
Tool implementation patterns
A2A protocol implementation details

Requirements

Python 3.12+
Dify Community Edition or Cloud
Dependencies:

Testing

Unit tests with mocked dependencies:

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👤 Contact

Author: Ryan Duff

Email: [email protected]
Website: https://github.com/flyryan
Issues: https://github.com/flyryan/dify-a2a-plugin/issues

🔒 Privacy

This plugin collects and stores agent configuration data (URLs, API keys, descriptions) to facilitate A2A protocol communication. All data is stored securely within Dify's credential management system.

For complete privacy details, see PRIVACY.md.

🚀 Marketplace Publication

We plan to submit this plugin to the Dify Marketplace. Once approved, the plugin will:

✅ Be officially signed (no needed)
✅ Work on both Community and Cloud editions
✅ Appear on marketplace.dify.ai
✅ Receive "certified" badge
✅ Enable one-click installation for all users

Marketplace submission benefits:

Wider distribution and visibility
Official Dify endorsement and security review
Automatic updates for users
No manual environment variable configuration required

Track marketplace submission progress in Issues.

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

For major changes, please open an issue first to discuss what you would like to change.

🌟 Support

If this plugin helps you build amazing agent workflows, please:

⭐ Star the repository
🐛 Report bugs via Issues
💡 Suggest features via Issues
📢 Share with the Dify community

🔗 Related Links

Built with ❤️ for the Dify and A2A communities