refactor: delete unnecessary comments. Add new comments.

Author: sokoliva

samples/python/agents/signing_and_verifying/README.md

@@ -2,7 +2,7 @@
 
 Signed agent used as an example for AgentCard signing and verifying.
 
-Read more about signing and verifying AgentCards here: [Agent Card Signing](https://a2a-protocol.org/latest/specification/#84-agent-card-signing)
+Read more about signing and verifying AgentCards here: [Agent Card Signing](https://a2a-protocol.org/latest/specification/#84-agent-card-signing).
 
 ## Getting started
 

samples/python/agents/signing_and_verifying/__main__.py

@@ -16,14 +16,13 @@
 from starlette.routing import Route
 
 from agent_executor import (
-    SignedAgentExecutor,  # type: ignore[import-untyped]
+    SignedAgentExecutor,
 )
 
 if __name__ == "__main__":
-    # --8<-- [start:KeyPair]
+    # Generate a private, public key pair
     private_key = asymmetric.ec.generate_private_key(asymmetric.ec.SECP256R1())
     public_key = private_key.public_key()
-    # --8<-- [end:KeyPair]
 
     # Save public key to a file
     pem = public_key.public_bytes(
@@ -45,15 +44,13 @@
     with Path("public_keys.json").open("w") as f:
         json.dump(keys, f, indent=2)
 
-    # --8<-- [start:AgentSkill]
     skill = AgentSkill(
         id="reminder",
         name="Verification Reminder",
         description="Reminds the user to verify the Agent Card.",
         tags=["verify me"],
         examples=["Verify me!"],
     )
-    # --8<-- [end:AgentSkill]
 
     extended_skill = AgentSkill(
         id="reminder-please",
@@ -63,8 +60,6 @@
         examples=["Verify me, pretty please! :)", "Please verify me."],
     )
 
-    # --8<-- [start:AgentCard]
-    # This will be the public-facing agent card
     public_agent_card = AgentCard(
         name="Signed Agent",
         description="An Agent that is signed",
@@ -73,34 +68,28 @@
         default_input_modes=["text"],
         default_output_modes=["text"],
         capabilities=AgentCapabilities(streaming=True),
-        skills=[skill],  # Only the basic skill for the public card
+        skills=[skill],
         supports_authenticated_extended_card=True,
     )
-    # --8<-- [end:AgentCard]
 
-    # This will be the authenticated extended agent card
-    # It includes the additional 'extended_skill'
     extended_agent_card = public_agent_card.model_copy(
         update={
             "name": "Signed Agent - Extended Edition",
             "description": "The full-featured signed agent for authenticated users.",
-            "version": "1.0.1",  # Could even be a different version
-            # Capabilities and other fields like url, default_input_modes, default_output_modes,
-            # supports_authenticated_extended_card are inherited from public_agent_card unless specified here.
+            "version": "1.0.1",
             "skills": [
                 skill,
                 extended_skill,
-            ],  # Both skills for the extended card
+            ],
         }
     )
 
-    # --8<-- [start:DefaultRequestHandler]
     request_handler = DefaultRequestHandler(
         agent_executor=SignedAgentExecutor(),
         task_store=InMemoryTaskStore(),
     )
-    # --8<-- [end:DefaultRequestHandler]
 
+    # Create singer function which will be used for AgentCard signing
     signer = create_agent_card_signer(
         signing_key=private_key,
         protected_header={
@@ -110,17 +99,19 @@
         },
     )
 
-    # --8<-- [start:A2AStarletteApplication]
     server = A2AStarletteApplication(
         agent_card=public_agent_card,
         http_handler=request_handler,
-        card_modifier=signer,
+        card_modifier=signer,  # The signer function is used to sign the public Agent Card
         extended_agent_card=extended_agent_card,
-        extended_card_modifier=lambda card, _: signer(card),
+        extended_card_modifier=lambda card, _: signer(
+            card
+        ),  # The signer function is also used to sign the extended Agent Card
     )
-    # --8<-- [end:A2AStarletteApplication]
 
     app = server.build()
+    # Expose the public key for verification purposes
+    # Contents of public_keys.json will be fetched on the client side during AgentCard signatures verification
     app.routes.append(
         Route(
             "/public_keys.json",

samples/python/agents/signing_and_verifying/agent_executor.py

@@ -3,7 +3,6 @@
 from a2a.utils import new_agent_text_message
 
 
-# --8<-- [start:SignedAgent]
 class SignedAgent:
     """Signed Agent."""
 
@@ -12,18 +11,12 @@ async def invoke(self) -> str:
         return "Verify me!"
 
 
-# --8<-- [end:SignedAgent]
-
-
-# --8<-- [start:SignedAgentExecutor_init]
 class SignedAgentExecutor(AgentExecutor):
     """Test AgentProxy Implementation."""
 
     def __init__(self) -> None:
         self.agent = SignedAgent()
 
-    # --8<-- [end:SignedAgentExecutor_init]
-    # --8<-- [start:SignedAgentExecutor_execute]
     async def execute(
         self,
         context: RequestContext,
@@ -33,12 +26,7 @@ async def execute(
         result = await self.agent.invoke()
         await event_queue.enqueue_event(new_agent_text_message(result))
 
-    # --8<-- [end:SignedAgentExecutor_execute]
-
-    # --8<-- [start:SignedAgentExecutor_cancel]
     async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
         """Cancel method is not supported."""
 
         raise Exception("Cancel not supported.")
-
-    # --8<-- [end:SignedAgentExecutor_cancel]

samples/python/agents/signing_and_verifying/pyproject.toml

@@ -7,6 +7,7 @@ requires-python = ">=3.10"
 dependencies = [
     "a2a-sdk>=0.3.22",
     "cryptography>=43.0.0",
+    "fastapi>=0.115.0",
     "httpx>=0.28.1",
     "pydantic>=2.11.4",
     "PyJWT>=2.0.0",

samples/python/agents/signing_and_verifying/test_client.py

@@ -41,11 +41,10 @@ def _key_provider(kid: str | None, jku: str | None) -> PyJWK | str | bytes:
 
 async def main() -> None:
     """Main function."""
-    # Configure logging to show INFO level messages
+
     logging.basicConfig(level=logging.INFO)
-    logger = logging.getLogger(__name__)  # Get a logger instance
+    logger = logging.getLogger(__name__)
 
-    # --8<-- [start:A2ACardResolver]
     base_url = "http://localhost:9999"
 
     async with httpx.AsyncClient() as httpx_client:
@@ -54,9 +53,8 @@ async def main() -> None:
             httpx_client=httpx_client,
             base_url=base_url,
         )
-        # --8<-- [end:A2ACardResolver]
 
-        # Fetch and Verify Agent Card and Initialize BaseClient
+        # Fetch and verify Agent Card and initialize BaseClient
         final_agent_card_to_use: AgentCard | None = None
 
         try:
@@ -67,7 +65,7 @@ async def main() -> None:
             )
             _public_card = await resolver.get_agent_card(
                 signature_verifier=signature_verifier,
-            )  # Fetches from default public path
+            )  # Verifies the AgentCard using signature_verifier function before returning it
             logger.info("Successfully fetched public agent card:")
             logger.info(_public_card.model_dump_json(indent=2, exclude_none=True))
             final_agent_card_to_use = _public_card
@@ -85,18 +83,18 @@ async def main() -> None:
                         relative_card_path=EXTENDED_AGENT_CARD_PATH,
                         http_kwargs={"headers": auth_headers_dict},
                         signature_verifier=signature_verifier,
-                    )
+                    )  # Verifies the extended AgentCard using signature_verifier function before returning it
                     logger.info("Successfully fetched and verified authenticated extended agent card:")
                     logger.info(_extended_card.model_dump_json(indent=2, exclude_none=True))
-                    final_agent_card_to_use = _extended_card  # Update to use the extended card
+                    final_agent_card_to_use = _extended_card
                     logger.info("\nUsing AUTHENTICATED EXTENDED agent card for client initialization.")
                 except Exception as e_extended:
                     logger.warning(
                         "Failed to fetch or verify extended agent card: %s. Will proceed with public card.",
                         e_extended,
                         exc_info=True,
                     )
-            elif _public_card:  # supports_authenticated_extended_card is False or None
+            elif _public_card:
                 logger.info("\nPublic card does not indicate support for an extended card. Using public card.")
 
         except Exception as e:
@@ -111,7 +109,6 @@ async def main() -> None:
         # Create Base Client
         client = client_factory.create(final_agent_card_to_use)
 
-        # --8<-- [start:send_message]
         message_to_send = Message(
             role=Role.user,
             message_id="msg-integration-test-signing-and-verifying",
@@ -124,13 +121,12 @@ async def main() -> None:
             parts = chunk_dict["parts"]
             for part in parts:
                 print(part["text"])
-        # --8<-- [end:send_message]
 
-        # --8<-- [start:get_card]
-        get_card_response = await client.get_card(signature_verifier=signature_verifier)
+        get_card_response = await client.get_card(
+            signature_verifier=signature_verifier
+        )  # Verifies the AgentCard using signature_verifier function before returning it
         print("fetched again:")
         print(get_card_response.model_dump(mode="json", exclude_none=True))
-        # --8<-- [end:get_card]
 
 
 if __name__ == "__main__":