Add comprehensive AGENTS.md documentation for coding agent onboarding

[Copilot]

Overview

This PR adds a comprehensive AGENTS.md file to help coding agents work more efficiently with this repository. The documentation significantly reduces the time needed for agents to understand the codebase, set up their environment, and make changes correctly.

What's Included

The AGENTS.md file provides:

1. Repository Overview

Clear description of the repository's purpose: a collection of Python scripts demonstrating OpenAI API usage with multiple LLM providers (GitHub Models, Azure OpenAI, OpenAI.com, and Ollama).

2. Code Layout & Architecture

Complete inventory of important files with descriptions:

• 25 Python example scripts organized by category (chat completions, function calling, structured outputs, RAG)
• Infrastructure files (Bicep templates, azd scripts for Azure provisioning)
• Configuration files (pyproject.toml, requirements files, pre-commit config)
• CI/CD workflows (linting/formatting checks, GitHub Models integration tests)
• Dev container configurations (4 variants for different LLM providers)

3. Environment Setup Instructions

Agent-facing guidance for:

• Creating Python virtual environments
• Installing dependencies (requirements.txt, requirements-rag.txt, requirements-dev.txt)
• Detecting available LLM providers by checking environment variables:
  • GitHub Models (RECOMMENDED): Check for GITHUB_TOKEN environment variable
  • Azure OpenAI: Check for AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_CHAT_DEPLOYMENT
  • OpenAI.com: Check for OPENAI_API_KEY
  • Ollama: Check if ollama is installed and running with command -v ollama and ollama list

4. Testing & Validation

Commands for:

• Running ruff for linting
• Running black for code formatting
• Setting up and using pre-commit hooks
• Manual testing with GitHub Models

5. Important Notes & Troubleshooting

Documentation of:

• Common errors and their solutions (missing dependencies, configuration issues, model compatibility)
• Model compatibility requirements for function calling
• CI/CD workflow differences (uv vs pip)
• Azure provisioning costs and cleanup procedures
• RAG script dependencies

6. Agent Workflow Recommendations

Best practices for making code changes:

1. Install dependencies first
2. Run linters before changes to understand baseline
3. Make minimal, surgical changes
4. Run linters after changes
5. Manually test with GitHub Models
6. Update Spanish translations if applicable

Benefits

This documentation will help coding agents:

• ✅ Reduce exploration time - Less need for grep, find, and code search
• ✅ Prevent common errors - Documented gotchas and solutions
• ✅ Minimize build failures - Clear linting, formatting, and testing instructions
• ✅ Work faster - Complete context in one file
• ✅ Make better decisions - Understanding of architecture and dependencies
• ✅ Detect available resources - Check which LLM providers are accessible

Validation

All commands and instructions in AGENTS.md have been tested and verified to work correctly:

• Virtual environment setup
• Dependency installation
• Linting and formatting commands
• Model names and configurations
• Infrastructure file references
• Environment variable detection scripts

Fixes #3

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add AGENTS.md to this repo</issue_title>
<issue_description>Add an AGENTS.md to this repo.

Your task is to "onboard" this repository to Copilot coding agent by adding an AGENTS.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently.

You will do this task only one time per repository and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions.

Goals

• Reduce the likelihood of a coding agent pull request getting rejected by the user due to
  generating code that fails the continuous integration build, fails a validation pipeline, or
  having misbehavior.
• Minimize bash command and build failures.
• Allow the agent to complete its task more quickly by minimizing the need for exploration using grep, find, str_replace_editor, and code search tools.

Sections

Add the following high level sections about the codebase to reduce the amount of searching the agent has to do to understand the codebase each time:

• Overview: A summary of what the repository does.
• Code layout: A listing of the important files for the repository: Python, Bicep, YAML config, etc, with their path and description. Do not list unimportant files like test data files. Include key facts about the layout and architecture of the codebase to help the agent find where to make changes with minimal searching.
• Running the code: A description of the steps to create the environment to run the repository code. Prefer using GitHub Models if that's an option for any LLM configuration, since the coding agent often won't have access to Azure OpenAI models.
• Running the tests: Steps needed to run the tests.
• Upgrading Python dependencies: What command to run to upgrade a given dependency (command depends if repo uses uv, pip, pop-compile, etc).

Tips for ensuring correctness:

• Any commands in the instructions should be validated by running it to ensure that it works correctly as well as any preconditions and postconditions.
• Try cleaning the repo and environment and running commands in different orders and document errors and and misbehavior observed as well as any steps used to mitigate the problem.
• Use language to indicate when something should always be done. For example: "always run npm install before building".
• Record any validation steps from documentation.

Steps

• Perform a comprehensive inventory of the codebase. Search for and view:
• README.md, CONTRIBUTING.md, and all other documentation files.
• Search the codebase for build steps and indications of workarounds like 'HACK', 'TODO', etc.
• All scripts, particularly those pertaining to build and repo or environment setup.
• All build and actions pipelines.
• All project files.
• All configuration and linting files.
• For each file:
• think: are the contents or the existence of the file information that the coding agent will need to implement, build, test, validate, or demo a code change?
• If yes:
  • Document the command or information in detail.
  • Explicitly indicate which commands work and which do not and the order in which commands should be run.
  • Document any errors encountered as well as the steps taken to workaround them.
• Document any other steps or information that the agent can use to reduce time spent exploring or trying and failing to run bash commands.
• Finally, explicitly instruct the agent to trust the instructions and only perform a search if the information in the instructions is incomplete or found to be in error.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #3

---

💡 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 in the docs.

[pamelafox]

Agents cant create a GITHUB PAT, but sometimes agent work in environment where theyre available. They can check to see if GITHUB_TOKEN is an env var.

[Copilot]

Updated to include agent-facing check for GITHUB_TOKEN environment variable. Commit 35c3d46

[pamelafox]

Agents cant do this themselves. They could check to see if the AZURE env variables already exist in the environment however.

[Copilot]

Updated to include agent-facing check for AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_CHAT_DEPLOYMENT environment variables. Commit 35c3d46

[pamelafox]

Ditto, all agents can do is check to see if OPENAI_API_KEY env var exists in environment, they cant make it themselves.

[Copilot]

Updated to include agent-facing check for OPENAI_API_KEY environment variable. Commit 35c3d46

[pamelafox]

Agents could check to see if ollama is running by running "ollama" and "ollama models list"

[Copilot]

Updated to include agent-facing check using "command -v ollama" and "ollama list" to verify if Ollama is installed and running. Commit 35c3d46

[pamelafox]

This repo does not actually compile dependencies, so this sectio can be entirely removed.

[Copilot]

Removed the entire "Upgrading Python Dependencies" section. Commit 35c3d46

[pamelafox]

Please reword the GitHub Models/Azure/OpenAI.com sections to be more agent-facing, per my comments

[pamelafox]

@copilot Address my feedback