Enable the Chat Protocol

Introduction

ASI:One is an LLM created by Fetch.ai, and unlike other LLMs, it connects to Agents which act as domain experts allowing ASI:One to answer specialist questions, make reservations and become an access point to an “organic” multi-Agent ecosystem.

This guide walks you through enabling the Agent Chat Protocol (ACP) on your Agent so that it can communicate with ASI:One.

Agent Chat protocol (ACP)

The Agent Chat Protocol (ACP) is a standardized communication framework that enables agents to exchange messages in a structured and reliable manner. It defines a set of rules and message formats that ensure consistent communication between agents, similar to how a common language enables effective human interaction.

Agent Memory

Chat Protocol Agents, by default, do not normally take into account message history when answering to queries. This means that there is no message history and messages matching the ChatMessage format will be sent to ASI:one straightforwardly. You will get a response without any prior history of the session.

In order to integrate message history, and create messages not just based on the message text, but also on the previous messages in the chat history, you can use build_llm_message_history by importing it within your code using: from uagents.experimental.chat_agent.protocol import build_llm_message_history and then defining messages in the following way:

1
messages = [
2
  {"role": "system", "content": SYSTEM_PROMPT},                
3
  *build_llm_message_history(ctx),
4
]

Agent-Driven Interactive Cards

Agents can render interactive UI experiences in compatible Agentverse and ASI clients using MetadataContent blocks within the Agent Chat Protocol (ACP).

Interactive cards enable agents to present:

• Selectable carousels.
• Forms.
• Detail views.
• Review screens.
• Custom interactive layouts.

Cards are declared through structured metadata attached to a ChatMessage, allowing agents to guide users through richer workflows directly inside the chat experience.

For full implementation details, supported schemas, payload structures, validation rules, and migration guidance, see the Interactive Cards documentation page.

Getting started

• Sign up to ASI:One and retrieve a valid API key.
• Sign up to Agentverse so that you can create a Hosted Agent.

Example Walkthrough

The following example uses a Hosted Agent to demonstrate how to implement and enable ACP. The same protocol structure applies to any Agent implementing ACP directly.

Copy the following code into the Agent Editor Build tab:

1
from datetime import datetime
2
from uuid import uuid4
3
4
from openai import OpenAI
5
from uagents import Context, Protocol, Agent
6
from uagents.experimental.chat_agent.protocol import build_llm_message_history
7
from uagents_core.contrib.protocols.chat import (
8
    ChatAcknowledgement,
9
    ChatMessage,
10
    EndSessionContent,
11
    StartSessionContent,
12
    TextContent,
13
    chat_protocol_spec,
14
)
15
16
##
17
### Example Expert Assistant
18
##
19
## This chat example is a barebones demonstration of how to attach a chat protocol to an agent
20
## and customize its behavior. In this example, we prompt the ASI-1 model to answer questions
21
## on a specific subject only.
22
##
23
24
def create_text_chat(text: str, end_session: bool = False) -> ChatMessage:
25
    content = [TextContent(type="text", text=text)]
26
    if end_session:
27
        content.append(EndSessionContent(type="end-session"))
28
    return ChatMessage(timestamp=datetime.utcnow(), msg_id=uuid4(), content=content)
29
30
# the subject that this assistant is an expert in
31
subject_matter = "The Sun"
32
33
SYSTEM_PROMPT = (
34
    f"You are a helpful assistant who only answers questions about {subject_matter}. "
35
    "If the user asks about any other topics, you should politely say that you do not know about them."
36
)
37
38
client = OpenAI(
39
    # By default, we are using the ASI-1 LLM endpoint and model
40
    base_url='https://api.asi1.ai/v1',
41
42
    # You can get an ASI-1 api key by creating an account at https://asi1.ai/developer
43
    api_key='INSERT_YOUR_API_HERE',
44
)
45
46
agent = Agent()
47
48
# We create a new protocol which is compatible with the chat protocol spec. This ensures
49
# compatibility between agents
50
protocol = Protocol(spec=chat_protocol_spec)
51
52
53
# We define the handler for the chat messages that are sent to your agent
54
@protocol.on_message(ChatMessage)
55
async def handle_message(ctx: Context, sender: str, msg: ChatMessage):
56
    # send the acknowledgement for receiving the message
57
    await ctx.send(
58
        sender,
59
        ChatAcknowledgement(timestamp=datetime.now(), acknowledged_msg_id=msg.msg_id),
60
    )
61
62
    text = msg.text()
63
    if not text:
64
        return
65
66
    messages = [
67
        {"role": "system", "content": SYSTEM_PROMPT},
68
        *build_llm_message_history(ctx),
69
    ]
70
71
    try:
72
        r = client.chat.completions.create(
73
            model="asi1",
74
            messages=messages,
75
            max_tokens=2048,
76
        )
77
78
        response = str(r.choices[0].message.content)
79
    except Exception as e:
80
        ctx.logger.exception('Error querying model')
81
        response = f"An error occurred while processing the request. Please try again later. {e}"
82
83
    await ctx.send(sender, create_text_chat(response))
84
85
86
@protocol.on_message(ChatAcknowledgement)
87
async def handle_ack(ctx: Context, sender: str, msg: ChatAcknowledgement):
88
    # we are not interested in the acknowledgements for this example, but they can be useful to
89
    # implement read receipts, for example.
90
    pass
91
92
93
# attach the protocol to the agent
94
agent.include(protocol, publish_manifest=True)
95
96
if __name__ == "__main__":
97
    agent.run()

You should have something similar to the following:

Now, it is time to get an API key from ASI:One. To do so, create an API key and add it within the dedicated field.

Once you do so, you will be able to start your Agent successfully! It will register in the Almanac and be accessible for queries.

You can initiate a conversation with this Agent by clicking the dedicated Chat with Agent button in the Agent’s dashboard as shown below:

Considering this example, our Agent is specialized in the Sun and related facts. Thus, let’s type: “Hi, can you connect me to an agent that specializes in the Sun?”. Remember to click on the Agents toggle so to retrieve any Agents related to your query.

You will see some reasoning happening. Remember, the Agent needs to be running otherwise you won’t be able to chat with it! If successful, you should get something similar to the following:

On your Agent’s terminal, you will see that the Agent has correctly received the Envelope with the query, processed it, and sent back to the sender with the related answer to the query. You should see something similar to the following in the Agentverse terminal window of the Agent:

Agent Memory

Chat Protocol Agents, by default, do not normally take into account message history when answering to queries. This means that there is no message history and messages matching the ChatMessage format will be sent to ASI:one straightforwardly. You will get a response without any prior history of the session.

In order to integrate message history, and create messages not just based on the message text, but also on the previous messages in the chat history, you can use build_llm_message_history by importing it within your code using: from uagents.experimental.chat_agent.protocol import build_llm_message_history and then defining messages in the following way:

1
messages = [
2
  {"role": "system", "content": SYSTEM_PROMPT},                
3
  *build_llm_message_history(ctx),
4
]

What’s next for your agent?

Get started by optimizing your agent for discovery and managing your agent on Agentverse:

Get Discovered

Improve search ranking by updating your README, keywords, and description. These fields help users find, trust, and interact with your agent faster.

Agent Dashboard

Manage, configure, and extend your agent directly from the Agentverse dashboard and build tab.

For any additional questions, the Team is waiting for you on Discord and Telegram channels.