Skip to content

Commit 29846cb

Browse files
Copilotekzhu
Copilot
and
ekzhu
authored
Add comprehensive GitHub Copilot instructions for AutoGen development (#7029)
Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: ekzhu <[email protected]> Co-authored-by: Eric Zhu <[email protected]>
1 parent 14809f5 commit 29846cb

File tree

2 files changed

+2114
-0
lines changed

2 files changed

+2114
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# AutoGen Multi-Agent AI Framework
2+
3+
AutoGen is a multi-language framework for creating AI agents that can act autonomously or work alongside humans. The project has separate Python and .NET implementations with their own development workflows.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Prerequisites and Environment Setup
10+
11+
**CRITICAL**: Install both .NET 8.0 and 9.0 for full compatibility:
12+
- Install uv package manager: `python3 -m pip install uv`
13+
- Install .NET 9.0 SDK: `wget https://dot.net/v1/dotnet-install.sh && chmod +x dotnet-install.sh && ./dotnet-install.sh --channel 9.0`
14+
- Install .NET 8.0 runtime: `./dotnet-install.sh --channel 8.0 --runtime dotnet && ./dotnet-install.sh --channel 8.0 --runtime aspnetcore`
15+
- Update PATH: `export PATH="$HOME/.dotnet:$PATH"`
16+
17+
### Python Development Workflow
18+
19+
**Bootstrap and build Python environment:**
20+
```bash
21+
cd /home/runner/work/autogen/autogen/python
22+
uv sync --all-extras # NEVER CANCEL: Takes 2 minutes. Set timeout to 300+ seconds.
23+
source .venv/bin/activate
24+
```
25+
26+
**Validate Python development:**
27+
```bash
28+
# Quick validation (under 1 second each)
29+
poe format # Code formatting
30+
poe lint # Linting with ruff
31+
32+
# Type checking - NEVER CANCEL these commands
33+
poe mypy # Takes 6 minutes. Set timeout to 600+ seconds.
34+
poe pyright # Takes 41 seconds. Set timeout to 120+ seconds.
35+
36+
# Individual package testing (core package example)
37+
poe --directory ./packages/autogen-core test # Takes 10 seconds. Set timeout to 60+ seconds.
38+
39+
# Documentation - NEVER CANCEL
40+
poe docs-build # Takes 1 minute 16 seconds. Set timeout to 300+ seconds.
41+
```
42+
43+
**CRITICAL TIMING EXPECTATIONS:**
44+
- **NEVER CANCEL**: Python environment setup takes 2 minutes minimum
45+
- **NEVER CANCEL**: mypy type checking takes 6 minutes
46+
- **NEVER CANCEL**: Documentation build takes 1+ minutes
47+
- Format/lint tasks complete in under 1 second
48+
- Individual package tests typically complete in 10-60 seconds
49+
50+
### .NET Development Workflow
51+
52+
**Bootstrap and build .NET environment:**
53+
```bash
54+
cd /home/runner/work/autogen/autogen/dotnet
55+
export PATH="$HOME/.dotnet:$PATH"
56+
dotnet restore # NEVER CANCEL: Takes 53 seconds. Set timeout to 300+ seconds.
57+
dotnet build --configuration Release # NEVER CANCEL: Takes 53 seconds. Set timeout to 300+ seconds.
58+
```
59+
60+
**Validate .NET development:**
61+
```bash
62+
# Unit tests - NEVER CANCEL
63+
dotnet test --configuration Release --filter "Category=UnitV2" --no-build # Takes 25 seconds. Set timeout to 120+ seconds.
64+
65+
# Format check (if build fails)
66+
dotnet format --verify-no-changes
67+
68+
# Run samples
69+
cd samples/Hello
70+
dotnet run
71+
```
72+
73+
**CRITICAL TIMING EXPECTATIONS:**
74+
- **NEVER CANCEL**: .NET restore takes 53 seconds minimum
75+
- **NEVER CANCEL**: .NET build takes 53 seconds minimum
76+
- **NEVER CANCEL**: .NET unit tests take 25 seconds minimum
77+
- All build and test commands require appropriate timeouts
78+
79+
### Complete Validation Workflow
80+
81+
**Run full check suite (Python):**
82+
```bash
83+
cd /home/runner/work/autogen/autogen/python
84+
source .venv/bin/activate
85+
poe check # NEVER CANCEL: Runs all checks. Takes 7+ minutes total. Set timeout to 900+ seconds.
86+
```
87+
88+
## Validation Scenarios
89+
90+
### Manual Validation Requirements
91+
Always manually validate changes by running complete user scenarios after making modifications:
92+
93+
**Python validation scenarios:**
94+
1. **Import test**: Verify core imports work:
95+
```python
96+
from autogen_agentchat.agents import AssistantAgent
97+
from autogen_core import AgentRuntime
98+
from autogen_ext.models.openai import OpenAIChatCompletionClient
99+
```
100+
101+
2. **AutoGen Studio test**: Verify web interface can start:
102+
```bash
103+
autogenstudio ui --help # Should show help without errors
104+
```
105+
106+
3. **Documentation test**: Build and verify docs generate without errors:
107+
```bash
108+
poe docs-build && ls docs/build/index.html
109+
```
110+
111+
**.NET validation scenarios:**
112+
1. **Sample execution**: Run Hello sample to verify runtime works:
113+
```bash
114+
cd dotnet/samples/Hello && dotnet run --help
115+
```
116+
117+
2. **Build validation**: Ensure all projects compile:
118+
```bash
119+
dotnet build --configuration Release --no-restore
120+
```
121+
122+
3. **Test execution**: Run unit tests to verify functionality:
123+
```bash
124+
dotnet test --filter "Category=UnitV2" --configuration Release --no-build
125+
```
126+
127+
## Common Issues and Workarounds
128+
129+
### Network-Related Issues
130+
- **Python tests may fail** with network errors (tiktoken downloads, Playwright browser downloads) in sandboxed environments - this is expected
131+
- **Documentation intersphinx warnings** due to inability to reach external documentation sites - this is expected
132+
- **Individual package tests work better** than full test suite in network-restricted environments
133+
134+
### .NET Runtime Issues
135+
- **Requires both .NET 8.0 and 9.0**: Build uses 9.0 SDK but tests need 8.0 runtime
136+
- **Global.json specifies 9.0.100**: Must install exact .NET 9.0 version or later
137+
- **Path configuration critical**: Ensure `$HOME/.dotnet` is in PATH before system .NET
138+
139+
### Python Package Issues
140+
- **Use uv exclusively**: Do not use pip/conda for dependency management
141+
- **Virtual environment required**: Always activate `.venv` before running commands
142+
- **Package workspace structure**: Project uses uv workspace with multiple packages
143+
144+
## Timing Reference
145+
146+
### Python Commands
147+
| Command | Expected Time | Timeout | Notes |
148+
|---------|---------------|---------|-------|
149+
| `uv sync --all-extras` | 2 minutes | 300+ seconds | NEVER CANCEL |
150+
| `poe mypy` | 6 minutes | 600+ seconds | NEVER CANCEL |
151+
| `poe pyright` | 41 seconds | 120+ seconds | NEVER CANCEL |
152+
| `poe docs-build` | 1 min 16 sec | 300+ seconds | NEVER CANCEL |
153+
| `poe format` | <1 second | 30 seconds | Quick |
154+
| `poe lint` | <1 second | 30 seconds | Quick |
155+
| Individual package test | 10 seconds | 60+ seconds | May have network failures |
156+
157+
### .NET Commands
158+
| Command | Expected Time | Timeout | Notes |
159+
|---------|---------------|---------|-------|
160+
| `dotnet restore` | 53 seconds | 300+ seconds | NEVER CANCEL |
161+
| `dotnet build --configuration Release` | 53 seconds | 300+ seconds | NEVER CANCEL |
162+
| `dotnet test --filter "Category=UnitV2"` | 25 seconds | 120+ seconds | NEVER CANCEL |
163+
| `dotnet format --verify-no-changes` | 5-10 seconds | 60 seconds | Quick validation |
164+
165+
## Repository Structure
166+
167+
### Python Packages (`python/packages/`)
168+
- `autogen-core`: Core agent runtime, model interfaces, and base components
169+
- `autogen-agentchat`: High-level multi-agent conversation APIs
170+
- `autogen-ext`: Extensions for specific model providers and tools
171+
- `autogen-studio`: Web-based IDE for agent workflows
172+
- `agbench`: Benchmarking suite for agent performance
173+
- `magentic-one-cli`: Multi-agent team CLI application
174+
175+
### .NET Projects (`dotnet/src/`)
176+
- `AutoGen`: Legacy 0.2-style .NET packages (being deprecated)
177+
- `Microsoft.AutoGen.*`: New event-driven .NET packages
178+
- `AutoGen.Core`: Core .NET agent functionality
179+
- Multiple provider packages: OpenAI, Anthropic, Ollama, etc.
180+
181+
### Key Configuration Files
182+
- `python/pyproject.toml`: Python workspace and tool configuration
183+
- `dotnet/global.json`: .NET SDK version requirements
184+
- `dotnet/AutoGen.sln`: .NET solution file
185+
- `python/uv.lock`: Locked Python dependencies
186+
187+
## Development Best Practices
188+
189+
### Before Committing Changes
190+
**ALWAYS run these validation steps:**
191+
192+
**Python:**
193+
```bash
194+
cd python && source .venv/bin/activate
195+
poe format # Fix formatting
196+
poe lint # Check code quality
197+
poe mypy # Type checking (6 minutes)
198+
poe docs-build # Verify docs build (1+ minutes)
199+
```
200+
201+
**.NET:**
202+
```bash
203+
cd dotnet && export PATH="$HOME/.dotnet:$PATH"
204+
dotnet format --verify-no-changes # Check formatting
205+
dotnet build --configuration Release --no-restore # Build (53 seconds)
206+
dotnet test --configuration Release --filter "Category=UnitV2" --no-build # Test (25 seconds)
207+
```
208+
209+
### Key Directories Reference
210+
```
211+
autogen/
212+
├── python/ # Python implementation
213+
│ ├── packages/ # Individual Python packages
214+
│ ├── docs/ # Sphinx documentation
215+
│ ├── samples/ # Example code
216+
│ └── pyproject.toml # Workspace configuration
217+
├── dotnet/ # .NET implementation
218+
│ ├── src/ # Source projects
219+
│ ├── test/ # Test projects
220+
│ ├── samples/ # Sample applications
221+
│ └── AutoGen.sln # Solution file
222+
├── .github/workflows/ # CI/CD pipelines
223+
└── docs/ # Additional documentation
224+
```
225+
226+
This framework supports creating both simple single-agent applications and complex multi-agent workflows with support for various LLM providers, tools, and deployment patterns.

0 commit comments

Comments
 (0)