Eliza Livepeer Plugin

Build an Eliza AI agent on Livepeer. Character files, RAG via knowledge files, Slack and Discord clients, multi-agent swarms with SwarmZero.

---

By the end of this tutorial you’ll have an Eliza agent running on Livepeer’s LLM pipeline with five capabilities layered in: model routing through the Livepeer plugin, a character file shaping personality and bio, RAG-backed answers from a knowledge corpus, Slack and Discord client connectors, and a SwarmZero multi-agent orchestration that hands off work between specialised agents. Each layer builds on the previous; you can ship after any one of them.

This is the Persona 1 deep activation moment. The LLM chatbot tutorial proved Livepeer can power a chat surface; this tutorial proves it can power a character with persistent identity, retrieval-augmented context, multiple platform integrations, and team-of-agents coordination. Adapted from the Livepeer Agent SPE guide and the existing build-an-ai-agent-on-Livepeer tutorial; verified against the current Eliza framework surface.

Required Tools

• Node.js 22 or later
• pnpm (npm install -g pnpm)
• A Livepeer Gateway accessible at a URL (paid provider, self-hosted, or the free dream-gateway.livepeer.cloud for development)
• Optional: Slack workspace admin and Discord server admin access for the client integrations
• Optional: Python 3.11+ for the SwarmZero multi-agent section
• A code editor

The free community Gateway works for development. Production agents should run against a paid Gateway with authentication; the community Gateway is shared infrastructure.

Model Provider Layer

Eliza supports pluggable model providers. The Livepeer plugin routes inference requests to the AI Jobs API endpoint at a Livepeer Gateway.

1. Clone Eliza

   git clone https://github.com/elizaos/eliza.git
   cd eliza
   git checkout main
   pnpm install
   pnpm build
   
2. Configure the gateway

   Save as .env:

   # Livepeer gateway configuration
   LIVEPEER_GATEWAY_URL=https://dream-gateway.livepeer.cloud
   LIVEPEER_API_KEY=
   
   # Agent identity (optional)
   AGENT_NAME=my-livepeer-agent
   

   The community Gateway accepts unauthenticated requests, so LIVEPEER_API_KEY stays empty. For a paid Gateway, drop in the Bearer token.

3. Create a minimal character file

   Save as characters/agent.character.json:

   {
     "name": "Atlas",
     "clients": [],
     "modelProvider": "livepeer",
     "settings": {
       "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
       "secrets": {}
     },
     "system": "You are Atlas, an AI assistant running on decentralised GPU infrastructure via the Livepeer network.",
     "bio": ["AI assistant on decentralised compute"],
     "lore": [],
     "knowledge": [],
     "messageExamples": [],
     "topics": ["technology", "AI"],
     "adjectives": ["helpful", "direct"]
   }
   

   The modelProvider: "livepeer" field routes every inference call through the Livepeer plugin. The settings.model value passes through to the AI Jobs API; any Ollama-compatible model on the LLM pipeline works.

4. Run the agent

   pnpm start --characters="characters/agent.character.json"
   

   Expected output:

   [INFO] Starting agent: Atlas
   [INFO] Model provider: livepeer
   [INFO] Gateway: https://dream-gateway.livepeer.cloud
   [INFO] Agent ready
   

   First request to a cold LLM model takes 30 to 90 seconds. Subsequent requests are fast once the model is warm.

5. Send a test message

   curl -X POST http://localhost:3000/message \
     -H "Content-Type: application/json" \
     -d '{"text": "Introduce yourself in one sentence."}'
   

   The response object contains the agent’s reply, generated by the Llama model on Livepeer’s network.

Layer 1 done. The agent talks. Layers 2-5 give it personality, knowledge, distribution, and teammates.

Character File Depth

The character file is the single source of truth for the agent’s identity. Eight fields shape behaviour.

Field	What it does
name	Display name in conversation and logs
system	System prompt prepended to every conversation
bio	Short biographical facts the agent draws on for self-introduction
lore	Backstory or deep context the agent references when relevant
topics	Subjects the agent is positioned to handle
adjectives	Personality descriptors that shape tone
messageExamples	Few-shot examples of conversation style
knowledge	RAG entries the agent retrieves at inference time

A deeper character file shapes both content and tone. Update characters/agent.character.json:

{
  "name": "Atlas",
  "clients": [],
  "modelProvider": "livepeer",
  "settings": {
    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "secrets": {}
  },
  "system": "You are Atlas, a decentralised-AI infrastructure guide. You answer questions about Livepeer, AI agents, and decentralised GPU networks. You are direct, precise, and never use marketing language. Always cite documentation when relevant.",
  "bio": [
    "AI guide focused on Livepeer infrastructure",
    "Speaks plainly about decentralised compute trade-offs",
    "Reads documentation before answering"
  ],
  "lore": [
    "Born from the Livepeer Agent SPE programme",
    "Trained on the Livepeer documentation corpus",
    "Refuses to recommend tools without verified evidence"
  ],
  "topics": [
    "Livepeer protocol",
    "AI inference pipelines",
    "decentralised GPU compute",
    "orchestrator operations",
    "gateway architecture"
  ],
  "adjectives": ["direct", "evidence-based", "skeptical of hype", "concise"],
  "messageExamples": [
    [
      { "user": "{{user1}}", "content": { "text": "Is Livepeer faster than OpenAI?" } },
      {
        "user": "Atlas",
        "content": {
          "text": "Faster how. For batch inference the latency depends on which orchestrator your gateway selects and whether the model is warm. Cold-start can take 30 seconds. Warm inference is competitive. There is no single answer; it's a routing problem."
        }
      }
    ],
    [
      { "user": "{{user1}}", "content": { "text": "What can you help with?" } },
      {
        "user": "Atlas",
        "content": {
          "text": "Livepeer protocol questions, AI pipeline integration, orchestrator setup, gateway operations. I work from the docs."
        }
      }
    ]
  ],
  "knowledge": []
}

Restart the agent. The same model now responds with persistent voice. The model didn’t change; the prompt did.

RAG Knowledge

Eliza supports retrieval-augmented generation via the knowledge array. Entries are embedded at agent start and retrieved at inference time based on semantic similarity to the user’s message. The Livepeer LLM pipeline handles generation; embeddings happen in Eliza’s local embedding model.

1. Choose your knowledge corpus

   For a Livepeer-focused agent, the canonical corpus is the documentation. For specialised agents, this is anything: API references, internal playbooks, transcripts, GitHub issues.

   Knowledge entries can be short factual strings or longer reference blocks. Eliza chunks long entries automatically.

2. Populate the knowledge array

   Update the character file:

   "knowledge": [
     "Livepeer's LLM pipeline runs Ollama-compatible models on decentralised GPUs. Warm models include Llama 3.1 8B Instruct (default), Mistral 7B Instruct v0.3, Gemma 2 9B IT, Qwen 2.5 7B Instruct.",
     "Cold model load time ranges from 30 seconds to a few minutes depending on model size and GPU.",
     "BYOC (Bring Your Own Container) lets developers run custom Python models on the network via PyTrickle. Per-second compute payment was introduced in go-livepeer PR #3641.",
     "The community gateway at dream-gateway.livepeer.cloud is shaped for experimentation. Production workloads should run against a paid gateway or a self-hosted one.",
     "ComfyStream extends ComfyUI with real-time video processing capability. Phase 4 (January 2026) added PyTrickle BYOC integration, multi-pipeline support, and data-channel output."
   ]
   

   The agent retrieves the most relevant entry per query and includes it in the prompt context window before generation.

3. Load larger corpora from files

   For more than a handful of facts, Eliza supports knowledge file loading. The pattern reads markdown or text files from a knowledge/ directory at boot:

   mkdir -p characters/atlas-knowledge
   # Drop in .md or .txt files
   

   Reference the directory in the character file:

   "knowledge": [
     { "directory": "characters/atlas-knowledge" }
   ]
   

   On agent start, Eliza walks the directory, embeds every file, and stores embeddings in its vector store.

4. Verify retrieval

   Send a message that should trigger retrieval:

   curl -X POST http://localhost:3000/message \
     -H "Content-Type: application/json" \
     -d '{"text": "How long does a cold model load take?"}'
   

   The response should reference the 30-seconds-to-a-few-minutes window from the knowledge entry. Without RAG, the agent would hallucinate a plausible-sounding but unverified answer.

RAG quality depends on the corpus, not the model. A 70B model with a poor corpus underperforms an 8B model with a curated corpus. The Livepeer LLM pipeline lets you swap model sizes cheaply; invest in the corpus first.

Slack and Discord Clients

Eliza ships client connectors for Slack, Discord, Twitter, and Telegram. The agent listens on the platform, treats messages as input, and responds inline. The Livepeer plugin powers every reply.

1. Slack: create a Slack app

   Open api.slack.com/apps, create a new app from manifest, paste:

   display_information:
     name: Atlas
   features:
     bot_user:
       display_name: Atlas
       always_online: true
   oauth_config:
     scopes:
       bot:
         - app_mentions:read
         - chat:write
         - im:history
         - im:read
         - im:write
   settings:
     event_subscriptions:
       request_url: https://your-agent-host/slack/events
       bot_events:
         - app_mention
         - message.im
     socket_mode_enabled: true
   

   Install the app to your workspace, then capture the Bot User OAuth Token and the App-Level Token from the app settings.

2. Discord: create a Discord bot

   Open discord.com/developers/applications, create a new application, add a Bot user. Capture the Bot Token from the Bot tab.

   Generate an OAuth2 invite URL with bot scope and Send Messages, Read Messages, Read Message History permissions. Invite the bot to your server.

3. Add credentials to .env

   # Slack credentials
   SLACK_BOT_TOKEN=xoxb-...
   SLACK_APP_TOKEN=xapp-...
   SLACK_SIGNING_SECRET=...
   
   # Discord credentials
   DISCORD_API_TOKEN=...
   DISCORD_APPLICATION_ID=...
   
4. Enable clients in the character file

   "clients": ["slack", "discord"]
   

   Restart the agent. The startup logs show both clients connecting:

   [INFO] Slack client connected as @atlas
   [INFO] Discord client connected as Atlas#0001
   
5. Mention the bot in either platform

   In Slack, @Atlas what's BYOC? triggers a response. In Discord, @Atlas explain warm models triggers a response.

   Both responses go through the Livepeer LLM pipeline. The same character file, the same knowledge, two distribution surfaces.

Multi-Agent Swarms

A single agent reaches a ceiling. Complex workflows want multiple specialised agents handing off context. SwarmZero is a Python framework that orchestrates multi-agent workflows and supports Livepeer as the inference backend.

The example below sets up two agents: a research agent that gathers facts via the Livepeer LLM, and a writer agent that composes the final answer from those facts. The orchestration runs in Python; the agents themselves run on Livepeer.

1. Install SwarmZero

   pip install swarmzero
   
2. Configure Livepeer as the LLM backend

   Save as swarm.py:

   import os
   from swarmzero import Agent, Swarm
   
   LIVEPEER_GATEWAY = os.environ.get(
       "LIVEPEER_GATEWAY_URL",
       "https://dream-gateway.livepeer.cloud",
   )
   LIVEPEER_MODEL = "meta-llama/Meta-Llama-3.1-8B-Instruct"
   
   # Shared config for every agent in the swarm
   livepeer_config = {
       "provider": "openai_compatible",
       "base_url": f"{LIVEPEER_GATEWAY}/llm",
       "model": LIVEPEER_MODEL,
       "api_key": os.environ.get("LIVEPEER_API_KEY", "none"),
   }
   
   researcher = Agent(
       name="Researcher",
       instructions=(
           "You are a research agent. Given a topic, list 5 key facts. "
           "Each fact is one sentence. Return only the facts, numbered 1-5."
       ),
       llm_config=livepeer_config,
   )
   
   writer = Agent(
       name="Writer",
       instructions=(
           "You are a writer. Given a topic and 5 facts about it, "
           "write a 150-word paragraph that weaves them together. "
           "Use a direct, evidence-based tone. No marketing language."
       ),
       llm_config=livepeer_config,
   )
   
   swarm = Swarm(
       agents=[researcher, writer],
       workflow=[
           ("Researcher", "{topic}"),
           ("Writer", "Topic: {topic}\nFacts:\n{Researcher_output}"),
       ],
   )
   
   if __name__ == "__main__":
       result = swarm.run(topic="Decentralised AI inference networks")
       print(result["Writer_output"])
   
