Add AGENTS.md file for AI coding agent support

[Copilot]

Overview

This PR adds a comprehensive AGENTS.md file to the repository root, following the open format specified at https://agents.md/. This file serves as a "README for agents" - providing AI coding agents with the detailed context and instructions they need to work effectively on this project.

What is AGENTS.md?

AGENTS.md is an emerging standard that provides a predictable location for agent-specific documentation. It complements the human-focused README.md by containing detailed technical instructions that coding agents need but might clutter the main README. The format is compatible with 20+ AI coding tools including Cursor, Aider, GitHub Copilot, and many others.

What's Included

The AGENTS.md file provides comprehensive coverage of the Contoso Chat project:

Core Development Information

• Project Overview: RAG-based retail copilot architecture with Azure AI Foundry and Prompty
• Key Technologies: Python 3.10+, FastAPI, Azure OpenAI, Azure AI Search, Azure Cosmos DB, Azure Container Apps
• Setup Commands: Three setup paths (GitHub Codespaces, Dev Containers, Local) with exact installation commands
• Development Workflow: Complete Azure Developer CLI (azd) workflow with provisioning and deployment steps

Testing and Quality

• Manual Testing: Interactive testing via FastAPI Swagger UI at /docs endpoint
• AI-Assisted Evaluation: Automated evaluation framework using custom Prompty evaluators
• CI/CD Integration: GitHub Actions workflow for continuous evaluation

Build and Deployment

• Docker Build: Containerization process and commands
• Azure Deployment: Step-by-step deployment using azd with expected infrastructure outcomes
• Infrastructure as Code: Bicep template information and configuration details

Security and Best Practices

• Authentication: Managed Identity usage for Azure services
• Secrets Management: Azure Key Vault integration
• Security Scanning: GitHub Actions security tooling
• Responsible AI: Content safety and best practices

Troubleshooting Support

• Common Issues: Region availability, quota limits, connection problems
• Logging and Observability: Application Insights, Prompty tracing, FastAPI logs
• Quick Reference: Command cheat sheet for fast lookup

Why This Matters

This file enables AI coding agents to:

• Understand the project architecture and technology stack immediately
• Execute exact commands for setup, development, testing, and deployment
• Navigate the codebase with knowledge of file organization and patterns
• Debug issues using project-specific troubleshooting guidance
• Follow security best practices and responsible AI guidelines

Implementation Approach

The AGENTS.md file was created by:

1. Analyzing the repository structure, including code, configuration, and documentation
2. Reviewing existing workflows in GitHub Actions
3. Extracting key commands from README.md and scripts
4. Documenting undocumented workflows discovered through code analysis
5. Organizing information in an agent-friendly, actionable format

All content is specific to this repository and based on actual analysis - no generic template content was copied.

Verification

• ✅ File created at repository root as AGENTS.md
• ✅ No other files were modified (minimal change principle)
• ✅ Contains actionable, executable commands
• ✅ Follows the agents.md open format guidelines
• ✅ Comprehensive coverage of all development workflows

Closes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add AGENTS.md file</issue_title>
<issue_description>Title: Add AGENTS.md file

Plan

We need to add a specific file named AGENTS.md into this repository. To do that, think through and analyze the following plan. After careful analysis, perform each step exactly as stated.

1. Scan the repository to get a complete understanding of what it contains.
2. Create an AGENTS.md file at the root of the repository if it does not exist. See "## AGENTS.md Instructions" below and follow that general template format based upon what you found in this repository. In addition to the provided template below, research the additional template available at https://github.com/gakeez/agents_md_collection/tree/main/examples so that you understand your options for creating the AGENTS.md file.

RULES:

• ONLY add the AGENTS.md file if it does not already exist. DO NOT modify any other files.
• DO NOT COPY the actual content from the template that is mentioned below. Use the template to understand the format that should be used to create the file.

AGENTS.md Instructions

Create high‑quality AGENTS.md file

You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/.

AGENTS.md is an open format designed to provide coding agents with the context and instructions they need to work effectively on a project.

What is AGENTS.md?

AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It complements README.md by containing detailed technical context that coding agents need but might clutter a human-focused README.

Key Principles

• Agent-focused: Contains detailed technical instructions for automated tools
• Complements README.md: Doesn't replace human documentation but adds agent-specific context
• Standardized location: Placed at repository root (or subproject roots for monorepos)
• Open format: Uses standard Markdown with flexible structure
• Ecosystem compatibility: Works across 20+ different AI coding tools and agents

File Structure and Content Guidelines

1. Required Setup

• Create the file as AGENTS.md in the repository root
• Use standard Markdown formatting
• No required fields - flexible structure based on project needs

2. Essential Sections to Include

Project Overview

• Brief description of what the project does
• Architecture overview if complex
• Key technologies and frameworks used

Setup Commands

• Installation instructions
• Environment setup steps
• Dependency management commands
• Database setup if applicable

Development Workflow

• How to start development server
• Build commands
• Watch/hot-reload setup
• Package manager specifics (npm, pnpm, yarn, etc.)

Testing Instructions

• How to run tests (unit, integration, e2e)
• Test file locations and naming conventions
• Coverage requirements
• Specific test patterns or frameworks used
• How to run subset of tests or focus on specific areas

Code Style Guidelines

• Language-specific conventions
• Linting and formatting rules
• File organization patterns
• Naming conventions
• Import/export patterns

Build and Deployment

• Build commands and outputs
• Environment configurations
• Deployment steps and requirements
• CI/CD pipeline information

3. Optional but Recommended Sections

Security Considerations

• Security testing requirements
• Secrets management
• Authentication patterns
• Permission models

Monorepo Instructions (if applicable)

• How to work with multiple packages
• Cross-package dependencies
• Selective building/testing
• Package-specific commands

Pull Request Guidelines

• Title format requirements
• Required checks before submission
• Review process
• Commit message conventions

Debugging and Troubleshooting

• Common issues and solutions
• Logging patterns
• Debug configuration
• Performance considerations

Example Template

Use this as a starting template and customize based on the specific project:

# AGENTS.md

## Project Overview

[Brief description of the project, its purpose, and key technologies]

## Setup Commands

- Install dependencies: `[package manager] install`
- Start development server: `[command]`
- Build for production: `[command]`

## Development Workflow

- [Development server startup instructions]
- [Hot reload/watch mode information]
- [Environment variable setup]

## Testing Instructions

- Run all tests: `[command]`
- Run unit tests: `[command]`
- Run integration tests: `[command]`
- Test coverage: `[command]`
- [Specific testing patterns or requirements]

## Code Style

- [Language and framework conventions]
- [Linting rules and commands]
- [Formatting requirements]
- [File orga...

</details>
Fixes Azure-Samples/contoso-chat#267

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.