🤖 AI & Agents

Overview

AetherShell integrates AI capabilities at the language level, enabling:

• 🤖 AI Agents - Autonomous task execution with tool access
• 🔄 Multi-Agent Systems - Coordinated agent workflows
• 📡 AgenticBinary Protocol - Efficient inter-agent communication
• 🎨 Multi-Modal Support - Images, audio, video processing
• 🌐 Model URIs - Unified interface to AI providers

AI Model URIs

Supported Providers

Environment Setup

# Set default AI provider
export AETHER_AI=openai

# OpenAI API key
export OPENAI_API_KEY=sk-...

# Ollama (local models)
ollama pull llama3

Single Agent Execution

Basic Agent

// Deploy agent with goal and allowed tools
result = agent(
    "Count all Rust source files in src/",
    "ls,find",    // Whitelisted commands
    5             // Max iterations
)
print(result)

Agent with Tool Restrictions

// Whitelist specific tools for security
export AGENT_ALLOW_CMDS=ls,cat,grep,find

// Agent can only use allowed tools
analysis = agent(
    "Find all TODO comments in the codebase",
    "grep,find",
    10
)

Agent Workflow

AgenticBinary Protocol

Protocol Overview

A compact binary protocol designed for efficient agent-to-agent communication. 3-5x more compact than JSON.

Message Types

Semantic Opcodes (16 total)

Encoding Messages

// Encode a PING command
ping = ab_encode("command", "ping", "hello")
// Returns: [0, 5, 104, 101, 108, 108, 111]
//   Header: 0 (version=0, type=command, opcode=PING)
//   Payload: varint(5) + "hello"

// Encode ACK response
ack = ab_encode("response", "ack", "received")

// Encode DELEGATE command
task = ab_encode("command", "delegate", "analyze_data")

// Encode DATA response
result = ab_encode("response", "data", "complete")

Decoding Messages

// Receive binary message
bytes = [0, 5, 104, 101, 108, 108, 111]

// Decode to structured format
msg = ab_decode(bytes)

print(msg.msg_type)  // "Command"
print(msg.opcode)    // "PING"
print(msg.payload)   // "hello"

Multi-Agent Coordination

Agent Roles

Coordination Example

// Phase 1: Workers learn protocol
spec = syntax_get("ab")
worker1_msg = ab_encode("command", "learn", spec.specification)
worker2_msg = ab_encode("command", "learn", spec.specification)

// Phase 2: Workers signal ready
worker1_ready = ab_encode("response", "ack", "worker1:ready")
worker2_ready = ab_encode("response", "ack", "worker2:ready")

// Phase 3: Coordinator delegates tasks
task1 = ab_encode("command", "delegate", "worker1:analyze_logs")
task2 = ab_encode("command", "delegate", "worker2:process_data")

// Phase 4: Workers execute
exec1 = ab_encode("command", "exec", "started:log_analysis")
exec2 = ab_encode("command", "exec", "started:data_processing")

// Phase 5: Workers collaborate (if needed)
collab = ab_encode("command", "collaborate", "worker2:need_log_data")

// Phase 6: Workers report results
result1 = ab_encode("response", "data", "complete:analysis.json")
result2 = ab_encode("response", "data", "complete:processed.json")

// Phase 7: Coordinator reflects
reflection = ab_encode("command", "reflect", "efficiency:95%")

Communication Patterns

Multi-Modal AI

Supported Modalities

Multi-Modal Examples (Future API)

// Analyze image
// image_data = cat("photo.jpg")
// result = ai_analyze(image_data, "Describe this image")

// Transcribe audio
// audio = cat("recording.mp3")
// transcript = ai_transcribe(audio)

// Generate image from text
// image = ai_generate("A futuristic cityscape at sunset")
// save(image, "output.png")

Model Context Protocol (MCP)

MCP Integration

AetherShell supports the Model Context Protocol for standardized AI tool integration.

MCP Functions

// List available MCP servers
servers = mcp_servers()
print(servers)

// Detect MCP servers in directory
detected = mcp_detect("./tools")

// Cache management
mcp_cache_clear()
status = mcp_cache_status()

MCP Server Discovery

// Scan workspace for MCP tools
tools = mcp_detect(".")

// Connect to specific server
// connection = mcp_connect("filesystem-server")

// Call tool through MCP
// result = mcp_call(connection, "read_file", {path: "data.txt"})

Best Practices

Security

Performance

• 🔹 Use AgenticBinary for frequent agent communication (3-5x compression)
• 🔹 Cache Syntax KB entries to reduce lookups
• 🔹 Batch agent tasks when possible to reduce API calls
• 🔹 Prefer local models (Ollama) for low-latency operations

Error Handling

// Check agent result status
result = agent("Task description", "ls,find", 5)

if type_of(result) == "Record" && result.status == "error" {
    print("Agent failed: ${result.message}")
    // Retry or fallback logic
} else {
    print("Success: ${result}")
}

Complete Multi-Agent Example

See examples/13_agent_coordination.ae for a full 10-phase workflow with:

• ✅ 4 agents (Coordinator + 3 Workers)
• ✅ 17 messages exchanged
• ✅ All major opcodes demonstrated
• ✅ Task delegation, collaboration, learning
• ✅ Error handling and recovery
• ✅ Final reflection and metrics

# Run the example
ae examples/13_agent_coordination.ae