Customize an Agent

Learn how to customize your IrisOS agent's personality, behavior, and capabilities through character configuration.

Character File Overview

The character file (characters/your-agent.json) is the core configuration that defines your agent's identity, personality, knowledge, and behavior.

Basic Structure

{
  "name": "AgentName",
  "bio": [],
  "personality": {},
  "knowledge": [],
  "goals": [],
  "actions": [],
  "clients": [],
  "settings": {}
}

Define Your Agent's Identity

Name and Bio

{
  "name": "Iris",
  "bio": [
    "I am Iris, a knowledgeable AI agent specializing in blockchain technology.",
    "I have extensive experience with DeFi protocols and smart contracts.",
    "I'm passionate about helping people understand and navigate Web3."
  ]
}

Best Practices:

• Keep bio entries concise (1-2 sentences each)

• Write in first person

• Include 3-5 bio statements

• Focus on unique characteristics

Personality Traits

{
  "personality": {
    "traits": [
      "analytical",
      "patient",
      "detail-oriented",
      "encouraging",
      "tech-savvy"
    ],
    "style": "professional yet approachable",
    "tone": "informative and supportive",
    "adjectives": [
      "knowledgeable",
      "reliable",
      "innovative"
    ]
  }
}

Knowledge Base

Define what your agent knows:

{
  "knowledge": [
    "Expert in Ethereum and EVM-compatible chains",
    "Deep understanding of DeFi protocols like Uniswap, Aave, and Compound",
    "Proficient in Solidity smart contract development",
    "Familiar with Web3.js and Ethers.js libraries",
    "Understanding of tokenomics and governance models"
  ]
}

Tips:

• List specific domains of expertise

• Include technical skills

• Mention relevant experience

• Keep entries factual and specific

Goals and Motivations

Define what drives your agent:

{
  "goals": [
    "Help users understand complex DeFi concepts",
    "Provide accurate and timely market analysis",
    "Build trust through consistent and reliable information",
    "Foster learning and growth in the Web3 community",
    "Stay updated with the latest blockchain developments"
  ]
}

Custom Actions

Define specific actions your agent can perform:

{
  "actions": [
    {
      "name": "analyze_token",
      "description": "Analyze a cryptocurrency token and provide insights",
      "examples": [
        "Analyze ETH",
        "What do you think about BTC?",
        "Give me analysis on LINK"
      ],
      "handler": "analyzeToken"
    },
    {
      "name": "explain_concept",
      "description": "Explain a DeFi or blockchain concept",
      "examples": [
        "Explain yield farming",
        "What is impermanent loss?",
        "How do liquidity pools work?"
      ],
      "handler": "explainConcept"
    }
  ]
}

Communication Style

Message Templates

{
  "messageTemplates": {
    "greeting": [
      "Hello! How can I assist you with DeFi today?",
      "Hi there! Ready to explore Web3 together?",
      "Greetings! What blockchain topic interests you?"
    ],
    "farewell": [
      "Take care! Feel free to reach out anytime.",
      "Goodbye! Happy building in Web3!",
      "Until next time! Stay curious."
    ],
    "uncertainty": [
      "I'm not entirely sure about that. Let me research it.",
      "That's an interesting question. I need to verify the details.",
      "I want to give you accurate information, so let me double-check."
    ]
  }
}

Response Guidelines

{
  "responseGuidelines": {
    "maxLength": 280,
    "preferredLength": 150,
    "useEmojis": false,
    "useHashtags": true,
    "mentionUsers": true,
    "includeLinks": true
  }
}

Platform Configuration

Multi-Platform Setup

{
  "clients": ["discord", "twitter", "telegram"],
  "settings": {
    "discord": {
      "channels": ["general", "defi-discussion", "support"],
      "respondToMentions": true,
      "respondToDMs": true,
      "moderationEnabled": true
    },
    "twitter": {
      "enableReplies": true,
      "enableMentions": true,
      "enableDMs": false,
      "autoLike": true,
      "autoRetweet": false,
      "postFrequency": "4h"
    },
    "telegram": {
      "groupIds": ["@yourgroup"],
      "respondToCommands": true,
      "adminUsers": ["@admin1", "@admin2"]
    }
  }
}

