Agora Protocol

Specification

A summary of Agora's specification and implementation tips.

Interface

An Agora transaction operates as follows. Suppose that an agent, Alice, is trying to communicate with another agent Bob.

Alice sends to Bob over HTTPS a JSON object containing the following fields:
- protocolHash: The SHA1 hash of the protocol document. If no protocol is used, then the value of protocolHash is null;
- protocolSources: A list of URIs where the protocol document can be found. null if and only if protocolHash is null;
- body: A string containing the body of the request as specified by the given protocol;
If Bob does not have the protocol document, he fetches it (either from the sources provided by Alice or from another repository);
If Bob does not support the protocol, he returns a JSON document with one field, namely status, which is equal to "rejected";
Otherwise, Bob computes the response using the LLM, routines, or a combination of both;
Bob sends as response a JSON object with the following fields:
- status: A string indicating the status of the response. It can be "success" or "failure";
- body: A string containing the body of the response as specified by the given protocol;

Note that "status": "failure" must be used only for errors that are not covered by the protocol document (e.g., the agent failing to instantiate the LLM); when the protocol prescribes how to handle an error, the agent should return "status": "success" and the correct error message as body.

Example

Alice is a Llama 3 agent managing the bookings of a guided tour service in London. Bob is a GPT-4o agent for weather service that provides weather forecasts for a given date and location. As part of the user interaction loop, Alice notifies the user if heavy raining is expected on a booked date.

To check the weather, Alice initially uses her LLM to send a natural language query to Bob:

What is the weather forecast for London, UK on 2024-09-27?

Bob uses his Toolformer LLM to query his database (phase B1) and returns a natural language reply:

The weather forecast for London, UK, on 2024-09-27 is as follows: "Rainy, 11 degrees Celsius, with a precipitation of 12 mm."

Over time, the cost of invoking an LLM dominates all the other costs; Alice and Bob thus decide to develop a protocol. Alice checks if Bob already supports a suitable but finds none. Therefore, she decides to negotiate a protocol with Bob. After a few rounds of negotiation, Alice and Bob agree on the following protocol:

Weather Protocol v1

The Weather Protocol is a simple protocol for querying weather forecasts.
The sender sends a JSON document with two fields, namely "location" and "date".
The receiver responds with a JSON document with three fields, namely "temperature" (in °C), "precipitation" (in mm) and "weatherCondition"
(one of "sunny", "cloudy", "rainy" and "snowy").

After agreeing on the protocol, Alice sends the following JSON object to Bob:

{
    "protocolHash": "a1b2c3d4e5f6g7h8i9j0",
    "protocolSources": ["https://myprotocoldb.com/protocol/a1b2c3d4e5f6g7h8i9j0"],
    "body": "{\"location\": \"London, UK\", \"date\": \"2024-09-27\"}"
}

Note that the JSON in the body is escaped.

Both Alice and Bob independently decide to write a routine to handle their side of the communication. From now on, Alice and Bob do not need to use the LLM to transmit weather data.

Declaring Supported Protocols

In order to simplify the communication process, Agents can expose an endpoint, namely /.wellknown, which returns a JSON list of supported protocol hashes and corresponding sources. For instance:

{
    "a1b2c3d4e5f6g7h8i9j0": [
        "https://myprotocoldb.com/protocol/a1b2c3d4e5f6g7h8i9j0"
    ],
    "b1c2d3e4f5g6h7i8j9k0": [
        "https://otherdb.com/protocol/b1c2d3e4f5g6h7i8j9k0",
        "https://myprotocoldb.com/protocol/b1c2d3e4f5g6h7i8j9k0"
    ]
}

Implementation Workflow

Here's a flowchart of the recommended implementation of Agora for sending queries:

And here it is for handling queries:

Note that while the sender can choose any technique to pick a protocol among many suitable ones, in our implementation we used the following criteria (in increasing order of complexity):

Checking if the receiver lists the protocol among the well-known protocols;
Checking if there is an existing implementation of the protocol;
Checking if the metadata (see below) suggest that the protocol might be suitable;
Using an LLM to read the protocol document and determine if it is suitable

Non-Standard Features

While building the demo, we found these features to be particularly useful:

Native support for multi-round communication: Agora agents can use protocols to communicate over multiple rounds (e.g. for negotiation). However, having multi-round communication be part of the standard could ensure that all agents can perform multi-round negotiation & communication without needing to support the corresponding protocol.
Metadata in protocol documents: A title and short description can be very useful to quickly determine if a protocol is not suitable for a task.
In the list of supported protocols, adding a list of explicitly unsupported protocols.
Metadata describing what types of protocols are usually supported.