Quickstart

​

Why build on Bhindi though?

1. If you have ever written tools for LLMs, you will feel right in place!
2. BCP - Bhindi Context Protocol is just that on steroids!
3. You connect with 15+ OAuth apps out of the box.
4. So you can focus on your idea and get it out before it becomes dead burried under other 99 dead ideas which you did not ship because some random setup issue took half of your day

​

Getting Started

​

Agent Starter Kit

• Public Tool Integration: Pre-configured calculator tools demonstrating basic agent capabilities
• Authenticated Tool Access: GitHub integration examples showcasing secure API interactions
• TypeScript Support: Full type safety and modern development practices
• Bhindi.io Specification: Complete implementation following the official Bhindi.io agent specification

​

Available OAuth Integrations

• GitHub
• Trello
• Notion
• Linear
• Gmail
• Google Calendar
• Google Docs
• Google Sheets
• GitHub Pages
• Slack
• X/Twitter
• Typeform
• Google Forms
• Reddit

​

Quick Start

​

0. Clone the agent starter template

git clone https://github.com/upsurgeio/bhindi-agent-starter

​

1. Install Dependencies

npm install

​

2. Build the Project

npm run build

​

3. Start the Server

npm start
# or for development with auto-reload:
npm run dev

​

4. Test the API

# Get available tools
curl -X GET "http://localhost:3000/tools"

# Test calculator (no auth needed)
curl -X POST "http://localhost:3000/tools/add" \
  -H "Content-Type: application/json" \
  -d '{"a": 5, "b": 3}'

# Test character counting
curl -X POST "http://localhost:3000/tools/countCharacter" \
  -H "Content-Type: application/json" \
  -d '{"character": "s", "text": "strawberrry"}'

​

Usage Examples

​

Calculator Tools (No Authentication)

# Basic addition
curl -X POST "http://localhost:3000/tools/add" \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 5}'

# Division with error handling
curl -X POST "http://localhost:3000/tools/divide" \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 0}'  # Will return error

# Factorial (requires confirmation)
curl -X POST "http://localhost:3000/tools/factorial" \
  -H "Content-Type: application/json" \
  -d '{"number": 5}'

# Percentage calculation
curl -X POST "http://localhost:3000/tools/percentage" \
  -H "Content-Type: application/json" \
  -d '{"percentage": 25, "of": 80}'

# Character counting in text
curl -X POST "http://localhost:3000/tools/countCharacter" \
  -H "Content-Type: application/json" \
  -d '{"character": "s", "text": "strawberrry"}'

# Expected response:
# {
#   "success": true,
#   "responseType": "mixed",
#   "data": {
#     "operation": "Count 's' in \"strawberrry\"",
#     "result": 1,
#     "message": "Calculated Count 's' in \"strawberrry\" = 1",
#     "tool_type": "calculator"
#   }
# }

​

GitHub Tools (Authentication Required)

# List repositories (requires GitHub token)
curl -X POST "http://localhost:3000/tools/listUserRepositories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_GITHUB_TOKEN" \
  -d '{"per_page": 5, "sort": "updated"}'

​

Available Tools

​

Calculator Tools

​

GitHub Tools (Private - Auth Required)

​

Authentication

• Calculator tools: No authentication required (public)
• GitHub tools: Bearer token authentication required (private)

​

API Endpoints

• GET /tools - Get list of available tools (public)
• POST /tools/:toolName - Execute a specific tool (auth depends on tool type)
• GET /health - Health check endpoint (shows tool authentication requirements)
• GET /docs - Swagger UI documentation (serves public/swagger.json)

​

Documentation & Examples

• Swagger Documentation - Available at /docs endpoint when server is running
• Postman Collection - Import Bhind-Agent-Starter.postman_collection.json for easy testing

​

Project Structure

src/
├── config/
│   └── tools.json          # Tool definitions with JSON Schema
├── controllers/
│   └── appController.ts    # Handles both calculator & GitHub tools
├── services/
│   ├── calculatorService.ts # Mathematical operations
│   └── githubService.ts     # Simple GitHub API calls
├── routes/
│   ├── toolsRoutes.ts      # GET /tools endpoint
│   └── appRoutes.ts        # POST /tools/:toolName endpoint
├── middlewares/
│   ├── auth.ts             # Authentication utilities
│   └── errorHandler.ts     # Error handling middleware
├── types/
│   └── agent.ts            # Response type definitions
├── __tests__/
│   └── calculatorService.test.ts # Comprehensive tests
├── app.ts                  # Express app configuration
└── server.ts              # Server entry point

​

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Format code
npm run format

# Development server with auto-reload
npm run dev

​

What This Starter Kit Demonstrates

• Public tools (Calculator - no authentication required)
• Authenticated tools (GitHub - Bearer token required)
• Mixed authentication patterns in a single agent
• Proper parameter validation using JSON Schema
• Advanced features like confirmationRequired
• Standardized response formats following agent specification

​

Features

​

Calculator Tools (No Authentication)

• 8 mathematical operations: Basic arithmetic, power, square root, percentage, factorial
• Parameter validation: Proper error handling for invalid inputs
• Confirmation required: Demonstrates user confirmation for certain operations

​

GitHub Tools (Authentication Required)

• Repository listing: List user’s GitHub repositories with Bearer token
• Simple REST API: Uses standard fetch calls (no heavy dependencies)
• Authentication demonstration: Shows how to handle Bearer tokens

​

Development Features

• Full TypeScript support with strict typing
• Comprehensive testing with Jest
• ESLint + Prettier for code quality
• JSON Schema validation for parameters
• Standardized error handling

​

Next Steps

1. Add more calculator functions: Trigonometry, logarithms, etc.
2. Add more authenticated tools: Twitter, Slack, database operations
3. Implement middleware authentication: Global auth patterns
4. Add validation middleware: Request/response validation
5. Add rate limiting: Protect expensive operations
6. Add database integration: Store calculation history

​

Agent Specification Compliance

• ✅ Required endpoints: GET /tools, POST /tools/:toolName
• ✅ Standardized response formats: BaseSuccessResponseDto, BaseErrorResponseDto
• ✅ JSON Schema parameter validation
• ✅ Tool confirmation flow
• ✅ Authentication patterns (Bearer tokens)
• ✅ Proper error handling and status codes

​

Need Help?

• Discord: Join our community and get help building your next cool agent!
• X: @bhindiai for the latest updates and new agent releases
• Email: info@bhindi.io