Add AGENTS.md file to align with AGENTS.md standards

[Copilot]

• Review existing .github/copilot-instructions.md file
• Understand repository structure and purpose
• Create AGENTS.md file at repository root following AGENTS.md standards
• Add repository metadata and AI agent guidelines
• Include SDK-specific automation workflows (codegen, API review, test matrix)
• Cross-link between .github/copilot-instructions.md and AGENTS.md
• Verify the content is accurate and helpful
• Fix broken relative links - replace with full GitHub URLs
• Replace non-ASCII characters with ASCII equivalents
• Update code generation section to reflect TypeSpec usage

Summary

Created a comprehensive AGENTS.md file at the repository root that provides guidance for AI agents working with the Azure SDK for C++ repository. The file includes:

• Repository Purpose: Description of the Azure SDK for C++ and its key technologies
• Agent Capabilities: Clear boundaries for supported, cautioned, and prohibited actions
• Key Workflows: Build, test, coverage, and documentation commands
• Repository Structure: Overview of directory layout (using ASCII characters only)
• SDK-Specific Workflows: Code generation using TypeSpec, API review, test matrix, versioning
• Testing Guidelines: Test modes, environment setup, and test proxy usage
• Common Scenarios: Adding services, fixing bugs, adding features
• Cross-References: Links to related documentation and resources (using full GitHub URLs)
• Best Practices: Guidelines for effective agent contributions

Also updated .github/copilot-instructions.md to cross-reference the new AGENTS.md file using full GitHub URLs for discoverability.

Latest Changes

Updated the code generation section to reflect that the C++ repository uses TypeSpec with the typespec-cpp emitter (https://github.com/azure/typespec-cpp) rather than AutoRest/Swagger. The section now accurately describes:

• TypeSpec project structure with tspconfig.yaml and tsp-location.yaml files
• Configuration through @azure-tools/typespec-cpp emitter
• Generated code locations
• Agent guidance for working with TypeSpec-generated code

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add AGENTS.md file</issue_title>
<issue_description># 🧩 Add AGENTS.md file to align with AGENTS.md standards

📄 Description

This repository currently includes a .github/copilot-instructions.md file, but it does not yet have an AGENTS.md file to describe how AI agents (e.g., Copilot, MCP, or LLM-based assistants) should interact with this repository.

To align with emerging AGENTS.md standards and ensure consistent developer experiences across Azure SDK repositories, we should add a top-level AGENTS.md file that defines:

• Repository purpose and scope
• Key workflows, commands, and automation boundaries for agents
• Supported contribution actions (e.g., PR triage, labeling, issue summarization)
• Guidance for safe and effective agent interactions with CI/CD pipelines, SDK tests, and documentation

✅ Proposed Tasks

• Review existing .github/copilot-instructions.md and identify relevant guidance to merge or reference in AGENTS.md.
• Create an AGENTS.md file at the root of the repository following the canonical structure defined at AGENTS.md.
• Cross-link between .github/copilot-instructions.md and AGENTS.md for discoverability.
• (Optional) Add repository metadata in AGENTS.md to describe SDK-specific automation workflows (e.g., codegen, API review, test matrix).

📘 Example References

• AGENTS.md — canonical spec
• Example .github/copilot-instructions.md

🧭 Context

This issue is part of a broader initiative to introduce AGENTS.md across all Azure SDK repositories (see the Azure SDK org overview) to standardize AI agent documentation and improve consistency in automation and Copilot-based contributions.</issue_description>

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

Fixes #6776

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[ronniegeraghty]

@copilot please fix these invalid links:
'file:///D:/a/_work/1/s/.github/copilot-instructions.md' has 1 broken link(s):
../AGENTS.md
'file:///D:/a/_work/1/s/AGENTS.md' has 5 broken link(s):
.github/copilot-instructions.md
CONTRIBUTING.md
doc/TestProxy.md
doc/PerformanceTesting.md
doc/DistributedTracing.md

Do not use relative links. Use the full URL links.

[Copilot]

@copilot please fix these invalid links:
'file:///D:/a/_work/1/s/.github/copilot-instructions.md' has 1 broken link(s):
../AGENTS.md
...

Fixed in commit 6c3a77c. All relative links have been replaced with full GitHub URLs in both AGENTS.md and .github/copilot-instructions.md.

[ronniegeraghty]

@copilot,
Can you fix the following pipeline error that says the files can only have valid ASCII characters:

Validate that the files in the repo contain only ASCII characters, saved as UTF-8, without a BOM at the start.
./AGENTS.md:25:### ✅ Supported Agent Actions
./AGENTS.md:52:### ⚠️ Actions Requiring Caution
./AGENTS.md:70:### 🚫 Actions Outside Agent Scope
./AGENTS.md:162:├── .github/              # GitHub configuration and workflows
./AGENTS.md:163:│   ├── copilot-instructions.md  # Copilot-specific guidance
./AGENTS.md:164:│   └── workflows/        # CI/CD workflows
./AGENTS.md:165:├── cmake-modules/        # CMake helper modules
./AGENTS.md:166:├── doc/                  # Documentation
./AGENTS.md:167:├── eng/                  # Engineering system scripts
./AGENTS.md:168:│   ├── common/           # Shared scripts across Azure SDKs
./AGENTS.md:169:│   └── docs/             # Documentation generation
./AGENTS.md:170:├── samples/              # Sample applications
./AGENTS.md:171:├── sdk/                  # SDK service libraries
./AGENTS.md:172:│   ├── core/             # Core libraries (azure-core, azure-core-amqp, etc.)
./AGENTS.md:173:│   ├── storage/          # Storage services (blobs, files, queues)
./AGENTS.md:174:│   ├── identity/         # Authentication and identity
./AGENTS.md:175:│   ├── keyvault/         # Key Vault (keys, secrets, certificates)
./AGENTS.md:176:│   └── template/         # Template for new services
./AGENTS.md:177:├── tools/                # Development tools
./AGENTS.md:178:├── vcpkg.json            # Package dependencies manifest
./AGENTS.md:179:├── CMakeLists.txt        # Root CMake configuration
./AGENTS.md:180:├── CONTRIBUTING.md       # Contribution guidelines
./AGENTS.md:181:└── AGENTS.md             # This file
Files found with non-ASCII characters: 23

[Copilot]

@copilot,
Can you fix the following pipeline error that says the files can only have valid ASCII characters:

...

Fixed in commit {commit_hash}. All non-ASCII characters have been replaced with ASCII equivalents:

• Removed emoji from section headers (✅ → "Supported", ⚠️ → "Requiring Caution", 🚫 → "Outside Scope")
• Replaced box-drawing characters in directory tree with ASCII (+, -) characters

[RickWinter]

@ronniegeraghty We should take this as the basis for our agent work. Its not perfect but its better than nothing. We can evolve it over time.