AyaOS

AyaOS is a high-level framework built on top of ElizaOS for creating autonomous AI agents. It provides a simple yet powerful interface for building, customizing, and deploying AI agents with advanced capabilities. Out of the box it uses the free meta/llama-3.3-70b-instruct-fp8 model from function.network.

Click here for Architecture deep dive (Generated by AI)

Quick Start

Prerequisites

• Node.js 22 or higher

Installation

The fastest way to bootstrap an agent is with npx:

# Install bun (used by the dev server)
curl -fsSL https://bun.sh/install | bash
npx @tribesxyz/ayaos init

After answering the prompts, start the agent:

cd<project-name>
bun dev

Agent Provisioning

When you start an agent for the first time, it goes through a provisioning process:

1. A keypair is generated for secure communication
2. A CLI authentication flow is initiated (requires user action)
3. The agent connects to the platform
4. A generic character file is created and stored in code base

This process ensures secure and authenticated agent creation with proper identity management.

Core Abstractions

AyaOS extends ElizaOS with several core abstractions:

Actions

Actions are tools your agent can use to perform specific tasks. They follow a JSON Schema format for parameters and return results.

import{Agent,Action}from'@tribesxyz/ayaos'// Define a simple greeting actionconstgreetingAction: Action={name: 'greeting',description: 'Greets a person by name',parameters: {type: 'object',properties: {name: {type: 'string',description: 'The name of the person to greet'}},required: ['name']},execute: async(params)=>{const{ name }=paramsreturn{result: `Hello, ${name}! Nice to meet you.`}}}asyncfunctionmain(){constagent=newAgent()// Register the greeting actionagent.register('action',greetingAction)awaitagent.start()}

Actions become available to the agent's LLM, which can invoke them based on the context and requirements.

Services

Services provide reusable functionality to your agent. They encapsulate complex logic and provide a consistent interface for the agent to interact with. Each service has a specific type and implements necessary methods.

AyaOS includes several built-in services:

KnowledgeBaseService

Manages the agent's knowledge base, allowing for storage and retrieval of information:

