{"owner":"microsoft","repo":"ai-agents-for-beginners","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# AGENTS.md\n\n## Project Overview\n\nThis repository contains \"AI Agents for Beginners\" - a comprehensive educational course teaching everything needed to build AI Agents. The course consists of 18 lessons (numbered 00-18) covering fundamentals, design patterns, frameworks, production deployment, local/on-device agents, and security of AI agents.\n\n**Key Technologies:**\n- Python 3.12+\n- Jupyter Notebooks for interactive learning\n- AI Frameworks: Microsoft Agent Framework (MAF)\n- Azure AI Services: Microsoft Foundry, Microsoft Foundry Agent Service V2\n\n**Architecture:**\n- Lesson-based structure (00-15+ directories)\n- Each lesson contains: README documentation, code samples (Jupyter notebooks), and images\n- Multi-language support via automated translation system\n- One Python notebook per lesson using Microsoft Agent Framework\n\n## Setup Commands\n\n### Prerequisites\n- Python 3.12 or higher\n- Azure subscription (for Microsoft Foundry)\n- Azure CLI installed and authenticated (`az login`)\n\n### Initial Setup\n\n1. **Clone or fork the repository:**\n   ```bash\n   gh repo fork microsoft/ai-agents-for-beginners --clone\n   # OR\n   git clone https://github.com/microsoft/ai-agents-for-beginners.git\n   cd ai-agents-for-beginners\n   ```\n\n2. **Create and activate Python virtual environment:**\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Set up environment variables:**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your API keys and endpoints\n   ```\n\n### Required Environment Variables\n\nFor **Microsoft Foundry** (Required):\n- `AZURE_AI_PROJECT_ENDPOINT` - Microsoft Foundry project endpoint\n- `AZURE_AI_MODEL_DEPLOYMENT_NAME` - Model deployment name (e.g., gpt-5-mini)\n\nFor **Azure AI Search** (Lesson 05 - RAG):\n- `AZURE_SEARCH_SERVICE_ENDPOINT` - Azure AI Search endpoint\n- `AZURE_SEARCH_API_KEY` - Azure AI Search API key\n\nAuthentication: Run `az login` before running notebooks (uses `AzureCliCredential`).\n\n## Development Workflow\n\n### Running Jupyter Notebooks\n\nEach lesson contains multiple Jupyter notebooks for different frameworks:\n\n1. **Start Jupyter:**\n   ```bash\n   jupyter notebook\n   ```\n\n2. **Navigate to a lesson directory** (e.g., `01-intro-to-ai-agents/code_samples/`)\n\n3. **Open and run notebooks:**\n   - `*-python-agent-framework.ipynb` - Using Microsoft Agent Framework (Python)\n   - `*-dotnet-agent-framework.ipynb` - Using Microsoft Agent Framework (.NET)\n\n### Working with Microsoft Agent Framework\n\n**Microsoft Agent Framework + Microsoft Foundry:**\n- Requires Azure subscription\n- Uses `FoundryChatClient` for Agent Service V2 (agents visible in Foundry portal)\n- Production-ready with built-in observability\n- File pattern: `*-python-agent-framework.ipynb`\n\n## Testing Instructions\n\nThis is an educational repository with example code rather than production code with automated tests. To verify your setup and changes:\n\n### Manual Testing\n\n1. **Test Python environment:**\n   ```bash\n   python --version  # Should be 3.12+\n   pip list | grep -E \"(agent-framework|azure-ai|azure-identity)\"\n   ```\n\n2. **Test notebook execution:**\n   ```bash\n   # Convert notebook to script and run (tests imports)\n   jupyter nbconvert --to script <lesson-folder>/code_samples/<notebook>.ipynb --stdout | python\n   ```\n\n3. **Verify environment variables:**\n   ```bash\n   python -c \"import os; from dotenv import load_dotenv; load_dotenv(); print('✓ AZURE_AI_PROJECT_ENDPOINT' if os.getenv('AZURE_AI_PROJECT_ENDPOINT') else '✗ AZURE_AI_PROJECT_ENDPOINT missing')\"\n   ```\n\n### Running Individual Notebooks\n\nOpen notebooks in Jupyter and execute cells sequentially. Each notebook is self-contained and includes:\n- Import statements\n- Configuration loading\n- Example agent implementations\n- Expected outputs in markdown cells\n\n### Smoke-Testing Deployed Agents\n\nFor lessons where an agent is deployed as a Microsoft Foundry hosted agent (01, 04, 05, 16), the repo ships smoke-test catalogs under `tests/` that are run by the `.github/workflows/smoke-test.yml` workflow via the [AI Smoke Test](https://github.com/marketplace/actions/ai-smoke-test) action. These are a lightweight post-deploy gate (is the agent reachable and following basic prompt expectations?), complementing the evaluation pipeline in Lessons 10 and 16. See [tests/README.md](./tests/README.md) for the catalog-to-lesson-to-agent mapping. Lesson 17 runs locally with Foundry Local and has no hosted endpoint, so it is validated by running its notebook directly.\n\n## Code Style\n\n### Python Conventions\n\n- **Python Version**: 3.12+\n- **Code Style**: Follow standard Python PEP 8 conventions\n- **Notebooks**: Use clear markdown cells to explain concepts\n- **Imports**: Group by standard library, third-party, local imports\n\n### Jupyter Notebook Conventions\n\n- Include descriptive markdown cells before code cells\n- Add output examples in notebooks for reference\n- Use clear variable names that match lesson concepts\n- Keep notebook execution order linear (cell 1 → 2 → 3...)\n\n### File Organization\n\n```\n<lesson-number>-<lesson-name>/\n├── README.md                     # Lesson documentation\n├── code_samples/\n│   ├── <number>-python-agent-framework.ipynb\n│   └── <number>-dotnet-agent-framework.ipynb  (optional)\n└── images/\n    └── *.png\n```\n\n## Build and Deployment\n\n### Building Documentation\n\nThis repository uses Markdown for documentation:\n- README.md files in each lesson folder\n- Main README.md at repository root\n- Automated translation system via GitHub Actions\n\n### CI/CD Pipeline\n\nLocated in `.github/workflows/`:\n\n1. **co-op-translator.yml** - Automatic translation to 50+ languages\n2. **welcome-issue.yml** - Welcomes new issue creators\n3. **welcome-pr.yml** - Welcomes new pull request contributors\n\n### Deployment\n\nThis is an educational repository - no deployment process. Users:\n1. Fork or clone the repository\n2. Run notebooks locally or in GitHub Codespaces\n3. Learn by modifying and experimenting with examples\n\n## Pull Request Guidelines\n\n### Before Submitting\n\n1. **Test your changes:**\n   - Run affected notebooks completely\n   - Verify all cells execute without errors\n   - Check that outputs are appropriate\n\n2. **Documentation updates:**\n   - Update README.md if adding new concepts\n   - Add comments in notebooks for complex code\n   - Ensure markdown cells explain the purpose\n\n3. **File changes:**\n   - Avoid committing `.env` files (use `.env.example`)\n   - Don't commit `venv/` or `__pycache__/` directories\n   - Keep notebook outputs when they demonstrate concepts\n   - Remove temporary files and backup notebooks (`*-backup.ipynb`)\n\n### PR Title Format\n\nUse descriptive titles:\n- `[Lesson-XX] Add new example for <concept>`\n- `[Fix] Correct typo in lesson-XX README`\n- `[Update] Improve code sample in lesson-XX`\n- `[Docs] Update setup instructions`\n\n### Required Checks\n\n- Notebooks should execute without errors\n- README files should be clear and accurate\n- Follow existing code patterns in the repository\n- Maintain consistency with other lessons\n\n## Additional Notes\n\n### Common Gotchas\n\n1. **Python version mismatch:**\n   - Ensure Python 3.12+ is used\n   - Some packages may not work with older versions\n   - Use `python3 -m venv` to specify Python version explicitly\n\n2. **Environment variables:**\n   - Always create `.env` from `.env.example`\n   - Don't commit `.env` file (it's in `.gitignore`)\n   - Sign in with `az login` for keyless Entra ID authentication\n\n3. **Package conflicts:**\n   - Use a fresh virtual environment\n   - Install from `requirements.txt` rather than individual packages\n   - Some notebooks may require additional packages mentioned in their markdown cells\n\n4. **Azure services:**\n   - Azure AI services require active subscription\n   - Some features are region-specific\n   - Ensure your Azure OpenAI model deployment supports the Responses API\n\n### Learning Path\n\nRecommended progression through lessons:\n1. **00-course-setup** - Start here for environment setup\n2. **01-intro-to-ai-agents** - Understand AI agent fundamentals\n3. **02-explore-agentic-frameworks** - Learn about different frameworks\n4. **03-agentic-design-patterns** - Core design patterns\n5. Continue through numbered lessons sequentially\n\n### Framework Selection\n\nChoose framework based on your goals:\n- **All lessons**: Microsoft Agent Framework (MAF) with `FoundryChatClient`\n- **Agents register server-side** in Microsoft Foundry Agent Service V2 and are visible in the Foundry portal\n\n### Getting Help\n\n- Join the [Microsoft Foundry Community Discord](https://aka.ms/ai-agents/discord)\n- Review lesson README files for specific guidance\n- Check the main [README.md](./README.md) for course overview\n- Refer to [Course Setup](./00-course-setup/README.md) for detailed setup instructions\n\n### Contributing\n\nThis is an open educational project. Contributions welcome:\n- Improve code examples\n- Fix typos or errors\n- Add clarifying comments\n- Suggest new lesson topics\n- Translate to additional languages\n\nSee [GitHub Issues](https://github.com/microsoft/ai-agents-for-beginners/issues) for current needs.\n\n## Project-Specific Context\n\n### Multi-Language Support\n\nThis repository uses an automated translation system:\n- 50+ languages supported\n- Translations in `/translations/<lang-code>/` directories\n- GitHub Actions workflow handles translation updates\n- Source files are in English at repository root\n\n### Lesson Structure\n\nEach lesson follows a consistent pattern:\n1. Video thumbnail with link\n2. Written lesson content (README.md)\n3. Code samples in multiple frameworks\n4. Learning objectives and prerequisites\n5. Extra learning resources linked\n\n### Code Sample Naming\n\nFormat: `<lesson-number>-python-agent-framework.ipynb`\n- `01-python-agent-framework.ipynb` - Lesson 1, MAF Python\n- `14-sequential.ipynb` - Lesson 14, MAF advanced patterns\n- `16-python-agent-framework.ipynb` - Lesson 16, production customer-support agent\n- `17-local-agent-foundry-local.ipynb` - Lesson 17, local agent with Foundry Local + Qwen\n\n### Special Directories\n\n- `translated_images/` - Localized images for translations\n- `images/` - Original images for English content\n- `.devcontainer/` - VS Code development container configuration\n- `.github/` - GitHub Actions workflows and templates\n\n### Dependencies\n\nKey packages from `requirements.txt`:\n- `agent-framework` - Microsoft Agent Framework\n- `a2a-sdk` - Agent-to-Agent protocol support\n- `azure-ai-inference`, `azure-ai-projects` - Azure AI services\n- `azure-identity` - Azure authentication (AzureCliCredential)\n- `azure-search-documents` - Azure AI Search integration\n- `mcp[cli]` - Model Context Protocol support\n"}}