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