Skip to content

Commit ac3d73e

Browse files
vinbytevinbyte
authored
Merge branch 'main' into fix/go-client-stream-unit-test
2 parents d5a0d10 + f53b6a5 commit ac3d73e

File tree

10 files changed

+1180
-0
lines changed

10 files changed

+1180
-0
lines changed

‎extensions/secure-passport/HOWTORUN.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# HOW TO RUN the Secure Passport Extension Sample
2+
3+
This guide provides step-by-step instructions for setting up the environment and running the Python sample code for the **Secure Passport Extension v1**.
4+
5+
The sample is located in the `samples/python/` directory.
6+
7+
---
8+
9+
## 1. Prerequisites
10+
11+
You need the following installed on your system:
12+
13+
* **Python** (version 3.9 or higher)
14+
* **Poetry** (Recommended for dependency management via `pyproject.toml`)
15+
16+
---
17+
18+
## 2. Setup and Installation
19+
20+
1. **From the repository root, navigate** to the sample project directory:
21+
```bash
22+
cd extensions/secure-passport/v1/samples/python
23+
```
24+
25+
2. **Install Dependencies** using Poetry. This command reads `pyproject.toml`, creates a virtual environment, and installs `pydantic` and `pytest`.
26+
```bash
27+
poetry install
28+
```
29+
30+
3. **Activate** the virtual environment:
31+
```bash
32+
poetry shell
33+
```
34+
35+
*(Note: All subsequent commands are run from within this activated environment.)*
36+
37+
---
38+
39+
## 3. Execution
40+
41+
There are two ways to run the code: using the automated unit tests or using a manual script.
42+
43+
### A. Run Unit Tests (Recommended)
44+
45+
Running the tests is the most complete way to verify the extension's data modeling, integrity checks, and validation logic.
46+
47+
```bash
48+
# Execute Pytest against the test directory
49+
pytest tests/
50+
51+
### B. Run Middleware Demo Script
52+
53+
Execute `run.py` to see the full client/server middleware pipeline in action for all four use cases:
54+
55+
```bash
56+
python run.py
57+
58+
### Expected Console Output
59+
60+
The output below demonstrates the successful execution of the four use cases via the simulated middleware pipeline:
61+
62+
========================================================= Secure Passport Extension Demo (Middleware)
63+
--- Use Case: Efficient Currency Conversion (via Middleware) ---
64+
[PIPELINE] Client Side: Middleware -> Transport
65+
[Middleware: Client] Attaching Secure Passport for a2a://travel-orchestrator.com
66+
[Transport] Message sent over the wire.
67+
[PIPELINE] Server Side: Middleware -> Agent Core
68+
[Middleware: Server] Extracted Secure Passport. Verified: True
69+
[Agent Core] Task received for processing.
70+
[Agent Core] Executing task with verified context: Currency=GBP, Tier=Silver
71+
72+
--- Use Case: Personalized Travel Booking (via Middleware) ---
73+
[PIPELINE] Client Side: Middleware -> Transport
74+
[Middleware: Client] Attaching Secure Passport for a2a://travel-portal.com
75+
[Transport] Message sent over the wire.
76+
[PIPELINE] Server Side: Middleware -> Agent Core
77+
[Middleware: Server] Extracted Secure Passport. Verified: True
78+
[Agent Core] Task received for processing.
79+
[Agent Core] Executing task with verified context: Currency=Unknown, Tier=Platinum
80+
81+
--- Use Case: Proactive Retail Assistance (via Middleware) ---
82+
[PIPELINE] Client Side: Middleware -> Transport
83+
[Middleware: Client] Attaching Secure Passport for a2a://ecommerce-front.com
84+
[Transport] Message sent over the wire.
85+
[PIPELINE] Server Side: Middleware -> Agent Core
86+
[Middleware: Server] Extracted Secure Passport. Verified: False
87+
[Agent Core] Task received for processing.
88+
[Agent Core] Executing task with unverified context (proceeding cautiously).
89+
90+
--- Use Case: Marketing Agent seek insights (via Middleware) ---
91+
[PIPELINE] Client Side: Middleware -> Transport
92+
[Middleware: Client] Attaching Secure Passport for a2a://marketing-agent.com
93+
[Transport] Message sent over the wire.
94+
[PIPELINE] Server Side: Middleware -> Agent Core
95+
[Middleware: Server] Extracted Secure Passport. Verified: True
96+
[Agent Core] Task received for processing.
97+
[Agent Core] Executing task with verified context: Currency=Unknown, Tier=Standard

‎extensions/secure-passport/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Secure Passport Extension
2+
3+
This directory contains the specification and a Python sample implementation for the **Secure Passport Extension v1** for the Agent2Agent (A2A) protocol.
4+
5+
## Purpose
6+
7+
The Secure Passport extension introduces a **trusted, contextual layer** for A2A communication. It allows a calling agent to securely and voluntarily share a structured subset of its current contextual state with the callee agent. This is designed to transform anonymous, transactional calls into collaborative partnerships, enabling:
8+
9+
* **Immediate Personalization:** Specialist agents can use context (like loyalty tier or preferred currency) immediately.
10+
* **Reduced Overhead:** Eliminates the need for multi-turn conversations to establish context.
11+
* **Enhanced Trust:** Includes a **`signature`** field for cryptographic verification of the data's origin and integrity.
12+
13+
## Specification
14+
15+
The full technical details, including data models, required fields, and security considerations, are documented here:
16+
17+
➡️ **[Full Specification (v1)](./v1/spec.md)**
18+
19+
## Sample Implementation
20+
21+
A runnable example demonstrating the implementation of the `CallerContext` data model and the utility functions for integration with the A2A SDK is provided in the `samples` directory.
22+
23+
➡️ **[Python Sample Usage Guide](./v1/samples/python/README.md)**

