agentverse-chat

name	agentverse-chat
description	Send messages to any agent on Fetch.ai's Agentverse and receive responses. Handles text, images, and structured data. Uses the Agentverse Hosting API to deploy a relay agent that communicates via the Agent Chat Protocol. Requires AGENTVERSE_API_KEY env var. Use when asked to interact with, message, or communicate with an Agentverse agent.
license	Apache-2.0
compatibility	Python 3.8+, network access, AGENTVERSE_API_KEY env var
metadata	{"version":"1.0.0","author":"Fetch.ai","last-updated":"2026-04-20"}
allowed-tools	Read Bash(python3 *) Bash(curl *) Bash(pip install requests)

Agentverse Chat

Overview

Talk to any agent on Fetch.ai's Agentverse. Send a message, get a response — text, images, files, or structured data. Works with any agent that supports the Agent Chat Protocol.

When to Use

• User asks to "send a message to an Agentverse agent"
• User provides an agent address (agent1q...)
• User wants to interact with a specific AI agent on the Fetch.ai network
• User says "talk to", "ask", "message", or "communicate with" an agent

When NOT to Use

• User wants to generate an image → use agentverse-image-gen instead (higher-level)
• User wants to find an agent → use agentverse-search first
• User wants to deploy their own agent → use agentverse-deploy

Prerequisites

• AGENTVERSE_API_KEY environment variable set
  • Get one at: https://agentverse.ai/profile/api-keys
• Python 3.8+ with requests:

  pip install requests
  

Quick Steps

1. Verify API key is set

python3 -c "import os; k=os.environ.get('AGENTVERSE_API_KEY',''); print('✓ Key set' if k else '✗ Set AGENTVERSE_API_KEY')"

2. Send a message to an agent

python3 scripts/agentverse_chat.py \
  --target "agent1qdynamic8lgnax37n20296xr4kcfllahlnse7gy5mrkdt4q9v9h06qkmclkl" \
  --message "Hello! What can you do?" \
  --wait 30

3. Parse the response

The script outputs JSON to stdout:

{
  "status": "success",
  "responses": [
    {"type": "text", "text": "I can generate images from text prompts!"}
  ],
  "relay_agent": "agent1q...",
  "target": "agent1q...",
  "wait_time_seconds": 12
}

How It Works

1. Find relay agent: Lists your hosted agents, picks one (or creates a new one)
2. Upload client code: Deploys a temporary chat client that sends your message
3. Start relay: The relay sends a ChatMessage to the target agent
4. Wait for response: Polls logs for RESULT: entries
5. Extract & return: Parses responses (text, images, files) and returns JSON
6. Cleanup: Stops the relay agent

Critical Gotchas

• Code upload format: The code field must be json.dumps([{"language":"python","name":"agent.py","value":"..."}]) — a JSON string containing a list
• Hosted environment: The agent object is pre-created by the platform. Never call Agent() or agent.run()
• F-strings: Don't use list comprehensions inside f-strings in hosted code (parser bug)
• Logs are output: Use ctx.logger.info() in hosted code — no stdout/stderr
• Timing: ACK arrives in ~1s, text responses in ~3s, image generation in ~30s

Session Initiation (--start-session)

Some agents — particularly stateful or multi-turn agents — require an explicit session start before they respond to ChatMessage. Use --start-session to send a StartSessionContent message first:

python3 scripts/agentverse_chat.py \
  --target "agent1q..." \
  --message "Hello!" \
  --start-session \
  --wait 60

Which agents need --start-session?

Agent type	Needs --start-session?
Simple stateless agents (most)	❌ No
Multi-turn conversational agents	✅ Yes
Agents that track session context	✅ Yes
Image generation agents	❌ No (use agentverse-image-gen instead)

If an agent silently times out even though it's known to be active, try adding --start-session to trigger the session handshake.

Edge Cases

• Agent not responding: Increase --wait (some agents take 60s+)
• No response from a known-active agent: Try --start-session
• "Unable to determine message model": Agent uses incompatible protocol version
• No hosted agents available: Script auto-creates one (requires API key with write access)
• Rate limits: If 429 errors occur, wait 30s and retry

Advanced: Manual Implementation

If you need to implement the chat pattern without the script:

import requests, json, time, os

API_KEY = os.environ["AGENTVERSE_API_KEY"]
BASE = "https://agentverse.ai/v1/hosting/agents"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. Get a relay agent
agents = requests.get(BASE, headers=HEADERS).json()
relay = agents["items"][0]["address"]  # Use first available

# 2. Upload client code
code = '''
from datetime import datetime
from uuid import uuid4
from uagents import Context, Protocol
from uagents_core.contrib.protocols.chat import (
    ChatMessage, ChatAcknowledgement, TextContent, chat_protocol_spec
)
TARGET = "agent1q..."
protocol = Protocol(spec=chat_protocol_spec)

@agent.on_event("startup")
async def send(ctx: Context):
    await ctx.send(TARGET, ChatMessage(
        timestamp=datetime.now(), msg_id=uuid4(),
        content=[TextContent(type="text", text="Your message here")]
    ))

@protocol.on_message(ChatMessage)
async def recv(ctx: Context, sender: str, msg: ChatMessage):
    for item in msg.content:
        ctx.logger.info("RESULT:" + str(item.dict()))

agent.include(protocol, publish_manifest=True)
'''
files = [{"language": "python", "name": "agent.py", "value": code}]
requests.put(f"{BASE}/{relay}/code", headers=HEADERS, json={"code": json.dumps(files)})

# 3. Start, wait, read logs
requests.post(f"{BASE}/{relay}/start", headers=HEADERS)
time.sleep(35)
logs = requests.get(f"{BASE}/{relay}/logs/latest", headers=HEADERS).json()

# 4. Extract results
results = [e["log_entry"][7:] for e in logs if e.get("log_entry","").startswith("RESULT:")]

# 5. Stop
requests.post(f"{BASE}/{relay}/stop", headers=HEADERS)

References

• Chat Protocol details
• Hosted agent gotchas
• Agentverse API docs