Building Your First Agent

This guide walks you through building your first ARAL-compliant agent from scratch. By the end, you’ll have a working agent that follows the ARAL Core specification.

Prerequisites

Before you begin, make sure you have:

Basic understanding of the 7-layer architecture
Development environment set up (Python 3.10+ or Node.js 18+)
Familiarity with JSON schemas
Access to an LLM API (OpenAI, Anthropic, or local model)

Project Setup

Create Project Directory

mkdir my-first-aral-agent
cd my-first-aral-agent

Initialize Project

For Python:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install aral-sdk anthropic

For Node.js:

npm init -y
npm install @aral/sdk anthropic

Create Configuration

Create agent.config.json:

{
  "agent_id": "my-first-agent",
  "version": "0.1.0",
  "runtime": {
    "max_memory_mb": 256,
    "max_cpu_percent": 50,
    "shutdown_timeout_ms": 10000
  }
}

Layer 1: Runtime

Set up the runtime layer to manage your agent’s lifecycle.

from aral import ARALAgent, RuntimeConfig

# Configure runtime
runtime = RuntimeConfig(
    agent_id="my-first-agent",
    version="0.1.0",
    max_memory_mb=256,
    health_check_port=8080
)

# Initialize agent
agent = ARALAgent(runtime=runtime)

# Start health check endpoint
agent.start_health_endpoint()

Layer 2: Memory

Add memory capabilities for context management.

from aral import MemoryLayer

# Initialize memory
memory = MemoryLayer(
    max_size_mb=100,
    ttl_seconds=3600,
    eviction_policy="lru"
)

# Add memory to agent
agent.set_memory(memory)

# Store context
memory.store({
    "type": "short_term",
    "content": {"user_preference": "concise responses"},
    "ttl_seconds": 3600
})

Layer 3: Capabilities

Define the actions your agent can perform.

from aral import Capability

# Define a simple capability
search_capability = Capability(
    id="web_search",
    name="Web Search",
    description="Search the web for information",
    input_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        },
        "required": ["query"]
    },
    permissions=["network:read"],
    handler=search_handler  # Your implementation
)

# Register capability
agent.register_capability(search_capability)

Layer 4: Reasoning

Configure the reasoning layer with your LLM.

from aral import ReasoningLayer
from anthropic import Anthropic

# Initialize LLM client
llm_client = Anthropic(api_key="your-api-key")

# Configure reasoning
reasoning = ReasoningLayer(
    llm_client=llm_client,
    model="claude-3-sonnet-20240229",
    max_reasoning_depth=3,
    temperature=0.7
)

# Set reasoning layer
agent.set_reasoning(reasoning)

Layer 5: Persona

Define your agent’s identity and constraints.

{
  "id": "persona-my-first-agent",
  "name": "Helpful Assistant",
  "role": "assistant",
  "version": "1.0.0",
  "constraints": {
    "allowed_capabilities": ["web_search", "calculate"],
    "denied_capabilities": [],
    "max_reasoning_depth": 3,
    "require_confirmation": []
  },
  "personality": {
    "tone": "friendly",
    "verbosity": "concise"
  }
}

from aral import Persona

# Load persona
persona = Persona.from_file("persona.json")

# Validate and set persona
agent.set_persona(persona)

Complete Agent

Here’s the complete agent code:

from aral import ARALAgent, RuntimeConfig, MemoryLayer, Capability, ReasoningLayer, Persona
from anthropic import Anthropic

# 1. Runtime
runtime = RuntimeConfig(
    agent_id="my-first-agent",
    version="0.1.0",
    max_memory_mb=256
)
agent = ARALAgent(runtime=runtime)

# 2. Memory
memory = MemoryLayer(max_size_mb=100, ttl_seconds=3600)
agent.set_memory(memory)

# 3. Capabilities
def search_handler(params):
    query = params["query"]
    # Your search implementation
    return {"results": [...]}

search_cap = Capability(
    id="web_search",
    name="Web Search",
    input_schema={"type": "object", "properties": {"query": {"type": "string"}}},
    permissions=["network:read"],
    handler=search_handler
)
agent.register_capability(search_cap)

# 4. Reasoning
llm = Anthropic(api_key="your-api-key")
reasoning = ReasoningLayer(llm_client=llm, model="claude-3-sonnet-20240229")
agent.set_reasoning(reasoning)

# 5. Persona
persona = Persona.from_file("persona.json")
agent.set_persona(persona)

# Start agent
if __name__ == "__main__":
    agent.start()

Running Your Agent

Start the agent
Terminal window
```
python agent.py
```
Check health
Terminal window
```
curl http://localhost:8080/health
```

Send a request

curl -X POST http://localhost:8080/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": "Search for ARAL documentation"}'

Testing

Verify your agent follows ARAL requirements:

# Install test suite
pip install aral-test-harness

# Run conformance tests
aral-test --agent-url http://localhost:8080 --profile CORE

Next Steps

Implement CORE Profile

Learn about ARAL-CORE conformance

Add More Capabilities

Explore custom capabilities

Multi-Agent Systems

Build orchestrated agents

Production Deployment

Read the specification

Troubleshooting

Agent Won’t Start

Check that all required fields in RuntimeConfig are set
Verify persona file is valid JSON
Ensure ports (8080, 9090) are available

Health Check Fails

Confirm agent is running: ps aux | grep python
Check logs for errors: tail -f agent.log
Verify health endpoint is enabled

Capability Not Working

Check input schema validation
Verify permissions are declared
Test handler function independently