DEV Community

Gaia profile image Sushmita - aka meowy
Sushmita - aka meowy Subscriber for Gaia

Posted on

Getting Started with Gaia: A Developer's Guide to Building AI Agents with Gaia

Building AI-powered applications can be daunting. Between choosing the right models, setting up infrastructure, and handling API integrations, developers often spend more time on setup than on building their actual product. That's where the Gaia Agent Starter Kit comes in—a streamlined foundation that gets you from idea to working AI application in minutes, not hours.

Why Another AI Starter Kit?

The AI development landscape is cluttered with complex frameworks and heavyweight solutions. Most require extensive configuration, vendor lock-in, or compromise on performance and privacy. Gaia's approach is different:

  • Decentralized by design - No single point of failure or vendor dependency
  • Privacy-focused - Your data stays where you want it
  • Developer-friendly - Clean APIs and straightforward integration
  • Production-ready - Built on proven infrastructure

This starter kit distills years of AI application development experience into a simple, extensible foundation.

The Starter Kit Architecture

The Gaia Agent Starter Kit follows a clean, modular architecture built on Next.js:

Core Components

Frontend Layer: A clean React interface with streaming chat capabilities
API Integration: Streamlined connection to Gaia's AI infrastructure

Tool System: Extensible framework for adding custom AI capabilities
Configuration Management: Simple environment-based setup

Quick Start: From Clone to Chat in 5 Minutes

Step 1: Project Setup 

git clone https://github.com/meowyx/gaia-agent-starter
cd gaia-agent-starter
pnpm install
Enter fullscreen mode Exit fullscreen mode

The project uses pnpm for faster dependency installation, but works with npm or yarn as well.

Step 2: Get Your Gaia API Credentials

The setup process is straightforward:

  1. Visit gaianet.ai and click Launch App
  2. Connect your wallet - MetaMask or other Web3 wallets work
  3. Access settings via the profile dropdown
  4. Create an API key in the "Gaia API Keys" section
  5. Choose your base URL from available public nodes

Step 3: Environment Configuration

Create your .env.local file:

NEXT_PUBLIC_GAIA_API_BASE_URL=
NEXT_PUBLIC_GAIA_API_KEY=your_api_key_here
Enter fullscreen mode Exit fullscreen mode

Step 4: Launch Your AI Agent 

pnpm dev
Enter fullscreen mode Exit fullscreen mode

Open http://localhost:3000 and start chatting with your AI agent.

Under the Hood: How It Works

API Route Implementation

The core API route demonstrates clean integration with Gaia:

import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";
import { tools } from "@/ai/tools";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const openai = createOpenAI({
    baseURL: process.env.NEXT_PUBLIC_GAIA_API_BASE_URL,
    apiKey: process.env.NEXT_PUBLIC_GAIA_API_KEY 
  });

  try {
    const result = streamText({
      model: openai("llama"),
      system: "you are a friendly assistant",
      messages,
      maxSteps: 5,
      tools,
    });

    return result.toDataStreamResponse();
  } catch (error) {
    console.error(error);
    return new Response("Internal server error", { status: 500 });
  }
}
Enter fullscreen mode Exit fullscreen mode

This approach provides:

  • Environment-based configuration - No hardcoded values
  • Error handling - Graceful failure management
  • Streaming responses - Real-time conversation flow
  • Tool integration - Extensible AI capabilities

Frontend Integration

The frontend uses a clean, welcoming interface:

