mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
146 lines
5.0 KiB
Markdown
146 lines
5.0 KiB
Markdown
# 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.
|
|
|
|
## What are Lab Packages?
|
|
|
|
Lab packages are extensions to the core Agent Framework that falls into
|
|
one of the following categories:
|
|
|
|
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
|
|
|
|
- [**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`)
|
|
|
|
## 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:
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
## Creating a New Lab Package
|
|
|
|
### Create The Package
|
|
|
|
First ensure `cookiecutter` is installed.
|
|
|
|
```bash
|
|
pip install cookiecutter
|
|
```
|
|
|
|
Then go to the directory where you want to create the package:
|
|
|
|
```bash
|
|
cookiecutter /path/to/agent-framework/python/packages/lab/cookiecutter-agent-framework-lab
|
|
```
|
|
|
|
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:
|
|
|
|
```python
|
|
from agent_framework.lab.your_package_name import YourClass, your_function
|
|
|
|
# Use the functionality
|
|
instance = YourClass()
|
|
result = your_function()
|
|
```
|
|
|
|
## Guidelines
|
|
|
|
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
|