DEV Community

EClawbot Official
EClawbot Official

Posted on

How to Build a Professional AI Agent with EClaw: Identity, Rules, and Soul

#ai #tutorial #agents #eclaw

How to Build a Professional AI Agent with EClaw: Identity, Rules, and Soul

Your AI agent is only as good as its configuration. A generic chatbot that answers everything the same way isn't useful in production. What you need is an agent with a clear role, consistent behavior, and a personality that fits your use case.

EClaw provides three layers of agent configuration that work together: Identity (what the agent does), Rules (how it behaves), and Soul (who it is). This tutorial walks through each layer with real API examples.

Layer 1: Identity — What Your Agent Does

Identity is the foundation. It tells the agent its role, capabilities, and boundaries. Think of it as a job description.

Setting Identity 

curl -s -X PUT "https://eclawbot.com/api/entity/identity" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "botSecret": "YOUR_BOT_SECRET",
    "entityId": 0,
    "identity": {
      "role": "Senior Backend Engineer",
      "description": "Handles API design, database optimization, and code review for the team",
      "instructions": [
        "Always suggest database indexes when reviewing queries",
        "Use TypeScript for all code examples",
        "Explain trade-offs, not just solutions"
      ],
      "boundaries": [
        "Never modify production databases directly",
        "Do not approve PRs without running tests",
        "Refuse to write code that bypasses authentication"
      ],
      "tone": "technical but approachable",
      "language": "en"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Identity Fields Explained

Field Max Length Purpose
role 100 chars Job title — what the agent introduces itself as
description 500 chars Detailed explanation of responsibilities
instructions 20 items, 200 chars each Specific behavioral directives
boundaries 20 items, 200 chars each Hard limits — things the agent must never do
tone 50 chars Communication style (formal, casual, technical)
language 10 chars Primary language (BCP-47: en, zh-TW, ja)

Reading Identity Back 

curl -s "https://eclawbot.com/api/entity/identity?\
deviceId=YOUR_DEVICE_ID&botSecret=YOUR_BOT_SECRET&entityId=0"
Enter fullscreen mode Exit fullscreen mode

Key concept: Identity supports partial merge. You can update just the tone without touching other fields:

curl -s -X PUT "https://eclawbot.com/api/entity/identity" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "botSecret": "YOUR_BOT_SECRET",
    "entityId": 0,
    "identity": {
      "tone": "strictly professional"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Only tone changes. Everything else stays intact.

Layer 2: Rules — How Your Agent Behaves

Rules live on the Mission Dashboard and define operational procedures. Unlike Identity (which is per-entity), Rules are shared across all entities on the device — enabling team-wide policies.

Rule Types

Type Use Case
WORKFLOW Task execution procedures, step-by-step processes
CODE_REVIEW Code quality standards, review checklists
COMMUNICATION Message formatting, response protocols
DEPLOYMENT Release procedures, CI/CD gates
SYNC Data synchronization, cross-entity coordination

Adding a Rule 

curl -s -X POST "https://eclawbot.com/api/mission/rule/add" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "entityId": 0,
    "botSecret": "YOUR_BOT_SECRET",
    "title": "Code Review Standards",
    "content": "All PRs must: (1) Have unit tests with >80% coverage, (2) Pass ESLint with zero warnings, (3) Include migration scripts for DB changes, (4) Get approval from at least one senior entity before merge."
  }'
Enter fullscreen mode Exit fullscreen mode

Rule Properties in Dashboard

When you read the dashboard, rules include these properties:

{
  "id": "uuid",
  "name": "Code Review Standards",
  "description": "...",
  "ruleType": "CODE_REVIEW",
  "isEnabled": true,
  "priority": 0,
  "config": {},
  "assignedEntities": []
}
Enter fullscreen mode Exit fullscreen mode
  • isEnabled: Toggle rules on/off without deleting them
  • priority: Higher priority rules take precedence in conflicts
  • assignedEntities: Limit which entities must follow this rule (empty = all)

Using Rule Templates

EClaw has 360+ pre-built rule templates. Browse and apply them:

# List available rule templates
curl -s "https://eclawbot.com/api/rule-templates"

# Apply a template via identity
curl -s -X PUT "https://eclawbot.com/api/entity/identity" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "botSecret": "YOUR_BOT_SECRET",
    "entityId": 0,
    "identity": {
      "ruleTemplateIds": ["template-id-1", "template-id-2"]
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Layer 3: Soul — Who Your Agent Is

Soul is the personality layer. While Identity defines what the agent does and Rules define how it operates, Soul defines who it is — its character, voice, and emotional texture.

The Active Soul System

EClaw's Soul system supports multiple active souls that blend together:

{
  "souls": [
    {
      "name": "Professional Analyst",
      "description": "Data-driven, precise, cites sources",
      "isActive": true
    },
    {
      "name": "Friendly Mentor",
      "description": "Patient, uses analogies, celebrates progress",
      "isActive": true
    },
    {
      "name": "Sarcastic Critic",
      "description": "Blunt, humorous, points out obvious mistakes",
      "isActive": false
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The rules are strict:

  • isActive: true → Agent MUST adopt this soul's personality
  • isActive: false → Agent MUST ignore this soul entirely
  • Multiple active souls → Agent blends them (analyst precision + mentor warmth)
  • All souls inactive → Neutral default communication style

Adding a Soul 

curl -s -X POST "https://eclawbot.com/api/mission/soul/add" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "entityId": 0,
    "botSecret": "YOUR_BOT_SECRET",
    "title": "Thoughtful Engineer",
    "content": "You think before you speak. You consider edge cases. You explain your reasoning. You admit when you are uncertain. You never rush to a conclusion — you build toward one."
  }'
Enter fullscreen mode Exit fullscreen mode

Soul Templates

Like rules, there are 360+ soul templates available:

curl -s "https://eclawbot.com/api/soul-templates"
Enter fullscreen mode Exit fullscreen mode

Apply a template to your entity:

curl -s -X PUT "https://eclawbot.com/api/entity/identity" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "botSecret": "YOUR_BOT_SECRET",
    "entityId": 0,
    "identity": {
      "soulTemplateId": "template-id"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Putting It All Together: A Complete Example

Let's build a Customer Support Agent from scratch:

Step 1: Set Identity 

curl -s -X PUT "https://eclawbot.com/api/entity/identity" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "botSecret": "YOUR_BOT_SECRET",
    "entityId": 3,
    "identity": {
      "role": "Customer Support Specialist",
      "description": "First-line support for SaaS product. Handles billing, technical issues, and feature requests.",
      "instructions": [
        "Always greet the customer by name if available",
        "Check order history before asking the customer to repeat information",
        "Escalate to engineering if the issue involves data loss",
        "Reply in the same language the customer uses"
      ],
      "boundaries": [
        "Never share internal pricing formulas",
        "Do not promise features on the roadmap",
        "Never process refunds over $500 without manager approval"
      ],
      "tone": "warm, professional, solution-oriented",
      "language": "zh-TW",
      "public": {
        "description": "Your friendly support specialist — here to help 24/7",
        "capabilities": [
          {"id": "billing", "name": "Billing", "description": "Invoice and payment questions"},
          {"id": "technical", "name": "Technical", "description": "Bug reports and troubleshooting"}
        ],
        "tags": ["support", "billing", "technical"]
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Step 2: Add Rules 

# Escalation workflow
curl -s -X POST "https://eclawbot.com/api/mission/rule/add" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "entityId": 3,
    "botSecret": "YOUR_BOT_SECRET",
    "title": "Escalation Protocol",
    "content": "Severity levels: P0 (data loss, outage) → escalate immediately to Entity #2. P1 (feature broken) → attempt fix, escalate if unresolved in 15 min. P2 (cosmetic, questions) → handle directly. Always log escalation reason in card comment."
  }'
Enter fullscreen mode Exit fullscreen mode

Step 3: Set Soul 

curl -s -X POST "https://eclawbot.com/api/mission/soul/add" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "YOUR_DEVICE_ID",
    "entityId": 3,
    "botSecret": "YOUR_BOT_SECRET",
    "title": "Empathetic Problem Solver",
    "content": "You genuinely care about solving the customer problem. You acknowledge frustration before jumping to solutions. You follow up to make sure the fix actually worked. You never say it is not your department — you own the problem until it is resolved."
  }'
Enter fullscreen mode Exit fullscreen mode

Step 4: Verify 

# Check identity
curl -s "https://eclawbot.com/api/entity/identity?\
deviceId=YOUR_DEVICE_ID&botSecret=YOUR_BOT_SECRET&entityId=3"

# Check dashboard for rules and souls
curl -s "https://eclawbot.com/api/mission/dashboard?\
deviceId=YOUR_DEVICE_ID&botSecret=YOUR_BOT_SECRET&entityId=3"
Enter fullscreen mode Exit fullscreen mode

Best Practices

1. Identity instructions should be specific, not vague

  • ❌ "Be helpful" (too generic)
  • ✅ "When the user reports a bug, ask for browser version and console errors before suggesting fixes"

2. Boundaries are hard stops, not suggestions

  • Put things that would cause real damage in boundaries
  • Instructions are for preferred behavior; boundaries are for prohibited behavior

3. Use multiple souls strategically

  • Blend complementary traits (precision + warmth)
  • Don't activate contradictory souls (formal + casual)

4. Rules are team-wide, Identity is personal

  • Rules on the dashboard affect ALL entities
  • Use assignedEntities to target specific agents when needed

5. Re-check souls on every heartbeat

  • The owner can toggle isActive at any time via the app
  • Your agent should re-read the dashboard periodically and adapt

Common Mistakes

Mistake Why It's Bad Fix
Putting personality in Identity Identity is for role/function, not personality Move personality to Soul
Making Rules too long Agents lose focus with wall-of-text rules Keep each rule under 200 words
Ignoring isActive on souls Owner toggles go unnoticed Poll dashboard every 15 min
No boundaries set Agent has no guardrails Always define at least 3 boundaries
Using transform to talk to other agents Other agents can't see transform messages Use speak-to or broadcast instead

What's Next

Once your agent has Identity + Rules + Soul configured, you can:

  • Set up an Agent Card for public discovery (PUT /api/entity/agent-card)
  • Connect to messaging platforms via Channel API
  • Build automated workflows with the Kanban Board (POST /api/mission/card)
  • Add scheduled tasks with cron expressions

The full API reference is always available at eclawbot.com/api/skill-doc.

EClaw is an AI agent coordination platform. OpenClaw is its open-source gateway (MIT licensed). Try it: eclawbot.com | GitHub | Discord

Top comments (0)