export default function Home() {
  return (
    <div 
      className="h-screen w-full overflow-y-auto grid grid-rows-[20px_1fr_60px]"
      style={{ 
        background: "linear-gradient(135deg, #fcf8e8 0%, #d4e2d4 100%)",
      }}
    >
      <main className="gap-8 row-start-2 sm:items-start h-full w-full">
        <div className="flex flex-col gap-3 items-center justify-center h-full">
          <div className="text-center mb-6">
            <h1 className="text-3xl font-bold mb-2 text-green-800">
              Hi there, Let's Chat 👋
            </h1>
            <p className="text-sm text-green-600 italic">
              powered by <Link href="https://www.gaianet.ai/">gaia</Link> 🌱
            </p>
          </div>
          <Chat />
        </div>
      </main>
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

The design emphasizes:

  • Approachable aesthetics - Warm, natural color scheme
  • Clear branding - Gaia attribution and links
  • Responsive layout - Works across all device sizes
  • Accessibility - Proper semantic structure

Customization and Extension

Adding Custom Tools

The starter kit includes a tools system for extending AI capabilities:

// ai/tools.ts
export const tools = {
  getCurrentTime: {
    description: 'Get the current time',
    parameters: z.object({}),
    execute: async () => {
      return new Date().toISOString();
    },
  },

  // Add your custom tools here
  calculateTip: {
    description: 'Calculate tip amount',
    parameters: z.object({
      amount: z.number(),
      percentage: z.number()
    }),
    execute: async ({ amount, percentage }) => {
      return amount * (percentage / 100);
    },
  }
};
Enter fullscreen mode Exit fullscreen mode

Customizing the AI Personality

Modify the system prompt to change your agent's behavior:

const result = streamText({
  model: openai("llama"),
  system: `You are a specialized assistant for [your domain].
           You should:
           - Be helpful and accurate
           - Focus on [your specific area]
           - Provide actionable advice
           - Ask clarifying questions when needed`,
  messages,
  maxSteps: 5,
  tools,
});
Enter fullscreen mode Exit fullscreen mode

Styling and Branding

The starter kit uses Tailwind CSS for easy customization:

/* Custom color scheme */
:root {
  --primary-green: #16a34a;
  --accent-green: #22c55e;
  --background-start: #fcf8e8;
  --background-end: #d4e2d4;
}
Enter fullscreen mode Exit fullscreen mode

Production Deployment

Environment Configuration

For production deployment, ensure your environment variables are properly set:

# Production environment
NEXT_PUBLIC_GAIA_API_BASE_URL=
NEXT_PUBLIC_GAIA_API_KEY=your_production_api_key
Enter fullscreen mode Exit fullscreen mode

Performance Optimizations

The starter kit includes several built-in optimizations:

  • Automatic code splitting - Next.js handles this automatically
  • Image optimization - Built-in Next.js image optimization
  • Streaming responses - Reduces perceived latency
  • Error boundaries - Graceful error handling

Security Considerations

While the starter kit is secure by default, consider these additional measures for production:

// Add rate limiting
import { rateLimit } from '@/lib/rate-limit';

export async function POST(request: Request) {
  const identifier = request.headers.get('x-forwarded-for') || 'localhost';
  const { success } = await rateLimit.limit(identifier);

  if (!success) {
    return new Response('Too many requests', { status: 429 });
  }

  // ... rest of your handler
}
Enter fullscreen mode Exit fullscreen mode

Common Use Cases and Extensions

Customer Support Agent

Transform the starter into a support agent:

const supportSystem = `You are a customer support agent for [Company Name].
You have access to:
- Product documentation
- Order lookup tools  
- Troubleshooting guides

Always be helpful, patient, and professional.`;
Enter fullscreen mode Exit fullscreen mode

Educational Tutor

Create a specialized learning assistant:

const tutorSystem = `You are an educational tutor specializing in [Subject].
You should:
- Break down complex concepts
- Provide examples and practice problems
- Adapt to the student's level
- Encourage learning`;
Enter fullscreen mode Exit fullscreen mode

Developer Assistant

Build a coding companion:

const devSystem = `You are a senior developer assistant.
You can help with:
- Code review and suggestions
- Debugging assistance
- Architecture recommendations
- Best practices guidance`;
Enter fullscreen mode Exit fullscreen mode

Connecting to Your Own Gaia Node

For maximum control and privacy, you can run your own Gaia node:

Local Node Setup 

# Install Gaia node
curl -sSfL 'https://github.com/GaiaNet-AI/gaianet-node/releases/latest/download/install.sh' | bash

# Initialize with your preferred model
gaianet init --config https://raw.githubusercontent.com/GaiaNet-AI/node-configs/main/llama-3-groq-8b-tool/config.json

# Start your node
gaianet start
Enter fullscreen mode Exit fullscreen mode

Configuration Update

Update your environment variables to point to your local node:

NEXT_PUBLIC_GAIA_API_BASE_URL=http://localhost:8080/v1
NEXT_PUBLIC_GAIA_API_KEY=""  # Can be empty for local nodes
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Common Issues

API Connection Problems

If you're having trouble connecting to Gaia:

  1. Verify your API key - Ensure it's correctly set in .env.local
  2. Check the base URL - Confirm the node is accessible
  3. Review network settings - Firewall or proxy issues
  4. Check rate limits - Some nodes have usage restrictions

Streaming Response Issues

If messages aren't streaming properly:

  1. Browser compatibility - Ensure modern browser support
  2. Network configuration - Some proxies block streaming
  3. Error handling - Check browser console for errors

Tool Integration Problems

If custom tools aren't working:

  1. Parameter validation - Ensure Zod schemas are correct
  2. Async handling - All tool functions should be async
  3. Error boundaries - Add proper error handling

Advanced Patterns

Multi-Agent Conversations

Extend the starter to support multiple AI agents:

const agents = {
  researcher: {
    system: "You are a research specialist...",
    model: "llama"
  },
  writer: {
    system: "You are a creative writer...",
    model: "llama"
  }
};

// Route to different agents based on context
const selectedAgent = agents[agentType];
Enter fullscreen mode Exit fullscreen mode

Context Persistence

Add conversation memory:

// Store conversation context
const conversation = {
  id: generateId(),
  messages: [],
  context: {},
  created: new Date()
};

// Retrieve and maintain context across sessions
Enter fullscreen mode Exit fullscreen mode

Integration with External APIs

Add external data sources:

const tools = {
  getWeather: {
    description: 'Get current weather',
    parameters: z.object({
      location: z.string()
    }),
    execute: async ({ location }) => {
      const response = await fetch(`https://api.weather.com/${location}`);
      return await response.json();
    }
  }
};
Enter fullscreen mode Exit fullscreen mode

Community and Ecosystem

The Gaia Agent Starter Kit is part of a growing ecosystem:

Community Resources

  • GitHub Discussions - Share experiences and get help
  • Discord Community - Real-time chat with other developers
  • Documentation - Comprehensive guides and tutorials
  • Example Projects - Inspiration and code samples

Contributing Back

Ways to contribute to the ecosystem:

  1. Share your extensions - Tools, UI components, integrations
  2. Submit bug reports - Help improve stability
  3. Write tutorials - Help others learn
  4. Contribute code - Direct improvements to the starter kit

The Future of AI Development

This starter kit represents a philosophy shift in AI development:

From Complexity to Simplicity

Instead of overwhelming developers with options, provide a clean foundation they can build upon.

From Centralized to Decentralized

Remove single points of failure and give developers control over their AI infrastructure.

From Proprietary to Open

Open-source tools and transparent infrastructure enable innovation and trust.

Conclusion: Getting started with your AI Agent Journey

The Gaia Agent Starter Kit removes the friction from AI application development. Whether you're building a customer service bot, an educational tutor, or a specialized domain assistant, this foundation gives you everything you need to start building immediately.

The real power comes from what you build on top of it. The starter kit is intentionally minimal—a clean canvas for your ideas rather than a prescriptive framework. This approach enables rapid prototyping while maintaining the flexibility to scale and customize as your application grows.

Ready to build your first AI agent? Clone the repository, follow the setup guide, and start experimenting.

Getting Started:

Top comments (0)