example(a2a,nacos): For #293, Add example for a2a and nacos a2a registry. (#458)

## AgentScope-Java Version

1.0.7

## Description

For #293 .

- example(a2a): add A2A protocol example with tools and Spring Boot app.
- chore(deps): Add Nacos extensions dependency into all-in-one and
update documents.
- example(a2a,nacos): Add Nacos A2A registry and discovery example in
a2a example module.

## Checklist

Please check the following items before code is ready to be reviewed.

- [x]  Code has been formatted with `mvn spotless:apply`
- [x]  All tests are passing (`mvn test`)
- [x]  Javadoc comments are complete and follow project conventions
- [x] Related documentation has been updated (e.g. links, examples,
etc.)
- [x]  Code is ready for review

Author: KomachiSion

agentscope-distribution/agentscope-all/pom.xml

@@ -52,6 +52,13 @@
             <scope>compile</scope>
             <optional>true</optional>
         </dependency>
+        
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-extensions-a2a-server</artifactId>
+            <scope>compile</scope>
+            <optional>true</optional>
+        </dependency>
 
         <dependency>
             <groupId>io.agentscope</groupId>
@@ -157,6 +164,13 @@
             <scope>compile</scope>
             <optional>true</optional>
         </dependency>
+        
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-extensions-nacos-a2a</artifactId>
+            <scope>compile</scope>
+            <optional>true</optional>
+        </dependency>
 
         <!-- Model Context Protocol (MCP) SDK -->
         <dependency>

