Merge branch 'main' into ryswee-xlang-aspire

.github/workflows/checks.yml

@@ -190,6 +190,7 @@ jobs:
         run: |
           source ${{ github.workspace }}/python/.venv/bin/activate
           poe gen-proto
+          poe gen-test-proto
         working-directory: ./python
       - name: Check if there are uncommited changes
         id: changes

CONTRIBUTING.md

@@ -24,10 +24,62 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
-## Roadmaps
+## Running CI checks locally
 
-To see what we are working on and what we plan to work on, please check our
-[Roadmap Issues](https://aka.ms/autogen-roadmap).
+It is important to use `uv` when running CI checks locally as it ensures that the correct dependencies and versions are used.
+
+Please follow the instructions [here](./python/README.md#setup) to get set up.
+
+For common tasks that are helpful during development and run in CI, see [here](./python/README.md#common-tasks).
+
+## Roadmap
+
+We use GitHub issues and milestones to track our roadmap. You can view the upcoming milestones [here]([Roadmap Issues](https://aka.ms/autogen-roadmap).
+
+## Versioning
+
+The set of `autogen-*` packages are generally all versioned together. When a change is made to one package, all packages are updated to the same version. This is to ensure that all packages are in sync with each other.
+
+We will update verion numbers according to the following rules:
+
+- Increase minor version (0.X.0) upon breaking changes
+- Increase patch version (0.0.X) upon new features or bug fixes
+
+## Release process
+
+1. Create a PR that updates the version numbers across the codebase ([example](https://github.com/microsoft/autogen/pull/4359))
+    2. The docs CI will fail for the PR, but this is expected and will be resolved in the next step
+2. After merging the PR, create and push a tag that corresponds to the new verion. For example, for `0.4.0.dev7`:
+    - `git tag 0.4.0.dev7 && git push origin 0.4.0.dev7`
+3. Restart the docs CI by finding the failed [job corresponding to the `push` event](https://github.com/microsoft/autogen/actions/workflows/docs.yml) and restarting all jobs
+4. Run [this](https://github.com/microsoft/autogen/actions/workflows/single-python-package.yml) workflow for each of the packages that need to be released and get an approval for the release for it to run
+
+## Triage process
+
+To help ensure the health of the project and community the AutoGen committers have a weekly triage process to ensure that all issues and pull requests are reviewed and addressed in a timely manner. The following documents the responsibilites while on triage duty:
+
+- Issues
+    - Review all new issues - these will be tagged with [`needs-triage`](https://github.com/microsoft/autogen/issues?q=is%3Aissue%20state%3Aopen%20label%3Aneeds-triage).
+    - Apply appropriate labels:
+        - One of `proj-*` labels based on the project the issue is related to
+        - `documentation`: related to documentation
+        - `x-lang`: related to cross language functionality
+        - `dotnet`: related to .NET
+    - Add the issue to a relevant milestone if necessary
+    - If you can resolve the issue or reply to the OP please do.
+    - If you cannot resolve the issue, assign it to the appropriate person.
+    - If awaiting a reply add the tag `awaiting-op-response` (this will be auto removed when the OP replies).
+    - Bonus: there is a backlog of old issues that need to be reviewed - if you have time, review these as well and close or refresh as many as you can.
+- PRs
+    - The UX on GH flags all recently updated PRs. Draft PRs can be ignored, otherwise review all recently updated PRs.
+    - If a PR is ready for review and you can provide one please go ahead. If you cant, please assign someone. You can quickly spin up a codespace with the PR to test it out.
+    - If a PR is needing a reply from the op, please tag it `awaiting-op-response`.
+    - If a PR is approved and passes CI, its ready to merge, please do so.
+    - If it looks like there is a possibly transient CI failure, re-run failed jobs.
+- Discussions
+    - Look for recently updated discussions and reply as needed or find someone on the team to reply.
+- Security
+    - Look through any securty alerts and file issues or dismiss as needed.
 
 ## Becoming a Reviewer
 

README.md

@@ -3,7 +3,9 @@
 <div align="center">
 <img src="https://microsoft.github.io/autogen/0.2/img/ag.svg" alt="AutoGen Logo" width="100">
 
-[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/cloudposse.svg?style=social&label=Follow%20%40pyautogen)](https://twitter.com/pyautogen)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/cloudposse.svg?style=social&label=Follow%20%40pyautogen)](https://twitter.com/pyautogen) [![GitHub Discussions](https://img.shields.io/badge/Discussions-Q%26A-green?logo=github)](https://github.com/microsoft/autogen/discussions) [![0.2 Docs](https://img.shields.io/badge/Docs-0.2-blue)](https://microsoft.github.io/autogen/0.2/) [![0.4 Docs](https://img.shields.io/badge/Docs-0.4-blue)](https://microsoft.github.io/autogen/dev/)
+[![PyPi autogen-core](https://img.shields.io/badge/PyPi-autogen--core-blue?logo=pypi)](https://pypi.org/project/autogen-core/0.4.0.dev7/) [![PyPi autogen-agentchat](https://img.shields.io/badge/PyPi-autogen--agentchat-blue?logo=pypi)](https://pypi.org/project/autogen-agentchat/0.4.0.dev7/) [![PyPi autogen-ext](https://img.shields.io/badge/PyPi-autogen--ext-blue?logo=pypi)](https://pypi.org/project/autogen-ext/0.4.0.dev7/)
+
 
 </div>
 
@@ -13,6 +15,7 @@
 > - (11/14/24) ⚠️ In response to a number of asks to clarify and distinguish between official AutoGen and its forks that created confusion, we issued a [clarification statement](https://github.com/microsoft/autogen/discussions/4217).
 > - (10/13/24) Interested in the standard AutoGen as a prior user? Find it at the actively-maintained *AutoGen* [0.2 branch](https://github.com/microsoft/autogen/tree/0.2) and `autogen-agentchat~=0.2` PyPi package.
 > - (10/02/24) [AutoGen 0.4](https://microsoft.github.io/autogen/dev) is a from-the-ground-up rewrite of AutoGen. Learn more about the history, goals and future at [this blog post](https://microsoft.github.io/autogen/blog). We’re excited to work with the community to gather feedback, refine, and improve the project before we officially release 0.4. This is a big change, so AutoGen 0.2 is still available, maintained, and developed in the [0.2 branch](https://github.com/microsoft/autogen/tree/0.2).
+> - *[Join us for Community Office Hours](https://github.com/microsoft/autogen/discussions/4059)* We will host a weekly open discussion to answer questions, talk about Roadmap, etc.
 
 AutoGen is an open-source framework for building AI agent systems.
 It simplifies the creation of event-driven, distributed, scalable, and resilient agentic applications.

docs/design/02 - Topics.md

@@ -51,3 +51,16 @@ Agents are able to handle certain types of messages. This is an internal detail
 
 > [!NOTE]
 > This might be revisited based on scaling and performance considerations.
+
+## Well known topic types
+
+Agents should subscribe via a prefix subscription to the `{AgentType}:` topic as a direct message channel for the agent type.
+
+For this subscription source should map directly to agent key.
+
+This subscription will therefore receive all events for the following well known topics:
+
+- `{AgentType}:` - General purpose direct messages. These should be routed to the approriate message handler.
+- `{AgentType}:rpc_request` - RPC request messages. These should be routed to the approriate RPC handler.
+- `{AgentType}:rpc_response={RequestId}` - RPC response messages. These should be routed back to the response future of the caller.
+- `{AgentType}:error={RequestId}` - Error message that corresponds to the given request.

docs/design/04 - Agent and Topic ID Specs.md

@@ -34,7 +34,7 @@ This document describes the structure, constraints, and behavior of Agent IDs an
 
 - Type: `string`
 - Description: Topic type is usually defined by application code to mark the type of messages the topic is for.
-- Constraints: UTF8 and only contain alphanumeric letters (a-z) and (0-9), or underscores (\_). A valid identifier cannot start with a number, or contain any spaces.
+- Constraints: UTF8 and only contain alphanumeric letters (a-z) and (0-9), ':', '=', or underscores (\_). A valid identifier cannot start with a number, or contain any spaces.
 - Examples:
   - `GitHub_Issues`
 

docs/design/readme.md

@@ -0,0 +1,3 @@
+# Docs
+
+You can find the project documentation [here](https://microsoft.github.io/autogen/dev/).

protos/agent_worker.proto

@@ -63,9 +63,15 @@ message TypeSubscription {
     string agent_type = 2;
 }
 
+message TypePrefixSubscription {
+    string topic_type_prefix = 1;
+    string agent_type = 2;
+}
+
 message Subscription {
     oneof subscription {
         TypeSubscription typeSubscription = 1;
+        TypePrefixSubscription typePrefixSubscription = 2;
     }
 }
 
@@ -111,12 +117,11 @@ message Message {
     oneof message {
         RpcRequest request = 1;
         RpcResponse response = 2;
-        Event event = 3;
+        cloudevent.CloudEvent cloudEvent = 3;
         RegisterAgentTypeRequest registerAgentTypeRequest = 4;
         RegisterAgentTypeResponse registerAgentTypeResponse = 5;
         AddSubscriptionRequest addSubscriptionRequest = 6;
         AddSubscriptionResponse addSubscriptionResponse = 7;
-        cloudevent.CloudEvent cloudEvent = 8;
     }
 }