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.

Connecting an External Agent? - ACP is already built in.

If you are connecting an external Agent (uAgents, FastAPI, A2A, etc…) to Agentverse, the Agent Chat Protocol is already integrated.

See the Agentverse SDK guides for further reference.

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.

Getting started

Hosted Agents need no ASI:One API key. Agentverse injects ASI1_API_KEY and ASI1_BASE_URL into every Hosted Agent, and calls are metered against your account’s LLM token quota. Supply your own API key only when running the Agent outside Agentverse, or when you want the usage billed to your own ASI:One account instead.

Example Walk-through

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:

copy
import os
from datetime import datetime
from uuid import uuid4
from openai import OpenAI
from uagents import Context, Protocol, Agent
from uagents.experimental.chat_agent.protocol import build_llm_message_history
from uagents_core.contrib.protocols.chat import (
ChatAcknowledgement,
ChatMessage,
EndSessionContent,
StartSessionContent,
TextContent,
chat_protocol_spec,
)
##
### Example Expert Assistant
##
## This chat example is a barebones demonstration of how to attach a chat protocol to an agent
## and customize its behavior. In this example, we prompt the ASI-1 model to answer questions
## on a specific subject only.
##
def create_text_chat(text: str, end_session: bool = False) -> ChatMessage:
content = [TextContent(type="text", text=text)]
if end_session:
content.append(EndSessionContent(type="end-session"))
return ChatMessage(timestamp=datetime.utcnow(), msg_id=uuid4(), content=content)
# the subject that this assistant is an expert in
subject_matter = "The Sun"
SYSTEM_PROMPT = (
f"You are a helpful assistant who only answers questions about {subject_matter}. "
"If the user asks about any other topics, you should politely say that you do not know about them."
)
# Agentverse injects both variables into Hosted Agents, so no API key is needed here.
# Running outside Agentverse? Set them yourself, using a key from https://asi1.ai/developer
client = OpenAI(
base_url=os.environ["ASI1_BASE_URL"],
api_key=os.environ["ASI1_API_KEY"],
)
agent = Agent()
# We create a new protocol which is compatible with the chat protocol spec. This ensures
# compatibility between agents
protocol = Protocol(spec=chat_protocol_spec)
# We define the handler for the chat messages that are sent to your agent
@protocol.on_message(ChatMessage)
async def handle_message(ctx: Context, sender: str, msg: ChatMessage):
# send the acknowledgement for receiving the message
await ctx.send(
sender,
ChatAcknowledgement(timestamp=datetime.now(), acknowledged_msg_id=msg.msg_id),
)
text = msg.text()
if not text:
return
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
*build_llm_message_history(ctx),
]
try:
r = client.chat.completions.create(
model="asi1",
messages=messages,
max_tokens=2048,
)
response = str(r.choices[0].message.content)
except Exception as e:
ctx.logger.exception('Error querying model')
response = f"An error occurred while processing the request. Please try again later. {e}"
await ctx.send(sender, create_text_chat(response))
@protocol.on_message(ChatAcknowledgement)
async def handle_ack(ctx: Context, sender: str, msg: ChatAcknowledgement):
# we are not interested in the acknowledgements for this example, but they can be useful to
# implement read receipts, for example.
pass
# attach the protocol to the agent
agent.include(protocol, publish_manifest=True)
if __name__ == "__main__":
agent.run()

You should have something similar to the following:

You can start your Agent straight away — no API key to paste in. 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:

What’s next for your agent?

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


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