A production-ready starter kit for building AI agents and multi-agent swarms on NEAR. This template provides the essential building blocks for creating autonomous agents that can interact with the NEAR blockchain, make decisions using LLMs, and collaborate in swarms. The NEAR AI Agent Studio is an educational and interactive starter kit designed for developers looking to build AI agents and agentic applications on NEAR.
Before you begin, ensure you have:
- Python 3.12 or higher
- Git
- Operating System:
- macOS 12.0+
- Ubuntu 20.04+ / Debian 11+
- Windows 10/11 with WSL2
- NEAR testnet account (created automatically by quickstart script)
- Or existing account with:
- Account ID
- Full access key
- Test NEAR tokens (available from NEAR Faucet)
- Hyperbolic API key for LLM capabilities
- Sign up at hyperbolic.xyz
- Free tier available for development
# Clone the repository
git clone https://github.com/jbarnes850/near-ai-agent-studio
cd near-ai-agent-studio
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: .\venv\Scripts\activate
# Install dependencies
pip install -e .
# Run the quickstart script
chmod +x scripts/quickstart.sh # Make script executable
./scripts/quickstart.sh
The quickstart script will:
- Set up your development environment
- Create a NEAR testnet account
- Install example agents
- Launch an interactive chat assistant to help you create your first agent
After setup, you'll enter an interactive chat session where you can:
- Create new agents with
/create agent <name>
- Configure agents with
/config agent <name>
- Run multiple agents together with
/run-agents
- List available agents with
/list
- Get help anytime with
/help
Start the chat manually anytime:
near-swarm chat # Regular mode
near-swarm chat --tutorial create-first-agent # Guided tutorial
# Copy environment template
cp .env.example .env
# Edit .env with your credentials
# Required variables:
# - NEAR_ACCOUNT_ID=your-account.testnet
# - NEAR_PRIVATE_KEY=your-private-key
# - LLM_PROVIDER=hyperbolic
# - LLM_API_KEY=your-api-key
Tip: Start with modifying the examples in
near_swarm/examples/
to understand the framework.
Note: This template runs on NEAR testnet by default for safe development. Always test thoroughly before deploying to mainnet.
graph TB
%% Core System
Core[Agent Framework]
style Core fill:black,stroke:#00C1DE,stroke-width:3px,color:white
%% Plugin Management
Registry[Agent Registry]
Loader[Agent Loader]
Config[Configuration]
style Registry fill:black,stroke:#00C1DE,stroke-width:2px,color:white
style Loader fill:black,stroke:#00C1DE,stroke-width:2px,color:white
style Config fill:black,stroke:#00C1DE,stroke-width:2px,color:white
%% Core Services
NEAR[NEAR Integration]
Market[Market Data]
LLM[LLM Provider]
style NEAR fill:#00C1DE,stroke:black,stroke-width:2px,color:black
style Market fill:#00C1DE,stroke:black,stroke-width:2px,color:black
style LLM fill:#00C1DE,stroke:black,stroke-width:2px,color:black
%% Plugin Layer
subgraph Plugins[Agent Plugins]
direction TB
TokenTransfer[Token Transfer<br/>Plugin]
Arbitrage[Arbitrage<br/>Plugin]
Custom[Custom<br/>Plugins]
style TokenTransfer fill:black,stroke:#00C1DE,stroke-width:2px,color:white
style Arbitrage fill:black,stroke:#00C1DE,stroke-width:2px,color:white
style Custom fill:black,stroke:#00C1DE,stroke-width:2px,color:white
end
style Plugins fill:none,stroke:#00C1DE,stroke-width:3px,color:white
%% Swarm Intelligence Layer
subgraph Swarm[Swarm Intelligence]
direction TB
SwarmAgent[Swarm Agent]
Consensus[Consensus Building]
Evaluation[Multi-Agent Evaluation]
style SwarmAgent fill:black,stroke:#00C1DE,stroke-width:2px,color:white
style Consensus fill:black,stroke:#00C1DE,stroke-width:2px,color:white
style Evaluation fill:black,stroke:#00C1DE,stroke-width:2px,color:white
end
style Swarm fill:none,stroke:#00C1DE,stroke-width:3px,color:white
%% Connections
Core --> Registry
Core --> Loader
Core --> Config
Registry --> Plugins
Loader --> Plugins
Plugins --> NEAR
Plugins --> Market
Plugins --> LLM
Plugins --> Swarm
SwarmAgent --> Consensus
SwarmAgent --> Evaluation
The architecture combines a flexible agent system with swarm intelligence capabilities:
-
Agent Framework Core
- Agent Registry for managing available plugins
- Agent Loader for dynamic loading/unloading
- Configuration management with validation
-
Core Services
- NEAR Protocol integration
- Market data feeds
- LLM provider interface
-
Agent Plugins
- Token Transfer agent for NEAR transactions
- Arbitrage agent for market opportunities
- Custom agents for specialized strategies
-
Swarm Intelligence
- Swarm Agent for coordinated decision-making
- Consensus building through multi-agent voting
- Role-based evaluation with LLM reasoning
near-swarm-intelligence/
├── near_swarm/
│ ├── core/
│ │ ├── agent.py
│ │ ├── swarm_agent.py
│ │ ├── llm_provider.py
│ │ ├── near_integration.py
│ │ └── config/
│ │ ├── agent_roles.json
│ │ └── swarm_config.json
│ └── examples/
│ ├── simple_strategy.py
│ └── arbitrage_strategy.py
├── scripts/
├── tests/
└── docs/
from near_swarm.core.agent import Agent, AgentConfig
from near_swarm.core.swarm_agent import SwarmAgent, SwarmConfig
# Configure your agent
config = AgentConfig(
near_network="testnet",
account_id="your-account.testnet",
private_key="your-private-key",
llm_provider="hyperbolic",
llm_api_key="your-api-key"
)
# Create and start agent
agent = Agent(config)
await agent.start()
# Execute actions
result = await agent.execute_action({
"type": "transaction",
"params": {
"receiver_id": "receiver.testnet",
"amount": "1.5"
}
})
# Create swarm configuration
swarm_config = SwarmConfig(
role="market_analyzer",
min_confidence=0.7,
min_votes=2,
timeout=1.0
)
# Initialize swarm agents
main_agent = SwarmAgent(config, swarm_config)
peer_agent = SwarmAgent(config, SwarmConfig(role="risk_manager"))
# Form swarm
await main_agent.join_swarm([peer_agent])
For more examples and reference implementations, check out our examples directory:
arbitrage_strategy.py
- Advanced DEX arbitragedemo.py
- Interactive demo of all features
Each example includes detailed comments and demonstrates different aspects of the framework. See our Examples Guide for detailed walkthroughs.
We welcome contributions! Please see our Contributing Guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ by the NEAR community