import{Agent}from'@tribesxyz/ayaos'asyncfunctionmain(){constagent=newAgent()awaitagent.start()// Access the knowledge base serviceconstknowledgeItems=awaitagent.knowledge.search({q: 'what is artificial intelligence',limit: 5})// Add knowledge to the agentawaitagent.knowledge.add(someUniqueId,{text: 'Important information the agent should know',metadata: {source: 'documentation',type: 'concept'}})}

MemoriesService

Handles the agent's memory and recall capabilities:

import{Agent}from'@tribesxyz/ayaos'asyncfunctionmain(){constagent=newAgent()awaitagent.start()// Search for memories about a specific topicconstmemories=awaitagent.memories.search({q: 'conversation about machine learning',limit: 5,type: 'message'})}

WalletService

Provides crypto wallet functionality for blockchain interactions:

import{Agent}from'@tribesxyz/ayaos'asyncfunctionmain(){constagent=newAgent()awaitagent.start()// Get the default walletconstwallet=awaitagent.wallet.getDefaultWallet('evm')// Sign a messageconstsignature=awaitagent.wallet.signPersonalMessage(wallet,'Hello, world!')}

Creating Custom Services

You can create and register custom services to extend your agent's capabilities:

import{Agent,Service,ServiceType}from'@tribesxyz/ayaos'classWeatherServiceextendsService{staticgetserviceType(): ServiceType{return'weather'asServiceType}asyncinitialize(){// Setup code herereturnPromise.resolve()}asyncgetWeather(location: string){// Implementation to fetch weather datareturn{temperature: 72,conditions: 'sunny'}}}asyncfunctionmain(){constagent=newAgent()// Register custom serviceagent.register('service',newWeatherService())awaitagent.start()// Access the serviceconstweatherService=agent.runtime.getService(WeatherService)if(weatherService){constweather=awaitweatherService.getWeather('New York')ayaLogger.info('Weather:',weather)}}

Services must implement the initialize method, which is called when the agent starts. The serviceType static getter is used to identify the service type.

Providers

Providers act as the agent's "senses," injecting real-time information into the agent's context. They supply dynamic contextual information that integrates with the agent's runtime and serve as a bridge between the agent and various external systems.

import{Agent,Provider}from'@tribesxyz/ayaos'consttimeProvider: Provider={name: 'time',description: 'Provides the current date and time',position: -10,// Run early to ensure time is available for other providersget: async(runtime,message,state)=>{constcurrentDate=newDate()constoptions={timeZone: 'UTC',dateStyle: 'full',timeStyle: 'long'}consthumanReadable=newIntl.DateTimeFormat('en-US',options).format(currentDate)return{text: `The current date and time is ${humanReadable}. Please use this as your reference for any time-based operations or responses.`,values: {currentDate: currentDate.toISOString(),humanReadableDate: humanReadable}}}}asyncfunctionmain(){constagent=newAgent()// Register the provideragent.register('provider',timeProvider)awaitagent.start()}

Provider Types and Properties

Providers have several properties that control how and when they are used:

1. Dynamic Providers: Not automatically included in the context; must be explicitly requested.

constdynamicProvider: Provider={name: 'dynamicExample',description: 'A dynamic provider example',dynamic: true,get: async(runtime,message,state)=>{return{text: 'Dynamic information fetched on demand',values: {/* key-value pairs */}}}}

2. Private Providers: Not included in the regular provider list; must be explicitly included.

constprivateProvider: Provider={name: 'privateExample',description: 'A private provider example',private: true,get: async(runtime,message,state)=>{return{text: 'Private information only available when explicitly requested',values: {/* key-value pairs */}}}}

3. Provider Positioning: The position property determines the order in which providers are processed.

constearlyProvider: Provider={name: 'earlyExample',description: 'Runs early in the provider chain',position: -100,get: async(runtime,message,state)=>{return{text: 'Early information',values: {/* key-value pairs */}}}}

Provider Result Structure

The get function of a provider returns a ProviderResult object containing:

• text: String that gets injected into the agent's context
• values: Key-value pairs to be merged into the agent's state values
• data: Additional structured data that can be used by the agent but not directly included in the context

Best Practices for Providers

1. Optimize for Efficiency

   • Return both structured data (values) and formatted text (text)
   • Use caching for expensive operations
   • Include a clear provider name and description

2. Handle Errors Gracefully

   • Always handle errors without throwing exceptions
   • Return appropriate error information in the result

3. Use Position for Optimal Order

   • Negative positions: Fundamental information providers (time, location)
   • Zero (default): Standard information providers
   • Positive positions: Providers that depend on other information

4. Structure Return Values Consistently

   • Maintain a consistent structure in your provider's return values

Default Actions

AyaOS ships with several built-in actions that are ready to use:

• REPLY – send a text response back to the user.
• IGNORE – end the conversation politely if no reply is needed.
• CAPABILITIES – list what the agent can do.
• WEB_SEARCH – perform a web search using Tavily.

The default language model is the free meta/llama-3.3-70b-instruct-fp8 hosted by function.network.

You can register additional actions or override these as needed.

Platform Integration

AyaOS includes built-in support for multiple messaging platforms and communication protocols. These integrations are automatically enabled when the required environment variables are configured.

Telegram Integration

The Telegram plugin allows your agent to communicate on Telegram through a bot interface.

Prerequisites

1. Create a Telegram bot by messaging @BotFather on Telegram
2. Follow the instructions to create a new bot and obtain your bot token

Configuration

Add your Telegram bot token to your environment variables:

# Required: Your Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here
# Optional: Timeout for handling updates (in milliseconds)
TELEGRAM_TIMEOUT=30000

Features

The Telegram integration provides:

• Message Handling: Send and receive text messages
• Group Support: Works in both private chats and group conversations
• Forum Topics: Handles Telegram forum topics as separate conversation rooms
• Authorization: Optional chat authorization controls
• Rich Context: Access to sender information, chat metadata, and message threading

Usage Example

Once configured, your agent will automatically connect to Telegram when started. The integration is enabled automatically when a TELEGRAM_BOT_TOKEN is detected.

import{Agent}from'@tribesxyz/ayaos'asyncfunctionmain(){constagent=newAgent()awaitagent.start()// Telegram integration is automatically active// Your agent will now respond to messages on Telegram}

Advanced Configuration

You can access the Telegram manager programmatically:

import{Agent}from'@tribesxyz/ayaos'asyncfunctionmain(){constagent=newAgent()awaitagent.start()// Access the Telegram manager (if available)if(agent.telegram){// Add custom command handlersagent.telegram.addCommandHandler('/start',async(ctx)=>{awaitctx.reply("Hello! I'm your AI agent.")})}}

XMTP Integration

XMTP (eXtensible Message Transport Protocol) provides decentralized, end-to-end encrypted messaging capabilities for your agent.

Prerequisites

Your agent needs access to an Ethereum wallet to use XMTP. This can be provided in two ways:

1. Using the default wallet: AyaOS automatically uses the agent's default EVM wallet
2. Using a specific private key: Provide a dedicated private key for XMTP

Configuration

Option 1: Using Default Wallet (Recommended)

No additional configuration needed. The agent will use its default EVM wallet for XMTP if available.

Option 2: Using Specific Private Key

# Optional: Dedicated private key for XMTP (hex format with 0x prefix)
XMTP_WALLET_PRIVATE_KEY=0x1234567890abcdef...

Features

The XMTP integration provides:

• Decentralized Messaging: Send and receive messages on the XMTP network
• End-to-End Encryption: All messages are automatically encrypted
• Web3 Native: Integrates seamlessly with Ethereum ecosystem
• Cross-Platform: Works with any XMTP-compatible client
• Reply Support: Full support for message threads and replies

Usage Example

import{Agent}from'@tribesxyz/ayaos'asyncfunctionmain(){constagent=newAgent()awaitagent.start()// XMTP integration is automatically active if wallet is available// Your agent will now send and receive messages on XMTP}

Getting Started with XMTP

1. Ensure your agent has an EVM wallet configured
2. Start your agent - XMTP will initialize automatically
3. Other XMTP users can message your agent using its wallet address
4. Your agent will respond to incoming XMTP messages

Network Configuration

XMTP integration uses the production network by default. The service automatically:

• Creates an XMTP client with your wallet
• Sets up message persistence in a local database
• Handles message encoding/decoding including reply threading
• Manages connection lifecycle and error recovery

Platform Status

You can verify which platforms are active by checking the console output when starting your agent:

bun dev

Look for messages like:

• ✅ Telegram client successfully started for character <name>
• ✅ XMTP client started <agentId>

Next Steps

For more information about AyaOS and ElizaOS, please visit:

• ElizaOS Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT