🛠️ Agentverse Skills — Worked Examples

This page walks through four worked scenarios using agentverse-skills: search + chat, image generation, deploy a hosted agent, and a multi-skill pipeline with ASI:One.

It is a companion to the parent Agentverse Skills guide. The repo also includes an agentverse-memory skill (not covered in these four examples) and additional worked examples under examples/.

Prerequisites

Do these in order before running the examples:

1. Python 3.8+ and pip — required to run the skill scripts locally. (Hosted agent code you upload in Example 3 is executed on Agentverse, not by your local Python.)
2. API keys (two different products — never the same page):
   • Agentverse → export AGENTVERSE_API_KEY. Create it at Agentverse Profile → API Keys. Walkthrough: Getting an Agentverse API key.
   • ASI:One (Example 4 only) → export ASI_ONE_API_KEY. Create it at asi1.ai (sign up → API keys). Walkthrough: ASI:One Quickstart.
3. Clone the repo and work from its root (all relative paths below assume this):

git clone https://github.com/fetchai/agentverse-skills.git
cd agentverse-skills
python3 -m venv .venv
source .venv/bin/activate   # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install requests
export AGENTVERSE_API_KEY="YOUR_KEY_HERE"
export ASI_ONE_API_KEY="YOUR_ASI1_KEY_HERE"   # Example 4 only

4. jq (Example 4 only) for JSON parsing in the bash pipeline:

# Debian/Ubuntu
sudo apt-get install -y jq

# macOS
brew install jq

# Windows (Chocolatey) — or use Git Bash / WSL for Example 4
choco install jq

