{"owner":"Azure","repo":"azure-sdk-for-python","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md - Azure SDK for Python\n\nThis file describes how AI agents (e.g., GitHub Copilot, MCP servers, or LLM-based assistants) should interact with this repository.\n\n## Repository Overview\n\n**Purpose**: This repository contains the active development of the Azure SDK for Python, providing client libraries and management libraries for Azure services.\n\n**Scope**: \n- 100+ Python packages for Azure services\n- Client libraries for data plane operations\n- Management libraries for Azure Resource Manager (ARM)\n- Shared core functionality (authentication, retries, logging, transport)\n- TypeSpec-based SDK generation from API specifications\n- Comprehensive testing, validation, and documentation infrastructure\n\n**Main Branch**: `main`\n\n**Key Documentation**:\n- [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html)\n- [Contributing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md)\n- [Developer Documentation](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev)\n\n## Repository Structure\n\n```\nazure-sdk-for-python/\n├── sdk/                    # Service-specific libraries (e.g., sdk/storage/, sdk/ai/)\n├── eng/                    # Engineering system tools and configurations\n├── doc/                    # Developer documentation and guides\n├── scripts/                # Automation scripts\n├── .github/                # GitHub workflows, Copilot instructions, skills, and prompts\n│   ├── copilot-instructions.md  # Detailed Copilot-specific guidance\n│   ├── skills/             # Reusable Copilot skills (e.g., find-package, fix-pylint)\n│   └── prompts/            # Copilot prompt files for common tasks\n└── tools/                  # Development tools\n```\n\n## AI Agent Guidelines\n\n### Supported Actions\n\nAI agents can assist with the following activities:\n\n#### Code Generation & Development\n- **TypeSpec SDK Generation**: Generate Python SDKs from TypeSpec specifications\n  - Follow the complete workflow in `.github/copilot-instructions.md`\n  - Use MCP tools for environment verification, code generation, and validation\n  - Time estimate: 10-15 minutes for full generation workflow\n  \n- **Code Fixes**: Address linting, type checking, and validation issues\n  - Pylint, MyPy, Pyright, Verifytypes, Sphinx warnings\n  - Follow official guidelines and existing patterns\n  - Make minimal, surgical changes\n\n- **Documentation**: Update CHANGELOG.md, README files, and API documentation\n  - Follow existing formatting conventions\n  - Include version information and release dates\n\n#### Testing & Validation\n- **Run Tests**: Execute test suites using the `azpysdk` test runner\n  - Unit tests, integration tests, samples\n  - Support both local and CI environments\n  \n- **Static Analysis**: Run and fix issues from:\n  - Pylint (code quality)\n  - MyPy, Pyright (type checking)\n  - Bandit (security)\n  - Black (formatting)\n  - Sphinx (documentation)\n\n#### Pull Request Management\n- **PR Creation**: Create draft PRs with descriptive titles and descriptions\n- **PR Review**: Analyze PR feedback and make requested changes\n- **Status Checks**: Monitor CI/CD pipeline status and address failures\n\n#### Issue Triage & Labeling\n- **Issue Analysis**: Review and categorize issues\n- **Service Labels**: Validate and create service labels (e.g., `Azure.AI.Projects`)\n- **CODEOWNERS**: Validate and update CODEOWNERS entries\n\n### Relationship to Copilot Instructions\n\nThis `AGENTS.md` file is the primary reference for AI agents working in this repository. It follows the [AGENTS.md standard](https://github.com/agentsmd/agents.md) that most AI coding tools recognize automatically. For additional Copilot-specific guidance (e.g., TypeSpec generation details, MCP tool usage), see [`.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md). Reusable skills are available in [`.github/skills/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/skills/) and prompt templates in [`.github/prompts/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/prompts/).\n\n### Key Workflows\n\n#### 1. TypeSpec SDK Generation Workflow\n\n**Prerequisites**:\n- GitHub CLI authenticated (`gh auth login`)\n- Feature branch (not `main`)\n- PowerShell installed (for MCP tools)\n- Python virtual environment active\n\n**Steps**:\n1. **Environment Verification** - Use `verify_setup` MCP tool\n2. **SDK Generation** - Use azure-sdk-python-mcp generation tools (~2 minutes)\n3. **Static Validation** - Run sequential validation steps (~3-5 minutes each):\n   - Pylint, MyPy, Pyright, Verifytypes\n   - Sphinx, Mindependency, Bandit, Black\n   - Samples, Breaking changes\n4. **Documentation Update** - Update CHANGELOG.md and version files\n5. **Commit & Push** - Stage, commit, and push changes\n6. **PR Creation** - Create draft PR with generated description\n7. **Handoff** - Provide PR link for azure-rest-api-specs agent\n\n**Estimated Time**: 10-15 minutes\n\n#### 2. Code Quality Workflow\n\n**Running Validation**:\n```bash\n# Use azpysdk with appropriate environment from the package directory\nazpysdk <environment> .\n\n# Examples:\nazpysdk pylint .\nazpysdk mypy .\n```\n\n**Fixing Issues**:\n- Reference official guidelines:\n  - [Pylint Guidelines](https://github.com/Azure/azure-sdk-tools/blob/main/tools/pylint-extensions/azure-pylint-guidelines-checker/README.md)\n  - [MyPy Type Checking Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md)\n  - [azpysdk Test Runner Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- Make minimal changes that address specific warnings\n- Avoid adding new dependencies or large refactoring\n- Rerun validation after each fix\n\n#### 3. SDK Release Workflow\n\n**Check Release Readiness**:\n- Use `CheckPackageReleaseReadiness` MCP tool\n- Validates: API review status, changelog, package approval, release date\n\n**Release Package**:\n- Use `ReleasePackage` MCP tool\n- Triggers release pipeline (requires approval)\n\n**Release Blocking Checks**:\n- MyPy: PASS\n- Pylint: PASS\n- Sphinx: PASS\n- Tests - CI: PASS\n\n### Automation Boundaries\n\n#### Safe Operations\n✅ Generate SDK code from TypeSpec specifications  \n✅ Run linting and static analysis tools  \n✅ Fix code quality warnings (with high confidence)  \n✅ Update documentation (CHANGELOG, README)  \n✅ Create and update PRs in draft mode  \n✅ Run existing test suites  \n✅ Validate CODEOWNERS entries  \n\n#### Restricted Operations\n⚠️ Modifying generated code (requires review)  \n⚠️ Adding new dependencies (requires justification)  \n⚠️ Changing API signatures (requires design review)  \n⚠️ Disabling or removing tests (requires explanation)  \n⚠️ Large-scale refactoring (requires approval)  \n\n#### Prohibited Operations\n❌ Merging PRs without human review  \n❌ Releasing packages to PyPI  \n❌ Modifying CI/CD pipeline definitions  \n❌ Changing security or authentication logic without security review  \n❌ Committing secrets or credentials  \n❌ Force pushing to protected branches  \n\n### Environment Requirements\n\n**Required Tools**:\n- Python 3.10 or later\n- Node.js (for TypeSpec generation)\n- azpysdk (test runner and automation)\n- GitHub CLI (for PR operations)\n- PowerShell (for MCP server on Windows)\n\n**MCP Server Tools**:\n- `azure-sdk-python-mcp` - Python-specific SDK operations\n- `azure-sdk-mcp` - Cross-language SDK operations\n- `azsdk-tools` - Engineering system utilities\n\n**Virtual Environment**:\n```bash\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n.venv\\Scripts\\activate      # Windows\n```\n\n### CI/CD Integration\n\n**Pipeline System**: Azure DevOps\n\n**Key Pipelines**:\n- **Python CI**: Core library tests and validation\n- **SDK Generation**: TypeSpec-based code generation\n- **Release**: Package publication to PyPI\n\n**Status Monitoring**:\n- Use `get_pipeline_status` MCP tool\n- Check build logs for failures\n- Analyze failed tests with `get_failed_test_cases` tool\n\n**Artifact Analysis**:\n- Download artifacts with `get_pipeline_llm_artifacts`\n- Review TRX test results\n- Analyze log files with `analyze_log_file` tool\n\n### SDK-Specific Conventions\n\n#### Package Naming\n- Client libraries: `azure-<service>-<component>` (e.g., `azure-storage-blob`)\n- Management libraries: `azure-mgmt-<service>` (e.g., `azure-mgmt-compute`)\n\n#### Version Conventions\n- Semantic versioning: `MAJOR.MINOR.PATCH`\n- Preview versions: `MAJOR.MINOR.PATCHbN` (e.g., `1.0.0b1`)\n- Pre-release format in CHANGELOG: `## 1.0.0b1 (YYYY-MM-DD)`\n\n#### Code Style\n- Follow [PEP 8](https://peps.python.org/pep-0008/)\n- Use Black for formatting\n- Type hints required (PEP 484)\n- Docstrings in NumPy/Google style\n\n#### Testing\n- Use pytest framework\n- Separate live and recorded tests\n- Test recordings in `tests/recordings/`\n- Environment variables for credentials (never hardcode)\n\n## Cross-References\n\n**Detailed Copilot Instructions**: See [.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md) for:\n- Complete TypeSpec SDK generation workflow\n- Detailed validation steps and commands\n- Pylint and MyPy fixing guidelines\n- SDK health status interpretation\n- SDK release procedures\n\n**Developer Documentation**: See [doc/dev/](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev) for:\n- [TypeSpec Generation Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/typespec_generation.md)\n- [Testing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- [Test Runner (azpysdk)](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- [Pylint Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md)\n- [Type Checking Cheat Sheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md)\n\n## Example Prompts\n\n### SDK Generation\n```\n\"Generate a Python SDK using TypeSpec from tspconfig.yaml at <path>\"\n\"Start TypeSpec SDK generation workflow\"\n\"Generate SDK from my local TypeSpec project at sdk/cognitiveservices/azure-ai-projects\"\n```\n\n### Validation & Fixes\n```\n\"Run pylint validation and fix any warnings\"\n\"Check if my SDK passes all static validation steps\"\n\"Fix the mypy errors in the generated SDK\"\n```\n\n### Release Management\n```\n\"Check if azure-ai-projects is ready for release\"\n\"What is the health status of azure-storage-blob?\"\n\"Release azure-ai-inference version 1.0.0\"\n```\n\n### Repository Health\n```\n\"Show me the health status for azure-ai-projects\"\n\"Which checks are blocking the release of this library?\"\n\"Are there any open customer issues for this package?\"\n```\n\n## Agent Behavior Guidelines\n\n### Best Practices\n1. **Always verify environment first** - Run `verify_setup` before SDK operations\n2. **Inform users of time expectations** - SDK generation takes 10-15 minutes\n3. **Make minimal changes** - Only modify files with validation errors\n4. **Reference official documentation** - Link to Azure SDK design guidelines\n5. **Run validation iteratively** - Fix and rerun each step before proceeding\n6. **Use MCP tools when available** - Leverage specialized SDK tooling\n7. **Create draft PRs** - Never create PRs in ready-for-review state\n8. **Report progress frequently** - Use incremental commits\n\n### Error Handling\n- For TypeSpec errors: Direct users to fix in source repository\n- For authentication failures: Guide through `gh auth login`\n- For missing dependencies: Provide installation instructions with links\n- For validation failures: Reference specific fixing guidelines\n- For pipeline failures: Analyze logs and provide actionable feedback\n\n### Communication Style\n- Don't repeat instructions - reference documentation links\n- Be concise and actionable\n- Use markdown formatting for commands and code\n- Provide time estimates for long operations\n- Highlight release-blocking issues clearly\n\n## Reporting Issues\n\nTo report issues with AI agent interactions or suggest improvements:\n- **GitHub Issues**: [Azure SDK for Python Issues](https://github.com/Azure/azure-sdk-for-python/issues)\n- **Label**: Use `Agent` label for agent-related issues\n- **Include**: Agent name/version, prompt used, expected vs actual behavior\n\n## Version\n\n**AGENTS.md Version**: 1.0.0  \n**Last Updated**: 2025-01-22  \n**Specification**: Follows the AGENTS.md canonical structure\n"},"files":{"AGENTS.md":"# AGENTS.md - Azure SDK for Python\n\nThis file describes how AI agents (e.g., GitHub Copilot, MCP servers, or LLM-based assistants) should interact with this repository.\n\n## Repository Overview\n\n**Purpose**: This repository contains the active development of the Azure SDK for Python, providing client libraries and management libraries for Azure services.\n\n**Scope**: \n- 100+ Python packages for Azure services\n- Client libraries for data plane operations\n- Management libraries for Azure Resource Manager (ARM)\n- Shared core functionality (authentication, retries, logging, transport)\n- TypeSpec-based SDK generation from API specifications\n- Comprehensive testing, validation, and documentation infrastructure\n\n**Main Branch**: `main`\n\n**Key Documentation**:\n- [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html)\n- [Contributing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md)\n- [Developer Documentation](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev)\n\n## Repository Structure\n\n```\nazure-sdk-for-python/\n├── sdk/                    # Service-specific libraries (e.g., sdk/storage/, sdk/ai/)\n├── eng/                    # Engineering system tools and configurations\n├── doc/                    # Developer documentation and guides\n├── scripts/                # Automation scripts\n├── .github/                # GitHub workflows, Copilot instructions, skills, and prompts\n│   ├── copilot-instructions.md  # Detailed Copilot-specific guidance\n│   ├── skills/             # Reusable Copilot skills (e.g., find-package, fix-pylint)\n│   └── prompts/            # Copilot prompt files for common tasks\n└── tools/                  # Development tools\n```\n\n## AI Agent Guidelines\n\n### Supported Actions\n\nAI agents can assist with the following activities:\n\n#### Code Generation & Development\n- **TypeSpec SDK Generation**: Generate Python SDKs from TypeSpec specifications\n  - Follow the complete workflow in `.github/copilot-instructions.md`\n  - Use MCP tools for environment verification, code generation, and validation\n  - Time estimate: 10-15 minutes for full generation workflow\n  \n- **Code Fixes**: Address linting, type checking, and validation issues\n  - Pylint, MyPy, Pyright, Verifytypes, Sphinx warnings\n  - Follow official guidelines and existing patterns\n  - Make minimal, surgical changes\n\n- **Documentation**: Update CHANGELOG.md, README files, and API documentation\n  - Follow existing formatting conventions\n  - Include version information and release dates\n\n#### Testing & Validation\n- **Run Tests**: Execute test suites using the `azpysdk` test runner\n  - Unit tests, integration tests, samples\n  - Support both local and CI environments\n  \n- **Static Analysis**: Run and fix issues from:\n  - Pylint (code quality)\n  - MyPy, Pyright (type checking)\n  - Bandit (security)\n  - Black (formatting)\n  - Sphinx (documentation)\n\n#### Pull Request Management\n- **PR Creation**: Create draft PRs with descriptive titles and descriptions\n- **PR Review**: Analyze PR feedback and make requested changes\n- **Status Checks**: Monitor CI/CD pipeline status and address failures\n\n#### Issue Triage & Labeling\n- **Issue Analysis**: Review and categorize issues\n- **Service Labels**: Validate and create service labels (e.g., `Azure.AI.Projects`)\n- **CODEOWNERS**: Validate and update CODEOWNERS entries\n\n### Relationship to Copilot Instructions\n\nThis `AGENTS.md` file is the primary reference for AI agents working in this repository. It follows the [AGENTS.md standard](https://github.com/agentsmd/agents.md) that most AI coding tools recognize automatically. For additional Copilot-specific guidance (e.g., TypeSpec generation details, MCP tool usage), see [`.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md). Reusable skills are available in [`.github/skills/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/skills/) and prompt templates in [`.github/prompts/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/prompts/).\n\n### Key Workflows\n\n#### 1. TypeSpec SDK Generation Workflow\n\n**Prerequisites**:\n- GitHub CLI authenticated (`gh auth login`)\n- Feature branch (not `main`)\n- PowerShell installed (for MCP tools)\n- Python virtual environment active\n\n**Steps**:\n1. **Environment Verification** - Use `verify_setup` MCP tool\n2. **SDK Generation** - Use azure-sdk-python-mcp generation tools (~2 minutes)\n3. **Static Validation** - Run sequential validation steps (~3-5 minutes each):\n   - Pylint, MyPy, Pyright, Verifytypes\n   - Sphinx, Mindependency, Bandit, Black\n   - Samples, Breaking changes\n4. **Documentation Update** - Update CHANGELOG.md and version files\n5. **Commit & Push** - Stage, commit, and push changes\n6. **PR Creation** - Create draft PR with generated description\n7. **Handoff** - Provide PR link for azure-rest-api-specs agent\n\n**Estimated Time**: 10-15 minutes\n\n#### 2. Code Quality Workflow\n\n**Running Validation**:\n```bash\n# Use azpysdk with appropriate environment from the package directory\nazpysdk <environment> .\n\n# Examples:\nazpysdk pylint .\nazpysdk mypy .\n```\n\n**Fixing Issues**:\n- Reference official guidelines:\n  - [Pylint Guidelines](https://github.com/Azure/azure-sdk-tools/blob/main/tools/pylint-extensions/azure-pylint-guidelines-checker/README.md)\n  - [MyPy Type Checking Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md)\n  - [azpysdk Test Runner Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- Make minimal changes that address specific warnings\n- Avoid adding new dependencies or large refactoring\n- Rerun validation after each fix\n\n#### 3. SDK Release Workflow\n\n**Check Release Readiness**:\n- Use `CheckPackageReleaseReadiness` MCP tool\n- Validates: API review status, changelog, package approval, release date\n\n**Release Package**:\n- Use `ReleasePackage` MCP tool\n- Triggers release pipeline (requires approval)\n\n**Release Blocking Checks**:\n- MyPy: PASS\n- Pylint: PASS\n- Sphinx: PASS\n- Tests - CI: PASS\n\n### Automation Boundaries\n\n#### Safe Operations\n✅ Generate SDK code from TypeSpec specifications  \n✅ Run linting and static analysis tools  \n✅ Fix code quality warnings (with high confidence)  \n✅ Update documentation (CHANGELOG, README)  \n✅ Create and update PRs in draft mode  \n✅ Run existing test suites  \n✅ Validate CODEOWNERS entries  \n\n#### Restricted Operations\n⚠️ Modifying generated code (requires review)  \n⚠️ Adding new dependencies (requires justification)  \n⚠️ Changing API signatures (requires design review)  \n⚠️ Disabling or removing tests (requires explanation)  \n⚠️ Large-scale refactoring (requires approval)  \n\n#### Prohibited Operations\n❌ Merging PRs without human review  \n❌ Releasing packages to PyPI  \n❌ Modifying CI/CD pipeline definitions  \n❌ Changing security or authentication logic without security review  \n❌ Committing secrets or credentials  \n❌ Force pushing to protected branches  \n\n### Environment Requirements\n\n**Required Tools**:\n- Python 3.10 or later\n- Node.js (for TypeSpec generation)\n- azpysdk (test runner and automation)\n- GitHub CLI (for PR operations)\n- PowerShell (for MCP server on Windows)\n\n**MCP Server Tools**:\n- `azure-sdk-python-mcp` - Python-specific SDK operations\n- `azure-sdk-mcp` - Cross-language SDK operations\n- `azsdk-tools` - Engineering system utilities\n\n**Virtual Environment**:\n```bash\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n.venv\\Scripts\\activate      # Windows\n```\n\n### CI/CD Integration\n\n**Pipeline System**: Azure DevOps\n\n**Key Pipelines**:\n- **Python CI**: Core library tests and validation\n- **SDK Generation**: TypeSpec-based code generation\n- **Release**: Package publication to PyPI\n\n**Status Monitoring**:\n- Use `get_pipeline_status` MCP tool\n- Check build logs for failures\n- Analyze failed tests with `get_failed_test_cases` tool\n\n**Artifact Analysis**:\n- Download artifacts with `get_pipeline_llm_artifacts`\n- Review TRX test results\n- Analyze log files with `analyze_log_file` tool\n\n### SDK-Specific Conventions\n\n#### Package Naming\n- Client libraries: `azure-<service>-<component>` (e.g., `azure-storage-blob`)\n- Management libraries: `azure-mgmt-<service>` (e.g., `azure-mgmt-compute`)\n\n#### Version Conventions\n- Semantic versioning: `MAJOR.MINOR.PATCH`\n- Preview versions: `MAJOR.MINOR.PATCHbN` (e.g., `1.0.0b1`)\n- Pre-release format in CHANGELOG: `## 1.0.0b1 (YYYY-MM-DD)`\n\n#### Code Style\n- Follow [PEP 8](https://peps.python.org/pep-0008/)\n- Use Black for formatting\n- Type hints required (PEP 484)\n- Docstrings in NumPy/Google style\n\n#### Testing\n- Use pytest framework\n- Separate live and recorded tests\n- Test recordings in `tests/recordings/`\n- Environment variables for credentials (never hardcode)\n\n## Cross-References\n\n**Detailed Copilot Instructions**: See [.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md) for:\n- Complete TypeSpec SDK generation workflow\n- Detailed validation steps and commands\n- Pylint and MyPy fixing guidelines\n- SDK health status interpretation\n- SDK release procedures\n\n**Developer Documentation**: See [doc/dev/](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev) for:\n- [TypeSpec Generation Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/typespec_generation.md)\n- [Testing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- [Test Runner (azpysdk)](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- [Pylint Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md)\n- [Type Checking Cheat Sheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md)\n\n## Example Prompts\n\n### SDK Generation\n```\n\"Generate a Python SDK using TypeSpec from tspconfig.yaml at <path>\"\n\"Start TypeSpec SDK generation workflow\"\n\"Generate SDK from my local TypeSpec project at sdk/cognitiveservices/azure-ai-projects\"\n```\n\n### Validation & Fixes\n```\n\"Run pylint validation and fix any warnings\"\n\"Check if my SDK passes all static validation steps\"\n\"Fix the mypy errors in the generated SDK\"\n```\n\n### Release Management\n```\n\"Check if azure-ai-projects is ready for release\"\n\"What is the health status of azure-storage-blob?\"\n\"Release azure-ai-inference version 1.0.0\"\n```\n\n### Repository Health\n```\n\"Show me the health status for azure-ai-projects\"\n\"Which checks are blocking the release of this library?\"\n\"Are there any open customer issues for this package?\"\n```\n\n## Agent Behavior Guidelines\n\n### Best Practices\n1. **Always verify environment first** - Run `verify_setup` before SDK operations\n2. **Inform users of time expectations** - SDK generation takes 10-15 minutes\n3. **Make minimal changes** - Only modify files with validation errors\n4. **Reference official documentation** - Link to Azure SDK design guidelines\n5. **Run validation iteratively** - Fix and rerun each step before proceeding\n6. **Use MCP tools when available** - Leverage specialized SDK tooling\n7. **Create draft PRs** - Never create PRs in ready-for-review state\n8. **Report progress frequently** - Use incremental commits\n\n### Error Handling\n- For TypeSpec errors: Direct users to fix in source repository\n- For authentication failures: Guide through `gh auth login`\n- For missing dependencies: Provide installation instructions with links\n- For validation failures: Reference specific fixing guidelines\n- For pipeline failures: Analyze logs and provide actionable feedback\n\n### Communication Style\n- Don't repeat instructions - reference documentation links\n- Be concise and actionable\n- Use markdown formatting for commands and code\n- Provide time estimates for long operations\n- Highlight release-blocking issues clearly\n\n## Reporting Issues\n\nTo report issues with AI agent interactions or suggest improvements:\n- **GitHub Issues**: [Azure SDK for Python Issues](https://github.com/Azure/azure-sdk-for-python/issues)\n- **Label**: Use `Agent` label for agent-related issues\n- **Include**: Agent name/version, prompt used, expected vs actual behavior\n\n## Version\n\n**AGENTS.md Version**: 1.0.0  \n**Last Updated**: 2025-01-22  \n**Specification**: Follows the AGENTS.md canonical structure\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md - Azure SDK for Python\n\nThis file describes how AI agents (e.g., GitHub Copilot, MCP servers, or LLM-based assistants) should interact with this repository.\n\n## Repository Overview\n\n**Purpose**: This repository contains the active development of the Azure SDK for Python, providing client libraries and management libraries for Azure services.\n\n**Scope**: \n- 100+ Python packages for Azure services\n- Client libraries for data plane operations\n- Management libraries for Azure Resource Manager (ARM)\n- Shared core functionality (authentication, retries, logging, transport)\n- TypeSpec-based SDK generation from API specifications\n- Comprehensive testing, validation, and documentation infrastructure\n\n**Main Branch**: `main`\n\n**Key Documentation**:\n- [Azure SDK Python Design Guidelines](https://azure.github.io/azure-sdk/python_design.html)\n- [Contributing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md)\n- [Developer Documentation](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev)\n\n## Repository Structure\n\n```\nazure-sdk-for-python/\n├── sdk/                    # Service-specific libraries (e.g., sdk/storage/, sdk/ai/)\n├── eng/                    # Engineering system tools and configurations\n├── doc/                    # Developer documentation and guides\n├── scripts/                # Automation scripts\n├── .github/                # GitHub workflows, Copilot instructions, skills, and prompts\n│   ├── copilot-instructions.md  # Detailed Copilot-specific guidance\n│   ├── skills/             # Reusable Copilot skills (e.g., find-package, fix-pylint)\n│   └── prompts/            # Copilot prompt files for common tasks\n└── tools/                  # Development tools\n```\n\n## AI Agent Guidelines\n\n### Supported Actions\n\nAI agents can assist with the following activities:\n\n#### Code Generation & Development\n- **TypeSpec SDK Generation**: Generate Python SDKs from TypeSpec specifications\n  - Follow the complete workflow in `.github/copilot-instructions.md`\n  - Use MCP tools for environment verification, code generation, and validation\n  - Time estimate: 10-15 minutes for full generation workflow\n  \n- **Code Fixes**: Address linting, type checking, and validation issues\n  - Pylint, MyPy, Pyright, Verifytypes, Sphinx warnings\n  - Follow official guidelines and existing patterns\n  - Make minimal, surgical changes\n\n- **Documentation**: Update CHANGELOG.md, README files, and API documentation\n  - Follow existing formatting conventions\n  - Include version information and release dates\n\n#### Testing & Validation\n- **Run Tests**: Execute test suites using the `azpysdk` test runner\n  - Unit tests, integration tests, samples\n  - Support both local and CI environments\n  \n- **Static Analysis**: Run and fix issues from:\n  - Pylint (code quality)\n  - MyPy, Pyright (type checking)\n  - Bandit (security)\n  - Black (formatting)\n  - Sphinx (documentation)\n\n#### Pull Request Management\n- **PR Creation**: Create draft PRs with descriptive titles and descriptions\n- **PR Review**: Analyze PR feedback and make requested changes\n- **Status Checks**: Monitor CI/CD pipeline status and address failures\n\n#### Issue Triage & Labeling\n- **Issue Analysis**: Review and categorize issues\n- **Service Labels**: Validate and create service labels (e.g., `Azure.AI.Projects`)\n- **CODEOWNERS**: Validate and update CODEOWNERS entries\n\n### Relationship to Copilot Instructions\n\nThis `AGENTS.md` file is the primary reference for AI agents working in this repository. It follows the [AGENTS.md standard](https://github.com/agentsmd/agents.md) that most AI coding tools recognize automatically. For additional Copilot-specific guidance (e.g., TypeSpec generation details, MCP tool usage), see [`.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md). Reusable skills are available in [`.github/skills/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/skills/) and prompt templates in [`.github/prompts/`](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/prompts/).\n\n### Key Workflows\n\n#### 1. TypeSpec SDK Generation Workflow\n\n**Prerequisites**:\n- GitHub CLI authenticated (`gh auth login`)\n- Feature branch (not `main`)\n- PowerShell installed (for MCP tools)\n- Python virtual environment active\n\n**Steps**:\n1. **Environment Verification** - Use `verify_setup` MCP tool\n2. **SDK Generation** - Use azure-sdk-python-mcp generation tools (~2 minutes)\n3. **Static Validation** - Run sequential validation steps (~3-5 minutes each):\n   - Pylint, MyPy, Pyright, Verifytypes\n   - Sphinx, Mindependency, Bandit, Black\n   - Samples, Breaking changes\n4. **Documentation Update** - Update CHANGELOG.md and version files\n5. **Commit & Push** - Stage, commit, and push changes\n6. **PR Creation** - Create draft PR with generated description\n7. **Handoff** - Provide PR link for azure-rest-api-specs agent\n\n**Estimated Time**: 10-15 minutes\n\n#### 2. Code Quality Workflow\n\n**Running Validation**:\n```bash\n# Use azpysdk with appropriate environment from the package directory\nazpysdk <environment> .\n\n# Examples:\nazpysdk pylint .\nazpysdk mypy .\n```\n\n**Fixing Issues**:\n- Reference official guidelines:\n  - [Pylint Guidelines](https://github.com/Azure/azure-sdk-tools/blob/main/tools/pylint-extensions/azure-pylint-guidelines-checker/README.md)\n  - [MyPy Type Checking Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md)\n  - [azpysdk Test Runner Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- Make minimal changes that address specific warnings\n- Avoid adding new dependencies or large refactoring\n- Rerun validation after each fix\n\n#### 3. SDK Release Workflow\n\n**Check Release Readiness**:\n- Use `CheckPackageReleaseReadiness` MCP tool\n- Validates: API review status, changelog, package approval, release date\n\n**Release Package**:\n- Use `ReleasePackage` MCP tool\n- Triggers release pipeline (requires approval)\n\n**Release Blocking Checks**:\n- MyPy: PASS\n- Pylint: PASS\n- Sphinx: PASS\n- Tests - CI: PASS\n\n### Automation Boundaries\n\n#### Safe Operations\n✅ Generate SDK code from TypeSpec specifications  \n✅ Run linting and static analysis tools  \n✅ Fix code quality warnings (with high confidence)  \n✅ Update documentation (CHANGELOG, README)  \n✅ Create and update PRs in draft mode  \n✅ Run existing test suites  \n✅ Validate CODEOWNERS entries  \n\n#### Restricted Operations\n⚠️ Modifying generated code (requires review)  \n⚠️ Adding new dependencies (requires justification)  \n⚠️ Changing API signatures (requires design review)  \n⚠️ Disabling or removing tests (requires explanation)  \n⚠️ Large-scale refactoring (requires approval)  \n\n#### Prohibited Operations\n❌ Merging PRs without human review  \n❌ Releasing packages to PyPI  \n❌ Modifying CI/CD pipeline definitions  \n❌ Changing security or authentication logic without security review  \n❌ Committing secrets or credentials  \n❌ Force pushing to protected branches  \n\n### Environment Requirements\n\n**Required Tools**:\n- Python 3.10 or later\n- Node.js (for TypeSpec generation)\n- azpysdk (test runner and automation)\n- GitHub CLI (for PR operations)\n- PowerShell (for MCP server on Windows)\n\n**MCP Server Tools**:\n- `azure-sdk-python-mcp` - Python-specific SDK operations\n- `azure-sdk-mcp` - Cross-language SDK operations\n- `azsdk-tools` - Engineering system utilities\n\n**Virtual Environment**:\n```bash\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n.venv\\Scripts\\activate      # Windows\n```\n\n### CI/CD Integration\n\n**Pipeline System**: Azure DevOps\n\n**Key Pipelines**:\n- **Python CI**: Core library tests and validation\n- **SDK Generation**: TypeSpec-based code generation\n- **Release**: Package publication to PyPI\n\n**Status Monitoring**:\n- Use `get_pipeline_status` MCP tool\n- Check build logs for failures\n- Analyze failed tests with `get_failed_test_cases` tool\n\n**Artifact Analysis**:\n- Download artifacts with `get_pipeline_llm_artifacts`\n- Review TRX test results\n- Analyze log files with `analyze_log_file` tool\n\n### SDK-Specific Conventions\n\n#### Package Naming\n- Client libraries: `azure-<service>-<component>` (e.g., `azure-storage-blob`)\n- Management libraries: `azure-mgmt-<service>` (e.g., `azure-mgmt-compute`)\n\n#### Version Conventions\n- Semantic versioning: `MAJOR.MINOR.PATCH`\n- Preview versions: `MAJOR.MINOR.PATCHbN` (e.g., `1.0.0b1`)\n- Pre-release format in CHANGELOG: `## 1.0.0b1 (YYYY-MM-DD)`\n\n#### Code Style\n- Follow [PEP 8](https://peps.python.org/pep-0008/)\n- Use Black for formatting\n- Type hints required (PEP 484)\n- Docstrings in NumPy/Google style\n\n#### Testing\n- Use pytest framework\n- Separate live and recorded tests\n- Test recordings in `tests/recordings/`\n- Environment variables for credentials (never hardcode)\n\n## Cross-References\n\n**Detailed Copilot Instructions**: See [.github/copilot-instructions.md](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/copilot-instructions.md) for:\n- Complete TypeSpec SDK generation workflow\n- Detailed validation steps and commands\n- Pylint and MyPy fixing guidelines\n- SDK health status interpretation\n- SDK release procedures\n\n**Developer Documentation**: See [doc/dev/](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev) for:\n- [TypeSpec Generation Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/typespec_generation.md)\n- [Testing Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- [Test Runner (azpysdk)](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md)\n- [Pylint Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md)\n- [Type Checking Cheat Sheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md)\n\n## Example Prompts\n\n### SDK Generation\n```\n\"Generate a Python SDK using TypeSpec from tspconfig.yaml at <path>\"\n\"Start TypeSpec SDK generation workflow\"\n\"Generate SDK from my local TypeSpec project at sdk/cognitiveservices/azure-ai-projects\"\n```\n\n### Validation & Fixes\n```\n\"Run pylint validation and fix any warnings\"\n\"Check if my SDK passes all static validation steps\"\n\"Fix the mypy errors in the generated SDK\"\n```\n\n### Release Management\n```\n\"Check if azure-ai-projects is ready for release\"\n\"What is the health status of azure-storage-blob?\"\n\"Release azure-ai-inference version 1.0.0\"\n```\n\n### Repository Health\n```\n\"Show me the health status for azure-ai-projects\"\n\"Which checks are blocking the release of this library?\"\n\"Are there any open customer issues for this package?\"\n```\n\n## Agent Behavior Guidelines\n\n### Best Practices\n1. **Always verify environment first** - Run `verify_setup` before SDK operations\n2. **Inform users of time expectations** - SDK generation takes 10-15 minutes\n3. **Make minimal changes** - Only modify files with validation errors\n4. **Reference official documentation** - Link to Azure SDK design guidelines\n5. **Run validation iteratively** - Fix and rerun each step before proceeding\n6. **Use MCP tools when available** - Leverage specialized SDK tooling\n7. **Create draft PRs** - Never create PRs in ready-for-review state\n8. **Report progress frequently** - Use incremental commits\n\n### Error Handling\n- For TypeSpec errors: Direct users to fix in source repository\n- For authentication failures: Guide through `gh auth login`\n- For missing dependencies: Provide installation instructions with links\n- For validation failures: Reference specific fixing guidelines\n- For pipeline failures: Analyze logs and provide actionable feedback\n\n### Communication Style\n- Don't repeat instructions - reference documentation links\n- Be concise and actionable\n- Use markdown formatting for commands and code\n- Provide time estimates for long operations\n- Highlight release-blocking issues clearly\n\n## Reporting Issues\n\nTo report issues with AI agent interactions or suggest improvements:\n- **GitHub Issues**: [Azure SDK for Python Issues](https://github.com/Azure/azure-sdk-for-python/issues)\n- **Label**: Use `Agent` label for agent-related issues\n- **Include**: Agent name/version, prompt used, expected vs actual behavior\n\n## Version\n\n**AGENTS.md Version**: 1.0.0  \n**Last Updated**: 2025-01-22  \n**Specification**: Follows the AGENTS.md canonical structure\n","category":"root","tokens":3104}]}