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

1. Clone the repository:

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

2. Create and activate a virtual environment:

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

3. Install dependencies using uv:

uv pip sync uv.lock

4. 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

1. 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"}

2. 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

📚 Resources

• Thirdweb AI Documentation
• Pydantic AI Documentation
• Twitter API Documentation

📝 License

MIT

🤝 Contributing

Contributions, issues, and feature requests are welcome!