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.

[github-actions]

Hi @copilot. Thank you for your interest in helping to improve the Azure SDK experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.