Merge remote-tracking branch 'origin/1.0-dev' into ishymko/845-validation

Author: ishymko

AGENTS.md

@@ -0,0 +1,3 @@
+Always check @./GEMINI.md for the full instruction list.
+
+This file exists for compatibility with tools that look for AGENTS.md.

GEMINI.md

@@ -1,20 +1,25 @@
-**A2A specification:** https://a2a-protocol.org/latest/specification/
+# Agent Command Center
 
-## Project frameworks
-- uv as package manager
+## 1. Project Overview & Purpose
+**Primary Goal**: This is the Python SDK for the Agent2Agent (A2A) Protocol. It allows developers to build and run agentic applications as A2A-compliant servers. It handles complex messaging, task management, and communication across different transports (REST, gRPC, JSON-RPC).
+**Specification**: [A2A-Protocol](https://a2a-protocol.org/latest/specification/)
 
-## Code style and mandatory checks
-1. Whenever writing python code, write types as well.
-2. After making the changes run ruff to check and fix the formatting issues
-   ```
-   uv run ruff check --fix
-   uv run ruff format
-   ```
-3. Run mypy type checkers to check for type errors
-   ```
-   uv run mypy src
-   ```
-4. Run the unit tests to make sure that none of the unit tests are broken.
-  ```
-  uv run pytest
-  ```
+## 2. Technology Stack & Architecture
+
+- **Language**: Python 3.10+
+- **Package Manager**: `uv`
+- **Lead Transports**: FastAPI (REST/JSON-RPC), gRPC
+- **Data Layer**: SQLAlchemy (SQL), Pydantic (Logic/Legacy), Protobuf (Modern Messaging)
+- **Key Directories**:
+    - `/src`: Core implementation logic.
+    - `/tests`: Comprehensive test suite.
+    - `/docs`: AI guides.
+
+## 3. Style Guidelines & Mandatory Checks
+- **Style Guidelines**: Follow the rules in @./docs/ai/coding_conventions.md for every response involving code.
+- **Mandatory Checks**: Run the commands in @./docs/ai/mandatory_checks.md after making any changes to the code and before committing.
+
+## 4. Mandatory AI Workflow for Coding Tasks
+1. **Required Reading**: You MUST read the contents of @./docs/ai/coding_conventions.md and @./docs/ai/mandatory_checks.md at the very beginning of EVERY coding task.
+2. **Initial Checklist**: Every `task.md` you create MUST include a section for **Mandatory Checks** from @./docs/ai/mandatory_checks.md.
+3. **Verification Requirement**: You MUST run all mandatory checks before declaring any task finished.

README.md

@@ -36,7 +36,10 @@
 
 ## 🧩 Compatibility
 
-This SDK implements the A2A Protocol Specification [`v0.3.0`](https://a2a-protocol.org/v0.3.0/specification).
+This SDK implements the A2A Protocol Specification [`0.3`](https://a2a-protocol.org/v0.3.0/specification).
+
+> [!IMPORTANT]
+> There is an [**alpha version**](https://github.com/a2aproject/a2a-python/releases?q=%22v1.0.0-alpha%22&expanded=true) available with support for both [`1.0`](https://a2a-protocol.org/v1.0.0/specification/) and [`0.3`](https://a2a-protocol.org/v0.3.0/specification) versions. Development for this version is taking place in the [`1.0-dev`](https://github.com/a2aproject/a2a-python/tree/1.0-dev) branch, tracked in [#701](https://github.com/a2aproject/a2a-python/issues/701).
 
 | Transport | Client | Server |
 | :--- | :---: | :---: |
@@ -65,6 +68,7 @@ Install the core SDK and any desired extras using your preferred package manager
 | **gRPC Support**         | `uv add "a2a-sdk[grpc]"`                   | `pip install "a2a-sdk[grpc]"`                |
 | **OpenTelemetry Tracing**| `uv add "a2a-sdk[telemetry]"`              | `pip install "a2a-sdk[telemetry]"`           |
 | **Encryption**           | `uv add "a2a-sdk[encryption]"`             | `pip install "a2a-sdk[encryption]"`          |
+| **Vertex AI Task Store** | `uv add "a2a-sdk[vertex]"`                 | `pip install "a2a-sdk[vertex]"`              |
 |                          |                                            |                                              |
 | **Database Drivers**     |                                            |                                              |
 | **PostgreSQL**           | `uv add "a2a-sdk[postgresql]"`             | `pip install "a2a-sdk[postgresql]"`          |

docs/ai/coding_conventions.md

@@ -0,0 +1,21 @@
+### Coding Conventions & Style Guide
+
+Non-negotiable rules for code quality and style.
+
+1. **Python Types**: All Python code MUST include type hints. All function definitions MUST include return types.
+2. **Type Safety**: All code MUST pass `mypy` and `pyright` checks.
+3. **Formatting & Linting**: All code MUST be formatted with `ruff`.
+
+#### Examples:
+
+**Correct Typing:**
+```python
+async def get_task_status(task: Task) -> TaskStatus:
+    return task.status
+```
+
+**Incorrect (Do NOT do this):**
+```python
+async def get_task_status(task): # Missing type hints for argument and return value
+    return task.status
+```

docs/ai/mandatory_checks.md

@@ -0,0 +1,26 @@
+### Test and Fix Commands
+
+Exact shell commands required to test the project and fix formatting issues.
+
+1. **Formatting & Linting**:
+   ```bash
+   uv run ruff check --fix
+   uv run ruff format
+   ```
+
+2. **Type Checking**:
+   ```bash
+   uv run mypy src
+   uv run pyright src
+   ```
+
+3. **Testing**:
+   ```bash
+   uv run pytest
+   ```
+
+4. **Coverage**:
+Only run this command after adding new source code and before committing.
+   ```bash
+   uv run pytest --cov=src --cov-report=term-missing
+   ```

samples/hello_world_agent.py

@@ -11,12 +11,13 @@
 from a2a.compat.v0_3.grpc_handler import CompatGrpcHandler
 from a2a.server.agent_execution.agent_executor import AgentExecutor
 from a2a.server.agent_execution.context import RequestContext
-from a2a.server.apps import A2AFastAPIApplication, A2ARESTFastAPIApplication
+from a2a.server.apps import A2ARESTFastAPIApplication
 from a2a.server.events.event_queue import EventQueue
 from a2a.server.request_handlers import GrpcHandler
 from a2a.server.request_handlers.default_request_handler import (
     DefaultRequestHandler,
 )
+from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
 from a2a.server.tasks.inmemory_task_store import InMemoryTaskStore
 from a2a.server.tasks.task_updater import TaskUpdater
 from a2a.types import (
@@ -197,14 +198,17 @@ async def serve(
     )
     rest_app = rest_app_builder.build()
 
-    jsonrpc_app_builder = A2AFastAPIApplication(
+    jsonrpc_routes = create_jsonrpc_routes(
+        agent_card=agent_card,
+        request_handler=request_handler,
+        rpc_url='/a2a/jsonrpc/',
+    )
+    agent_card_routes = create_agent_card_routes(
         agent_card=agent_card,
-        http_handler=request_handler,
-        enable_v0_3_compat=True,
     )
-
     app = FastAPI()
-    jsonrpc_app_builder.add_routes_to_app(app, rpc_url='/a2a/jsonrpc/')
+    app.routes.extend(jsonrpc_routes)
+    app.routes.extend(agent_card_routes)
     app.mount('/a2a/rest', rest_app)
 
     grpc_server = grpc.aio.server()

src/a2a/compat/v0_3/jsonrpc_adapter.py

@@ -10,8 +10,8 @@
 if TYPE_CHECKING:
     from starlette.requests import Request
 
-    from a2a.server.apps.jsonrpc.jsonrpc_app import CallContextBuilder
     from a2a.server.request_handlers.request_handler import RequestHandler
+    from a2a.server.routes import CallContextBuilder
     from a2a.types.a2a_pb2 import AgentCard
 
     _package_starlette_installed = True

src/a2a/compat/v0_3/rest_adapter.py

@@ -33,12 +33,9 @@
 
 from a2a.compat.v0_3 import conversions
 from a2a.compat.v0_3.rest_handler import REST03Handler
-from a2a.server.apps.jsonrpc.jsonrpc_app import (
-    CallContextBuilder,
-    DefaultCallContextBuilder,
-)
 from a2a.server.apps.rest.rest_adapter import RESTAdapterInterface
 from a2a.server.context import ServerCallContext
+from a2a.server.routes import CallContextBuilder, DefaultCallContextBuilder
 from a2a.utils.error_handlers import (
     rest_error_handler,
     rest_stream_error_handler,

src/a2a/contrib/tasks/vertex_task_converter.py

@@ -1,4 +1,5 @@
 try:
+    from google.genai import types as genai_types
     from vertexai import types as vertexai_types
 except ImportError as e:
     raise ImportError(
@@ -25,70 +26,70 @@
 
 
 _TO_SDK_TASK_STATE = {
-    vertexai_types.State.STATE_UNSPECIFIED: TaskState.unknown,
-    vertexai_types.State.SUBMITTED: TaskState.submitted,
-    vertexai_types.State.WORKING: TaskState.working,
-    vertexai_types.State.COMPLETED: TaskState.completed,
-    vertexai_types.State.CANCELLED: TaskState.canceled,
-    vertexai_types.State.FAILED: TaskState.failed,
-    vertexai_types.State.REJECTED: TaskState.rejected,
-    vertexai_types.State.INPUT_REQUIRED: TaskState.input_required,
-    vertexai_types.State.AUTH_REQUIRED: TaskState.auth_required,
+    vertexai_types.A2aTaskState.STATE_UNSPECIFIED: TaskState.unknown,
+    vertexai_types.A2aTaskState.SUBMITTED: TaskState.submitted,
+    vertexai_types.A2aTaskState.WORKING: TaskState.working,
+    vertexai_types.A2aTaskState.COMPLETED: TaskState.completed,
+    vertexai_types.A2aTaskState.CANCELLED: TaskState.canceled,
+    vertexai_types.A2aTaskState.FAILED: TaskState.failed,
+    vertexai_types.A2aTaskState.REJECTED: TaskState.rejected,
+    vertexai_types.A2aTaskState.INPUT_REQUIRED: TaskState.input_required,
+    vertexai_types.A2aTaskState.AUTH_REQUIRED: TaskState.auth_required,
 }
 
 _SDK_TO_STORED_TASK_STATE = {v: k for k, v in _TO_SDK_TASK_STATE.items()}
 
 
-def to_sdk_task_state(stored_state: vertexai_types.State) -> TaskState:
+def to_sdk_task_state(stored_state: vertexai_types.A2aTaskState) -> TaskState:
     """Converts a proto A2aTask.State to a TaskState enum."""
     return _TO_SDK_TASK_STATE.get(stored_state, TaskState.unknown)
 
 
-def to_stored_task_state(task_state: TaskState) -> vertexai_types.State:
+def to_stored_task_state(task_state: TaskState) -> vertexai_types.A2aTaskState:
     """Converts a TaskState enum to a proto A2aTask.State enum value."""
     return _SDK_TO_STORED_TASK_STATE.get(
-        task_state, vertexai_types.State.STATE_UNSPECIFIED
+        task_state, vertexai_types.A2aTaskState.STATE_UNSPECIFIED
     )
 
 
-def to_stored_part(part: Part) -> vertexai_types.Part:
+def to_stored_part(part: Part) -> genai_types.Part:
     """Converts a SDK Part to a proto Part."""
     if isinstance(part.root, TextPart):
-        return vertexai_types.Part(text=part.root.text)
+        return genai_types.Part(text=part.root.text)
     if isinstance(part.root, DataPart):
         data_bytes = json.dumps(part.root.data).encode('utf-8')
-        return vertexai_types.Part(
-            inline_data=vertexai_types.Blob(
+        return genai_types.Part(
+            inline_data=genai_types.Blob(
                 mime_type='application/json', data=data_bytes
             )
         )
     if isinstance(part.root, FilePart):
         file_content = part.root.file
         if isinstance(file_content, FileWithBytes):
             decoded_bytes = base64.b64decode(file_content.bytes)
-            return vertexai_types.Part(
-                inline_data=vertexai_types.Blob(
+            return genai_types.Part(
+                inline_data=genai_types.Blob(
                     mime_type=file_content.mime_type or '', data=decoded_bytes
                 )
             )
         if isinstance(file_content, FileWithUri):
-            return vertexai_types.Part(
-                file_data=vertexai_types.FileData(
+            return genai_types.Part(
+                file_data=genai_types.FileData(
                     mime_type=file_content.mime_type or '',
                     file_uri=file_content.uri,
                 )
             )
     raise ValueError(f'Unsupported part type: {type(part.root)}')
 
 
-def to_sdk_part(stored_part: vertexai_types.Part) -> Part:
+def to_sdk_part(stored_part: genai_types.Part) -> Part:
     """Converts a proto Part to a SDK Part."""
     if stored_part.text:
         return Part(root=TextPart(text=stored_part.text))
     if stored_part.inline_data:
-        encoded_bytes = base64.b64encode(stored_part.inline_data.data).decode(
-            'utf-8'
-        )
+        encoded_bytes = base64.b64encode(
+            stored_part.inline_data.data or b''
+        ).decode('utf-8')
         return Part(
             root=FilePart(
                 file=FileWithBytes(
@@ -97,7 +98,7 @@ def to_sdk_part(stored_part: vertexai_types.Part) -> Part:
                 )
             )
         )
-    if stored_part.file_data:
+    if stored_part.file_data and stored_part.file_data.file_uri:
         return Part(
             root=FilePart(
                 file=FileWithUri(

src/a2a/server/apps/__init__.py

@@ -1,18 +1,8 @@
 """HTTP application components for the A2A server."""
 
-from a2a.server.apps.jsonrpc import (
-    A2AFastAPIApplication,
-    A2AStarletteApplication,
-    CallContextBuilder,
-    JSONRPCApplication,
-)
 from a2a.server.apps.rest import A2ARESTFastAPIApplication
 
 
 __all__ = [
-    'A2AFastAPIApplication',
     'A2ARESTFastAPIApplication',
-    'A2AStarletteApplication',
-    'CallContextBuilder',
-    'JSONRPCApplication',
 ]