Build & Deploy AI Agents

Required Software

Required API Keys (Multi-LLM Support)

Install ngrok

# macOS
brew install ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

# Set auth token (get from https://dashboard.ngrok.com/get-started/your-authtoken)
ngrok authtoken YOUR_AUTH_TOKEN

Install NEST Framework & Dependencies

# Install NEST framework
pip install git+https://github.com/projnanda/NEST.git@v1

# Install additional dependencies
pip install pyngrok python-dotenv

This installs nanda-core with Flask, Anthropic/OpenAI SDKs, A2A protocol, MCP support, and ngrok tunnel integration.

Create Project Directory

mkdir my-agent-project
cd my-agent-project

Create .env File

# API Keys (at least one required - Multi-LLM Support)
ANTHROPIC_API_KEY=sk-ant-api03-...        # For Claude models
OPENAI_API_KEY=sk-proj-...                # For GPT models
GOOGLE_API_KEY=AIza...                    # For Gemini models

# Agent Configuration
AGENT_ID=my-custom-agent-001
AGENT_NAME=My Custom Agent
AGENT_DOMAIN=general
AGENT_SPECIALIZATION=helpful assistant
AGENT_DESCRIPTION=A custom AI agent that helps with tasks
AGENT_CAPABILITIES=conversation,analysis,research

# Server Configuration
PORT=7000
PUBLIC_URL=http://localhost:7000

# Mumbai Hacks Registry
REGISTRY_URL=https://mumbaihacksindex.chat39.com

# LLM Provider (anthropic, openai, or gemini)
LLM_PROVIDER=anthropic

# Tunnel Configuration (for public deployment)
ENABLE_TUNNEL=true
NGROK_AUTH_TOKEN=your-ngrok-auth-token    # Get from https://dashboard.ngrok.com

# Optional: MCP Tools (LLM provider agnostic)
SMITHERY_API_KEY=your-smithery-api-key

Template 1

Basic Echo Agent (No LLM)

Simple rule-based agent for testing. Create my_agent.py:

#!/usr/bin/env python3
import os
from dotenv import load_dotenv
from nanda_core import NANDA
from pyngrok import ngrok

load_dotenv()

# ============================================
# CUSTOMIZE THIS FUNCTION FOR YOUR AGENT
# ============================================
def agent_logic(message: str, conversation_id: str) -> str:
    """
    Your agent's brain - customize this function only.
    
    Args:
        message: User's input text
        conversation_id: Unique conversation identifier
        
    Returns:
        str: Your agent's response
    """
    msg = message.lower()
    
    # Add your custom logic here
    if "hello" in msg or "hi" in msg:
        return f"Hello! I'm {os.getenv('AGENT_ID')}. How can I help?"
    elif "help" in msg:
        return "I can respond to greetings and questions. Try asking me something!"
    elif "?" in message:
        return f"Great question! Let me think... {message}"
    else:
        return f"You said: {message}. (Echo mode)"

# ============================================
# DO NOT MODIFY BELOW (NEST Infrastructure)
# ============================================
if __name__ == "__main__":
    port = int(os.getenv("PORT", "7000"))
    
    # Setup ngrok tunnel
    if os.getenv("ENABLE_TUNNEL", "false").lower() == "true":
        ngrok.set_auth_token(os.getenv("NGROK_AUTH_TOKEN"))
        tunnel = ngrok.connect(port, bind_tls=True)
        public_url = tunnel.public_url
        print(f"🌐 Tunnel URL: {public_url}")
    else:
        public_url = os.getenv("PUBLIC_URL", f"http://localhost:{port}")
    
    # Initialize NANDA agent
    nanda = NANDA(
        agent_id=os.getenv("AGENT_ID"),
        agent_logic=agent_logic,  # Your custom function
        port=port,
        public_url=public_url,
        registry_url=os.getenv("REGISTRY_URL"),
        enable_telemetry=True
    )
    
    print(f"🤖 Agent '{os.getenv('AGENT_ID')}' ready!")
    print(f"📡 Listening on port {port}")
    
    # Start the agent server
    nanda.start()

Template 2

LLM-Powered Agent (Claude/GPT/Gemini)

Use Claude, GPT, or Gemini for intelligent responses:

#!/usr/bin/env python3
import os
from dotenv import load_dotenv
from nanda_core import NANDA
from pyngrok import ngrok
# Choose your LLM client:
from anthropic import Anthropic  # or: from openai import OpenAI

load_dotenv()

# Initialize LLM client
llm_client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
# For OpenAI: llm_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# ============================================
# CUSTOMIZE THIS FUNCTION FOR YOUR AGENT
# ============================================
def agent_logic(message: str, conversation_id: str) -> str:
    """
    LLM-powered agent - customize the system prompt and model.
    """
    
    # CUSTOMIZE: Your agent's personality and instructions
    system_prompt = f"""You are {os.getenv('AGENT_ID')}, a helpful AI assistant.
Your specialization: {os.getenv('AGENT_SPECIALIZATION', 'general assistance')}
Your capabilities: {os.getenv('AGENT_CAPABILITIES', 'conversation')}

Be concise, friendly, and helpful in your responses."""
    
    try:
        # Call LLM (Claude example)
        response = llm_client.messages.create(
            model="claude-3-5-sonnet-20241022",  # CUSTOMIZE: model choice
            max_tokens=1024,
            system=system_prompt,
            messages=[{"role": "user", "content": message}]
        )
        return response.content[0].text
        
        # For OpenAI/GPT:
        # response = llm_client.chat.completions.create(
        #     model="gpt-4",
        #     messages=[
        #         {"role": "system", "content": system_prompt},
        #         {"role": "user", "content": message}
        #     ]
        # )
        # return response.choices[0].message.content
        
    except Exception as e:
        return f"Error processing request: {str(e)}"

# ============================================
# DO NOT MODIFY BELOW (NEST Infrastructure)
# ============================================
if __name__ == "__main__":
    port = int(os.getenv("PORT", "7000"))
    
    # Setup ngrok tunnel
    if os.getenv("ENABLE_TUNNEL", "false").lower() == "true":
        ngrok.set_auth_token(os.getenv("NGROK_AUTH_TOKEN"))
        tunnel = ngrok.connect(port, bind_tls=True)
        public_url = tunnel.public_url
        print(f"🌐 Tunnel URL: {public_url}")
    else:
        public_url = os.getenv("PUBLIC_URL", f"http://localhost:{port}")
    
    nanda = NANDA(
        agent_id=os.getenv("AGENT_ID"),
        agent_logic=agent_logic,
        port=port,
        public_url=public_url,
        registry_url=os.getenv("REGISTRY_URL"),
        enable_telemetry=True
    )
    
    print(f"🤖 LLM Agent '{os.getenv('AGENT_ID')}' ready!")
    nanda.start()

Template 3

Stateful Agent with Memory

Track conversation history and maintain state:

#!/usr/bin/env python3
import os
from dotenv import load_dotenv
from nanda_core import NANDA
from pyngrok import ngrok

load_dotenv()

# Conversation memory storage
conversation_history = {}

# ============================================
# CUSTOMIZE THIS FUNCTION FOR YOUR AGENT
# ============================================
def agent_logic(message: str, conversation_id: str) -> str:
    """
    Stateful agent that remembers conversation context.
    """
    
    # Initialize conversation history
    if conversation_id not in conversation_history:
        conversation_history[conversation_id] = []
    
    # Add current message to history
    conversation_history[conversation_id].append({
        "role": "user",
        "content": message
    })
    
    # CUSTOMIZE: Your stateful logic here
    history = conversation_history[conversation_id]
    message_count = len(history)
    
    # Example: Count-based responses
    if message_count == 1:
        response = "Hello! This is our first message. What's your name?"
    elif message_count == 2:
        response = f"Nice to meet you! You said: {history[0]['content']}"
    else:
        response = f"This is message #{message_count}. Previous: {history[-2]['content']}"
    
    # Save agent response to history
    conversation_history[conversation_id].append({
        "role": "assistant",
        "content": response
    })
    
    return response

# ============================================
# DO NOT MODIFY BELOW
# ============================================
if __name__ == "__main__":
    port = int(os.getenv("PORT", "7000"))
    
    if os.getenv("ENABLE_TUNNEL", "false").lower() == "true":
        ngrok.set_auth_token(os.getenv("NGROK_AUTH_TOKEN"))
        tunnel = ngrok.connect(port, bind_tls=True)
        public_url = tunnel.public_url
        print(f"🌐 Tunnel URL: {public_url}")
    else:
        public_url = os.getenv("PUBLIC_URL", f"http://localhost:{port}")
    
    nanda = NANDA(
        agent_id=os.getenv("AGENT_ID"),
        agent_logic=agent_logic,
        port=port,
        public_url=public_url,
        registry_url=os.getenv("REGISTRY_URL"),
        enable_telemetry=True
    )
    
    print(f"🤖 Stateful Agent '{os.getenv('AGENT_ID')}' ready!")
    nanda.start()

Start Your Agent

python my_agent.py

Expected output:

🤖 Agent 'my-agent-001' starting...
📡 Port: 7000
🌐 Registry: https://mumbaihacksindex.chat39.com
🔌 Tunnel: true
🚀 Starting agent 'my-agent-001' on 0.0.0.0:7000
📊 Telemetry enabled for my-agent-001
🌐 Tunnel URL: https://abc123.ngrok.io

Test with cURL

curl -X POST http://localhost:7000/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "content": {"text": "Hello, agent!", "type": "text"},
    "role": "user",
    "conversation_id": "test-123"
  }'

Verify Tunnel

Look for the tunnel URL in your agent logs:

🌐 Tunnel URL: https://abc123.ngrok.io

Test the tunnel:

curl -X POST https://abc123.ngrok.io/a2a \
  -H "Content-Type: application/json" \
  -d '{"content": {"text": "Hello via tunnel!", "type": "text"}, "role": "user", "conversation_id": "test"}'

Check Registry Listing

curl https://mumbaihacksindex.chat39.com/list

You should see your agent in the response.

Access via Frontend

Once registered, your agent will appear on the Agent Gallery page.

Agent Won't Start

Issue: "Address already in use" or "Port XXXX is in use"

# Find and kill process using the port
lsof -ti:7000 | xargs kill -9

# Or change PORT in .env file
PORT=7001

Agent Not Registering

• Check REGISTRY_URL is correct: https://mumbaihacksindex.chat39.com
• Verify tunnel is working: check for tunnel URL in logs
• Test registry manually: curl https://mumbaihacksindex.chat39.com/list

Tunnel Issues

• Install ngrok: brew install ngrok (macOS)
• Set auth token: ngrok authtoken YOUR_TOKEN
• Test manually: ngrok http 7000

Can't Access via Frontend

• Verify tunnel URL is publicly accessible
• Check CORS settings (handled by NEST automatically)
• Verify agent is still running: ps aux | grep my_agent.py