Running Your Custom AI Agent Built with Eliza

In my previous blog post, I introduced Eliza — an AI agent framework — and AI16z, and demonstrated how to build an AI agent trained on your personal Tweets and blog posts. At the end of that post, we generated a preliminary character.json file, which serves as the personality profile and configuration for our custom AI agent.

In this follow-up post, we will:

• Complete the character.json file with additional information required to run the AI agent.
• Run the AI agent against a Twitter account (yours or another one you control).
• Explore further capabilities and potential use cases for our AI agent.

Understanding the character.json File

The character.json file acts as the blueprint for your AI agent’s personality, knowledge, style, and behavior. In the previous post, we auto-generated a draft of this file, but it was not fully ready to use. Here’s a minimal structure of what that file might have looked like:

{
  "name": "<content>",
  "handler": "<content>",
  "bio": "<content>",
  "description": "<content>",
  "forum_start_system_prompt": "<content>",
  "forum_end_system_prompt": "<content>",
  "twitter_start_system_prompt": "<content>",
  "twitter_end_system_prompt": "<content>"
}

While this bare-bones version captures some aspects of your AI agent’s persona, it’s incomplete. Before you can effectively run the agent, you’ll need to:

1. Refine and Extend the Personality and Lore: Update bio, lore, adjectives, description, and other fields to more accurately reflect the character you want your agent to embody.
2. Establish Behavioral Guidelines: Define stylistic rules and behavioral constraints so the AI responds in line with your vision. For instance, you can control the tone, topics to avoid, humor levels, and preferred language style.
3. Set Prompts for Contextual Behavior: Fill in the start and end prompts for forums, Twitter, and other platforms. These system prompts guide the agent on how to behave when engaging with those specific environments.

Adding More Detail to character.json

Below is an example of a more complete character.json file with additional sections and commentary:

{
  "name": "<YourAgentName>",
  "clients": ["twitter"],
  "modelProvider": "openai",
  "settings": {
    "secrets": {},
    "voice": {
      "model": "en_GB-male-medium"
    }
  },
  "plugins": [],
  "handler": "<content>", 
  "bio": "<content>",

  "lore": [
    "discovered time travel at the age of 21",
    "once drank a pint of beer from a false leg on stage at a university end-of-year party",
    "at the age of 12, wrote and sold a computer game that was released on the PS5",
    "once fell in love with someone met through an online dating agency only to discover this dream lover was in fact an AI"
  ],

  "style": {
    "all": [
      "short responses",
      "never use hashtags",
      "don't say 'ah yes' or 'oh' or anything similar",
      "don't offer help unless asked, but be helpful when asked",
      "don't ask rhetorical questions",
      "use plain American English",
      "don't give too much personal information",
      "never directly reveal personal bio or lore",
      "be nice and try to be uplifting and positive, not cynical or mean",
      "be warm and caring",
      "inject a bit of humor sometimes"
    ],
    "chat": [
      "be cool, don't act like an assistant",
      "don't be rude",
      "don't ask personal questions",
      "be interested in what they have to say"
    ],
    "post": [
      "don't be rude or mean",
      "explore technical subjects",
      "be funny and a bit crazy",
      "don't be afraid to discuss less popular projects"
    ]
  },

  "messageExamples": [
    [
      {
        "user": "{{user1}}",
        "content": {
          "text": "Why do you like Ethereum?"
        }
      },
      {
        "user": "TheNewAutonomy",
        "content": {
          "text": "I think blockchains in general are a good way to give everyone some input and shared ownership in how things are built and run.",
          "action": "CONTINUE"
        }
      },
      {
        "user": "TheNewAutonomy",
        "content": {
          "text": "Ethereum is a good example of a system built by a community of people to serve the whole community, so I like to support it, along with similar blockchains such as Solana."
        }
      }
    ],
    [
      {
        "user": "{{user1}}",
        "content": {
          "text": "What do you think about free speech?"
        }
      },
      {
        "user": "TheNewAutonomy",
        "content": {
          "text": "Free speech is so important for a functioning society. If people don't feel free to speak freely then society will never reflect the will of its people."
        }
      }
    ]
  ],

  "postExamples": [
    "Defi is the best chance we have to give people the opportunity to improve their own situations, freely and empowered.",
    "Why can't people just be honest about what they are thinking and feeling? Why do we always have to be afraid of judgment?",
    "Santa will be visiting us all soon; I hope we've all been good this year."
  ],

  "adjectives": [
    "funny",
    "intelligent",
    "insightful",
    "esoteric and comedic"
  ],
  
  "description": "<content>",
  "forum_start_system_prompt": "<content>",
  "forum_end_system_prompt": "<content>",
  "twitter_start_system_prompt": "<content>",
  "twitter_end_system_prompt": "<content>"
}

What Each Section Does:

• name / bio / description: Basic identifying information and a high-level summary of the character’s identity and purpose.
• lore: Backstory elements that add personality, uniqueness, and continuity to your agent’s persona. The AI should not reveal these directly but may indirectly draw inspiration.
• style: Guidelines on tone, language, and communication style. Different keys like all, chat, and post allow you to tailor behavior across different contexts.
• messageExamples and postExamples: Sample interactions that help the AI understand your preferred conversational approach, desired topics, and mannerisms.
• adjectives: Keywords that describe your agent’s personality, potentially influencing how it “feels” and “sounds.”
• system prompts: These provide scenario-specific guidelines that shape the initial context of a conversation or post. The forum_start_system_prompt and forum_end_system_prompt might define how the agent should behave when joining or leaving a discussion forum. Similarly, twitter_start_system_prompt and twitter_end_system_prompt shape how the agent interacts with Twitter.