agentscope-examples/a2a/pom.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2024-2026 the original author or authors.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.agentscope</groupId>
+        <artifactId>agentscope-examples</artifactId>
+        <version>${revision}</version>
+    </parent>
+    
+    <groupId>io.agentscope.examples</groupId>
+    <artifactId>a2a</artifactId>
+    <packaging>jar</packaging>
+    
+    <name>AgentScope Examples - A2A</name>
+    <description>A2A(Agent2Agent) Protocol example for AgentScope Java SDK</description>
+    
+    <dependencyManagement>
+        <dependencies>
+            <!-- Spring Boot BOM -->
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-dependencies</artifactId>
+                <version>${spring.boot.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+    
+    <dependencies>
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-a2a-spring-boot-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.agentscope</groupId>
+            <artifactId>agentscope-nacos-spring-boot-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>

agentscope-examples/a2a/src/main/java/io/agentscope/examples/a2a/A2aAgentExampleRunner.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2024-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.agentscope.examples.a2a;
+
+import io.agentscope.core.a2a.agent.A2aAgent;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.message.MsgRole;
+import io.agentscope.core.message.TextBlock;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import reactor.core.publisher.Flux;
+
+/**
+ * Example runner for A2aAgent usage.
+ *
+ * <p>This example demonstrates how to request remote agent via the A2A protocol
+ * using AgentScope A2aAgent.
+ */
+public class A2aAgentExampleRunner {
+
+    private static final String USER_INPUT_PREFIX = "\u001B[34mYou>\u001B[0m ";
+
+    private static final String AGENT_RESPONSE_PREFIX = "\u001B[32mAgent>\u001B[0m ";
+
+    private final A2aAgent agent;
+
+    public A2aAgentExampleRunner(A2aAgent agent) {
+        this.agent = agent;
+    }
+
+    /**
+     * Start to run the example for A2aAgent.
+     */
+    public void startExample() {
+        try (BufferedReader reader = new BufferedReader(new InputStreamReader(System.in))) {
+            while (true) {
+                // User Input Hint.
+                System.out.print(USER_INPUT_PREFIX);
+                String input = reader.readLine();
+
+                // Exit example.
+                if (input == null
+                        || input.trim().equalsIgnoreCase("exit")
+                        || input.trim().equalsIgnoreCase("quit")) {
+                    System.out.println(AGENT_RESPONSE_PREFIX + "Bye!");
+                    break;
+                }
+
+                System.out.println(
+                        AGENT_RESPONSE_PREFIX + "I have received your question: " + input);
+                System.out.print(AGENT_RESPONSE_PREFIX);
+
+                // Handle user input and get response.
+                processInput(agent, input).doOnNext(System.out::print).then().block();
+
+                System.out.println();
+            }
+        } catch (IOException e) {
+            System.err.println("input error: " + e.getMessage());
+        }
+    }
+
+    private Flux<String> processInput(A2aAgent agent, String input) {
+        Msg msg =
+                Msg.builder()
+                        .role(MsgRole.USER)
+                        .content(TextBlock.builder().text(input).build())
+                        .build();
+        return agent.stream(msg)
+                .map(
+                        event -> {
+                            if (event.isLast()) {
+                                // The last message is whole artifact message result, which has been
+                                // processed and printed in the previous event handling.
+                                return "";
+                            }
+                            Msg message = event.getMessage();
+                            StringBuilder partText = new StringBuilder();
+                            message.getContent().stream()
+                                    .filter(block -> block instanceof TextBlock)
+                                    .map(block -> (TextBlock) block)
+                                    .forEach(block -> partText.append(block.getText()));
+                            return partText.toString();
+                        });
+    }
+}

agentscope-examples/a2a/src/main/java/io/agentscope/examples/a2a/A2aExampleApplication.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2024-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.agentscope.examples.a2a;
+
+import io.agentscope.core.tool.Toolkit;
+import io.agentscope.examples.a2a.tools.ExampleTools;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * A2A(Agent2Agent) Protocol Example Application.
+ *
+ * <p>This application demonstrates how to expose AgentScope agents via the A2A protocol
+ * using Spring Web.
+ *
+ * <p><b>Usage:</b>
+ * <ol>
+ *   <li>Set the DASHSCOPE_API_KEY environment variable</li>
+ *   <li>Run this application</li>
+ *   <li>Use curl: {@code curl -X GET http://localhost:8888/.well-known/agent-card.json} to get AgentCard.</li>
+ *   <li>Use curl: {@code curl --location --request POST 'http://localhost:8888' \
+ *   --header 'Content-Type: application/json' \
+ *   --data-raw '{
+ *     "method": "message/stream",
+ *     "id": "2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc",
+ *     "jsonrpc": "2.0",
+ *     "params": {
+ *       "message": {
+ *         "role": "user",
+ *         "kind": "message",
+ *         "contextId": "aa9c67d2-c6fc-42d4-9c9e-b67d69f77cfa",
+ *         "metadata": {
+ *           "userId": "me",
+ *           "sessionId": "test12"
+ *         },
+ *         "parts": [
+ *           {
+ *             "kind": "text",
+ *             "text": "Hello, please calculate the 346 * 47"
+ *           }
+ *         ],
+ *         "messageId": "c4911b64c8404b7a8bf7200dd225b152"
+ *       }
+ *     }
+ *   }'}</li>
+ *   <li>Or run {@link SimpleA2aAgentExample#main(String[])} and input question like: {@code Hello, please calculate the 346 * 47}</li>
+ * </ol>
+ *
+ * <p>This example application also demonstrates how to register agents to Nacos A2A registry.
+ *
+ * <p><b>Usage: </b>
+ * <ol>
+ *     <li>Set the DASHSCOPE_API_KEY environment variable.</li>
+ *     <li>Enabled Nacos Registry by set Nacos environment variable: {@code NACOS_ENABLED=true}.</li>
+ *     <li>Start Nacos Server according to <a href="https://nacos.io/en/docs/latest/quickstart/quick-start-docker">documents</a>.</li>
+ *     <li>Set more Nacos environment variables: NACOS_SERVER_ADDR, NACOS_USERNAME and NACOS_PASSWORD if Nacos Server is not in local and enabled authentication.</li>
+ *     <li>Run this application</li>
+ *     <li>Run Example {@link NacosA2aAgentExample#main(String[])} and input question like: {@code Hello, please calculate the 346 * 47}</li>
+ * </ol>
+ */
+@SpringBootApplication
+public class A2aExampleApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(A2aExampleApplication.class, args);
+    }
+
+    /**
+     * Optional, if you want to register tools for the agent.
+     */
+    @Bean
+    public Toolkit toolkit() {
+        Toolkit toolkit = new Toolkit();
+        toolkit.registerTool(new ExampleTools());
+        return toolkit;
+    }
+}

agentscope-examples/a2a/src/main/java/io/agentscope/examples/a2a/NacosA2aAgentExample.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2024-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.agentscope.examples.a2a;
+
+import com.alibaba.nacos.api.PropertyKeyConst;
+import com.alibaba.nacos.api.ai.AiFactory;
+import com.alibaba.nacos.api.ai.AiService;
+import com.alibaba.nacos.api.exception.NacosException;
+import io.agentscope.core.a2a.agent.A2aAgent;
+import io.agentscope.core.a2a.agent.card.AgentCardResolver;
+import io.agentscope.core.nacos.a2a.discovery.NacosAgentCardResolver;
+import java.util.Properties;
+
+/**
+ * Example for A2aAgent with Nacos Registry.
+ *
+ * <p>This example demonstrates how to request remote agent via the A2A protocol
+ * using AgentScope A2aAgent which discovers AgentCard by Nacos Registry.
+ *
+ * <p>If your Nacos Server is not deployed locally, you should set environment variable NACOS_SERVER_ADDR.
+ *
+ * <p>If your Nacos Server has authentication enabled, you should set environment variable NACOS_USERNAME and NACOS_PASSWORD.
+ */
+public class NacosA2aAgentExample {
+
+    public static void main(String[] args) throws NacosException {
+        // Create agent card resolver by Nacos.
+        AgentCardResolver agentCardResolver = new NacosAgentCardResolver(buildNacosClient());
+        // Create A2aAgent
+        A2aAgent agent =
+                A2aAgent.builder()
+                        .name("agentscope-a2a-example-agent")
+                        .agentCardResolver(agentCardResolver)
+                        .build();
+        A2aAgentExampleRunner exampleRunner = new A2aAgentExampleRunner(agent);
+        exampleRunner.startExample();
+    }
+
+    private static AiService buildNacosClient() throws NacosException {
+        String nacosServerAddr = System.getenv("NACOS_SERVER_ADDR");
+        if (nacosServerAddr == null) {
+            nacosServerAddr = "localhost:8848";
+        }
+        String nacosUsername = System.getenv("NACOS_USERNAME");
+        String nacosPassword = System.getenv("NACOS_PASSWORD");
+        Properties properties = new Properties();
+        properties.put(PropertyKeyConst.SERVER_ADDR, nacosServerAddr);
+        if (nacosUsername != null && nacosPassword != null) {
+            properties.put(PropertyKeyConst.USERNAME, nacosUsername);
+            properties.put(PropertyKeyConst.PASSWORD, nacosPassword);
+        }
+        return AiFactory.createAiService(properties);
+    }
+}