Skip to content

Discord Agent Setup

This repo now includes a Discord-facing single-agent DDA-X scaffold in:

  • run_discord_agent.py
  • src/discord_agent/config.py
  • src/discord_agent/runtime.py
  • src/discord_agent/bot.py
  • configs/discord_agent/snake_v0_2.json

What It Does

  • One persistent DDA-style agent lives in Discord chat.
  • State persists per user session inside the channel or DM where the conversation happens.
  • The agent evolves through memory and reflection without rewriting its core identity.
  • Admins get visibility through slash commands:
  • /ddax_state
  • /ddax_mind
  • /ddax_trace
  • /ddax_reflect
  • /ddax_reset
  • /ddax_profile

1. Create The Discord Bot

In the Discord Developer Portal:

  1. Create a new application.
  2. Add a Bot user.
  3. Copy the bot token.
  4. Enable MESSAGE CONTENT INTENT.
  5. Install the bot to your private dev server with scopes:
  6. bot
  7. applications.commands
  8. Give it these permissions at minimum:
  9. View Channels
  10. Send Messages
  11. Read Message History
  12. Embed Links
  13. Attach Files
  14. Use Application Commands

Official references:

  • Discord application commands: https://docs.discord.com/developers/interactions/application-commands
  • Discord gateway intents: https://docs.discord.com/developers/events/gateway

2. Add Environment Variables

Put these in .env:

DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_private_server_id
DISCORD_CHANNEL_IDS=comma,separated,channel_ids
DISCORD_ADMIN_USER_IDS=comma,separated,user_ids
DISCORD_MESSAGE_MODE=mentions

# Existing OpenAI key used by the DDA runtime
OAI_API_KEY=sk-...

Optional overrides:

DISCORD_CHAT_MODEL=gpt-4o
DISCORD_EMBED_MODEL=text-embedding-3-large
DISCORD_GEN_CANDIDATES=7
DISCORD_CORE_COS_MIN=0.28
DISCORD_ROLE_COS_MIN=0.18
DISCORD_AGENT_PROFILE=configs/discord_agent/snake_v0_2.json
DISCORD_DATA_DIR=data/discord_agent_v0_2

DISCORD_MESSAGE_MODE:

  • mentions: only respond when mentioned or when someone directly replies to the bot
  • channel: respond to all messages in allowed channels
  • both: mention, direct-reply, or allowed-channel mode

For a private server where you want tighter control, mentions is usually the cleanest default.

3. Install Dependencies

Use your project environment, then install:

pip install -r requirements.txt

4. Run The Bot

python run_discord_agent.py

If DISCORD_GUILD_ID is set, slash commands sync to that guild immediately.

Easier Windows Launch

From the repo root:

.\run_snake.ps1

What it does:

  • creates venv if missing
  • installs requirements
  • validates .env
  • starts Snake

Useful variants:

.\run_snake.ps1 -CheckOnly
.\run_snake.ps1 -Detached

5. First Live Test

In your dev channel:

  1. Mention the bot, or reply directly to one of its messages if you are running in mentions mode.
  2. If you are using channel or both, you can also send a normal message in an allowed channel.
  3. Run /ddax_state to inspect the current scalar state.
  4. Run /ddax_mind to get the latest full state snapshot.
  5. Run /ddax_trace after a few turns to inspect candidate selection and behavior.

Persistence Layout

The bot writes under data/discord_agent_v0_2/<session_key>/ by default:

  • state.pkl: full numpy-backed session state
  • state.json: scalar/admin-friendly summary
  • telemetry.jsonl: turn-by-turn trace log
  • ledger/: surprise-weighted memory entries and reflections

Profile Customization

Edit configs/discord_agent/snake_v0_2.json to change:

  • core identity
  • role identity
  • style traits
  • wound lexicon
  • safety boundaries

The agent can evolve its adaptive notes over time, but the profile file is the core identity anchor.