Azure AI Agents JavaScript Sample: Complete Guide to Building Intelligent File-Aware Agents

Azure AI Agents JavaScript Sample: Complete Guide to Building Intelligent File-Aware Agents

Project Announcement

I’m excited to share a new open-source project I’ve just published: Azure AI Agents JavaScript Sample! This comprehensive Node.js sample demonstrates how to work with Azure AI Project Agents, featuring advanced capabilities like file processing, vector stores, and intelligent document search.

🔗 Repository: github.com/cihancinar/azure-ai-agents-js-sample

What Makes This Sample Special

This isn’t just another chatbot example. The sample showcases production-ready patterns for building AI agents that can intelligently search through your documents and provide contextual responses based on your content.

🌟 Key Features

  • 🤖 Agent Management: Create, list, and delete AI agents with full lifecycle management
  • 📁 File Processing: Upload documents and create searchable vector stores automatically
  • 💬 Dual Conversation Modes: Both standard request-response and real-time streaming interactions
  • 🔍 Intelligent File Search: AI agents that can search through uploaded documents and provide contextual answers
  • 🧹 Resource Cleanup: Automatic cleanup of agents, files, and vector stores for cost management

Supported File Types

The sample supports a wide range of file types for agent file search, making it versatile for different use cases:

  • Code Files: .c, .cpp, .java, .php, .py, .rb, .js, .ts, .css, .sh
  • Documents: .doc, .docx, .pdf, .txt, .md, .tex
  • Web Files: .html, .json
  • Presentations: .pptx

Quick Start Guide

Getting started is straightforward. Here’s how you can have it running in minutes:

1. Clone and Setup

git clone https://github.com/cihancinar/azure-ai-agents-js-sample.git
cd azure-ai-agents-js-sample
npm install

2. Configure Environment

Create a .env.local file with your Azure AI Project details:

AZURE_AI_PROJECT_ENDPOINT_STRING=your_endpoint_here
AZURE_AI_MODEL=gpt-4o

3. Authentication Options

For Local Development:

az login

That’s it! The sample uses DefaultAzureCredential for seamless local development.

For Production: Add service principal credentials to your environment:

AZURE_TENANT_ID=your_tenant_id
AZURE_CLIENT_ID=your_client_id
AZURE_CLIENT_SECRET=your_client_secret

4. Add Your Documents

Place any supported documents in the docs/ folder. The sample includes a company_faq.txt as an example to get you started.

5. Run the Sample

npm start

What Happens When You Run It

The sample demonstrates a complete workflow:

  1. Creates an AI Agent with file search capabilities enabled
  2. Uploads documents from the docs/ folder to create a searchable knowledge base
  3. Demonstrates conversations where the agent can reference your uploaded documents
  4. Shows streaming responses for real-time interaction
  5. Optionally cleans up all created resources (commented out by default for inspection)

Code Architecture

The sample is designed for clarity and educational purposes:

├── azure-ai-agents.js     # Main application with all functionality
├── package.json           # Dependencies and scripts
├── .env.example           # Environment template
├── docs/                  # Your documents for search
│   └── company_faq.txt    # Sample document
└── README.md             # Comprehensive documentation

Key Functions Explained

  • createAgent() - Creates a new AI agent with specified capabilities
  • setupFileSearchTools() - Handles file uploads and vector store creation
  • startConversation() - Standard request-response interaction
  • startConversationWithStreaming() - Real-time streaming conversation
  • cleanup() - Resource management and cost control

Authentication Flexibility

One of the strengths of this sample is its flexible authentication approach:

Local Development

Uses Azure CLI authentication with DefaultAzureCredential. Perfect for development and testing.

Production Deployment

Uses service principal authentication with EnvironmentCredential. Ideal for CI/CD pipelines and production environments.

Error Handling & Best Practices

The sample includes comprehensive error handling for:

  • Missing environment variables
  • File upload failures
  • Agent creation/deletion issues
  • Conversation errors

Why I Built This

Working with Azure AI Agents in JavaScript can be challenging due to limited examples and documentation. This sample fills that gap by providing:

  • Real-world patterns for production use
  • Complete error handling for robust applications
  • Flexible authentication for different environments
  • Clear documentation with step-by-step instructions
  • Resource management to control costs

Get Started Today

Whether you’re building a customer support bot, a technical documentation assistant, or any AI agent that needs to understand your documents, this sample provides the foundation you need.

⭐ If this sample helps you, please give it a star on GitHub!

Resources & Next Steps

Have questions or suggestions? Feel free to open an issue on GitHub or reach out to me directly. I’d love to hear how you’re using this sample in your projects!