Add AGENTS.md file to align with AGENTS.md standards (Azure#3169)

Copilot · ronniegeraghty · heaths · web-flow · commit ff01b097da0f · 2025-10-09T21:45:57.000Z
- [x] Understand the issue and requirements - [x] Review existing .github/copilot-instructions.md - [x] Review CONTRIBUTING.md and README.md for context - [x] Create AGENTS.md file following agents.md canonical structure - [x] Include repository purpose and scope - [x] Document key workflows and commands - [x] Specify automation boundaries for agents - [x] Add guidance for safe CI/CD interactions - [x] Cross-link between .github/copilot-instructions.md and AGENTS.md - [x] Cross-link from CONTRIBUTING.md and README.md to AGENTS.md - [x] Validate the file format and content - [x] Address review feedback to improve accuracy and conciseness - [x] Clarify examples directory location and fix spelling - [x] Add rustfmt to cspell and enforce absolute links ## Summary Created a comprehensive AGENTS.md file at the root of the repository that: 1. **Defines repository purpose and scope**: Describes the Azure SDK for Rust, its status, primary language, and key technologies 2. **Documents repository structure**: Provides a clear overview of service directories vs. crate directories 3. **Specifies agent capabilities**: Lists recommended actions (code generation, code review, documentation, issue triage, refactoring) and restricted actions (no modifying generated code, breaking API compatibility, bypassing CI/CD checks, committing secrets, etc.) 4. **Describes key workflows**: Includes commands for building, testing (with provisioning), linting, formatting, code generation, and running examples 5. **Provides coding standards**: References .github/copilot-instructions.md for detailed Rust conventions, with correct guidance on azure_core::Result<T>, import consolidation, rustfmt, and absolute links 6. **Documents CI/CD integration**: Explains automated checks and references CONTRIBUTING.md for detailed Test Proxy usage 7. **Emphasizes safety and security**: Outlines code review, static analysis, secret scanning, and vulnerability reporting 8. **Cross-references documentation**: Links to relevant files like CONTRIBUTING.md, copilot-instructions.md, and Azure SDK design guidelines ### Latest Changes - **Added "rustfmt" to .vscode/cspell.json**: Ensures spell checking passes for this term - **Fixed relative link**: Updated .github/copilot-instructions.md to use absolute GitHub URL for AGENTS.md - **Added absolute link guidance**: AGENTS.md now includes repository requirement that all markdown links must be absolute URLs that work both online (from github.com) and offline (in IDE)  <details> <summary>Original prompt</summary> > > ---- > > *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](https://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](https://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](https://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](https://agents.md) > - [Example `.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-go/blob/main/.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](https://github.com/Azure/azure-sdk)) 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) > > <comments> > </comments> > </details> Fixes Azure#3168  --- 💡 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. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: ronniegeraghty <28957151+ronniegeraghty@users.noreply.github.com> Co-authored-by: heaths <1532486+heaths@users.noreply.github.com>
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -6,6 +6,8 @@ You are an expert Rust programmer. You write safe, efficient, maintainable, and
 -   Do not be overly apologetic and focus on clear guidance.
 -   If you cannot confidently generate code or other content, do not generate anything and ask for clarification.
 
+> **Note**: For comprehensive guidance on how AI agents should interact with this repository, including workflows, automation boundaries, and repository structure, see [AGENTS.md](https://github.com/Azure/azure-sdk-for-rust/blob/main/AGENTS.md).
+
 ## Prerequisites
 
 - To use Azure SDK MCP tool calls, the user must have PowerShell installed. Provide [PowerShell installation instructions](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) if not installed, and recommend restarting the IDE to start the MCP server.
diff --git a/.vscode/cspell.json b/.vscode/cspell.json
@@ -34,6 +34,7 @@
     "bugbug",
     "checkpointstore",
     "clippy",
+    "codeowners",
     "contoso",
     "cplusplus",
     "cpptools",
@@ -71,6 +72,7 @@
     "pwsh",
     "reqwest",
     "rsplit",
+    "rustfmt",
     "runtimes",
     "rustup",
     "schannel",
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,255 @@
+# AGENTS.md
+
+This document provides guidance for AI agents (e.g., GitHub Copilot, MCP servers, or LLM-based assistants) interacting with the Azure SDK for Rust repository.
+
+## Repository Overview
+
+### Purpose
+
+The Azure SDK for Rust provides Rust language bindings and client libraries for Azure services, following the [Azure SDK Design Guidelines for Rust](https://azure.github.io/azure-sdk/rust_introduction.html).
+
+### Status
+
+⚠️ Under active development. Large breaking changes may occur before 1.0 release.
+
+### Primary Language
+
+Rust (MSRV: 1.85)
+
+### Key Technologies
+
+- Rust toolchain with Cargo
+- TypeSpec for API specification and code generation
+- OpenTelemetry for distributed tracing
+- Test Proxy for recorded integration tests
+
+## Repository Structure
+
+```
+.
+├── sdk/                       # Service-specific crates organized by service
+│   └── <service>/            # Service directory (e.g., "keyvault", "storage")
+│       ├── <crate>/          # Service crate (e.g., "azure_security_keyvault_secrets")
+│       ├── assets.json       # Pointer to test recordings (may be under <crate>/)
+│       ├── test-resources.bicep # Test resource definitions (may be under <crate>/)
+│       └── tsp-location.yaml # Pointer to TypeSpec in azure-rest-api-specs (may be under <crate>/)
+├── eng/                      # Engineering system scripts and common tooling
+├── doc/                      # Additional documentation
+├── .github/              
+│   ├── copilot-instructions.md # Copilot-specific Rust coding guidelines
+│   ├── instructions/         # Agent instruction files for specific tasks
+│   └── prompts/              # Reusable Copilot prompts
+├── CONTRIBUTING.md           # Contribution guidelines (see for detailed workflows)
+└── README.md                 # Repository overview
+```
+
+## Agent Capabilities
+
+### Recommended Actions
+
+AI agents can assist with:
+
+1. **Code Generation**
+   - Writing new Rust code following repository conventions (see `.github/copilot-instructions.md`)
+   - Generating unit tests using `#[cfg(test)]` modules
+   - Creating integration tests with `#[recorded::test]` attributes (see `CONTRIBUTING.md` for details)
+   - Generating documentation tests in `.rs` files (avoid `no_run` when tests can be run)
+   - In README markdown files, use ` ```rust no_run` for examples with placeholders
+   - Running `rustfmt` on all generated code to ensure proper formatting
+
+2. **Code Review Support**
+   - Identifying potential bugs or safety issues
+   - Suggesting improvements for idiomatic Rust patterns
+   - Checking adherence to Azure SDK design guidelines
+   - Reviewing error handling using `azure_core::Result<T>`
+
+3. **Documentation**
+   - Improving inline documentation (using `///` doc comments)
+   - Updating README files
+   - Creating or updating CHANGELOG entries (see `.github/instructions/changelog.instructions.md`)
+   - Writing hero scenario examples in doc comments (avoid examples in `examples/` directories unless demonstrating primary use cases)
+
+4. **Issue Triage**
+   - Labeling issues with appropriate tags
+   - Identifying duplicate issues
+   - Suggesting relevant code owners based on `CODEOWNERS`
+   - Summarizing issue discussions
+
+5. **Refactoring**
+   - Applying clippy suggestions
+   - Improving code organization and modularity
+   - Updating dependencies in `Cargo.toml`
+   - Consolidating imports (e.g., `use std::{borrow::Cow, marker::PhantomData};` instead of separate lines)
+
+### Restricted Actions
+
+AI agents **should not**:
+
+1. **Modify Generated Code**
+   - Never edit files in `generated/` subdirectories
+   - These are produced by TypeSpec code generators and will be overwritten
+   - Instead, propose changes to TypeSpec specifications in [Azure/azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs)
+
+2. **Break API Compatibility**
+   - Avoid introducing breaking changes without explicit approval
+   - Check if changes affect public APIs before proceeding
+   - Consider deprecation process (see `doc/deprecation-process.md`)
+
+3. **Bypass CI/CD Checks**
+   - Do not suggest skipping or disabling CI checks
+   - All code must pass `cargo build`, `cargo test`, and `cargo clippy`
+
+4. **Commit Secrets**
+   - Never include credentials, keys, or tokens in code
+   - Use environment variables for sensitive data
+   - Sanitize test recordings to remove secrets
+
+5. **Modify Security or License Files**
+   - Do not alter `SECURITY.md`, `LICENSE.txt`, or `CODE_OF_CONDUCT.md` without maintainer approval
+
+## Key Workflows
+
+### Building
+
+```bash
+# Build a specific crate
+cargo build -p <crate-name>
+
+# Build entire workspace (not recommended unless necessary)
+cargo build --workspace
+```
+
+### Testing
+
+```bash
+# Run tests for a specific crate
+cargo test -p <crate-name>
+
+# Run integration tests with recordings
+cargo test -p <crate-name> --test <test-name>
+
+# Provision test resources (see CONTRIBUTING.md for details)
+eng/common/TestResources/New-TestResources.ps1 -ServiceDirectory <service>
+
+# Record new test sessions (requires provisioned resources)
+AZURE_TEST_MODE=record cargo test -p <crate-name> --test <test-name>
+```
+
+See `CONTRIBUTING.md` for comprehensive testing guidance including debugging, Test Proxy usage, and trace logging.
+
+### Linting and Formatting
+
+```bash
+# Check for common issues
+cargo clippy -p <crate-name>
+
+# Auto-fix some issues
+cargo clippy --fix -p <crate-name>
+
+# Format code
+cargo fmt -p <crate-name>
+```
+
+### Code Generation
+
+For crates with TypeSpec specifications:
+
+```bash
+cd sdk/<service>/<crate-name>
+tsp-client update
+```
+
+### Running Examples
+
+```bash
+cargo run --package <crate-name> --example <example-name>
+```
+
+## Coding Standards
+
+Agents should follow guidelines in `.github/copilot-instructions.md` and `CONTRIBUTING.md`, including:
+
+- **Naming Conventions**: 
+  - Types/variants: `PascalCase`
+  - Functions/fields/parameters: `snake_case`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Crates/modules: `snake_case`
+
+- **Import Style**:
+  - Explicit imports (no `use foo::*`)
+  - Consolidate related imports (e.g., `use std::{borrow::Cow, marker::PhantomData};`)
+  - Prefer `crate::` for internal references
+
+- **Error Handling**:
+  - Service crate code should return `azure_core::Result<T>` (where `E` defaults to `azure_core::Error`)
+  - Use the `?` operator for error propagation
+  - Examples should use `Result<(), Box<dyn std::error::Error>>`
+
+- **Documentation**:
+  - All public APIs need `///` doc comments
+  - Include runnable doc test examples where appropriate
+  - Hero scenario examples under the `examples/` directory should have `#[tokio::main]` async main functions
+  - Use absolute links in markdown files (e.g., `https://github.com/Azure/azure-sdk-for-rust/blob/main/AGENTS.md`) instead of relative links (e.g., `../AGENTS.md`)
+  - Links must work both online (from github.com) and offline (when viewed in an IDE)
+
+- **Testing**:
+  - Place unit tests in `#[cfg(test)] mod tests`
+  - Use `#[recorded::test]` for integration tests (see `CONTRIBUTING.md`)
+  - Test names should be descriptive, not prefixed with "test"
+
+## CI/CD Integration
+
+All pull requests trigger:
+- `cargo build` - Compilation check
+- `cargo test` - Unit and integration tests
+- `cargo clippy` - Lint checks
+- `cargo fmt --check` - Format validation
+- License/CLA verification
+- Code coverage analysis
+
+Integration tests use the Azure SDK Test Proxy for recording/playback. See `CONTRIBUTING.md` for Test Proxy setup and usage.
+
+## Safety and Security
+
+1. **Code Review**: All changes require review and approval from code owners
+2. **Static Analysis**: Must pass `cargo clippy` without warnings
+3. **Secret Scanning**: Automated checks prevent committing credentials
+4. **Dependencies**: Managed through workspace `Cargo.toml`, vetted for security
+5. **Vulnerability Reporting**: Via MSRC at <secure@microsoft.com>
+
+## Cross-References
+
+For detailed guidance, see:
+
+- **Rust Coding Guidelines**: `.github/copilot-instructions.md`
+- **Contribution Workflows**: `CONTRIBUTING.md`
+- **Changelog Guidelines**: `.github/instructions/changelog.instructions.md`
+- **Git Commit Standards**: `doc/git-commit-instructions.md`
+- **Deprecation Process**: `doc/deprecation-process.md`
+- **Azure SDK Design Guidelines**: https://azure.github.io/azure-sdk/rust_introduction.html
+
+## Agent-Specific Instructions
+
+Additional specialized instructions for specific workflows can be found in:
+- `.github/instructions/` - Task-specific agent instructions
+- `.github/prompts/` - Reusable Copilot prompts (use `#prompt` in Copilot)
+
+## Getting Help
+
+- **Issues**: https://github.com/Azure/azure-sdk-for-rust/issues
+- **Discussions**: Use issue comments or StackOverflow with `azure` + `rust` tags
+- **Code Owners**: See `.github/CODEOWNERS` for service-specific contacts
+
+## Telemetry and Privacy
+
+The SDK includes telemetry via `User-Agent` headers. Follow Microsoft Privacy Statement: https://go.microsoft.com/fwlink/?LinkID=824704
+
+## License
+
+All contributions are licensed under the MIT License. See `LICENSE.txt`.
+
+---
+
+**Last Updated**: 2025-01-20  
+**Version**: 1.0  
+**Canonical Spec**: https://agents.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,6 +29,8 @@ To generate a new performance test, for example, you might prompt with:
 Using #perf-test.prompt.md generate a perf test for SecretClient::get_secret.
 ```
 
+For comprehensive guidance on how AI agents should interact with this repository, including workflows, automation boundaries, and safety guidelines, see [AGENTS.md](https://github.com/Azure/azure-sdk-for-rust/blob/main/AGENTS.md).
+
 ## Generated code
 
 If you want to contribute to a file that is generated (the file is located in a `generated` subdirectory), the best approach is to open a PR on the TypeSpec specification since we cannot replace generated code that will be replaced when regenerated.
diff --git a/README.md b/README.md
@@ -102,6 +102,8 @@ We would love to incorporate the community's input into our library design proce
 
 For details on contributing to this repository, see the [contributing guide](https://github.com/Azure/azure-sdk-for-rust/blob/main/CONTRIBUTING.md).
 
+For guidance on how AI agents should interact with this repository, see [AGENTS.md](https://github.com/Azure/azure-sdk-for-rust/blob/main/AGENTS.md).
+
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
 the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