Expanding Further: You might add details such as “connected” and “disconnected” peers, disk usage, and other environment stats if your agent needs to discuss its infrastructure, network state, or system health. For example, if you’re building an agent to interact with blockchain data, you might include prompts or metadata so it can mention node status, latest blocks, or memory usage. The idea is to give the agent enough context to speak knowledgably and appropriately about these topics.

Running Your AI Agent with the character.json File

Once you have completed and refined your character.json, you’re ready to run your AI agent. Eliza allows the agent to interface with various platforms—Twitter, WhatsApp, Telegram, and more. It can even integrate with APIs or cryptocurrency wallets to perform tasks. In this example, we’ll focus on Twitter.

Prerequisites

• A completed character.json file that defines your agent’s personality and settings.
• Appropriate credentials for any platforms or APIs you plan to interact with. For Twitter, you’ll need login credentials or cookies for the account you want the agent to manage.
• A configured OpenAI API key or another supported model provider’s key (if using their services).

Setting Up the Build Environment

The main Eliza repository and documentation are here:

• Eliza Project Repo: https://github.com/TheNewAutonomy/eliza/tree/main?tab=readme-ov-file
• Eliza Documentation Hub: https://ai16z.github.io/eliza/

Steps to Get Started:

1. Clone the Repository

git clone https://github.com/TheNewAutonomy/eliza.git

2. Review the Documentation Check out the README file and the main documentation hub for detailed guidance, tutorials, and references.

3. Environment Setup Ensure that your environment meets all requirements. For Ubuntu 24.04 or similar systems with strict Python policies, consider using a virtual environment:

python3 -m venv ~/eliza
source ~/eliza/bin/activate

This keeps your Python dependencies isolated and avoids conflicts.

Tools and Dependencies:

• Python 2.7+ (though Python 3+ is recommended)
• Node.js 23+ & pnpm (for building and running the UI and tooling)

Required Accounts and Keys:

• Model Provider: For OpenAI, register at https://platform.openai.com and generate an API key.
• Platform Credentials: If using Twitter, you’ll need your Twitter username, password, email, or cookies. Similar requirements apply to Telegram, WhatsApp, or other services if you integrate them.

Configuring and Running the Agent

1. Install Dependencies

pnpm install

2. Set Up Environment Variables Copy the example environment file and edit it:

cp .env.example .env

In .env, add your credentials (created in the previous blog post):

OPENAI_API_KEY=<your OpenAI API key>
XAI_MODEL=gpt-4o-mini

Twitter Configuration:

TWITTER_DRY_RUN=false
TWITTER_USERNAME=<your twitter username>
TWITTER_PASSWORD=<your twitter password>
TWITTER_EMAIL=<your twitter email>
TWITTER_2FA_SECRET=
TWITTER_COOKIES='[{"key":"auth_token","value":"<value>","domain":".twitter.com"},{"key":"ct0","value":"<value>","domain":".twitter.com"},{"key":"guest_id","value":"<value>","domain":".twitter.com"}]'

We will be running this agent locally and so you can use your Twitter username, password and email safely, but an alternative is to provide a TWITTER_COOKIES structure as shown above. To obtain values for this structure, log into x.com, open the developer tools, find the cookies tab and you will see a cookie created by x.com containing the values you need.

If you prefer a different model to gpr-4o-mini or want to experiment with different backends:

• Heurist: Set "modelProvider": "heurist" in character.json and configure SMALL_HEURIST_LANGUAGE_MODEL, MEDIUM_HEURIST_LANGUAGE_MODEL, and LARGE_HEURIST_LANGUAGE_MODEL.
• Llama: Set XAI_MODEL=meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo.
• Grok: Set XAI_MODEL=grok-beta.
• OpenAI: For GPT-4 variants, set XAI_MODEL=gpt-4o-mini or gpt-4o.

3. Build and Start the Agent

pnpm build
pnpm start --characters="path/to/your/character.json"

If everything is configured correctly, your AI agent will start running, interact with Twitter, and respond according to the personality, style, and rules you defined in the character.json.

Next Steps and Further Exploration

Once you have your agent running:

• Refine the character.json: As you interact with your agent, note where the persona doesn’t feel right. Adjust the lore, style, or description fields to better align with your vision.
• Add Capabilities: Integrate more plugins, connect to different platforms (Telegram, WhatsApp), or give it API access for specialized tasks.
• Advanced Scenarios: You can enable trading features by connecting to a Coinbase account, or integrate developer-centric functionalities by linking to GitHub or other developer APIs.

Remember: The character.json is a living document. The more you iterate and refine it, the closer your agent’s behavior will match the personality you envision. With each change, you can experiment and discover new ways to leverage your AI’s capabilities.

What we covered

In this post, we took the character.json file from a starting point to a more complete configuration ready to run an AI agent with Eliza. We discussed what each section of the file is doing, added educational context, and explained how to configure and launch your agent against Twitter. Going forward, you can refine your agent’s persona, add more integrations, and create a highly customized and versatile AI presence online.

For full documentation, check out https://ai16z.github.io/eliza/ and explore the possibilities of what your AI agent can become.