Aries Agents

Pico Labs has implemented Pico Agents and is beginning work on https://github.com/Picolab/aries-cloudagent-pico (Aries cloudagent Pico). In the previous sentence each name is linked to the corresponding code repository in GitHub.

The Aries specification is maintained by the Aries community in a GitHub repo. Each part of the specification is called an “RFC” and they are grouped into concepts and features. Pico Labs maintains a fork of the official repo (for making pull requests) and we strive to keep the fork even with the Aries repo. Instructions for making a pull request located here.

Pico Agents

This project was created specifically to pass the five tests of the pytest (deprecated) Agent interoperability test suite. Later it was augmented to provide an agency, and to support edge and router agents.

Usage

First prepare your pico-engine by registering the rulesets. Then create the Picos and make them into Pico Agents of the various kinds.

Deprecation notice

These rulesets continue to function but our intention is to only apply bug fixes going forward.

New development has moved to ACA-pico.

Preparing a pico-engine to host Pico Agents

Need to register a few rulesets with the pico-engine. These are:

1 2 3 4 5 6 7 https://raw.githubusercontent.com/Picolab/G2S/master/krl/html.krl https://raw.githubusercontent.com/Picolab/G2S/master/krl/webfinger.krl https://raw.githubusercontent.com/Picolab/G2S/master/krl/org.sovrin.agent.ui.krl https://raw.githubusercontent.com/Picolab/G2S/master/krl/org.sovrin.agent_message.krl https://raw.githubusercontent.com/Picolab/G2S/master/krl/org.sovrin.agent.krl https://raw.githubusercontent.com/Picolab/G2S/master/krl/org.sovrin.edge.krl https://raw.githubusercontent.com/Picolab/G2S/master/krl/org.sovrin.router.krl

The easiest way to register these rulesets manually is to visit the Register rulesets page. Then, if necessary, edit the “localhost:8080” text (by clicking on it, adjusting it, and hitting the Return key) to be the domain and port where your pico-engine is running. Click on the ruleset URIs in order (and go back to the page after seeing each one registered to click on the next one). You could also write code to register these rulesets with the engine and run it at a time and in a way of your choosing.

Cloud Agents

To make a Pico into a Pico Agent, all you need to do is install the org.sovrin.agent ruleset in the Pico. With this ruleset installed, the Pico is now an Aries cloud agent.