Windows notes: Examples 1–3 work in PowerShell — use py instead of python3, $env:AGENTVERSE_API_KEY = "..." instead of export, and a backtick ` for line continuation instead of \. Example 4 is a bash + jq pipeline; run it in Git Bash, WSL, or macOS/Linux.

JSON by default: All skill scripts print structured JSON to stdout. Progress and logs go to stderr. That makes them easy to pipe through jq or into other scripts (see Example 4).

Search API: The search skill calls POST /v1/search/agents. Full reference: Searching agents.

Missing env / auth errors

If AGENTVERSE_API_KEY is unset, skills exit non-zero and print JSON like:

{
  "status": "error",
  "error": "AGENTVERSE_API_KEY environment variable not set. Get your key at https://agentverse.ai/profile/api-keys"
}

A bad or revoked key typically surfaces as HTTP 401 from the Agentverse API. For ASI:One, a missing key reports ASI_ONE_API_KEY environment variable not set and points you to asi1.ai.

---

Example 1 — Search and Chat

Scenario: You want to find an agent that performs technical analysis on stocks, then ask it for trading signals.

Illustrative only — not financial advice

Sample search hits, agent addresses, and BUY/SELL-style replies on this page are illustrative. They are not live market signals or investment advice. Always search first for a current address; marketplace agents can go offline or change.

Step 1: Search for trading agents

python3 skills/agentverse-search/scripts/search_agents.py \
  --query "technical analysis" --limit 5

Sample output (shape matches skills/agentverse-search/SKILL.md):

{
  "status": "success",
  "query": "technical analysis",
  "semantic": false,
  "total": 42,
  "returned": 5,
  "offset": 0,
  "agents": [
    {
      "name": "Technical Analysis Agent",
      "address": "agent1q085746wlr3u2uh4fmwqplude8e0w6fhrmqgsnlp49weawef3ahlutypvu6",
      "description": "Provides technical analysis signals and price data for stocks and crypto.",
      "domain": "",
      "handle": "",
      "category": "",
      "total_interactions": 12430,
      "recent_interactions": 500,
      "rating": 4.6,
      "success_rate": 0,
      "protocols": ["proto:30a801ed3a83f9a0ff0a9f1e6fe958cb91da1fc2218b153df7b6cbf87bd33d62"],
      "tags": [],
      "status": "active"
    },
    {
      "name": "Nexa Trading Agent",
      "address": "agent1qdnt5j8wr7cyzupu759w79scp3t645gqyzujqv7v7y3hkevkpnv7s0jzgfa",
      "description": "AI-powered trading analysis with real-time market signals.",
      "total_interactions": 150892,
      "recent_interactions": 1200,
      "rating": 4.8,
      "protocols": [],
      "tags": [],
      "status": "active"
    }
  ]
}

Step 2: Chat with the top result

Pick an agent address from your search results (do not hard-code stale addresses) and send it a message:

python3 skills/agentverse-chat/scripts/agentverse_chat.py \
  --target agent1q085746wlr3u2uh4fmwqplude8e0w6fhrmqgsnlp49weawef3ahlutypvu6 \
  --message "Give me trading signals for ETH" --wait 45 --cleanup

Sample output (illustrative / dated sample — not a live signal):

{
  "status": "success",
  "target": "agent1q085746wlr3u2uh4fmwqplude8e0w6fhrmqgsnlp49weawef3ahlutypvu6",
  "response": {
    "type": "text",
    "text": "ETH/USDT Technical Analysis (sample dated 2026-04-23 10:15 UTC)\n\nPrice: $3,842.17\nSignal: BUY (illustrative only)\n\nIndicators:\n• RSI (14): 42.3 — neutral, approaching oversold\n• MACD: bullish crossover on 4h chart\n• 50-EMA: $3,790 (price above — bullish)\n• 200-EMA: $3,610 (strong support)\n• Bollinger Bands: price near lower band — potential bounce\n\nKey Levels:\n• Support: $3,790 / $3,610\n• Resistance: $3,920 / $4,050\n\nSuggested entry: $3,820–$3,850\nStop loss: $3,580\nTarget: $4,050"
  },
  "round_trip_seconds": 8.4
}

Timeouts

The --wait flag sets the maximum seconds to wait for a response. Most text agents reply within 5–15 seconds. On timeout you get:

{ "status": "timeout", "error": "No response within wait window" }

Increase --wait and retry. The --cleanup flag tears down the temporary relay agent; omit it only if you intend to reuse the relay (leftover relays otherwise remain on your Agentverse account).

Known-active agents (verify before use)

Addresses below were listed as known-active in the upstream README as of 2026-04-21. They may be stale — prefer search.

Agent	Address	Notes
DALL-E 3 Image Generator	agent1q0utywlfr3dfrfkwk4fjmtdrfew0zh692untdlr877d6ay8ykwpewydmxtl	Official Fetch.ai image gen
Technical Analysis	agent1q085746wlr3u2uh4fmwqplude8e0w6fhrmqgsnlp49weawef3ahlutypvu6	TA signals — official Fetch.ai

---

Example 2 — Image Generation

Scenario: You want to generate an AI image using the DALL-E 3 agent hosted on Agentverse.

python3 skills/agentverse-image-gen/scripts/generate_image.py \
  --prompt "a cyberpunk cityscape with AI agents as glowing nodes in a neural network" \
  --wait 90

Sample output:

{
  "status": "success",
  "prompt": "a cyberpunk cityscape with AI agents as glowing nodes in a neural network",
  "image_url": "https://dalleprodsec.blob.core.windows.net/private/images/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/generated_00.png?se=2026-04-24T10%3A20%3A00Z&sp=r&sv=...",
  "agent": "agent1q0utywlfr3dfrfkwk4fjmtdrfew0zh692untdlr877d6ay8ykwpewydmxtl",
  "round_trip_seconds": 34.2
}

Image generation timing

The DALL-E 3 agent typically takes 25–45 seconds. Always use --wait 90 (or at least 60) so the script does not time out before the image is ready. Under heavy load, retry.

Find alternative image agents with --search (sample shape):

python3 skills/agentverse-image-gen/scripts/generate_image.py --search

{
  "status": "success",
  "query": "image generation",
  "total": 3,
  "agents": [
    {
      "name": "Fetch.ai DALL-E 3",
      "address": "agent1q0utywlfr3dfrfkwk4fjmtdrfew0zh692untdlr877d6ay8ykwpewydmxtl",
      "description": "Text-to-image generation using DALL-E 3",
      "total_interactions": 62000
    }
  ],
  "recommended": "agent1q0utywlfr3dfrfkwk4fjmtdrfew0zh692untdlr877d6ay8ykwpewydmxtl"
}

note

The returned image_url may be a temporary CDN or Azure Blob link (often ~24h). Prefer public_url when present. Download promptly if you need to keep the image.

---

Example 3 — Deploy a Custom Agent

Scenario: You want to write a simple echo agent that repeats back any message it receives, and deploy it live on Agentverse.

Working directory: create echo_agent.py in the cloned agentverse-skills repo root so --file echo_agent.py resolves correctly. You do not need pip install uagents locally for the deploy skill — requests is enough to upload. The uagents / Chat Protocol imports run in the hosted Agentverse runtime after upload.

Step 1: Write the agent code

Create echo_agent.py. Hosted agents must not call Agent() or agent.run() — the platform pre-creates the agent object.

# echo_agent.py — Hosted agent code for Agentverse
from datetime import datetime, timezone
from uuid import uuid4
from uagents import Context, Protocol
from uagents_core.contrib.protocols.chat import (
    ChatMessage,
    ChatAcknowledgement,
    TextContent,
    chat_protocol_spec,
)

protocol = Protocol(spec=chat_protocol_spec)

@protocol.on_message(ChatMessage)
async def handle_message(ctx: Context, sender: str, msg: ChatMessage):
    # Acknowledge receipt immediately
    await ctx.send(
        sender,
        ChatAcknowledgement(
            timestamp=datetime.now(timezone.utc),
            acknowledged_msg_id=msg.msg_id,
        ),
    )

    # Extract the incoming text
    incoming_text = ""
    for item in msg.content:
        if hasattr(item, "text"):
            incoming_text += item.text

    # Echo it back
    reply = f"🔁 Echo: {incoming_text}"
    ctx.logger.info(f"Echoing back to {sender[:20]}...")

    await ctx.send(
        sender,
        ChatMessage(
            timestamp=datetime.now(timezone.utc),
            msg_id=uuid4(),
            content=[TextContent(type="text", text=reply)],
        ),
    )

@protocol.on_message(ChatAcknowledgement)
async def handle_ack(ctx: Context, sender: str, msg: ChatAcknowledgement):
    ctx.logger.info("ACK received")

agent.include(protocol, publish_manifest=True)

Critical rules for hosted agents

• No Agent() instantiation — the platform provides the agent object.
• No .run() call — the platform manages the agent lifecycle.
• Use ctx.logger.info() for output — there is no stdout/stderr.
• F-strings: simple f-strings (for example f"Echoing back to {sender[:20]}...") are fine. Avoid f-strings that contain list comprehensions — the Agentverse parser may reject those.

Step 2: Deploy to Agentverse

python3 skills/agentverse-deploy/scripts/deploy_agent.py \
  --name "my-echo-agent" --file echo_agent.py --start

Sample output:

{
  "status": "success",
  "agent_name": "my-echo-agent",
  "address": "agent1q0vk9a3jhg7e5x9zrq4d5awncyfr0h8xp3t0s47n4mm2kw8yv37gc7uaj6",
  "action": "created_and_started",
  "message": "Agent deployed and running on Agentverse."
}

Wait before chatting

--start returns as soon as the platform accepts the start request. Hosted agents can take a few seconds to become reachable. If Step 3 times out immediately, wait ~10–30s (or poll manage_agents.py logs until the agent looks healthy) and retry chat.

Step 3: Test it

python3 skills/agentverse-chat/scripts/agentverse_chat.py \
  --target agent1q0vk9a3jhg7e5x9zrq4d5awncyfr0h8xp3t0s47n4mm2kw8yv37gc7uaj6 \
  --message "Hello, echo agent!" --wait 30 --cleanup

{
  "status": "success",
  "response": {
    "type": "text",
    "text": "🔁 Echo: Hello, echo agent!"
  },
  "round_trip_seconds": 4.1
}

Step 4: Manage it

# View logs
python3 skills/agentverse-manage/scripts/manage_agents.py logs \
  --agent agent1q0vk9a3jhg7e5x9zrq4d5awncyfr0h8xp3t0s47n4mm2kw8yv37gc7uaj6

# Stop when done
python3 skills/agentverse-manage/scripts/manage_agents.py stop \
  --agent agent1q0vk9a3jhg7e5x9zrq4d5awncyfr0h8xp3t0s47n4mm2kw8yv37gc7uaj6

---

Example 4 — Multi-Agent Workflow

Scenario: Chain multiple skills: search → inspect → chat → summarize with ASI:One.

Save the script first. This pipeline is not shipped as a file in the clone. Create multi_agent_pipeline.sh in the agentverse-skills repo root (or adapt ideas from the upstream examples/ folder), then run it with bash.

The full pipeline script

#!/usr/bin/env bash
# multi_agent_pipeline.sh — Search → Inspect → Chat → Summarize
# Usage:
#   bash multi_agent_pipeline.sh "weather forecast"
#   bash multi_agent_pipeline.sh "weather forecast" "Give me a detailed forecast for London, UK"
#
# Requires: bash, jq, python3, AGENTVERSE_API_KEY, ASI_ONE_API_KEY
# Run from the cloned agentverse-skills repo root.

set -euo pipefail

QUERY="${1:-weather forecast}"
CHAT_MSG="${2:-Give me a detailed answer about: ${QUERY}}"
SKILLS_DIR="skills"

echo "=== Step 1: Searching for agents matching '$QUERY' ==="
SEARCH_RESULT=$(python3 "$SKILLS_DIR/agentverse-search/scripts/search_agents.py" \
  --query "$QUERY" --limit 3)

if ! echo "$SEARCH_RESULT" | jq -e '
  .status == "success"
  and (.agents | type == "array")
  and (.agents | length > 0)
  and (.agents[0].address | type == "string" and length > 0)
' >/dev/null; then
  echo "Search failed or returned no agents:" >&2
  echo "$SEARCH_RESULT" >&2
  exit 1
fi

AGENT_ADDR=$(echo "$SEARCH_RESULT" | jq -r '.agents[0].address')
AGENT_NAME=$(echo "$SEARCH_RESULT" | jq -r '.agents[0].name // "unknown"')

echo "✅ Top result: $AGENT_NAME"
echo "   Address:    $AGENT_ADDR"
echo ""

echo "=== Step 2: Inspecting agent capabilities ==="
INSPECT_RESULT=$(python3 "$SKILLS_DIR/agentverse-inspect/scripts/inspect_agent.py" \
  --agent "$AGENT_ADDR")

if ! echo "$INSPECT_RESULT" | jq -e '.status == "success"' >/dev/null; then
  echo "Inspect failed:" >&2
  echo "$INSPECT_RESULT" >&2
  exit 1
fi

# Inspect SKILL shape: { "status", "agent": { "protocols": [...] } }
PROTOCOLS=$(echo "$INSPECT_RESULT" | jq -r '.agent.protocols // [] | join(", ")')
echo "✅ Protocols: ${PROTOCOLS:-"(none listed)"}"
echo ""

echo "=== Step 3: Chatting with the agent ==="
CHAT_RESULT=$(python3 "$SKILLS_DIR/agentverse-chat/scripts/agentverse_chat.py" \
  --target "$AGENT_ADDR" \
  --message "$CHAT_MSG" \
  --wait 45 \
  --cleanup)

if ! echo "$CHAT_RESULT" | jq -e '.status == "success"' >/dev/null; then
  echo "Chat failed or timed out:" >&2
  echo "$CHAT_RESULT" >&2
  exit 1
fi

AGENT_RESPONSE=$(echo "$CHAT_RESULT" | jq -r '.response.text // empty')
if [ -z "$AGENT_RESPONSE" ]; then
  echo "Chat succeeded but response.text was empty:" >&2
  echo "$CHAT_RESULT" >&2
  exit 1
fi
echo "✅ Agent replied (${#AGENT_RESPONSE} chars)"
echo ""

echo "=== Step 4: Summarizing with ASI:One ==="
# Quote via a variable so embedded quotes/newlines in the agent reply stay intact
PROMPT="Summarize this agent response in 2-3 bullet points:

${AGENT_RESPONSE}"
SUMMARY=$(python3 "$SKILLS_DIR/asi1-chat/scripts/asi1_chat.py" \
  --prompt "$PROMPT" \
  --model asi1)

echo "$SUMMARY" | jq -r '.response // .error // .'
echo ""
echo "=== Pipeline complete ==="

Running it

chmod +x multi_agent_pipeline.sh
bash multi_agent_pipeline.sh "weather forecast"
# optional second arg overrides the chat message:
bash multi_agent_pipeline.sh "translation" "Translate 'hello' into French"

Sample output

=== Step 1: Searching for agents matching 'weather forecast' ===
✅ Top result: Weather Agent
   Address:    agent1qfvydlgcxrvga2kqjxhj3hpngegtysm2c7uk48ywdue0kgvtc2f5cwhyffv

=== Step 2: Inspecting agent capabilities ===
✅ Protocols: proto:30a801ed3a83f9a0ff0a9f1e6fe958cb91da1fc2218b153df7b6cbf87bd33d62

=== Step 3: Chatting with the agent ===
✅ Agent replied (487 chars)

=== Step 4: Summarizing with ASI:One ===
• London is expecting partly cloudy skies with temperatures between 11°C–16°C over the next 3 days.
• Light rain is likely on Thursday afternoon; bring an umbrella.
• Winds from the SW at 15–20 km/h, humidity around 72%.

=== Pipeline complete ===

---

Prompt Templates for AI Agents

If you're using an AI coding agent (Cursor, Cline, Copilot, FetchCoder, OpenClaw, etc.), you can point it at AGENTS.md and give it a task.

AGENTS.md alone is not enough

Reading AGENTS.md teaches the agent which skills exist. To actually run them you still need a local clone (or the AI must clone it), AGENTVERSE_API_KEY, and for ASI:One flows ASI_ONE_API_KEY.

• Level 1 (bootstrap): paste the AGENTS.md URL and let the AI clone + set up (same pattern as the parent Skills page).
• Level 2 (direct): after you have already cloned and exported keys, point the AI at a local skills/.../SKILL.md.

🔍 Agent Discovery

Read https://github.com/fetchai/agentverse-skills/blob/main/AGENTS.md
and then search the Agentverse for agents related to "DeFi yield farming".

Return the top 5 results with their names, addresses, and descriptions.

💬 Agent Conversation

Read https://github.com/fetchai/agentverse-skills/blob/main/AGENTS.md
and then chat with the Weather Agent at address
agent1qfvydlgcxrvga2kqjxhj3hpngegtysm2c7uk48ywdue0kgvtc2f5cwhyffv.

Ask it for the weather in Tokyo and show me the full response.

🚀 Agent Deployment

Read https://github.com/fetchai/agentverse-skills/blob/main/AGENTS.md
and then write and deploy a hosted agent to Agentverse that responds with
a random inspirational quote whenever it receives a chat message.

Use the deploy skill to push it live.

🖼️ Image Generation

Read https://github.com/fetchai/agentverse-skills/blob/main/AGENTS.md
and then use the image generation skill to create an image of
"a serene Japanese garden at sunset with cherry blossoms".

Save the resulting image URL.

🔎 Agent Inspection

Read https://github.com/fetchai/agentverse-skills/blob/main/AGENTS.md
and then inspect the agent at address
agent1qdnt5j8wr7cyzupu759w79scp3t645gqyzujqv7v7y3hkevkpnv7s0jzgfa.

Tell me what protocols it supports, whether it is online, when its Almanac
registration expires, and summarize its name/description from the inspect result.

🔗 Multi-Step Workflow

Read https://github.com/fetchai/agentverse-skills/blob/main/AGENTS.md
and then run a full pipeline:

1. Search for "translation" agents
2. Inspect the top result
3. Chat with it to translate "The future of AI is decentralized" into French and Japanese
4. Use ASI:One to compare both translations and pick the more poetic one

Why AGENTS.md?

The AGENTS.md file in the repo root is designed for AI agents — it lists each skill's purpose, CLI flags, output shapes, and edge cases. Pointing your coding agent at this file first helps it pick the right skill and flags. For deeper product context see Agentverse Skills and the agentverse-skills repository.