A2A Server Plugin

Author: nacos
Version: 0.0.4
Type: extension
Repository: https://github.com/nacos-group/nacos-dify-plugins

Expose Dify apps as A2A (Agent-to-Agent) protocol agents for external discovery and invocation.

Features

• A2A Protocol Support: Expose any Dify App (Chatbot/Agent/Chatflow/Workflow) as an A2A-compatible agent
• Agent Discovery: Support /.well-known/agent.json endpoint for agent metadata discovery
• Nacos Integration: Optional registration to Nacos Agent Registry for centralized agent management
• Multi-turn Conversation: Maintain conversation context across multiple requests using Dify Plugin Storage
• Streaming Response: Support streaming mode for Agent Chat Apps

Quick Start

Step 1: Install the Plugin

1. Download the plugin package from GitHub Releases
2. In Dify, go to Plugins → Install Plugin
3. Upload the plugin package and complete the installation

Step 2: Create an Endpoint (First Time)

1. Go to Plugins → a2a_server → Create Endpoint
2. Configure the required settings:

Parameter	Example Value	Description
Dify App	Select your app	The Dify App to expose
Agent Name	My Assistant	Display name for your agent
Agent Description	A helpful AI assistant	What your agent does
Agent Public URL	https://your-domain.com/a2a	Placeholder value (will update later)

3. Click Save to create the endpoint

Important: The endpoint ID is generated by Dify after you save. You cannot know the correct URL before creating the endpoint. Use a placeholder value first (e.g., https://your-domain.com/a2a).

Step 3: Update the Correct URL

After saving, Dify will generate an endpoint ID (e.g., abc123). Now you need to update the URL:

1. Go back to Edit Endpoint
2. Update Agent Public URL to the correct value:

   https://your-domain.com/e/abc123/a2a
   

3. Click Save again

Your final A2A URLs will be:

Agent Card:  https://your-domain.com/e/{endpoint_id}/a2a/.well-known/agent.json
JSON-RPC:    https://your-domain.com/e/{endpoint_id}/a2a

Step 4: Test the Agent

Test by fetching the Agent Card:

curl https://your-domain.com/e/{endpoint_id}/a2a/.well-known/agent.json

If successful, you'll receive a JSON response with your agent's metadata.

Note: If Nacos registration is enabled, the agent will be registered to Nacos when you call this GET endpoint for the first time. Before calling this endpoint, the agent is NOT registered to Nacos.

For sending messages via the POST endpoint, it's recommended to use an A2A SDK or A2A-compatible client.

Configuration Reference

Parameter	Required	Default	Description
Dify App	Yes	-	Select the Dify App to expose as A2A agent
Agent Name	Yes	-	Name of the A2A agent
Agent Description	Yes	-	Description of the agent's capabilities
Agent Public URL	Yes	-	Public URL where this agent can be accessed
Agent Version	No	1.0.0	Version string
Enable Nacos Registry	Yes	true	Enable/disable Nacos registration
Nacos Address	No	-	Nacos server address (e.g., 127.0.0.1:8848)
Nacos Namespace ID	No	public	Nacos namespace ID
Nacos Username	No	-	Username for Nacos authentication
Nacos Password	No	-	Password for Nacos authentication
Aliyun AccessKey	No	-	AccessKey for Aliyun MSE Nacos
Aliyun SecretKey	No	-	SecretKey for Aliyun MSE Nacos

Nacos Registration

When to Use Nacos

• You have multiple A2A agents and want centralized discovery
• You're using Nacos as your service registry
• You want agents to discover each other automatically

Registration Behavior

1. Lazy Registration: The agent is NOT registered to Nacos immediately when the plugin starts
2. First Request Trigger: Registration only occurs when the first GET request is made to /.well-known/agent.json
3. Cache-based Deduplication: After registration, the AgentCard is cached locally (15 seconds TTL) to avoid duplicate registrations
4. Change Detection: If the agent configuration changes (name, description, or URL), the agent will be re-registered to Nacos
5. Remote Sync: After successful registration, the plugin fetches the AgentCard from Nacos to ensure cache consistency

Configuration Examples

Self-hosted Nacos:

Nacos Address: 192.168.1.100:8848
Nacos Username: nacos
Nacos Password: nacos

Aliyun MSE Nacos:

Nacos Address: mse-xxx.mse.aliyuncs.com:8848
Aliyun AccessKey: LTAI5t***
Aliyun SecretKey: ***

API Reference

Endpoints

Method	Path	Description
GET	/a2a/.well-known/agent.json	Returns AgentCard metadata
POST	/a2a	JSON-RPC endpoint for A2A protocol

Supported JSON-RPC Methods

Method	Description
message/send	Send a message to the agent and receive a response

Response Format

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-id",
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "parts": [{"kind": "text", "text": "Agent response here"}]
      }
    ]
  },
  "id": "1"
}

Troubleshooting

Agent Card Not Returned

• Check that the endpoint is correctly configured
• Verify the URL path includes /a2a/.well-known/agent.json
• Check Dify logs for error messages

Nacos Registration Failed

• Verify Nacos server is accessible from Dify
• Check authentication credentials
• Ensure the namespace ID exists in Nacos

Message Send Returns Error

• Verify the Dify App is properly configured
• Check that the app supports chat/conversation mode
• Review the JSON-RPC request format

Requirements

• Dify version with plugin support
• Python 3.12+
• (Optional) Nacos server for agent registration

License

Apache License 2.0