diff --git a/00_STATE.md b/00_STATE.md new file mode 100644 index 000000000000..ae629708c16f --- /dev/null +++ b/00_STATE.md @@ -0,0 +1,65 @@ +# 00_STATE.md — AutoGen Repository Analysis + +## Repository Identity +- **Full Name**: microsoft/autogen +- **Fork**: okwn/autogen (forked from microsoft/autogen) +- **License**: CC-BY-4.0 (Creative Commons Attribution 4.0 International) +- **Archived**: false +- **Language**: Python +- **Stars**: 58,298 +- **Forks**: 8,802 +- **Open Issues**: 843 +- **Default Branch**: main + +## Repository Status +- **Maintenance Mode**: AutoGen is in maintenance mode as of late 2024/early 2025 +- **Recommendation**: New users directed to Microsoft Agent Framework +- **Community-Managed**: Going forward, community managed + +## Key Metadata +- **Python Version**: 3.10+ required +- **Package Manager**: uv (Astral) +- **Task Runner**: poethepoet (poe) +- **Linting**: ruff +- **Type Checking**: mypy, pyright +- **Testing**: pytest, pytest-asyncio, pytest-xdist + +## Package Structure +``` +python/packages/ +├── autogen-core/ # Core interface definitions and reference implementations +├── autogen-agentchat/ # Single/multi-agent workflows on top of autogen-core +├── autogen-ext/ # Ecosystem integrations (OpenAI, Azure, MCP, etc.) +├── autogen-studio/ # Web-based IDE for building/running agents +├── autogen-test-utils/ # Shared test utilities +├── agbench/ # Benchmarking suite for agent performance +├── magentic-one-cli/ # CLI for Magentic-One (multi-agent team) +├── component-schema-gen/ # Schema generation for components +└── pyautogen/ # Legacy v0.2 compatibility package +``` + +## CI/CD Workflows +- `checks.yml`: format, lint, mypy, pyright, test, docs, samples-code-check, markdown-code-lint, check-proto-changes +- `integration.yml`: Integration tests +- `docs.yml`: Documentation build +- `python-package-0.2.yml`: Legacy v0.2 package tests +- `dotnet-build.yml` / `dotnet-release.yml`: .NET builds +- `codeql.yml`: Code security scanning +- `single-python-package.yml`: Per-package releases + +## Development Setup +```bash +cd python +uv sync --all-extras +source .venv/bin/activate +poe check # Run all checks +``` + +## Key Commands +- `poe format` — Format code +- `poe lint` — Lint code +- `poe test` — Run tests +- `poe mypy` — Type check with mypy +- `poe pyright` — Type check with pyright +- `poe docs-build` — Build documentation +- `poe docs-check` — Check documentation \ No newline at end of file diff --git a/01_REPO_MAP.md b/01_REPO_MAP.md new file mode 100644 index 000000000000..ecf136f1fde4 --- /dev/null +++ b/01_REPO_MAP.md @@ -0,0 +1,111 @@ +# 01_REPO_MAP.md — AutoGen Repository Map + +## Directory Structure +``` +autogen/ +├── .github/ +│ ├── ISSUE_TEMPLATE/ # Issue templates (bug, doc, maintainer) +│ └── workflows/ # CI/CD workflows +├── docs/ # Top-level documentation +├── dotnet/ # .NET implementation +├── protos/ # Protocol Buffer definitions +├── python/ # Main Python implementation +│ ├── docs/ # Sphinx documentation source +│ ├── packages/ # Python packages (see below) +│ ├── samples/ # Example scripts +│ ├── templates/ # Package templates +│ ├── pyproject.toml # Workspace root config +│ └── README.md # Development guide +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md +├── FAQ.md +├── LICENSE +├── README.md +├── SECURITY.md +├── SUPPORT.md +└── TRANSPARENCY_FAQS.md +``` + +## Python Packages + +### autogen-core +- **Path**: `python/packages/autogen-core/` +- **Purpose**: Interface definitions, agent runtime, model/tool/workbench/memory/tracing implementations +- **CI Tests**: mypy, pyright, test + +### autogen-agentchat +- **Path**: `python/packages/autogen-agentchat/` +- **Purpose**: Single and multi-agent workflows (AgentChat API) +- **Built on**: autogen-core +- **CI Tests**: mypy, pyright, test + +### autogen-ext +- **Path**: `python/packages/autogen-ext/` +- **Purpose**: Ecosystem integrations (OpenAI, Azure AI, MCP, code executors, etc.) +- **Extras**: openai, azure, mcp, anthropic, google, litellm, docker, etc. +- **CI Tests**: mypy, pyright, test, test-grpc, test-windows (PowerShell) + +### autogen-studio +- **Path**: `python/packages/autogen-studio/` +- **Purpose**: Web-based IDE for building/running AutoGen agents +- **Frontend**: Node.js-based UI + +### agbench +- **Path**: `python/packages/agbench/` +- **Purpose**: Benchmarking suite for evaluating agent performance +- **CI Tests**: mypy, pyright + +### magentic-one-cli +- **Path**: `python/packages/magentic-one-cli/` +- **Purpose**: CLI for Magentic-One multi-agent system +- **CI Tests**: mypy, pyright + +### pyautogen (Legacy) +- **Path**: `python/packages/pyautogen/` +- **Purpose**: Legacy v0.2 compatibility layer +- **Note**: For migration from v0.2 to v0.4+ + +### autogen-test-utils +- **Path**: `python/packages/autogen-test-utils/` +- **Purpose**: Shared test utilities for all packages + +### component-schema-gen +- **Path**: `python/packages/component-schema-gen/` +- **Purpose**: Schema generation for components + +## Key Entry Points + +### Core API +- `autogen_core` package entry point + +### AgentChat API +- `autogen_agentchat` package entry point +- Key classes: `AssistantAgent`, `BaseGroupChat`, `AgentTool` + +### Extensions API +- `autogen_ext` package with submodules for various integrations + +### AutoGen Studio +- `autogenstudio ui --port 8080` — Run studio + +## Code Quality Tools +- **Formatter**: ruff (with format plugin) +- **Linter**: ruff (E, F, W, B, Q, I, ASYNC, T20 rules) +- **Type Checkers**: mypy (strict), pyright +- **Test Runner**: pytest with asyncio support +- **Code Coverage**: pytest-cov + codecov + +## Recent Issue Activity (Sample) +- Many UTF-8 encoding fixes across packages (Windows compatibility) +- BaseGroupChat validation improvements +- MCP tool serialization fixes +- Documentation typo fixes +- Security fixes (SSRF, memory poisoning) + +## Contributing Notes +- Uses `uv` for dependency management +- Uses `poethepoet` (poe) for task automation +- All packages versioned together (semantic versioning) +- Breaking changes bump minor version, patches for features/fixes +- Docstring format: Google-style with versionadded/versionchanged directives +- CLA required for contributions \ No newline at end of file diff --git a/05_PR_CANDIDATES.md b/05_PR_CANDIDATES.md new file mode 100644 index 000000000000..01e710d3c9c1 --- /dev/null +++ b/05_PR_CANDIDATES.md @@ -0,0 +1,91 @@ +# 05_PR_CANDIDATES.md — AutoGen PR Candidate Analysis + +## Overview +This document outlines potential PR candidates identified during repository analysis. Given AutoGen's maintenance mode status, focus is on safe, small PRs that improve documentation, fix typos, add examples, or address isolated issues. + +## High-Priority Documentation PRs + +### 1. Issue #7690 — Fix duplicated words in Python docs +- **Type**: Documentation (docstring typo fix) +- **Description**: Fixes duplicated words in Python documentation comments +- **Status**: Open issue, no PR yet +- **Action**: Find the duplicated words in docstrings and fix them +- **Risk**: Very Low — only comment/docstring changes +- **Package**: Likely autogen-core or autogen-agentchat + +### 2. Issue #7689 — Fix typo in custom agents documentation +- **Type**: Documentation typo fix +- **Description**: Fix typo in custom agents documentation +- **Status**: Open issue, no PR yet +- **Action**: Find and fix the typo +- **Risk**: Very Low + +### 3. Issue #7676 — Add missing TextMessage import in custom agents docs +- **Type**: Documentation fix +- **Description**: docs(agentchat): add missing TextMessage import in custom agents docs +- **Status**: Open PR likely associated or issue open +- **Action**: Verify the docs have the correct import +- **Risk**: Very Low + +## UTF-8 Encoding Fixes (Windows Compatibility) + +### 4. Issue #5566 — open() needs encoding='utf-8' for non-English environments +- **Type**: Bug fix (cross-platform compatibility) +- **Description**: Many open() calls missing encoding parameter +- **Status**: Multiple PRs already fixed parts of this (see PRs 7699, 7707, 7717, 7723, etc.) +- **Action**: Check if any open() calls in samples/ or less-tested areas still lack encoding +- **Risk**: Low — adding explicit encoding parameter + +## Good First Issue Candidates + +### 5. Issue #6271 — LLMs.txt for AutoGen Documentation Guides +- **Type**: Documentation +- **Labels**: documentation, help wanted +- **Description**: Add llms.txt index for AutoGen documentation +- **Status**: Has PR associated (#7623 merged) +- **Action**: Verify if complete or needs more work + +### 6. Issue #6090 — Autogen website accessibility issues +- **Type**: Accessibility/Documentation +- **Labels**: documentation, help wanted +- **Description**: Low severity accessibility issues +- **Risk**: Low + +### 7. Issue #5626 — Provide a Streamlit example +- **Type**: Sample/Documentation +- **Labels**: documentation, sample-request +- **Description**: Streamlit example of a Team with Assistant Agent and User Proxy Agent +- **Risk**: Low + +## Code Quality Candidates + +### 8. TODO Comments in autogen-core +- **Type**: Code cleanup +- **Description**: Several TODO comments found in: + - `_runtime_impl_helpers.py` (optimization) + - `_tracing_config.py` (pythonic improvement) + - `_single_threaded_agent_runtime.py` (error handling) +- **Action**: Review TODOs for potential removal or implementation +- **Risk**: Medium — requires understanding context + +### 9. Issue #7627 — mutable default arguments + bare except in code executors +- **Type**: Code quality/bug fix +- **Description**: Code quality issue in code executors +- **Status**: Open +- **Risk**: Medium + +## Chosen Top 5 PR Candidates + +Based on analysis, these are the most actionable small PRs: + +1. **Fix duplicated words in Python docs** — Issue #7690 — Docstring typo fix +2. **Fix typo in custom agents docs** — Issue #7689 — Documentation typo fix +3. **Add encoding='utf-8' to remaining open() calls in samples** — Continuation of UTF-8 fixes +4. **Fix doc typo in agentchat** — Issue #7675 (minor doc comment typos) +5. **Verify/update sample with missing encoding** — Sample code improvement + +## Notes +- AutoGen is in maintenance mode — focus on small, safe PRs +- No new features being added +- Community-managed going forward +- CLA required for contributions \ No newline at end of file diff --git a/06_SELECTED_5_PR_PLAN.md b/06_SELECTED_5_PR_PLAN.md new file mode 100644 index 000000000000..c72e393af3e7 --- /dev/null +++ b/06_SELECTED_5_PR_PLAN.md @@ -0,0 +1,119 @@ +# 06_SELECTED_5_PR_PLAN.md — Selected PR Plan for AutoGen + +## Repository +- **Name**: microsoft/autogen (fork: okwn/autogen) +- **License**: CC-BY-4.0 +- **Status**: Maintenance mode, community-managed + +## Selected PR Candidates + +### PR 1: Fix duplicated words in Python docs +- **Issue**: #7690 +- **Title**: docs: fix duplicated words in Python docs +- **Type**: Documentation fix +- **Risk Level**: Very Low +- **Packages Affected**: Likely autogen-core or autogen-agentchat + +**Steps**: +1. Search for duplicated words in Python source docstrings +2. Fix any duplicated word occurrences +3. Run `poe --directory ./packages/autogen-core fmt` to format +4. Run `poe --directory ./packages/autogen-core lint` to verify +5. Create PR + +**Search Pattern**: Use regex to find common duplicated words (e.g., "the the", "and and", etc.) + +--- + +### PR 2: Fix typo in custom agents documentation +- **Issue**: #7689 +- **Title**: Fix typo in custom agents documentation +- **Type**: Documentation typo fix +- **Risk Level**: Very Low + +**Steps**: +1. Find custom agents documentation +2. Identify and fix the typo +3. Run formatting/linting +4. Create PR + +--- + +### PR 3: Add missing TextMessage import in custom agents docs +- **Issue**: #7676 +- **Title**: docs(agentchat): add missing TextMessage import in custom agents docs +- **Type**: Documentation fix +- **Risk Level**: Very Low + +**Steps**: +1. Find the custom agents documentation file +2. Check if TextMessage import is missing +3. Add the import if needed +4. Run formatting/linting +5. Create PR + +--- + +### PR 4: Fix minor doc comment typos +- **Issue**: #7675 +- **Title**: docs: fix minor doc comment typos +- **Type**: Documentation typo fix +- **Risk Level**: Very Low + +**Steps**: +1. Search for common typos in docstrings +2. Fix any found typos +3. Verify with `poe fmt` and `poe lint` +4. Create PR + +--- + +### PR 5: Add encoding='utf-8' to remaining open() calls +- **Issue**: #5566 continuation +- **Title**: fix: add encoding='utf-8' to open() calls in remaining samples +- **Type**: Bug fix (cross-platform compatibility) +- **Risk Level**: Low + +**Steps**: +1. Find all open() calls in python/samples that lack encoding parameter +2. Add encoding='utf-8' to each +3. Verify with tests if applicable +4. Create PR + +--- + +## CI/CD Checks Required + +All PRs must pass: +- `poe format` — Code formatting +- `poe lint` — Linting +- `poe mypy` — Type checking +- `poe test` — Unit tests + +## Development Workflow + +```bash +cd /root/oss-pr-campaign/repos/autogen/python + +# Setup +uv sync --all-extras +source .venv/bin/activate + +# Make changes +# ... edit files ... + +# Verify +poe format +poe lint +poe --directory ./packages/autogen-core test + +# Commit and push to fork +git add . +git commit -m "fix: description" +git push origin main +``` + +## Notes +- AutoGen is in maintenance mode — only small fixes and documentation improvements +- CLA must be signed before PR can be merged +- Community-managed, responses may be limited \ No newline at end of file diff --git a/python/docs/src/user-guide/agentchat-user-guide/migration-guide.md b/python/docs/src/user-guide/agentchat-user-guide/migration-guide.md index ce93cee66ea5..52aa81395826 100644 --- a/python/docs/src/user-guide/agentchat-user-guide/migration-guide.md +++ b/python/docs/src/user-guide/agentchat-user-guide/migration-guide.md @@ -1033,7 +1033,7 @@ In `v0.2` group chat, when tools are involved, you need to register the tool fun and include the user proxy in the group chat. The tool calls made by other agents will be routed to the user proxy to execute. -We have observed numerous issues with this approach, such as the the tool call +We have observed numerous issues with this approach, such as the tool call routing not working as expected, and the tool call request and result cannot be accepted by models without support for function calling. diff --git a/python/docs/src/user-guide/core-user-guide/faqs.md b/python/docs/src/user-guide/core-user-guide/faqs.md index cbec0e6afdec..6160c783712d 100644 --- a/python/docs/src/user-guide/core-user-guide/faqs.md +++ b/python/docs/src/user-guide/core-user-guide/faqs.md @@ -4,7 +4,7 @@ Agents might be distributed across multiple machines, so the underlying agent instance is intentionally discouraged from being accessed. If the agent is definitely running on the same machine, you can access the agent instance by calling {py:meth}`autogen_core.AgentRuntime.try_get_underlying_agent_instance` on the `AgentRuntime`. If the agent is not available this will throw an exception. -## How do I call call a function on an agent? +## How do I call a function on an agent? Since the instance itself is not accessible, you can't call a function on an agent directly. Instead, you should create a type to represent the function call and its arguments, and then send that message to the agent. Then in the agent, create a handler for that message type and implement the required logic. This also supports returning a response to the caller. diff --git a/python/samples/agentchat_chess_game/README.md b/python/samples/agentchat_chess_game/README.md index 769e54837c95..27cd9cf7eb04 100644 --- a/python/samples/agentchat_chess_game/README.md +++ b/python/samples/agentchat_chess_game/README.md @@ -24,7 +24,7 @@ To run this sample, you will need to install the following packages: pip install -U autogen-agentchat pyyaml ``` -Create a new file named `model_config.yaml` in the the same directory as the script +Create a new file named `model_config.yaml` in the same directory as the script to configure the model you want to use. For example, to use `gpt-4o` model from OpenAI, you can use the following configuration: diff --git a/python/samples/agentchat_streamlit/README.md b/python/samples/agentchat_streamlit/README.md index abcc451c9a79..2484392cddde 100644 --- a/python/samples/agentchat_streamlit/README.md +++ b/python/samples/agentchat_streamlit/README.md @@ -18,7 +18,7 @@ pip install "autogen-ext[openai,azure]" # pip install "autogen-ext[openai]" for OpenAI models ``` -Create a new file named `model_config.yml` in the the same directory as the script +Create a new file named `model_config.yml` in the same directory as the script to configure the model you want to use. For example, to use `gpt-4o-mini` model from Azure OpenAI, you can use the following configuration: