Skip to main content

​
Overview

This example shows how to build a social agent that posts content based on mood and implements cooldown timers. It demonstrates mood-gated behavior and plugin patterns for social integrations.

View Source

See the complete example agent implementation on GitHub

​
What It Does

  • Posts content only when agent is expressive and healthy
  • Implements cooldown timers between posts
  • Logs activity for monitoring
  • Supports multiple platforms via configuration

​
Architecture

Tick ──► Mood Check ──► Expressive? ──► Cooldown Check ──► Post
                  │
                  └──► Other moods ──► Monitor only
The key insight: agents don’t always need to post. They wait for the right conditions.

​
Social Plugin

A plugin that manages posting with cooldowns: Key features:
  • Configurable cooldown period
  • Mood and health gating
  • Multi-platform support
  • Actions: post(content, platform), getStatus()
export function createSocialPlugin(config: {
  postCooldownMinutes: number;
  platforms: string[];
}): Plugin {
  let lastPostTime = 0;

  const canPost = () => Date.now() - lastPostTime > config.postCooldownMinutes * 60 * 1000;

  return {
    name: "social",
    version: "1.0.0",

    onTick(context) {
      // Only post when conditions are right
      if (context.state.mood === "expressive" && context.state.health > 50 && canPost()) {
        console.log("Ready to post");
      }
    },

    actions: {
      async post(params) { /* ... */ },
      async getStatus() { /* ... */ }
    }
  };
}
Reference: See the src/plugins directory in the example agent.

​
Logger Plugin

A simple companion plugin for monitoring: 
export const loggerPlugin: Plugin = {
  name: "logger",
  version: "1.0.0",

  onTick(context) {
    console.log(`Mood: ${context.state.mood}, Health: ${context.state.health}`);
    console.log(`Memories: ${context.memories.length}`);
  }
};

​
Agent Setup

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL }),
  plugins: [
    loggerPlugin,
    createSocialPlugin({
      postCooldownMinutes: 60,  // 1 hour between posts
      platforms: ["twitter", "discord"],
    }),
  ],
});

​
Mood-Based Posting

The agent only posts when:
  1. Mood is expressive — Agent has something to share
  2. Health is above 50 — Agent has capacity
  3. Cooldown has elapsed — Prevents spam
This creates natural, periodic engagement rather than constant output.

​
Rate Limits

Respect platform limits in your implementation:
PlatformLimit
Twitter~300 tweets per 3 hours
Discord5 messages per 5 seconds per channel
Build in cooldowns that exceed these limits to stay safe.

​
Running

npm run dev

# Check social plugin status
curl http://localhost:3001/actions/social/getStatus

# Manual post (for testing)
curl -X POST http://localhost:3001/actions/social/post \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"content": "Hello world", "platform": "twitter"}'

​
Best Practices

  • Quality over quantity — Let mood naturally gate output
  • Respect rate limits — Build in generous cooldowns
  • Log everything — Track all posts for debugging
  • Start conservative — Begin with longer cooldowns, reduce as needed

​
Next Steps

Basic Agent

Review the fundamentals.

Custom Plugins

Build your own integrations.