Aries Cloud Agent Python (ACA-Py)

Aries Cloud Agent Python (ACA-Py) is an open-source, production-ready framework written in Python for building interoperable decentralized identity agents that implement the W3C Verifiable Credentials data model and the Decentralized Identifiers (DIDs) specification. It serves as a foundational component in the Hyperledger Aries project ecosystem, providing a standardized set of protocols—such as DIDComm for secure messaging and the Aries RFCs—for issuing, holding, presenting, and verifying credentials in a privacy-preserving manner. ACA-Py enables developers to create cloud-based or edge agents that act on behalf of individuals, organizations, or IoT devices to manage their digital identities and interactions without relying on a central authority.

The architecture of ACA-Py is built around the concept of a mediator agent, which handles secure, peer-to-peer communication channels using the DIDComm v2 encrypted messaging protocol. An agent can hold multiple DIDs and manage associated verifiable credentials, facilitating complex interactions like credential issuance flows and presentation exchanges. It provides a clear separation between the core agent logic and the controller—the business application that dictates the agent's behavior via a well-defined administrative API. This modular design allows developers to integrate ACA-Py into existing systems, such as mobile wallets, enterprise backends, or government services, while ensuring compliance with global interoperability standards like those from the Trust Over IP (ToIP) Foundation.

A key feature of ACA-Py is its support for zero-knowledge proofs (ZKPs) through AnonCreds, a credential format that enables selective disclosure of attributes and predicate proofs (e.g., proving one is over 21 without revealing their exact birth date). This is critical for implementing privacy-by-design principles. The framework also includes built-in support for various ledgers (like Hyperledger Indy, Sovrin, or others via the BCovrin test network) for publishing and resolving DIDs, though it is ledger-agnostic at its core. Developers typically interact with ACA-Py through its Swagger-based Admin API to trigger protocol steps, manage connections, and handle credential workflows.

In practice, ACA-Py is used to power a wide range of digital trust ecosystems. Common implementations include issuers (like universities issuing digital diplomas), verifiers (like employers checking credentials), and holders (like individuals using a mobile wallet). For example, a government health agency could deploy an ACA-Py-based issuer agent to distribute verifiable COVID-19 vaccination credentials, which citizens could then store in their wallet agent and present to a verifier agent at an airport. The framework's active development under the Linux Foundation ensures continuous updates for new protocols, enhanced security, and scalability, making it a cornerstone for building the decentralized identity layer of the internet.

Aries Cloud Agent - Python (ACA-Py) is an open-source, production-ready framework for implementing Self-Sovereign Identity (SSI) agents that communicate using the Aries Interoperability Protocol. It provides a set of core services - including DID management, secure messaging, credential issuance and verification, and proof presentation - packaged as a single deployable component. Developers interact with ACA-Py through its administrative API to orchestrate identity interactions, while the agent handles the complex, standards-based cryptography and protocol logic under the hood, connecting to distributed ledgers and other agents.

At its core, ACA-Py operates on a message-based architecture. All interactions, from establishing a connection to presenting a verifiable credential, are modeled as the exchange of DIDComm messages. The agent's internal message router receives these encrypted messages, determines their type (e.g., connection-request, present-proof), and dispatches them to the appropriate protocol handler. This modular design separates the protocol logic from transport concerns, allowing ACA-Py to support multiple transports like HTTP, WebSockets, or other queues while maintaining the same application-level semantics.

A fundamental workflow is the DID Exchange protocol, which establishes a secure, peer-to-peer channel. Two ACA-Py instances exchange their public DIDs and generate a unique, encrypted pairwise DID for the relationship. This creates a private communication channel independent of any public ledger. Once a connection is established, the Issue Credential and Present Proof protocols can execute. These protocols involve a structured series of DIDComm messages that enable an issuer to populate a credential schema with claims, sign it to create a Verifiable Credential, and later allow a holder to generate a Verifiable Presentation that discloses selective claims to a verifier.

ACA-Py relies on several external components. It requires a verifiable data registry (VDR), typically a blockchain like Indy or a universal resolver, to write and resolve Decentralized Identifiers (DIDs). For storing credentials, private keys, and other sensitive data, it uses a wallet backend, with implementations for PostgreSQL, SQLite, and Indy-SDK. The agent's stateless design means all persistent data is stored in this wallet and the VDR, enabling scalable, containerized deployments where multiple agent instances can share the same wallet database.

ACA-Py is a foundational agent framework that provides a comprehensive toolkit for building Self-Sovereign Identity (SSI) ecosystems. It implements the core W3C Verifiable Credentials data model and the Decentralized Identifiers (DIDs) specification, enabling entities to issue, hold, and verify cryptographically secure digital credentials. The agent acts as a secure, cloud-based service that manages keys, performs cryptographic operations, and facilitates peer-to-peer messaging, abstracting the underlying complexity of the Aries protocols for developers.

Its primary function is to support the Aries Interoperability Protocols, a suite of standardized interactions defined in Aries RFCs. This includes the DIDComm v2 encrypted messaging protocol for secure peer-to-peer communication, the Connection protocol for establishing trusted relationships, and the core Issue Credential and Present Proof protocols for credential exchange. By adhering to these open standards, ACA-Py ensures interoperability between different vendors and systems within the broader SSI landscape, preventing vendor lock-in.

The agent provides a flexible architecture with support for multiple ledgers (like Hyperledger Indy, Sovrin, and others via the Aries BDR protocol), wallet backends for secure storage, and pluggable components for extensibility. Developers interact with ACA-Py primarily through its Administrative API, issuing commands to create invitations, manage connections, and handle credential flows, while the agent handles all the protocol-level details and state management automatically.

A key design principle is protocol neutrality. ACA-Py does not enforce specific business logic or user experience; it is a protocol engine. This allows developers to build diverse applications—from mobile wallet apps and enterprise credential issuers to government services—on top of the same robust, standards-compliant foundation. The agent handles the secure, standardized 'plumbing,' freeing developers to focus on application-specific features and user interfaces.

Maintained by the Hyperledger Foundation community, ACA-Py's active development and rigorous adherence to Aries RFCs make it a trusted reference implementation. It is widely used in production deployments across various sectors, serving as the backbone for digital identity networks that require verifiable, privacy-preserving credentials and interoperable trust relationships between organizations and individuals.