> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bhindi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with building your own custom agent on Bhindi Platform in a few minutes!

## 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

Access our comprehensive TypeScript-based agent starter kit to begin building intelligent agents with the Bhindi.io platform.

**Repository**: [github.com/upsurgeio/bhindi-agent-starter](https://github.com/upsurgeio/bhindi-agent-starter)

This open-source starter kit provides a robust foundation for agent development, featuring:

* **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](https://bhindi.io) agent specification

The starter kit serves as both a learning resource and a production-ready template for developers looking to create custom agents on the Bhindi.io platform.

### Available OAuth Integrations

Here is a list of Bhindi Agents you can have access of in your agent!

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

You can find these agents and their available tools at [https://directory.bhindi.io/](https://directory.bhindi.io/)

## Quick Start

### 0. Clone the agent starter template

```bash theme={null}
git clone https://github.com/upsurgeio/bhindi-agent-starter
```

### 1. Install Dependencies

```bash theme={null}
npm install
```

### 2. Build the Project

```bash theme={null}
npm run build
```

### 3. Start the Server

```bash theme={null}
npm start
# or for development with auto-reload:
npm run dev
```

### 4. Test the API

```bash theme={null}
# 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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

| Tool             | Description                         | Special Features                    |
| :--------------- | :---------------------------------- | :---------------------------------- |
| `add`            | Add two numbers                     | Basic operation                     |
| `subtract`       | Subtract two numbers                | `confirmationRequired: true`        |
| `multiply`       | Multiply two numbers                | Basic operation                     |
| `divide`         | Divide two numbers                  | Error handling for division by zero |
| `power`          | Calculate a^b                       | Supports negative exponents         |
| `sqrt`           | Square root                         | Error handling for negative inputs  |
| `percentage`     | Calculate percentage                | Handles decimal percentages         |
| `factorial`      | Calculate factorial                 | `confirmationRequired: true`        |
| `countCharacter` | Count character occurrences in text | String manipulation                 |

### GitHub Tools (Private - Auth Required)

| Tool                   | Description              | Authentication        |
| :--------------------- | :----------------------- | :-------------------- |
| `listUserRepositories` | List user's repositories | Bearer token required |

## Authentication

This agent demonstrates **hybrid 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

```bash theme={null}
# 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

This starter kit teaches you how to build agents with:

* **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

Once you understand this agent, you can:

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

This starter follows the [Bhindi.io](https://bhindi.io) agent specification:

* ✅ 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

Perfect for learning how to build production-ready agents! 🎉

## Need Help?

We're here for you! You can reach out to us at:

* **Discord**: [Join our community](https://discord.gg/hSfTG33ymy) and get help building your next cool agent!
* **X**: [@bhindiai](https://x.com/bhindiai) for the latest updates and new agent releases
* **Email**: [info@bhindi.io](mailto:info@bhindi.io)