ElizaOS is an early but promising open-source framework designed to accelerate building autonomous on-chain AI agents. It provides a core runtime environment alongside a flexible plugin system for extending blockchain connectivity, cryptographic operations, and AI-model interaction.
If you’re here looking for an ElizaOS tutorial getting started guide, you’re in the right spot. This walkthrough focuses on hands-on setup, character configuration, and plugin development—especially around Web3 integrations.
What I appreciate most about ElizaOS is its modular architecture, letting you swap in your favorite AI models or connect to chains beyond the initial support using plugins.
Before we start coding, make sure you have these:
For this tutorial, I am using ElizaOS v0.9.1 (check the official repo for the latest). The plugin API has changed little since v0.8, so this guide should remain relevant for a while.
Let’s get a minimal agent running locally:
npm init -y
npm install @elizaos/core
# Simple run script
cat > index.ts <<EOF
import { createAgent } from '@elizaos/core';
async function main() {
const agent = await createAgent({
name: 'basic-agent',
chain: 'ethereum:goerli',
wallet: process.env.AGENT_WALLET || '',
});
const response = await agent.chat('Hello, ElizaOS!');
console.log('Agent response:', response);
}
main();
EOF
npx ts-node index.ts
This example initializes an agent on Goerli testnet with a wallet key injected via env. You’ll get a basic AI chat response—usually just a static echo if you haven’t connected a model plugin yet.
In my experience, the wallet setup step tends to be the most common source of errors. Always double-check your seed phrase or private key before running.
Linking this setup to onchain-ai-agent-setup can deepen wallet management best practices.
Character configuration in ElizaOS defines your agent’s personality, permissions, and operational rules. It's typically stored as a JSON or YAML file and includes:
Here’s a minimal YAML snippet:
name: 'trader-bot'
permissions:
- read:blockchain
- execute:tx
spendingLimits:
maxGas: 500000
maxTokens: 10
sessionKeys:
- key1
- key2
Why does this matter? Proper character config helps prevent accidental exposure—say if the agent wallet is compromised. A scoped session key with tight spending limits can save your deployment from meltdown.
Plugins are the meat and potatoes for extending ElizaOS’s functionalities. The plugin API exposes hooks for:
Plugins are Rust crates that implement specific traits defined by ElizaOS. Here’s a simplified Rust signature for a plugin:
pub trait Plugin {
fn init(&mut self, config: PluginConfig) -> Result<()>;
fn handle_message(&mut self, msg: &Message) -> Result<Message>;
fn shutdown(&mut self) -> Result<()>;
}
You interact with them via the ElizaOS runtime, and they can expose custom RPC endpoints or subscribe to on-chain events.
Check the current docs for plug-in API v0.9 to avoid mismatches.
Solana plugin development differs from EVM integrations mainly in RPC call structure and key management. To set your plugin up:
cargo new elizaos-solana-plugin
cd elizaos-solana-plugin
cargo add elizaos-plugin-sdk
use elizaos_plugin_sdk::{Plugin, PluginConfig, Message, Result};
use solana_client::rpc_client::RpcClient;
pub struct SolanaPlugin {
rpc_client: RpcClient,
}
impl Plugin for SolanaPlugin {
fn init(&mut self, config: PluginConfig) -> Result<()> {
let endpoint = config.get("rpc_endpoint").unwrap_or_else(|| "https://api.devnet.solana.com");
self.rpc_client = RpcClient::new(endpoint.to_string());
Ok(())
}
fn handle_message(&mut self, msg: &Message) -> Result<Message> {
// Handle on-chain queries or transaction construction
Ok(msg.clone())
}
fn shutdown(&mut self) -> Result<()> {
Ok(())
}
}
plugins:
- name: solana-plugin
config:
rpc_endpoint: "https://api.devnet.solana.com"
I ran into some minor serialization issues converting Solana account data; off-the-shelf JSON doesn’t always cut it. The gotcha? Watch out for RPC rate limits on devnet if polling often.
For more on Solana integration, see solana-agent-kit-guides.
AgentKit is a popular SDK for deploying account abstraction-based on-chain agents, particularly on EVM-compatible chains. Integrating ElizaOS with AgentKit lets you marry AI logic with smart contract execution managed via ERC-4337 or similar standards.
The integration usually involves:
Here’s a TypeScript snippet illustrating how to connect your ElizaOS agent’s output to an AgentKit Tx builder:
import { AgentKit } from 'agentkit';
import { createAgent } from '@elizaos/core';
async function main() {
const elizaAgent = await createAgent({ name: 'ak-agent', chain: 'ethereum:mainnet', wallet: process.env.AGENT_WALLET });
const agentKit = new AgentKit({ chain: 'mainnet' });
const aiDecision = await elizaAgent.chat('Should I swap tokens?');
if (aiDecision.approve) {
const tx = agentKit.buildTx({ to: aiDecision.to, data: aiDecision.data });
const signedTx = await agentKit.signTx(tx);
await agentKit.sendTx(signedTx);
}
}
main();
The key is synchronizing state: ElizaOS for reasoning, AgentKit for wallet and transaction management. This approach can scale better than embedding all logic on-chain.
Because ElizaOS agents hold private keys and can execute transactions, wallet security is a big concern. Here’s what I watch out for:
ElizaOS doesn’t enforce these; they’re up to you. See agent-wallet-security for wallet management best practices applicable here.
Some issues you might hit:
In my experience, logging everything at init and message hooks catches most bugs early.
You’ve now got an overview and practical starting points for the ElizaOS runtime, character config, plugin development (including a Solana example), and AgentKit integration.
Try extending your agent with a real AI model plugin or build a minimal MCP server integration next. Don’t forget to harden your wallet setup before moving to mainnet.
For deeper dives, check out the linked guides on setting up agents, integrating MCP servers, and building MEV trading bots.
Ready to build your first Web3 AI agent? Get your hands dirty with the code, and expect some rough edges. The ecosystem is evolving fast, but that’s where the fun is.
Explore:
Happy coding!