FCP HIPE: Agents explainer

[dhh1128]

Signed-off-by: Daniel Hardman daniel.hardman@gmail.com

[kdenhartog]

I think this is an excellent document to help developers understand what we mean when we say "agent".

My one piece of feedback is that I think this document would fit better in the Indy-Agent/doc directory than with the HIPEs because it's specific to agents. Organization of these documents is something we've brought up in the past (VCX hipe), but we didn't decide on. Should we decide on this before accepting this?

[TelegramSam]

paper key storage feels more like a wallet, though different in a way than described above.

[dhh1128]

Agreed. I've updated the verbiage to clarify this.

[TelegramSam]

We may want to draw out the difference between an API call as an RPC and an agent message or event. APIs and RPC implies a master/slave relationship, while Agent Messages are Peer Interactions.

(I'm just realizing that Admin Message Families are more RPC like, whch is different than Agent Messaging between peers.)

[dhh1128]

I like this suggestion and I am agreeing with it, but I'm struggling to find a graceful way to modify the text. Do you have any suggestions, @TelegramSam ?

[TelegramSam]

Daniel, this is excellent high level work. I've added a few comments, but overall this is excellent.

[mwherman2000]

1. Checkout this taxonomy chart: https://hyperonomy.com/2019/02/01/architecture-driven-taxonomy-for-ssi-agents/ (You already have)
2. IoT things are mentioned but non-fungible entities (NFEs) aka Things are not ...can create an implication in most readers minds that things are excluded. Please mention Things or NFEs wherever IoT things are mentioned - 2 places?
3. [Essential Characteristics] In the Lightweight Agent scenario (https://hyperonomy.files.wordpress.com/2019/02/hbb-ssi-agents-v0.4.png), bullet 2 doesn't apply. #sorry
4. [Canonical Examples] Can you give each of these scenarios a name? e.g. in order, Full Function Agent, Relay Agent, Advanced Function Agent.
5. [How Agents Talk] I know the goal is to stay somewhat high-level but my first question when I read this section is how does one discover how to setup and initiate a conversion? A sentence is needed in this section. [The steps are described near the end of the General Patterns section ...we just need a sentence earlier about discoverability.]
6. [General Patterns] Please add subsections for each pattern so that github will create hyperlinks for each pattern.
7. Change "ralized" to "realized" in https://github.com/hyperledger/indy-hipe/blob/8388429d437f99378b7d72aff9a36d78aa9db5c0/text/0002-agents/README.md#by-location
8. Change "has to talk" to "have to talk" in https://github.com/hyperledger/indy-hipe/blob/8388429d437f99378b7d72aff9a36d78aa9db5c0/text/0002-agents/README.md#the-agent-ness-continuum
9. and "speaks" to "talks" in the same section
10. Smile. Great job!

[dhh1128]

@mwherman2000 : Thanks for the detailed comment. I have addressed the items as follows:

2: Agreed. Adjusted verbiage. I am not using the term "NFE", but I have used "thing" in its broader sense and given examples, and I have stopped being so IoT-centric.
3: You can't participate in the agent ecosystem without keys. It is a universal requirement. You can hold a key without a wallet (e.g., in a config file). This is how static agents were defined. You can't get so lightweight that you don't use keys. An entity that doesn't hold keys can call an agent to get its work done, but is not in and of itself an agent.
4. I am very reluctant to apply an authoritative name, because there are several valid ways to name them. However, I changed the scenarios to be numbered, and then added a paragraph discussing appropriate names for each one. See what you think.
5. Agreed. Added some sentences about discoverability and connection in the middle of "How Agents Talk".
6. Done. Good idea.
7. Done.
8. Done.
9. Done.

[swcurran]

Awesome document with great writing. It's technically helpful and correct, and the style and writing is extremely accessible.

I'm a little worried that for it's intended audience - a developer wanting to get started on developing SSI code - the Reference section raises way more question than it answers. There are a ton of very subtle points raised in that section that could overwhelm someone new, and I don't think help a new developer. Perhaps replace it with a link to another document with a note - "yes, there be dragons, and once you know enough, this will help you".

I would consider adding some more to the general patterns section, focusing specifically on the two scenarios - Alice's agents and Faber's issuing agent.

• how agents connect - person to person, person to enterprise
• pairwise DIDs and where the ledger comes into play - always a question from new devs
• how Alice's two agents work together
• a bit more on how a Faber issuer might behave - this is partially covered but nice to have separated
• message families/protocols

Adding those in the same style would be awesome. Great work!

[mwherman2000]

@dhh1128, unpacking your reply to 3...

You can't participate in the agent ecosystem without keys. It is a universal requirement.

Agree ...for self-sovereign identities ...but this document is specifically about agents, characteristics of agents, and type of agents.

You can hold a key without a wallet (e.g., in a config file). This is how static agents were defined.

Agree. Updated https://hyperonomy.com/2019/02/01/architecture-driven-taxonomy-for-ssi-agents/ to reflect this. Missed the small print at the top of the Complexity diagram in the document.

You can't get so lightweight that you don't use keys.

Agree ...for self-sovereign identities ...but this document is specifically about agents, characteristics of agents, and type of agents (repeated from above).

An entity that doesn't hold keys can call an agent to get its work done, but is not in and of itself an agent.

[What do you mean, specifically, by entity?]

Disagree ... and this is an important distinction for developers/builders. Lightweight apps/clients/nodes typically have no local state (or virtually no local state). In the context of the SSI Lightweight Agent, I'm assuming this to be true as well ...that the Lightweight Agent has no local state: no local wallet and no local configuration state (related specifically to the management of identities). Lightweight Agents rely on a Cloud-located Agent for its wallet functionality. @dhh1128 I think we differ on this. ...here's v0.5 of the chart (significantly improved because of your comments related to point 3).

Reference: https://hyperonomy.com/2019/02/01/architecture-driven-taxonomy-for-ssi-agents/

Thoughts? Feedback?

[dhh1128]

@swcurran Agreed. I will move the "here be dragons" stuff into a separate doc.

[dhh1128]

@mwherman2000 The Indy community has chosen to define an agent using the 3 characteristics that I listed. This is not controversial; it has been settled for a long time. We know that "agent" has other definitions in other circles; in the intelligence community, they think about James Bond when they hear that word. In Archimate, there may be a different definition as well. But this is an SSI ecosystem, not a general-purpose enterprise software ecosystem. This is why an early paragraph of the doc says When we use the term "agent" in the SSI community, we more properly mean "an agent of self-sovereign identity." This means something more specific than just a "user agent" or a "software agent."

The reason why we chose our definition is that cryptographic keys are central to many constructs in the ecosystem. Keys are the unit of control and delegation for DIDs. They are also the unit of revocation for cred defs and agents. They are the unit of addressing and encryption when a message is packaged for one or more destinations. Keys govern credential issuance. Keys are the unit of signing. We want agents to align with these constructs, not span them in unhelpful ways.

Agents can't prove they hold delegated authority (my characteristic #1) without keys. So if you say that keys are not a defining characteristic of agents, you also eliminate delegation as a formally programmable/testable property. Furthermore, non-key-holding entitites can't participate in protocols either (except as an unknowable, invisible, unidentifiable entity fronted by something that does have keys), since all protocols depend on knowable participants, and knowable participants depend on encryption, which requires keys. So without keys, you can't have characteristic 3, either.

An app that doesn't hold keys cannot be held accountable for its own actions as a discrete participant in A2A interactions. An unaccountable piece of software is one that cannot be certified to comply with a trust framework and cannot be audited (e.g., to show that it generated a proof or sent a message). From A2A's perspective, it isn't a participant in interactions at the level of the protocol.

There is NO problem with building software that doesn't hold keys. Such software can add tons of business value and can act on the digital landscape. I'm sure there will be lots of stuff that works that way. But that stuff won't be an agent. We can't call it that, without completely reinventing a mental model that has huge momentum.

The thing you are calling a lightweight agent on a mobile device, I would call a tool or app or UI, but only half of an agent in the sense that our ecosystem expects. The agent is the combination of the front end on mobile, and the back end on cloud; together it exposes one discrete interaction surface to other participants, and its boundaries do not have to match hardware boundaries.

Static agents, which you placed in the "lightweight" bucket, DO hold keys. They just hold a statically configured set of them, and they don't negotiate new relationships. It is the staticness that defines them, not lack of keys.

[mwherman2000]

@dhh1128 Apologies for triggering a lengthy reply. Based on your reply, what do you think of this?

[mwherman2000]

Idea/Suggestion for re-crafting the Complexities section: After working through various versions of the above model, I'm wondering if it makes sense to craft the Complexity section using a Capabilities based model. For example, the list of capabilities that an Agent can assume might include:

• UsesLocalWallet or HasLocalWallet

• UsesLocalConfig

• UsesLocalLedger

• IsRelay

• IsMediatorAgent

• EdgeLocated

• CloudLocated

etc. etc. etc.

[dhh1128]

@mwherman2000 Yes, I think that new diagram is great. The only things I would change are:

1. I think client apps could have local config. Not a local wallet, but local config.
2. I don't think relays have to be agents, because they don't need keys. Mediators are agents, but relays either could be or could not be.

[mwherman2000]

1. I think client apps could have local config. Not a local wallet, but local config.

I was envisioning Client Apps to be the front-end thingy in your first reply @dhh1128 : "The agent is the combination of the front end on mobile, and the back end on cloud; together it exposes one discrete interaction surface to other participants, and its boundaries do not have to match hardware boundaries."