- Node.js v18+ and npm for package management
- Rust 1.70+ (ElizaOS core and plugins are Rust-based, with Node.js bindings)
- A basic understanding of Web3 concepts like RPC, MPC, and agent wallets
- Experience with TypeScript or Rust will help but isn’t mandatory
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.
Setting Up Your First ElizaOS Agent
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.
Understanding ElizaOS Character Configuration
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:
- Name and description: Helps identify agents in complex deployments
- Allowed actions: Example, read blockchain state, execute transactions
- Spending limits: Define max gas or token spend to mitigate wallet drains
- Session keys: Scoped ephemeral keys enhancing security
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.
ElizaOS Plugin API Overview
Plugins are the meat and potatoes for extending ElizaOS’s functionalities. The plugin API exposes hooks for:
- Lifecycle management (init, start, stop)
- Message interception/modification
- Blockchain calls (RPC, event subscriptions)
- Model query and response transformation
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.
Developing a Solana Plugin for ElizaOS
Solana plugin development differs from EVM integrations mainly in RPC call structure and key management. To set your plugin up:
- Start a Rust crate with the ElizaOS plugin dependencies:
cargo new elizaos-solana-plugin
cd elizaos-solana-plugin
cargo add elizaos-plugin-sdk
- Implement the plugin trait, handling Solana RPC:
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(())
}
}
- Build and register your plugin in ElizaOS’s config:
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.
Integrating ElizaOS with AgentKit
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:
- Setting ElizaOS as the off-chain brains hosting AI decisions
- Using AgentKit to wire up wallet sessions, gas payment via sponsored accounts, and transaction bundling
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.
Security Considerations for On-Chain AI Agents
Because ElizaOS agents hold private keys and can execute transactions, wallet security is a big concern. Here’s what I watch out for:
- Session keys with limited scopes reduce blast radius on key compromise.
- Spending limits on agent transactions stop runaway gas or token drain.
- Avoid hardcoding private keys in source; use environment variables or hardware signing.
- Untrusted plugins or MCP servers can inject malicious code.
ElizaOS doesn’t enforce these; they’re up to you. See agent-wallet-security for wallet management best practices applicable here.
Troubleshooting and Common Gotchas
Some issues you might hit:
- Agent wallet connection errors: check key format and network compatibility.
- Plugin initialization fails: verify plugin config matches expected schema.
- RPC timeouts under heavy polling: add caching or exponential backoff.
- Serialization errors with Solana plugin: custom data models may be necessary.
In my experience, logging everything at init and message hooks catches most bugs early.
Summary and Next Steps
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!
