feat(a2a_dart): Add an A2A library for Dart

[gspencergoog]

Description

This is a port of the A2A python implementation to Dart. It's a native port that supports HTTP JSON RPC and SSE transport modes.

Here's the python implementation: https://github.com/a2aproject/a2a-python

See The A2A Protocol for more information on A2A.

Summary of Changes

This pull request introduces 'a2a_dart', a new Dart library that ports the Agent2Agent (A2A) protocol from its Python implementation. This foundational framework enables Dart and Flutter applications to engage in A2A communication, offering both client and server capabilities. The library emphasizes type safety and idiomatic Dart practices, supporting HTTP JSON-RPC and Server-Sent Events (SSE) for diverse interaction patterns, and includes comprehensive documentation and initial test coverage.

Highlights

• Core A2A Protocol Implementation: A new Dart library, 'a2a_dart', has been introduced, providing a native implementation of the Agent2Agent (A2A) protocol, ported from its Python counterpart.
• Client and Server Components: The library includes both client-side APIs for interacting with A2A agents and a server framework for building A2A-compliant agents, enabling full-stack A2A communication in Dart.
• Robust Data Models: Comprehensive, type-safe, and immutable data models for the A2A specification have been implemented using the 'freezed' and 'json_serializable' packages, ensuring data integrity and ease of use.
• HTTP JSON-RPC and SSE Support: The library supports HTTP JSON-RPC for standard request-response interactions and includes initial support for Server-Sent Events (SSE) for real-time streaming communication.
• Comprehensive Documentation: Detailed design documents ('DESIGN.md'), implementation plans ('IMPLEMENTATION.md'), and usage examples ('README.md', 'GEMINI.md') are provided to guide developers.
• Initial Test Coverage: A suite of unit tests for data models, client, and server components, along with an integration test, has been added to ensure functionality and reliability.

Changelog

• packages/a2a_dart/.gitignore
  • Added standard Dart '.gitignore' file.
• packages/a2a_dart/CHANGELOG.md
  • Added initial changelog entry for version 1.0.0.
• packages/a2a_dart/DESIGN.md
  • Added a detailed design document outlining the architecture, goals, implemented features, and technical choices for the 'a2a_dart' library.
• packages/a2a_dart/GEMINI.md
  • Added a markdown file providing an overview of the A2A Dart package, covering client, server, and data models.
• packages/a2a_dart/IMPLEMENTATION.md
  • Added a phased implementation plan and journal detailing the development process, learnings, and completed tasks for the library.
• packages/a2a_dart/LICENSE
  • Added the license file for the package.
• packages/a2a_dart/README.md
  • Added a comprehensive 'README.md' file with features, installation instructions, and usage examples for both client and server components.
• packages/a2a_dart/analysis_options.yaml
  • Added Dart analysis options, including recommended lints.
• packages/a2a_dart/bin/server.dart
  • Added a simple executable server entry point for the A2A Dart server.
• packages/a2a_dart/build.yaml
  • Added 'build.yaml' configuration for 'json_serializable' to ensure 'explicit_to_json: true'.
• packages/a2a_dart/example_freezed_json.md
  • Added an example markdown file demonstrating the integration of 'json_serializable' with 'freezed'.
• packages/a2a_dart/lib/a2a_dart.dart
  • Added the main library export file, consolidating core, client, and server APIs.
• packages/a2a_dart/lib/src/client/a2a_client.dart
  • Added the 'A2AClient' class, providing a high-level API for interacting with A2A servers, including methods for 'getAgentCard', 'createTask', 'messageStream', and 'executeTask'.
• packages/a2a_dart/lib/src/client/a2a_exception.dart
  • Added 'A2AException' sealed class for client-side exceptions, including 'A2AJsonRpcException' and 'A2AParsingException'.
• packages/a2a_dart/lib/src/client/a2a_exception.freezed.dart
  • Generated Freezed code for 'A2AException'.
• packages/a2a_dart/lib/src/client/a2a_exception.g.dart
  • Generated JSON serialization code for 'A2AException'.
• packages/a2a_dart/lib/src/client/a2a_handler.dart
  • Added 'A2AHandler' abstract class and 'A2AHandlerPipeline' for request/response interception.
• packages/a2a_dart/lib/src/client/http_transport.dart
  • Added 'HttpTransport' implementation for standard HTTP request-response communication.
• packages/a2a_dart/lib/src/client/sse_parser.dart
  • Added 'SseParser' for parsing Server-Sent Events (SSE) streams, handling multi-line data, comments, and JSON-RPC errors.
• packages/a2a_dart/lib/src/client/sse_transport.dart
  • Added 'SseTransport' implementation for Server-Sent Events (SSE) streaming, extending 'HttpTransport'.
• packages/a2a_dart/lib/src/client/transport.dart
  • Added 'Transport' abstract interface for A2A communication mechanisms.
• packages/a2a_dart/lib/src/core/agent_capabilities.dart
  • Added 'AgentCapabilities' data model for defining agent features like streaming and push notifications.
• packages/a2a_dart/lib/src/core/agent_capabilities.freezed.dart
  • Generated Freezed code for 'AgentCapabilities'.
• packages/a2a_dart/lib/src/core/agent_capabilities.g.dart
  • Generated JSON serialization code for 'AgentCapabilities'.
• packages/a2a_dart/lib/src/core/agent_card.dart
  • Added 'AgentCard' data model, a self-describing manifest for an agent.
• packages/a2a_dart/lib/src/core/agent_card.freezed.dart
  • Generated Freezed code for 'AgentCard'.
• packages/a2a_dart/lib/src/core/agent_card.g.dart
  • Generated JSON serialization code for 'AgentCard'.
• packages/a2a_dart/lib/src/core/agent_extension.dart
  • Added 'AgentExtension' data model for declaring protocol extensions.
• packages/a2a_dart/lib/src/core/agent_extension.freezed.dart
  • Generated Freezed code for 'AgentExtension'.
• packages/a2a_dart/lib/src/core/agent_extension.g.dart
  • Generated JSON serialization code for 'AgentExtension'.
• packages/a2a_dart/lib/src/core/agent_interface.dart
  • Added 'AgentInterface' data model and 'TransportProtocol' enum for defining communication endpoints.
• packages/a2a_dart/lib/src/core/agent_interface.freezed.dart
  • Generated Freezed code for 'AgentInterface'.
• packages/a2a_dart/lib/src/core/agent_interface.g.dart
  • Generated JSON serialization code for 'AgentInterface'.
• packages/a2a_dart/lib/src/core/agent_provider.dart
  • Added 'AgentProvider' data model for agent service provider information.
• packages/a2a_dart/lib/src/core/agent_provider.freezed.dart
  • Generated Freezed code for 'AgentProvider'.
• packages/a2a_dart/lib/src/core/agent_provider.g.dart
  • Generated JSON serialization code for 'AgentProvider'.
• packages/a2a_dart/lib/src/core/agent_skill.dart
  • Added 'AgentSkill' data model for defining agent capabilities and functions.
• packages/a2a_dart/lib/src/core/agent_skill.freezed.dart
  • Generated Freezed code for 'AgentSkill'.
• packages/a2a_dart/lib/src/core/agent_skill.g.dart
  • Generated JSON serialization code for 'AgentSkill'.
• packages/a2a_dart/lib/src/core/events.dart
  • Added 'StreamingEvent' sealed class for task status and artifact updates during streaming.
• packages/a2a_dart/lib/src/core/events.freezed.dart
  • Generated Freezed code for 'StreamingEvent'.
• packages/a2a_dart/lib/src/core/events.g.dart
  • Generated JSON serialization code for 'StreamingEvent'.
• packages/a2a_dart/lib/src/core/message.dart
  • Added 'Message' data model and 'Role' enum for conversation messages.
• packages/a2a_dart/lib/src/core/message.freezed.dart
  • Generated Freezed code for 'Message'.
• packages/a2a_dart/lib/src/core/message.g.dart
  • Generated JSON serialization code for 'Message'.
• packages/a2a_dart/lib/src/core/part.dart
  • Added 'Part' sealed class (TextPart, FilePart, DataPart) and 'FileType' sealed class (FileWithUri, FileWithBytes) for message content.
• packages/a2a_dart/lib/src/core/part.freezed.dart
  • Generated Freezed code for 'Part' and 'FileType'.
• packages/a2a_dart/lib/src/core/part.g.dart
  • Generated JSON serialization code for 'Part' and 'FileType'.
• packages/a2a_dart/lib/src/core/security_scheme.dart
  • Added 'SecurityScheme' sealed class (APIKey, HTTP, OAuth2, OpenID Connect, Mutual TLS) and related OAuth models for authentication.
• packages/a2a_dart/lib/src/core/security_scheme.freezed.dart
  • Generated Freezed code for 'SecurityScheme', 'OAuthFlows', and 'OAuthFlow'.
• packages/a2a_dart/lib/src/core/security_scheme.g.dart
  • Generated JSON serialization code for 'SecurityScheme', 'OAuthFlows', and 'OAuthFlow'.
• packages/a2a_dart/lib/src/core/task.dart
  • Added 'Task' data model, 'TaskStatus' data model, 'TaskState' enum, and 'Artifact' data model for managing agent operations.
• packages/a2a_dart/lib/src/core/task.freezed.dart
  • Generated Freezed code for 'Task', 'TaskStatus', and 'Artifact'.
• packages/a2a_dart/lib/src/core/task.g.dart
  • Generated JSON serialization code for 'Task', 'TaskStatus', and 'Artifact'.
• packages/a2a_dart/lib/src/server/a2a_server.dart
  • Added 'A2AServer' class for handling A2A RPC calls, including request routing and error handling.
• packages/a2a_dart/lib/src/server/a2a_server_exception.dart
  • Added 'A2AServerException' class for server-side errors.
• packages/a2a_dart/lib/src/server/create_task_handler.dart
  • Added 'CreateTaskHandler' for the 'create_task' RPC method, utilizing 'TaskManager'.
• packages/a2a_dart/lib/src/server/handler_result.dart
  • Added 'HandlerResult' sealed class to represent single or streaming responses from request handlers.
• packages/a2a_dart/lib/src/server/io/a2a_server.dart
  • Added native (dart:io) implementation of 'A2AServer'.
• packages/a2a_dart/lib/src/server/request_handler.dart
  • Added 'RequestHandler' abstract interface for defining RPC method handlers.
• packages/a2a_dart/lib/src/server/task_manager.dart
  • Added 'TaskManager' class for managing the lifecycle of A2A tasks in memory.
• packages/a2a_dart/lib/src/server/web/a2a_server.dart
  • Added web stub implementation for 'A2AServer' as it's not supported in browser environments.
• packages/a2a_dart/prompt.txt
  • Added the prompt file used to generate this pull request.
• packages/a2a_dart/pubspec.yaml
  • Added 'pubspec.yaml' for the 'a2a_dart' package, including dependencies like 'freezed', 'json_serializable', 'http', 'logging', 'shelf', 'shelf_router', 'sse_channel', and 'uuid'.
• packages/a2a_dart/test/client/a2a_client_test.dart
  • Added unit tests for 'A2AClient' functionality, including 'getAgentCard', 'createTask', and 'executeTask', and specific tests for 'SseTransport' behavior.
• packages/a2a_dart/test/client/http_transport_test.dart
  • Added unit tests for 'HttpTransport' to verify send and get operations.
• packages/a2a_dart/test/client/sse_transport_test.dart
  • Added unit tests for 'SseTransport' to verify handling of multi-line data, comments, and various error scenarios.
• packages/a2a_dart/test/core/agent_card_test.dart
  • Added unit tests for 'AgentCard' serialization and deserialization.
• packages/a2a_dart/test/core/data_models_test.dart
  • Added comprehensive unit tests for all core data models ('AgentCard', 'Message', 'Task', 'Part', 'SecurityScheme') to verify serialization and deserialization.
• packages/a2a_dart/test/fakes.dart
  • Added fake implementations for 'HttpClient', 'Transport', and 'TaskManager' to facilitate testing.
• packages/a2a_dart/test/integration/client_server_test.dart
  • Added an integration test to verify client-server communication for task creation and execution, including a mock 'ExecuteTaskHandler'.
• packages/a2a_dart/test/server/a2a_server_test.dart
  • Added unit tests for 'A2AServer' functionality, covering valid requests, invalid methods, malformed JSON, error handling, and streaming requests.
• packages/a2a_dart/test/server/create_task_handler_test.dart
  • Added unit tests for 'CreateTaskHandler'.
• packages/a2a_dart/test/server/task_manager_test.dart
  • Added unit tests for 'TaskManager' functionality, including task creation, retrieval, and updates.