AP3 - Quickstart
Extension URI
The URI for the AP3 extension is:
https://github.com/silence-laboratories/ap3/tree/main
Agents that support the AP3 extension MUST use this URI.
SDK helper caveat
The SDK method AP3ExtensionParameters.get_agent_card_extension() currently returns the URI https://github.com/silence-laboratories/ap3 (without /tree/main).
The discovery helper RemoteAgentDiscoveryService.extract_ap3_params() currently looks for https://github.com/silence-laboratories/ap3/tree/main.
For now, prefer advertising the /tree/main URI in your AgentCard to ensure discovery works out-of-the-box.
Agent AP3 Role
Every Agent that supports the AP3 extension MUST perform at least one Role from the AP3 specification. This role is specified in the AgentCard extension object.
Read more about Roles in the AP3 specification.
AgentCard Extension Object
Agents that support the AP3 extension MUST advertise their support using the Extension URI.
Example AgentCard Extension Object
Below agent is capable of performing the initiator and receiver roles of AP3 protocol, and added a commitment of a structured blacklist in manufacturing. It supports PSI as operations.
{
"name": "XYZ Agent",
"url": "http://localhost:10001/",
"version": "1.0.0",
"description": "Perform secure operations",
"preferredTransport": "JSONRPC",
"capabilities": {
"extensions": [
{
"uri": "https://github.com/silence-laboratories/ap3/tree/main",
"description": "AP3 extension for secure collaboration",
"params": {
"roles": [
"ap3_initiator", "ap3_receiver"
],
"supported_operations": [
"PSI", "PIR"
],
"commitments": [
{
"commitment_id": "xyz_data_commitment_v1",
"data_structure": "blacklist",
"data_format": "structured",
"entry_count": 10000,
"field_count": 5,
"estimated_size_mb": 4.8,
"last_updated": "2025-01-01",
"data_freshness": "real_time",
"industry": "manufacturing"
}
]
},
"required": true
}
],
"streaming": true
}
}
Schema Definition
{
"type": "object",
"name": "AP3ExtensionParameters",
"description": "The schema for parameters expressed in AgentExtension.params for the AP3 A2A extension.",
"properties": {
"roles": {
"type": "array",
"name": "AP3 Roles",
"description": "The roles that this agent performs in the AP3 model.",
"minItems": 1,
"items": {
"enum": ["ap3_initiator", "ap3_receiver"]
}
},
"supported_operations": {
"type": "array",
"description": "Types of privacy-preserving operations supported.",
"minItems": 1,
"items": {
"enum": ["PSI", "PIR"]
}
},
"commitments": {
"type": "array",
"description": "Data commitments this agent supports for privacy-preserving computations.",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"commitment_id": "string",
"agent_id": "string",
"data_structure": {
"type": "string",
"enum": [
"blacklist",
"customer_list",
"transaction_log",
"product_catalog",
"supply_chain_data",
"financial_records",
"user_profiles",
"inventory_data"
]
},
"data_format": {
"type": "string",
"enum": ["structured", "unstructured", "semi_structured", "binary"]
},
"entry_count": "number",
"field_count": "number",
"estimated_size_mb": "number",
"last_updated": "string",
"data_freshness": {
"type": "string",
"enum": ["real_time", "daily", "weekly"]
},
"coverage_area": {
"type": "string",
"enum": ["global", "regional", "local"]
},
"industry": {
"type": "string",
"enum": ["food_delivery", "retail", "finance", "healthcare", "manufacturing", "transportation", "other"]
}
}
}
}
},
"required": ["roles", "supported_operations", "commitments"]
}
Directives
Intent Directive
{
"messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contextId": "supply-chain-optimization-context",
"taskId": "cost-optimization-task-001",
"role": "agent",
"parts": [
{
"kind": "data",
"data": {
"ap3.directives.PrivacyIntentDirective": {
"ap3_session_id": "session_id",
"intent_directive_id": "pi_12345",
"operation_type": "PSI",
"participants": [
"manufacturer_agent",
"supplier_agent"
],
"expiry": "2025-01-15T10:00:00Z",
"signature": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjQwOTA..."
}
}
}
]
}
Result Directive
{
"messageId": "c3d4e5f6-g7h8-9012-cdef-345678901234",
"contextId": "supply-chain-optimization-context",
"taskId": "cost-optimization-task-001",
"role": "agent",
"parts": [
{
"kind": "data",
"data": {
"ap3.directives.PrivacyResultDirective": {
"ap3_session_id": "session_id",
"result_directive_id": "rm_11111",
"result_data": {
"encrypted_result": "0x1a2b3c4d5e6f...",
"result_hash": "sha256:789abc...",
"metadata": {
"computation_time": "45.2s",
"elements_processed": 127
}
},
"proofs": {
"correctness_proof": "0x9f8e7d6c5b4a...",
"privacy_proof": "0x3f2e1d0c9b8a...",
"verification_proof": "0x7e6d5c4b3a29..."
},
"signature": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjQwOTA..."
}
}
}
]
}
Error Handling
AP3 agents MUST handle the following error conditions gracefully:
Privacy Protocol Errors
{
"messageId": "error-001",
"contextId": "computation-context",
"taskId": "failed-computation",
"role": "agent",
"parts": [
{
"kind": "data",
"data": {
"ap3.errors.PrivacyProtocolError": {
"error_code": "PROTOCOL_FAILURE",
"error_message": "MPC protocol failed due to malicious participant",
"operation_type": "PSI",
"recovery_options": ["restart_protocol", "switch_protocol"],
"timestamp": "2025-01-15T10:30:00Z"
}
}
}
]
}
Privacy Violation Errors
{
"messageId": "error-002",
"contextId": "computation-context",
"taskId": "privacy-violation",
"role": "agent",
"parts": [
{
"kind": "data",
"data": {
"ap3.errors.PrivacyViolationError": {
"error_code": "PRIVACY_BREACH_DETECTED",
"error_message": "Computation revealed more information than allowed",
"violation_type": "excessive_reveal",
"allowed_reveal": "intersection_only",
"actual_reveal": "full_set_contents",
"timestamp": "2025-01-15T10:35:00Z"
}
}
}
]
}