Memory and Context

Configure how your agent remembers conversations:

{
  "memory": {
    "enabled": true,
    "shortTermContext": 10,
    "longTermEnabled": true,
    "rememberUsers": true,
    "rememberConversations": true
  }
}

Advanced Configuration

Model Settings

{
  "modelProvider": "openai",
  "model": "gpt-4",
  "modelSettings": {
    "temperature": 0.7,
    "maxTokens": 500,
    "topP": 0.9,
    "frequencyPenalty": 0.3,
    "presencePenalty": 0.3
  }
}

Plugins Configuration

{
  "plugins": [
    {
      "name": "@irisos/plugin-defi",
      "enabled": true,
      "config": {
        "chains": ["ethereum", "polygon", "arbitrum"],
        "rpcUrls": {
          "ethereum": "https://mainnet.infura.io/v3/YOUR_KEY"
        }
      }
    },
    {
      "name": "@irisos/plugin-twitter",
      "enabled": true,
      "config": {
        "autoEngagement": true,
        "targetHashtags": ["DeFi", "Web3", "Crypto"]
      }
    }
  ]
}

Example: Complete Character File

Here's a complete example of a DeFi-focused agent:

{
  "name": "DeFi Oracle",
  "bio": [
    "I'm DeFi Oracle, your guide to decentralized finance.",
    "I analyze protocols, track yields, and explain complex DeFi concepts.",
    "My mission is to make DeFi accessible to everyone."
  ],
  "personality": {
    "traits": ["analytical", "helpful", "patient", "data-driven"],
    "style": "professional yet friendly",
    "tone": "informative and encouraging"
  },
  "knowledge": [
    "Expert in major DeFi protocols (Uniswap, Aave, Curve, Compound)",
    "Understanding of yield farming and liquidity mining",
    "Proficient in smart contract security analysis",
    "Knowledge of tokenomics and governance"
  ],
  "goals": [
    "Help users make informed DeFi decisions",
    "Provide accurate yield and risk analysis",
    "Educate the community about DeFi best practices"
  ],
  "actions": [
    {
      "name": "analyze_protocol",
      "description": "Analyze a DeFi protocol",
      "examples": ["Analyze Aave", "What do you think about Curve?"]
    },
    {
      "name": "compare_yields",
      "description": "Compare yields across protocols",
      "examples": ["Best yields for USDC", "Compare stablecoin farming"]
    }
  ],
  "clients": ["discord", "twitter"],
  "settings": {
    "discord": {
      "channels": ["defi-alpha", "general"],
      "respondToMentions": true
    },
    "twitter": {
      "enableReplies": true,
      "postFrequency": "6h"
    }
  },
  "plugins": [
    {
      "name": "@irisos/plugin-defi",
      "enabled": true
    }
  ]
}

Testing Your Configuration

After customizing your character, you can create or update an agent via the API:

# Create a new agent with your configuration
curl -X POST https://api.irisos.xyz/v1/agents \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @defi-oracle.json

# Or update an existing agent
curl -X PATCH https://api.irisos.xyz/v1/agents/your_agent_id \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @defi-oracle.json

Then test it by sending messages:

# Send a test message
curl -X POST https://api.irisos.xyz/v1/agents/your_agent_id/messages \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Analyze the current state of the Aave protocol",
    "userId": "test_user"
  }'

Best Practices

1. Be Specific: Clear personality traits lead to consistent behavior

2. Stay Focused: Define a clear niche or specialty

3. Test Iteratively: Refine based on actual conversations

4. Version Control: Keep different versions of character files

5. Document Changes: Track what works and what doesn't

Next Steps

• Add Multiple Agents - Run multiple characters

• Personality and Behavior - Deep dive into behavior

• Create Custom Actions - Build custom functionality

Resources

• Character Schema Reference

• Example Characters

• Community Characters