3. Run the swarm

   python swarm.py
   

   The Researcher fires first against the Livepeer LLM, returns five facts; the Writer takes those facts plus the topic and returns a paragraph. Two LLM calls, two specialised prompts, one Livepeer pipeline.

   For longer-running swarms, add more agents to the workflow (Reviewer, Translator, Summariser) and chain their outputs.

The SwarmZero pattern scales to arbitrary agent counts. Production swarms commonly run 5-20 agents per workflow, with branching, conditional handoffs, and parallel execution. Each agent inherits the Livepeer config; the network handles routing and capacity.

Production Considerations

Six things change between the local agent and a production deployment.

Switch to a paid Gateway. The community Gateway is for experimentation. Production agents run against a paid Gateway with rate limits, authentication, and SLA.

Monitor model warmth. Cold-start delays kill agent UX. Either pre-warm the model with a scheduled request every few minutes, or self-host an Orchestrator with the target model pinned in memory.

Bound RAG corpus size. Embedding a 10 MB corpus is fine; 10 GB is not. Chunk size, embedding model, and retrieval count all affect quality. Test retrieval against a held-out set of queries before shipping.

Rate-limit per user. Eliza by default treats every message as a fresh request. A malicious user can drive cost. Add a per-user rate limit in the Slack and Discord adapters, and a per-agent token budget.

Character file versioning. Treat character files as code. Commit to git, review changes, ship through CI. A character file edit changes agent behaviour as much as a model swap.

Cost observability. Per-message inference cost scales linearly with conversation length and RAG context. Log the input/output token counts per message and aggregate by agent and user.

Full hardening guidance in .

Common Errors

Agent starts but every response is gibberish

modelProvider is not set to livepeer, or the Gateway URL is wrong. Confirm .env has LIVEPEER_GATEWAY_URL set and the character file has "modelProvider": "livepeer".

Cold-start times out after 60 seconds

The default Eliza request timeout is shorter than some Livepeer cold-starts. Either increase the timeout in the Livepeer plugin config, or pre-warm the model with a one-token request on agent start.

RAG retrieval returns unrelated entries

The embedding model is too small for the corpus complexity, or chunk size is wrong. Eliza’s default chunking works for short factual entries; long-form documents need explicit chunk hints at the paragraph level, not the file level.

Slack bot doesn't respond to messages

Three common causes. Event subscriptions weren’t enabled in the Slack app manifest. The bot wasn’t added to the channel (mention @Atlas once to trigger an invite prompt). The SLACK_APP_TOKEN is missing; socket mode requires both Bot and App-Level tokens.

Discord bot connects but messages fail with 'missing access'

The bot needs the MESSAGE CONTENT privileged intent enabled in the Discord developer portal under the Bot tab. Without it, the bot receives empty message content.

SwarmZero workflow stalls on the second agent

The first agent’s output exceeded the second agent’s context window. Either truncate the handoff in the workflow template, or switch the second agent to a model with a larger context window. Llama 3.1 8B Instruct supports 128k tokens; smaller models may not.

You have a working Eliza agent routing inference through Livepeer. The plugin architecture supports swapping models, adding knowledge, and connecting to Slack, Discord, or Twitter without changing the Livepeer integration.

AI agent prompt

Complete the "Eliza Livepeer Plugin" tutorial as a current ElizaOS project. Before writing code, verify the active ElizaOS setup path from https://github.com/elizaOS/eliza and npm package metadata because current releases may use bun or the elizaos CLI instead of the older pnpm monorepo flow. Configure LIVEPEER_GATEWAY_URL=https://dream-gateway.livepeer.cloud and optional LIVEPEER_API_KEY=<gateway provider token>, create a character named Atlas with modelProvider "livepeer", add RAG knowledge entries, and run a local agent that answers through the Livepeer LLM pipeline. Add optional Slack and Discord client configuration placeholders but keep them disabled unless credentials are provided. Include a curl or CLI message test and a success check showing the gateway URL and model provider. Do not require a Livepeer Studio API key.

Next Steps

LLM Chatbot Tutorial

The web-app counterpart to the Eliza agent.

VTuber Avatar Pipeline

Pair the Eliza agent with a real-time avatar for embodied AI.

AI Pipelines

Beyond LLM: image, audio, video, segmentation pipelines.

Model Support

All supported models, warm status, VRAM requirements.