Merge branch '1.0-dev' of https://github.com/a2aproject/a2a-python into reduce-boilerplate

Author: sokoliva

.gitignore

@@ -12,6 +12,7 @@ coverage.xml
 spec.json
 docker-compose.yaml
 .geminiignore
+docs/ai/ai_learnings.md
 
 # ITK Integration Test Artifacts
 itk/a2a-samples/

GEMINI.md

@@ -23,3 +23,20 @@
 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.
+
+## 5. Mistake Reflection Protocol
+
+When you realise you have made a mistake — whether caught by the user,
+by a tool, or by your own reasoning — you MUST:
+
+1. **Acknowledge the mistake explicitly** and explain what went wrong.
+2. **Reflect on the root cause**: was it a missing check, a false
+   assumption, skipped verification, or a gap in the workflow?
+3. **Immediately append a new entry to @./docs/ai/ai_learnings.md**
+   following the format defined in that file. This is not optional and
+   does not require user confirmation. Do it before continuing. Update user
+   about the changes to the workflow in the current chat.
+
+The goal is to treat every mistake as a signal that the workflow is
+incomplete, and to improve it in place so the same mistake cannot
+happen again.

docs/ai/ai_learnings.md

@@ -0,0 +1,19 @@
+> [!NOTE] for Users:
+> This document is meant to be read by an AI assistant (Gemini) in order to 
+> learn from its mistakes and improve its behavior on this project. Use
+> its findings to improve GEMINI.md setup.
+
+# AI Learnings
+
+A living record of mistakes made during this project and the rules
+derived from them. Every entry must follow the format below. 
+
+---
+
+## Entry format
+
+**Mistake**: What went wrong.
+**Root cause**: Why it happened.
+**Rule**: The concrete rule added to prevent recurrence.
+
+---

samples/cli.py

@@ -11,41 +11,52 @@
 
 from a2a.client import A2ACardResolver, ClientConfig, create_client
 from a2a.types import Message, Part, Role, SendMessageRequest, TaskState
-from a2a.utils.message import get_message_text
+from a2a.utils import get_artifact_text, get_message_text
+from a2a.utils.agent_card import display_agent_card
 
 
 async def _handle_stream(
     stream: Any, current_task_id: str | None
 ) -> str | None:
     async for event in stream:
+        if event.HasField('message'):
+            print('Message:', get_message_text(event.message, delimiter=' '))
+            return None
+
         if not current_task_id:
-            current_task_id = event.task.id
-        if event:
-            if event.HasField('status_update'):
-                state_name = TaskState.Name(event.status_update.status.state)
-                print(f'TaskStatusUpdate [state={state_name}]:', end=' ')
-                if event.status_update.status.HasField('message'):
-                    message = event.status_update.status.message
-                    print(get_message_text(message, delimiter=' '))
-                print()
-
-                if (
-                    event.status_update.status.state
-                    == TaskState.TASK_STATE_COMPLETED
-                ):
-                    current_task_id = None
-                    print('--- Task Completed ---')
-
-            elif event.HasField('artifact_update'):
-                print(
-                    f'TaskArtifactUpdate [name={event.artifact_update.artifact.name}]:',
-                    end=' ',
+            if event.HasField('task'):
+                current_task_id = event.task.id
+                print('--- Task Started ---')
+                print(f'Task [state={TaskState.Name(event.task.status.state)}]')
+            else:
+                raise ValueError(f'Unexpected first event: {event}')
+
+        if event.HasField('status_update'):
+            state_name = TaskState.Name(event.status_update.status.state)
+            message_text = (
+                ': '
+                + get_message_text(
+                    event.status_update.status.message, delimiter=' '
                 )
-                for part in event.artifact_update.artifact.parts:
-                    if part.text:
-                        print(part.text, end=' ')
-                print()
-
+                if event.status_update.status.HasField('message')
+                else ''
+            )
+            print(f'TaskStatusUpdate [state={state_name}]{message_text}')
+            if state_name in (
+                'TASK_STATE_COMPLETED',
+                'TASK_STATE_FAILED',
+                'TASK_STATE_CANCELED',
+                'TASK_STATE_REJECTED',
+            ):
+                current_task_id = None
+                print('--- Task Finished ---')
+        elif event.HasField('artifact_update'):
+            print(
+                f'TaskArtifactUpdate [name={event.artifact_update.artifact.name}]:',
+                get_artifact_text(
+                    event.artifact_update.artifact, delimiter=' '
+                ),
+            )
     return current_task_id
 
 
@@ -76,7 +87,7 @@ async def main() -> None:
         resolver = A2ACardResolver(httpx_client, args.url)
         card = await resolver.get_agent_card()
         print('\n✓ Agent Card Found:')
-        print(f'  Name: {card.name}')
+        display_agent_card(card)
 
     client = await create_client(card, client_config=config)
 

samples/hello_world_agent.py

@@ -27,6 +27,9 @@
     AgentProvider,
     AgentSkill,
     Part,
+    Task,
+    TaskState,
+    TaskStatus,
     a2a_pb2_grpc,
 )
 