‎extensions/secure-passport/v1/samples/python/README.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Secure Passport Python Sample
2+
3+
This sample provides the runnable code for the **Secure Passport Extension v1** for the Agent2Agent (A2A) protocol, demonstrating its implementation and usage in a Python environment.
4+
5+
## 1. Extension Overview
6+
7+
The core of this extension is the **`CallerContext`** data model, which is attached to the A2A message metadata under the extension's unique URI. This enables the secure transfer of trusted contextual state between collaborating agents.
8+
9+
### Extension URI
10+
11+
The unique identifier for this extension is:
12+
`https://github.com/a2aproject/a2a-samples/tree/main/samples/python/extensions/secure-passport`
13+
14+
---
15+
16+
## 2. Comprehensive Usage and Middleware Demonstration
17+
18+
The `run.py` script demonstrates the full client-server pipeline using the conceptual **middleware layers** for seamless integration.
19+
20+
### A. Use Case Code Demonstration
21+
22+
The following code demonstrates how to create the specific `CallerContext` payloads for the four core use cases, verifying that the structure and integrity checks work as intended.
23+
24+
```python
25+
from secure_passport_ext import (
26+
CallerContext,
27+
A2AMessage,
28+
add_secure_passport,
29+
get_secure_passport
30+
)
31+
32+
def demonstrate_use_case(title: str, client_id: str, state: dict, signature: str | None = None, session_id: str | None = None):
33+
print(f"\n--- Demonstrating: {title} ---")
34+
35+
passport = CallerContext(
36+
client_id=client_id,
37+
session_id=session_id,
38+
signature=signature,
39+
state=state
40+
)
41+
42+
message = A2AMessage()
43+
add_secure_passport(message, passport)
44+
retrieved = get_secure_passport(message)
45+
46+
if retrieved:
47+
print(f" Source: {retrieved.client_id}")
48+
print(f" Verified: {retrieved.is_verified}")
49+
print(f" Context: {retrieved.state}")
50+
else:
51+
print(" [ERROR] Passport retrieval failed.")
52+
53+
# 1. Efficient Currency Conversion (Low Context, High Trust)
54+
55+
demonstrate_use_case(
56+
title="1. Currency Conversion (GBP)",
57+
client_id="a2a://travel-orchestrator.com",
58+
state={"user_preferred_currency": "GBP", "user_id": "U001"},
59+
signature="sig-currency-1"
60+
)
61+
62+
# 2. Personalized Travel Booking (High Context, Session Data)
63+
64+
demonstrate_use_case(
65+
title="2. Personalized Travel (Platinum Tier)",
66+
client_id="a2a://travel-portal.com",
67+
session_id="travel-session-999",
68+
state={
69+
"destination": "Bali, Indonesia",
70+
"loyalty_tier": "Platinum"
71+
},
72+
signature="sig-travel-2"
73+
)
74+
75+
# 3. Proactive Retail Assistance (Unsigned, Quick Context)
76+
77+
demonstrate_use_case(
78+
title="3. Retail Assistance (Unverified)",
79+
client_id="a2a://ecommerce-front.com",
80+
state={"product_sku": "Nikon-Z-50mm-f1.8", "user_intent": "seeking_reviews"},
81+
signature=None
82+
)
83+
84+
# 4. Marketing Agent seek insights (High Trust, Secured Scope)
85+
86+
demonstrate_use_case(
87+
title="4. Secured DB Access (Finance)",
88+
client_id="a2a://marketing-agent.com",
89+
state={
90+
"query_type": "quarterly_revenue",
91+
"access_scope": ["read:finance_db", "user:Gulli"]
92+
},
93+
signature="sig-finance-4"
94+
)
95+
```
96+
97+
### B. Convenience Method: AgentCard Declaration
98+
99+
The `SecurePassportExtension` class provides a static method to easily generate the necessary JSON structure for including this extension in an agent's `AgentCard`. This ensures the structure is always compliant.
100+
101+
```python
102+
from secure_passport_ext import SecurePassportExtension
103+
104+
# Scenario 1: Agent supports basic Secure Passport
105+
simple_declaration = SecurePassportExtension.get_agent_card_declaration()
106+
# Output will be: {'uri': '...', 'params': {'receivesCallerContext': True}}
107+
108+
# Scenario 2: Agent supports specific keys (e.g., the Travel Agent)
109+
travel_keys = ["destination", "loyalty_tier", "dates"]
110+
complex_declaration = SecurePassportExtension.get_agent_card_declaration(travel_keys)
111+
# Output will include: 'supportedStateKeys': ['destination', 'loyalty_tier', 'dates']
112+
```
113+
114+
## 3. How to Run the Sample 🚀
115+
116+
To run the sample and execute the comprehensive unit tests, follow these steps.
117+
118+
### A. Setup and Installation
119+
120+
1. **Navigate** to the Python sample directory:
121+
```bash
122+
cd extensions/secure-passport/v1/samples/python
123+
```
124+
2. **Install Dependencies** (using Poetry):
125+
```bash
126+
poetry install
127+
128+
# Activate the virtual environment
129+
poetry shell
130+
```
131+
132+
### B. Verification and Execution
133+
134+
#### 1. Run Unit Tests (Recommended)
135+
136+
Confirm all 11 core logic and validation tests pass:
137+
138+
```bash
139+
pytest tests/
140+
```
141+
142+
#### 2. Run Middleware Demo Script
143+
144+
Execute `run.py` to see the full client/server middleware pipeline in action for all four use cases:
145+
146+
```bash
147+
python run.py
148+
```

0 commit comments

Comments
 (0)