test: improved itk logging (#977)

# Description

New version of itk
https://github.com/a2aproject/a2a-samples/releases/tag/itk-v.015-alpha
improves log readabiulity for debugging by spliting the logs of
individual tested agents into separate files if the `ITK_LOG_LEVEL`
environmental variable is set to "DEBUG"

This PR integrates the change into python's sdk CI and updates the
instruction on how to set debugging mode for tests

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- Important Prefixes for
[release-please](https://github.com/googleapis/release-please):
- `fix:` which represents bug fixes, and correlates to a
[SemVer](https://semver.org/) patch.
- `feat:` represents a new feature, and correlates to a SemVer minor.
- `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking
change (indicated by the `!`) and will result in a SemVer major.
- [x] Ensure the tests and linter pass (Run `bash scripts/format.sh`
from the repository root to format)
- [x] Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

Co-authored-by: Krzysztof Dziedzic <dziedzick@google.com>
Co-authored-by: Ivan Shymko <ishymko@google.com>

Author: 3 people

.github/workflows/itk.yaml

@@ -28,4 +28,4 @@ jobs:
         run: bash run_itk.sh
         working-directory: itk
         env:
-          A2A_SAMPLES_REVISION: itk-v.0.11-alpha
+          A2A_SAMPLES_REVISION: itk-v.015-alpha

.gitignore

@@ -18,3 +18,4 @@ docs/ai/ai_learnings.md
 itk/a2a-samples/
 itk/pyproto/
 itk/instruction.proto
+itk/logs/

itk/README.md

@@ -36,7 +36,7 @@ You must set the `A2A_SAMPLES_REVISION` environment variable to specify which re
 
 Example:
 ```bash
-export A2A_SAMPLES_REVISION=itk-v.0.11-alpha
+export A2A_SAMPLES_REVISION=itk-v.015-alpha
 ```
 
 ### 2. Execute Tests
@@ -52,3 +52,22 @@ The script will:
 - Checkout the specified revision.
 - Build the ITK service Docker image.
 - Run the tests and output results.
+
+## Debugging
+
+To enable debug logging and persist logs for inspection:
+
+1.  Set the `ITK_LOG_LEVEL` environment variable to `DEBUG`:
+    ```bash
+    export ITK_LOG_LEVEL=DEBUG
+    ```
+2.  Run the test script:
+    ```bash
+    ./run_itk.sh
+    ```
+
+When run in `DEBUG` mode:
+- The `logs/` directory will be created in this directory (if it doesn't exist).
+- The `logs/` directory will be mounted to the container.
+- The test execution will produce detailed logs in `logs/` (e.g., `agent_current.log`).
+- The `logs/` directory will **not** be removed during cleanup.

itk/main.py

@@ -2,6 +2,7 @@
 import asyncio
 import base64
 import logging
+import os
 import uuid
 
 import grpc
@@ -36,7 +37,8 @@
 from a2a.utils import TransportProtocol
 
 
-logging.basicConfig(level=logging.INFO)
+log_level = os.environ.get('ITK_LOG_LEVEL', 'INFO').upper()
+logging.basicConfig(level=log_level)
 logger = logging.getLogger(__name__)
 
 
@@ -352,8 +354,9 @@ async def main_async(http_port: int, grpc_port: int) -> None:
         grpc_port,
     )
 
+    uvicorn_log_level = os.environ.get('ITK_LOG_LEVEL', 'INFO').lower()
     config = uvicorn.Config(
-        app, host='127.0.0.1', port=http_port, log_level='info'
+        app, host='127.0.0.1', port=http_port, log_level=uvicorn_log_level
     )
     uvicorn_server = uvicorn.Server(config)
 

itk/run_itk.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -ex
 
+# Set default log level
+export ITK_LOG_LEVEL="${ITK_LOG_LEVEL:-INFO}"
+
 # Initialize default exit code
 RESULT=1
 
@@ -63,9 +66,21 @@ ITK_DIR=$(pwd)
 # Stop existing container if any
 docker rm -f itk-service || true
 
+# Create logs directory if debug
+if [ "${ITK_LOG_LEVEL^^}" = "DEBUG" ]; then
+  mkdir -p "$ITK_DIR/logs"
+fi
+
+DOCKER_MOUNT_LOGS=""
+if [ "${ITK_LOG_LEVEL^^}" = "DEBUG" ]; then
+  DOCKER_MOUNT_LOGS="-v $ITK_DIR/logs:/app/logs"
+fi
+
 docker run -d --name itk-service \
   -v "$A2A_PYTHON_ROOT:/app/agents/repo" \
   -v "$ITK_DIR:/app/agents/repo/itk" \
+  $DOCKER_MOUNT_LOGS \
+  -e ITK_LOG_LEVEL="$ITK_LOG_LEVEL" \
   -p 8000:8000 \
   itk_service