Ask Nebula - Blockchain Agent Template

A flexible template for building autonomous agents that interact with blockchain data using Thirdweb AI and Pydantic AI. This template allows you to quickly deploy agents that can analyze blockchain transactions, respond to queries, and even post analysis to Twitter.

🚀 Features

Multiple Agent Examples:
- Basic agent for simple blockchain queries
- Pydantic structured agent for type-safe blockchain data
- Twitter bot for responding to mentions
- Direct query tool for one-off analysis
Built-in Tools:
- Transaction analysis
- Smart thread generation
- Twitter integration
Developer-Friendly:
- Type annotations throughout
- Modular architecture
- Easy to customize and extend

📋 Requirements

Python 3.11+
uv for dependency management
Thirdweb account and API key
Twitter Developer account (optional, for Twitter integration)

🛠️ Installation

Clone the repository:

[git clone https://github.com/yourusername/ask-nebula.git](https://github.com/thirdweb-example/ask-nebula-template)
cd ask-nebula-template

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies using uv:

uv pip sync uv.lock

Copy the example environment file and fill in your API keys:

cp .env.example .env

⚙️ Configuration

Edit the .env file and add your API keys:

# Required for all agents
OPENAI_API_KEY=your_openai_api_key
THIRDWEB_SECRET_KEY=your_thirdweb_secret_key

# Optional for Thirdweb Engine
THIRDWEB_ENGINE_URL=your_thirdweb_engine_url
THIRDWEB_ENGINE_AUTH_JWT=your_thirdweb_engine_jwt

# Required only for Twitter integration
TWITTER_API_KEY=your_twitter_api_key
TWITTER_API_SECRET=your_twitter_api_secret
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret
BEARER_TOKEN=your_bearer_token

🔍 Usage

Basic Blockchain Agent

Run the basic agent to analyze a transaction:

python basic_agent.py

Structured Pydantic Agent

Use the Pydantic agent for strongly-typed blockchain data:

python pydantic_agent_simple.py

Twitter Bot

Start the Twitter bot to listen for mentions:

python twitter_bot.py

Direct Query

Run a one-off blockchain query and optionally post to Twitter:

python direct_query.py

📦 Project Structure

basic_agent.py - Simple blockchain analysis agent
pydantic_agent_simple.py - Structured blockchain data agent using Pydantic models
twitter_bot.py - Twitter bot for monitoring mentions and auto-responding
thread_creator.py - Twitter thread generator
direct_query.py - Command-line tool for one-off blockchain queries

🧩 Customizing the Agents

Adding New Capabilities

Add a new tool to an existing agent:

@agent.tool(name="your_new_tool")
def your_new_tool(ctx: RunContext, param1: str, param2: int) -> dict:
    """Your tool description."""
    # Tool implementation
    return {"result": "data"}

Create a new agent class by extending the existing ones.

Modifying the Twitter Thread Format

Edit the generate_twitter_thread function in thread_creator.py to customize the format of generated Twitter threads.

🧪 Testing

You can test your agents locally:

# Test the basic agent
python basic_agent.py

# Test the Twitter thread creator
python thread_creator.py

thirdweb-example/ask-nebula-template