Merge pull request #1114 from emmanuelallen/feat-a2a-task

Add new `a2a` call task to the specification and schema

Author: cdavernas

dsl-reference.md

@@ -14,6 +14,7 @@
         + [gRPC](#grpc-call)
         + [HTTP](#http-call)
         + [OpenAPI](#openapi-call)
+        + [A2A](#a2a-call)
     - [Do](#do)
     - [Emit](#emit)
     - [For](#for)
@@ -320,6 +321,7 @@ Serverless Workflow defines several default functions that **MUST** be supported
 - [gRPC](#grpc-call)
 - [HTTP](#http-call)
 - [OpenAPI](#openapi-call)
+- [A2A](#a2a-call)
 
 ##### AsyncAPI Call
 
@@ -483,6 +485,48 @@ do:
           status: available
 ```
 
+##### A2A Call
+
+The [A2A Call](#a2a-call) enables workflows to interact with AI agents described by [A2A](https://a2a-protocol.org/).
+
+###### Properties
+
+| Name | Type | Required | Description|
+|:--|:---:|:---:|:---|
+| method | `string` | `yes` | The A2A JSON-RPC method to send.<br>*Supported values are:  `message/send`, `message/stream`, `tasks/get`, `tasks/list`, `tasks/cancel`, `tasks/resubscribe`, `tasks/pushNotificationConfig/set`, `tasks/pushNotificationConfig/get`, `tasks/pushNotificationConfig/list`, `tasks/pushNotificationConfig/delete`, and `agent/getAuthenticatedExtendedCard`* |
+| agentCard | [`externalResource`](#external-resource) | `no` | The AgentCard resource that describes the agent to call.<br>*Required if `server` has not been set.* |
+| server | `string`\|[`endpoint`](#endpoint) | `no` | An URI or an object that describes the A2A server to call.<br>*Required if `agentCard` has not been set, otherwise ignored* |
+| parameters | `map` <br> `string` | `no` | The parameters for the A2A RPC method. For the `message/send` and `message/stream` methods, runtimes must default `message.messageId` to a uuid and `message.role` to `user`.<br>*Can be an object or a direct runtime expression.* |
+
+> [!NOTE]
+> The `security` and `securitySchemes` fields of the AgentCard contain authentication requirements and schemes for when communicating with the agent.
+>
+> On success the output is the JSON-RPC result. On failure runtimes must raise an error with type [https://serverlessworkflow.io/spec/1.0.0/errors/runtime](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#standard-error-types).
+>
+> For `message/stream` and `tasks/resubscribe` methods the output is a sequentially ordered array of all the result objects.
+
+###### Examples
+
+```yaml
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: a2a-example
+  version: '0.1.0'
+do:
+  - GenerateReport:
+      call: a2a
+      with:
+        method: message/send
+        agentCard:
+          endpoint: https://example.com/.well-known/agent-card.json
+        parameters:
+          message:
+            parts:
+              - kind: text
+                text: Generate the Q1 sales report.
+```
+
 #### Do
 
 Serves as a fundamental building block within workflows, enabling the sequential execution of multiple subtasks. By defining a series of subtasks to perform in sequence, the Do task facilitates the efficient execution of complex operations, ensuring that each subtask is completed before the next one begins.

dsl.md

@@ -596,6 +596,7 @@ Serverless Workflow DSL is designed to seamlessly interact with a variety of ser
 - [**gRPC**](dsl-reference.md#grpc-call): Supports Remote Procedure Call (RPC) using gRPC, a high-performance, open-source universal RPC framework. This is suitable for connecting to services that require low-latency and high-throughput communication.
 - [**AsyncAPI**](dsl-reference.md#asyncapi-call): Facilitates interaction with asynchronous messaging protocols. AsyncAPI is designed for event-driven architectures, allowing workflows to publish and subscribe to events.
 - [**OpenAPI**](dsl-reference.md#openapi-call): Enables communication with services that provide OpenAPI specifications, which is useful for defining and consuming RESTful APIs.
+- [**A2A**](dsl-reference.md#a2a-call): Enables interaction with A2A servers (agents described by A2A).
 
 Runtimes **must** raise an error with type `https://serverlessworkflow.io/spec/1.0.0/errors/communication` if and when a problem occurs during a call.
 

schema/workflow.yaml

@@ -430,6 +430,44 @@ $defs:
                 description: Specifies whether redirection status codes (`300–399`) should be treated as errors.
             required: [ document, operationId ]
             unevaluatedProperties: false
+      - title: CallA2A
+        description: Defines the A2A call to perform.
+        $ref: '#/$defs/taskBase'
+        type: object
+        unevaluatedProperties: false
+        required: [ call, with ]
+        properties:
+          call:
+            type: string
+            const: a2a
+          with:
+            type: object
+            title: A2AArguments
+            description: The A2A call arguments.
+            properties:
+              agentCard:
+                $ref: '#/$defs/externalResource'
+                title: WithA2AAgentCard
+                description: The Agent Card that defines the agent to call.
+              server:
+                title: A2AServer
+                description: The server endpoint to send the request to.
+                $ref: '#/$defs/endpoint'
+              method:
+                type: string
+                title: WithA2AMethod
+                description: The A2A method to send.
+                enum: [ 'message/send', 'message/stream', 'tasks/get', 'tasks/list', 'tasks/cancel', 'tasks/resubscribe', 'tasks/pushNotificationConfig/set', 'tasks/pushNotificationConfig/get', 'tasks/pushNotificationConfig/list', 'tasks/pushNotificationConfig/delete', 'agent/getAuthenticatedExtendedCard' ]
+              parameters:
+                oneOf:
+                  - type: object
+                    minProperties: 1
+                    additionalProperties: true
+                  - type: string
+                title: WithA2AParameters
+                description: The parameters object to send with the A2A method.
+            required: [ method ]
+            unevaluatedProperties: false
       - title: CallFunction
         description: Defines the function call to perform.
         $ref: '#/$defs/taskBase'
@@ -440,7 +478,7 @@ $defs:
           call:
             type: string
             not:
-              enum: ["asyncapi", "grpc", "http", "openapi"]
+              enum: ["asyncapi", "grpc", "http", "openapi", "a2a"]
             description: The name of the function to call.
           with:
             type: object