@@ -75,6 +78,15 @@ async def execute(
             context_id,
         )
 
+        await event_queue.enqueue_event(
+            Task(
+                id=task_id,
+                context_id=context_id,
+                status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED),
+                history=[user_message],
+            )
+        )
+
         updater = TaskUpdater(
             event_queue=event_queue,
             task_id=task_id,

src/a2a/utils/__init__.py

@@ -1,6 +1,7 @@
 """Utility functions for the A2A Python SDK."""
 
 from a2a.utils import proto_utils
+from a2a.utils.agent_card import display_agent_card
 from a2a.utils.artifact import (
     get_artifact_text,
     new_artifact,
@@ -44,6 +45,7 @@
     'build_text_artifact',
     'completed_task',
     'create_task_obj',
+    'display_agent_card',
     'get_artifact_text',
     'get_data_parts',
     'get_file_parts',

src/a2a/utils/agent_card.py

@@ -0,0 +1,76 @@
+"""Utility functions for inspecting AgentCard instances."""
+
+from a2a.types.a2a_pb2 import AgentCard
+
+
+def display_agent_card(card: AgentCard) -> None:
+    """Print a human-readable summary of an AgentCard to stdout.
+
+    Args:
+        card: The AgentCard proto message to display.
+    """
+    width = 52
+    sep = '=' * width
+    thin = '-' * width
+
+    lines: list[str] = [sep, 'AgentCard'.center(width), sep]
+
+    lines += [
+        '--- General ---',
+        f'Name        : {card.name}',
+        f'Description : {card.description}',
+        f'Version     : {card.version}',
+    ]
+    if card.documentation_url:
+        lines.append(f'Docs URL    : {card.documentation_url}')
+    if card.icon_url:
+        lines.append(f'Icon URL    : {card.icon_url}')
+    if card.HasField('provider'):
+        url_suffix = f' ({card.provider.url})' if card.provider.url else ''
+        lines.append(f'Provider    : {card.provider.organization}{url_suffix}')
+
+    lines += ['', '--- Interfaces ---']
+    for i, iface in enumerate(card.supported_interfaces):
+        binding = f'{iface.protocol_binding} {iface.protocol_version}'.strip()
+        parts = [
+            p
+            for p in [binding, f'tenant={iface.tenant}' if iface.tenant else '']
+            if p
+        ]
+        suffix = f'  ({", ".join(parts)})' if parts else ''
+        line = f'  [{i}] {iface.url}{suffix}'
+        lines.append(line)
+
+    lines += [
+        '',
+        '--- Capabilities ---',
+        f'Streaming           : {card.capabilities.streaming}',
+        f'Push notifications  : {card.capabilities.push_notifications}',
+        f'Extended agent card : {card.capabilities.extended_agent_card}',
+    ]
+
+    lines += [
+        '',
+        '--- I/O Modes ---',
+        f'Input  : {", ".join(card.default_input_modes) or "(none)"}',
+        f'Output : {", ".join(card.default_output_modes) or "(none)"}',
+    ]
+
+    lines += ['', '--- Skills ---']
+    if card.skills:
+        for skill in card.skills:
+            lines += [
+                thin,
+                f'  ID          : {skill.id}',
+                f'  Name        : {skill.name}',
+                f'  Description : {skill.description}',
+                f'  Tags        : {", ".join(skill.tags) or "(none)"}',
+            ]
+            if skill.examples:
+                for ex in skill.examples:
+                    lines.append(f'  Example     : {ex}')
+    else:
+        lines.append('  (none)')
+
+    lines.append(sep)
+    print('\n'.join(lines))