mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: consolidate lab packages into a single one; update contribution guidelines (#940)
* consolidate lab packages into a single one; update contribution guidelines * update dep list * add poe tasks; fix tests and lint erros * add lab tests for CI * fix test * update root pyproject.toml
This commit is contained in:
Eric Zhu
+70
-116
@@ -1,145 +1,99 @@
|
||||
# Agent Framework Lab
|
||||
|
||||
This directory contains experimental packages for Microsoft Agent Framework that are distributed as separate installable packages under the `agent_framework.lab` namespace.
|
||||
Lab packages are not part of the core framework and may experience breaking changes or be deprecated in the future.
|
||||
This is the experimental package for Microsoft Agent Framework, `agent-framework-lab`, which contains
|
||||
various lab modules built on top of the core framework.
|
||||
Lab modules are not part of the core framework and may experience breaking changes or be deprecated in the future.
|
||||
|
||||
## What are Lab Packages?
|
||||
## What are Lab Modules?
|
||||
|
||||
Lab packages are extensions to the core Agent Framework that falls into
|
||||
Lab modules are extensions to the core Agent Framework that fall into
|
||||
one of the following categories:
|
||||
|
||||
1. Incubation of new features that may get incorporated by the core framework.
|
||||
1. Incubation of new features that may get incorporated by the core framework.
|
||||
2. Research prototypes built on the core framework.
|
||||
3. Benchmarks and experimentation tools.
|
||||
|
||||
## Lab Packages
|
||||
## Lab Modules
|
||||
|
||||
- [**gaia**](./gaia/): GAIA benchmark implementation (`agent-framework-lab-gaia`)
|
||||
- [**lightning**](./lightning/): Reinforcement learning for agents (`agent-framework-lab-lightning`)
|
||||
- [**tau2**](./tau2/): Customer service agent simulation framework (`agent-framework-lab-tau2`)
|
||||
- [**gaia**](./gaia/): Evaluate your agents using the GAIA benchmark for general assistant tasks
|
||||
- [**tau2**](./tau2/): Evaluate your agents using the TAU2 benchmark for customer support tasks
|
||||
- [**lightning**](./lightning/): RL training for agents (in development)
|
||||
|
||||
## How do I contribute?
|
||||
|
||||
This repo only contains lab packages maintained by Microsoft.
|
||||
If you want to contribute, please take the following steps:
|
||||
|
||||
1. Follow the [Create a New Lab Package](#create-new-lab-package) guide
|
||||
below to create your own lab package.
|
||||
2. Create a new repo on GitHub and check in your package there.
|
||||
3. Tag your repo with `agent-framework-lab` for better discovery.
|
||||
4. Submit a PR to this repo (github.com/microsoft/agent-framework)
|
||||
to add a link to your repo in the [list](#lab-packages) above.
|
||||
**The PR title must contain "[New Lab Package]"**.
|
||||
5. We will review your repo and decide whether to approve it.
|
||||
|
||||
Follow the [guidelines](#guidelines) when you create your package, our decision
|
||||
to accept your PR will be based on your idea as well as the quality of your
|
||||
code.
|
||||
|
||||
We may decide to maintain your package in this repo. In that case, we will
|
||||
contact you directly.
|
||||
|
||||
## Package Structure
|
||||
|
||||
Each lab package follows this structure:
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
packages/lab/{lab_name}/
|
||||
├── agent_framework/
|
||||
│ └── lab/
|
||||
│ └── {lab_name}/
|
||||
│ └── __init__.py # Imports from agent_framework_lab_{lab_name}
|
||||
├── agent_framework_lab_{lab_name}/ # Actual implementation package
|
||||
│ ├── __init__.py # Main exports and __version__
|
||||
│ ├── {module_files}.py # Implementation modules
|
||||
│ └── py.typed # Type hints marker
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ └── test_{lab_name}.py # Package tests
|
||||
├── pyproject.toml # Package configuration
|
||||
├── README.md # Package-specific documentation
|
||||
└── LICENSE # MIT License
|
||||
agent-framework-lab/
|
||||
├── pyproject.toml # Single package configuration for agent-framework-lab
|
||||
├── README.md # This file
|
||||
├── LICENSE # License file
|
||||
├── namespace/ # Centralized namespace package files
|
||||
│ └── agent_framework/
|
||||
│ └── lab/
|
||||
│ ├── gaia/ # Re-exports from agent_framework_lab_gaia
|
||||
│ ├── lightning/ # Re-exports from agent_framework_lab_lightning
|
||||
│ └── tau2/ # Re-exports from agent_framework_lab_tau2
|
||||
├── gaia/ # GAIA module implementation
|
||||
│ └── agent_framework_lab_gaia/
|
||||
├── lightning/ # Lightning module implementation
|
||||
│ └── agent_framework_lab_lightning/
|
||||
└── tau2/ # TAU2 module implementation
|
||||
└── agent_framework_lab_tau2/
|
||||
```
|
||||
|
||||
## Creating a New Lab Package
|
||||
This structure maintains a single PyPI package `agent-framework-lab` while supporting modular imports through the namespace package mechanism.
|
||||
|
||||
### Create The Package
|
||||
## Installation
|
||||
|
||||
First ensure `cookiecutter` is installed.
|
||||
Install the base lab package:
|
||||
|
||||
```bash
|
||||
pip install cookiecutter
|
||||
pip install agent-framework-lab
|
||||
```
|
||||
|
||||
Then go to the directory where you want to create the package:
|
||||
For details on installing individual modules, see their respective README files listed above.
|
||||
|
||||
```bash
|
||||
cookiecutter /path/to/agent-framework/python/packages/lab/cookiecutter-agent-framework-lab
|
||||
```
|
||||
## Usage
|
||||
|
||||
You will be prompted for:
|
||||
|
||||
- **package_name**: The name of your lab package (e.g., "lightning", "vision")
|
||||
- **package_display_name**: Human-readable name (e.g., "Lighting Tools", "Computer Vision")
|
||||
- **package_description**: Brief description (auto-generated from display name)
|
||||
- **include_cli_script**: Whether to include a CLI script (y/n)
|
||||
|
||||
### After Package Creation
|
||||
|
||||
1. **Implement your functionality** in `agent_framework_lab_your_package_name/`
|
||||
2. **Update exports** in `__init__.py` `__all__` list
|
||||
3. **Add dependencies** to `pyproject.toml`
|
||||
4. **Write tests** in the `tests/` directory
|
||||
5. **Update README** with usage examples and API documentation
|
||||
|
||||
### Add to Workspace (only for packages maintained in this repo)
|
||||
|
||||
After creating your package, add it to the workspace configuration:
|
||||
|
||||
```
|
||||
# Edit python/pyproject.toml
|
||||
# Add to dependencies section:
|
||||
dependencies = [
|
||||
# ... existing packages ...
|
||||
"agent-framework-lab-your-package-name",
|
||||
]
|
||||
|
||||
# Add to [tool.uv.sources] section:
|
||||
agent-framework-lab-your-package-name = { workspace = true }
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
Once created, users can install your lab package
|
||||
|
||||
1. directly from your repo:
|
||||
|
||||
```bash
|
||||
pip install git+https://github.com/your-username/your-lab-package-repo.git
|
||||
```
|
||||
|
||||
2. or from PyPI if you have uploaded your lab package there:
|
||||
|
||||
```bash
|
||||
pip install "agent-framework-lab-your-package-name"
|
||||
```
|
||||
|
||||
Then, they can use your lab package:
|
||||
Import and use lab modules from the `agent_framework.lab` namespace.
|
||||
For example, to use the GAIA module:
|
||||
|
||||
```python
|
||||
from agent_framework.lab.your_package_name import YourClass, your_function
|
||||
|
||||
# Use the functionality
|
||||
instance = YourClass()
|
||||
result = your_function()
|
||||
# Using GAIA module
|
||||
from agent_framework.lab.gaia import GAIA
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
## Should I consume Lab Modules?
|
||||
|
||||
1. **Naming**: Use lowercase with hyphens for package names (`agent-framework-lab-your-package-name`)
|
||||
2. **Namespace**: Always use `agent_framework.lab.your_package_name` for imports
|
||||
3. **Versioning**: Start with `0.1.0b1` for beta releases
|
||||
4. **Dependencies**: Minimize external dependencies, always include `agent-framework`
|
||||
5. **Documentation**: Include comprehensive README with usage examples
|
||||
6. **Tests**: Write comprehensive tests with good coverage
|
||||
7. **Type hints**: Always include type hints and `py.typed` file
|
||||
If you are looking for stable and production-ready features, you should not use lab modules. Stick to the core framework.
|
||||
|
||||
If you are looking for experimentation, research, or want to
|
||||
benchmark different approaches -- most importantly, if you don't mind breaking changes and potential deprecations --
|
||||
then lab modules are for you.
|
||||
|
||||
## Contributing to Lab Modules
|
||||
|
||||
### Microsoft-maintained modules
|
||||
|
||||
For Microsoft-maintained modules in this repository, please follow standard contribution guidelines and submit pull requests directly to this repository.
|
||||
|
||||
### Community modules
|
||||
|
||||
If you want to contribute a community-maintained lab module:
|
||||
|
||||
1. Create a new repository on GitHub for your module
|
||||
2. Tag your repository with `agent-framework-lab` for discoverability
|
||||
3. Submit a PR to add a link to your repository in the [Lab Modules](#lab-modules) section above
|
||||
4. Use the PR title format: `[New Lab Module] Your Module Name`
|
||||
|
||||
We will review your submission based on the guidelines below.
|
||||
|
||||
### Guidelines
|
||||
|
||||
1. **Purpose**: Community modules should fit into one of the three categories of lab modules (incubation, research, benchmarks)
|
||||
2. **Namespace**: Community modules should avoid the `agent_framework.lab` namespace (reserved for modules maintained in this repository)
|
||||
3. **Dependencies**: Minimize external dependencies, always include `agent-framework` as a base dependency
|
||||
4. **Documentation**: Include comprehensive README with installation instructions and usage examples
|
||||
5. **Tests**: Write comprehensive tests with good coverage
|
||||
6. **Type hints**: Always include type hints and a `py.typed` file
|
||||
7. **Versioning**: Use semantic versioning, start with `0.1.0` for initial releases
|
||||
|
||||
Reference in New Issue
Block a user