AP3 - A2A Extension
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.
Extension Declaration
Agents declare their support for extensions in their Agent Card by including AgentExtension objects within their AgentCapabilities object.
Read more about AgentExtensions in A2A Protocol.
AgentCard Extension Object
Agents that support the AP3 extension:
- MUST advertise their support using the Extension URI.
- MUST use the
paramsobject to specify the AP3 capabilities of the agent.
In the params object, the agent MUST specify the following:
roles: The roles that the agent performs in the AP3 protocol.commitments: The data commitments that the agent declares for other agents to perform the AP3 protocol.supported_operations: The operations that the agent supports.
Read more about Roles, Commitments and Operations in the AP3 specification.
The params object MUST adhere to the following JSON schema:
AP3ExtensionParameters Schema
{
"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"
]
}
},
"commitments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"commitment_id": "string",
"data_structure": {
"type": "string",
"enum": [
"blacklist",
"customer_list",
"transaction_log",
"product_catalog",
"supply_chain_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"
]
}
}
}
},
"supported_operations": {
"type": "array",
"items": {
"enum": [
"PSI",
"PIR",
"SFE"
]
}
}
},
"required": [
"roles",
"commitments",
"operations"
]
}
Example AgentCard with AP3 extension
{
"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", "SFE"
],
"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
}
}
AP3 Directives
AP3 directives are used to structure privacy-preserving computations:
* PrivacyIntentDirective: The intent directive is used to declare the computation to be performed.
* PrivacyResultDirective: The result directive is used to contain the computation result with cryptographic proofs.
Read more about Directives in the AP3 specification.
Privacy Intent Directive Message
To provide an PrivacyIntentDirective, the agent MUST create a PrivacyIntentDirective Message. A PrivacyIntentDirective Message is an A2A Message profile with the following requirements.
The Message MUST contain a DataPart that contains a key of ap3.directives.PrivacyIntentDirective and a value that adheres to the PrivacyIntentDirective schema.
PrivacyIntentDirective Schema
{
"type": "object",
"name": "PrivacyIntentDirective",
"description": "The schema for PrivacyIntentDirective messages.",
"properties": {
"ap3_session_id": {
"type": "string",
"description": "Unique identifier for this session"
},
"intent_directive_id": {
"type": "string",
"description": "Unique identifier for this privacy intent"
},
"operation_type": {
"type": "string",
"description": "Type of privacy-preserving operation (PSI, PIR, SFE)"
},
"participants": {
"type": "array",
"description": "List of participants in the privacy-preserving operation",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"ap3_initiator",
"ap3_receiver"
]
},
"agent_id": {
"type": "string",
"description": "Agent ID of the participant"
},
"data_commitment": {
"type": "string",
"description": "Hash of the data commitment for the participant"
}
},
"required": [
"role",
"agent_id",
"data_commitment"
]
}
},
"expiry": {
"type": "string",
"description": "Expiry time in ISO 8601 format"
},
"signature": {
"type": "string",
"description": "Cryptographic signature of the initiator agent"
}
},
"required": [
"ap3_session_id",
"intent_directive_id",
"operation_type",
"participants",
"expiry",
"signature"
]
}
Below example shows the JSON object of a PrivacyIntentDirective Message.
{
"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": [
{
"role": "initiator",
"agent_id": "manufacturer_agent",
"data_commitment": "sha256:abc123..."
},
{
"role": "receiver",
"agent_id": "supplier_agent",
"data_commitment": "sha256:def456..."
}
],
"expiry": "2025-01-15T10:00:00Z",
"signature": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjQwOTA..."
}
}
}
]
}
Privacy Result Directive Message
To provide a PrivacyResultDirective, the agent MUST create a PrivacyResultDirective Message. A PrivacyResultDirective Message is an A2A Message profile with the following requirements.
The Message MUST contain a DataPart that contains a key of ap3.directives.PrivacyResultDirective and a value that adheres to the PrivacyResultDirective schema.
PrivacyResultDirective Schema
{
"type": "object",
"name": "PrivacyResultDirective",
"description": "The schema for PrivacyResultDirective messages.",
"properties": {
"ap3_session_id": {
"type": "string",
"description": "Unique identifier for this session"
},
"result_directive_id": {
"type": "string",
"description": "Unique identifier for this result directive"
},
"operation_type": {
"type": "string",
"description": "Type of privacy-preserving operation (PSI, PIR, SFE)"
},
"result_data": {
"type": "object",
"description": "Encrypted result data and metadata",
"properties": {
"encrypted_result": "string",
"result_hash": "string",
"metadata": {
"type": "object",
"description": "Metadata about the result"
}
}
},
"proofs": {
"type": "object",
"description": "Cryptographic proofs of correctness and privacy"
},
"signature": {
"type": "string",
"description": "Cryptographic signature of the initiator agent"
}
},
"required": [
"ap3_session_id",
"result_directive_id",
"operation_type",
"result_data",
"proofs",
"signature"
]
}
Below example shows the JSON object of a PrivacyResultDirective Message.
{
"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",
"operation_type": "PSI",
"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 error conditions gracefully:
Privacy Protocol Errors Message
To provide a PrivacyProtocolError, the agent MUST create a PrivacyProtocolError Message. A PrivacyProtocolError Message is an A2A Message profile with the following requirements.
The Message MUST contain a DataPart that contains a key of ap3.errors.PrivacyProtocolError and a value that adheres to the PrivacyProtocolError schema.
PrivacyProtocolError Schema
{
"type": "object",
"name": "PrivacyProtocolError",
"description": "The schema for PrivacyProtocolError messages.",
"properties": {
"error_code": {
"type": "string",
"description": "Machine-readable error code"
},
"error_message": {
"type": "string",
"description": "Human-readable error message"
},
"directive_id": {
"type": "string",
"description": "Unique identifier for this computation directive"
},
"recovery_options": {
"type": "array",
"description": "Available recovery options",
"items": {
"type": "string"
}
},
"timestamp": {
"type": "string",
"description": "Timestamp when the error occurred"
}
},
"required": [
"error_code",
"error_message",
"computation_directive_id",
"recovery_options",
"timestamp"
]
}
Below example shows the JSON object of a PrivacyProtocolError Message.
{
"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",
"directive_id": "pi_67890",
"timestamp": "2025-01-15T10:30:00Z"
}
}
}
]
}