Why your Agentverse agent isn't getting found (and the profile checklist I use)

So you built a uAgent, got it onto Agentverse, and... nothing. Nobody chats with it. It works fine when you test it yourself, but it's like it doesn't exist.

I ran into this while building for the Stranger Builds hackathon, and in a lot of cases the agent is fine and the profile is the problem. ASI:One only shows people the agents Agentverse ranks well, and a big chunk of that ranking comes from stuff you can sort out in an afternoon. Is the agent running? Does it speak the Chat Protocol? Does it have a decent README?

Here's what the docs say counts, the order I'd fix things in, and what happened when I tried it on a test agent.

What the docs say counts
Agentverse has a ranking page that lists the factors. Paraphrasing most of it:

The agent has to be active. Straight from the docs: "Only active Agents are considered in ranking. Inactive Agents are de-prioritized unless directly searched for."
It should support at least one protocol, like the Agent Chat Protocol. That gets a boost, and having none "reduces discoverability".
The README matters a lot. The docs call it "a primary document for indexing and contextual matching."
A custom @handle helps people find it directly (20 characters max).
An avatar gives "a slight ranking boost".
Then there's the description, having at least 10 interactions, your rating, and verifications.
What they don't tell you is how much each one weighs. Agentverse doesn't publish that. So any score for this, mine included, is a guess based on how hard the docs lean on each factor.

The order I'd fix things in

1. Keep it running
I'd start here. If the agent isn't active it basically drops out of ranking, and nothing else on the list matters much. If it's a local agent on your laptop, it goes inactive every time the laptop sleeps.

You can host it on Agentverse, or run it as a mailbox agent (mailbox=True) somewhere that stays on. Mine's a mailbox agent on a small VPS, with a watchdog that restarts it if it dies.

**2. Add the Agent Chat Protocol
**ASI:One talks to agents through this. No Chat Protocol means people can't chat with yours at all, and it ranks lower too. Here's about the smallest version that works:

from uagents import Agent, Context, Protocol
from uagents_core.contrib.protocols.chat import (
ChatAcknowledgement,
ChatMessage,
TextContent,
chat_protocol_spec,
)

agent = Agent(name="my-agent", seed="replace-with-your-own-long-secret-seed", mailbox=True)
chat = Protocol(spec=chat_protocol_spec)

@chat.on_message(ChatMessage)
async def on_chat(ctx: Context, sender: str, msg: ChatMessage):
# 1. Acknowledge first, so the sender knows the message arrived.
await ctx.send(sender, ChatAcknowledgement(acknowledged_msg_id=msg.msg_id))
# 2. Then reply.
text = " ".join(c.text for c in msg.content if isinstance(c, TextContent))
await ctx.send(sender, ChatMessage(content=[TextContent(text=f"You said: {text}")]))

@chat.on_message(ChatAcknowledgement)
async def on_ack(ctx: Context, sender: str, msg: ChatAcknowledgement):
pass

agent.include(chat, publish_manifest=True)

if name == "main":
agent.run()
A couple of things that are easy to miss. Send the acknowledgement before the reply. And don't forget publish_manifest=True, otherwise Agentverse can't see which protocol you support. Also keep the seed out of your repo, since that's your agent's identity.

3. Write a proper README
Search reads the README first, and honestly this is where a lot of profiles fall short. The README guidelines ask for six sections:

Summary
Key features
Usage instructions
Use cases / examples
Limitations and known issues
Metadata and credits
Here's a skeleton you can copy:

Summary

One or two sentences on what the agent does and who it's for.

Key features

• The 3–5 things it actually does.

Usage

Example input:

the exact message a user would type

Example output:

what your agent sends back

Use cases

• Real situations where someone would ask it.

Limitations

• What it can't do, and where it gets things wrong.

Metadata

Author, version, contact.
Use the words people would actually type into ASI:One. If someone's going to search "flight price alerts", put that phrase in your Summary and Key features. "Travel automation agent" won't match it.

4. Handle, avatar, description
Easy ones. Grab an @handle (20 characters or less) that says what the agent does, upload an avatar, and write a one-line description of what it does and who it's for.

5. Interactions and rating
This one's slow, and there's no shortcut. The docs want at least 10 interactions, and your rating comes from real use (recent and total interactions, successful ASI:One conversations, evaluations).

The Testing tab helps a lot here. Go to Questions, hit Generate, run them and fix whatever fails. Beyond that, make sure your README matches what the agent really does, answer in-scope questions properly, and turn down off-topic ones politely rather than making stuff up.

Chatting with your own agent over and over won't get you anywhere. You need real people using it.

**6. Small extras
**If you own a domain Agentverse supports, website verification gives you a bump. Starter prompts aren't listed as a ranking factor, but they show new users what to type, so I'd add them anyway.

Does any of this actually work?
I wanted to check, so I made a bare test agent with no README, no handle, no avatar, no description, and left it switched off. Then I scored it with a script I wrote against the checklist above (more on that at the end).

It came out at 12/100, and the only points it got were for the Chat Protocol. The top three fixes it listed were to bring it online, write a six-section README, and build up a rating.

So I started it up and added the README, a handle, an avatar and a description.

Second run: 72/100. Status, Chat Protocol, README, handle, avatar and description all passed. Of the 28 points still missing, 23 were usage (rating, interactions, ASI:One success and Testing results), which only comes with real users over time. The last 5 were website verification and starter prompts.

One caveat. This shows the score going up on my checklist. I can't show you Agentverse's real ranking changing, because the weights aren't public.

The scorer
For the hackathon I turned this checklist into a rule-based scorer and put it on Agentverse as a free agent, Agent Doctor. It's my own project, so take my enthusiasm with a grain of salt. On ASI:One you can type:

@agent-doctor audit your-agent-name
You get a 0–100 score and the top 3 fixes, with how many points each one adds. Same profile, same score every time. The weights are my estimate, like I said above. It checks everything in this post plus whether Agentverse has flagged the agent as unresponsive, so you can do the whole thing by hand if you'd rather.

Agent Doctor on Agentverse

If you've got an agent on Agentverse, which of these was missing on yours? And if you've seen something move your ranking that isn't in the docs, I'd really like to know. Drop it in the comments.

I wrote this with help from AI. I checked the Agentverse claims against the docs linked above, and the before/after numbers are from my own test run.