If you install the ruleset manually, the agent’s name will be the same as the Pico name. When installing the ruleset programmatically (by sending the Pico the wrangler:install_rulesets_requested event, you can give the agent a different name by including an extra attribute, named label. For example, this event:

 

1 http://localhost:8080/sky/event/<ECI>/make-agent/wrangler/install_ruleset_requested?rid=org.sovrin.agent&label=Alice

would make the Pico whose ECI is mentioned become a cloud agent labelled “Alice” regardless of the Pico name.

With the ruleset installed, the cloud agent can provide connection invitations for, and accept connection invitations from, other Aries agents.

The invitation is obtained by invoking the ui function of the ruleset. A URI to invoke the function would look like:

 

1 http://localhost:8080/sky/cloud/<ECI>/org.sovrin.agent/ui

and would return a JSON structure like:

1 2 3 4 5 6 { "name": "Alice", "connections": null, "invitation": "http://localhost:8080/sky/cloud/<ECI>/org.sovrin.agent/html.html?c_i=<INVITE>", "wf": null, }

giving the cloud agent’s label, the fact that it has no connections yet, and the invitation URI.

The invitation URI is sent to another Aries agent. Only the parameter, named c_i, is the actual invitation. It is a BASE64 encoded JSON structure, as described in the Aries connection protocol. The enclosing URI invokes the html function of the ruleset and provides a human-readable view of the invitation, including a QR Code which can be scanned by Aries agents capable of doing that to initiate a connection.

The Pico Agent can accept an invitation from another Aries agent using this event:

1 http://localhost:8080/sky/event/<ECI>/accept_invitation/sovrin/new_invitation?url=http...

where “http…” is the entire invitation URL from the other agent. Upon receipt of this event, the Pico Agent will send the connections request and receive and accept the connections response from the other agent, resulting in a new connection.

Once a connection has been made (whether by issuing an invitation or accepting an invitation), the Pico Agent can exchange basic messages and trust pings over an encrypted and signed DIDComm connection with the other agent.

Edge Agents

Forwarding Agents

Agency

ACA-Pico

This project’s goal is to become a reference implementation of the Aries agent specification.

ACA-Pico (or Aries cloud agents implemented as Picos) is a refactoring of the Pico Agent code base. The various DIDComm protocols are broken out into different rulesets, and we follow and refer to the RFCs in the https://github.com/hyperledger/aries-rfcs repository.

Preparing a pico-engine to host Pico Agents

Need to register a few rulesets with the pico-engine. These are:

1 2 3 4 5 6 https://raw.githubusercontent.com/Picolab/aries-cloudagent-pico/master/krl/html.krl https://raw.githubusercontent.com/Picolab/aries-cloudagent-pico/master/krl/org.sovrin.aca.krl https://raw.githubusercontent.com/Picolab/aries-cloudagent-pico/master/krl/org.sovrin.aca.connections.ui.krl https://raw.githubusercontent.com/Picolab/aries-cloudagent-pico/master/krl/org.sovrin.aca.connections.krl https://raw.githubusercontent.com/Picolab/aries-cloudagent-pico/master/krl/org.sovrin.aca.basicmessage.krl https://raw.githubusercontent.com/Picolab/aries-cloudagent-pico/master/krl/org.sovrin.aca.trust_ping.krl

The easiest way to register these rulesets manually is to visit your pico-engine Rulesets Editor page. Then, copy and paste one line at a time from the list above, pasting into the box labelled “raw source URL” and click on the button “register url.” You could also write code to register these rulesets with the engine and run it at a time and in a way of your choosing.

Cloud Agents

To make a Pico into a ACA-Pico agent, all you need to do is install the org.sovrin.aca ruleset in the Pico. With this ruleset installed, the Pico is now an Aries cloud agent.

If you install the ruleset manually, the agent’s name will be the same as the Pico name. When installing the ruleset programmatically (by sending the Pico the wrangler:install_rulesets_requested event, you can give the agent a different name by including an extra attribute, named label. For example, this event:

1 http://localhost:8080/sky/event/<ECI>/make-agent/wrangler/install_ruleset_requested?rid=org.sovrin.aca&label=Alice

would make the Pico whose ECI is mentioned become a cloud agent labelled “Alice” regardless of the Pico name.

As an agent, the Pico now can send and receive packed messages and can receive out of band messages. It also maintains an array of connections. But it lacks the ability to create connections, or to exchange DIDs.

In order to make connections, you will need to install the org.sovrin.aca.connections ruleset into the agent Pico.

With this ruleset installed, an invitation can be obtained from this Aries agent by invoking the invitation function:

1 http://localhost:8080/sky/cloud/<ECI>/org.sovrin.aca.connections/invitation

The invitation will be a URL with this form:

1 http://localhost:8080/sky/cloud/<ECI>/org.sovrin.aca.connections/html.html?c_i=<INVITE>

The invitation URI can be sent to another Aries agent. Only the parameter, named c_i, is the actual invitation. It is a BASE64 encoded JSON structure, as described in the Aries connection protocol. The enclosing URI invokes the html function of the connections ruleset and provides a human-readable view of the invitation, including a QR Code which can be scanned by Aries agents capable of doing that to initiate a connection.

An invitation is (in Aries terminology) an “out of band” message. The Pico Agent can accept an invitation from another Aries agent using this event:

1 http://localhost:8080/sky/event/<ECI>/accept_invitation/didcomm/message?url=http...

where “http…” is the entire invitation URL from the other agent. Upon receipt of this event, the Pico Agent will send the connections request and receive and accept the connections response from the other agent, resulting in a new connection.

Once a connection has been made (whether by issuing an invitation or accepting an invitation), the Pico Agent can exchange basic messages and trust pings over an encrypted and signed DIDComm connection with the other agent, assuming the presence in the Pico of the corresponding rulesets.

For basic messages, install the org.sovrin.aca.basicmessage ruleset. This implements the Aries basic message protocol.

For trust pings, install the org.sovrin.aca.trust_ping ruleset. This implements the Aries trust ping protocol.