From 1e60b67f2e240740f076551a7f39afc3544f172f Mon Sep 17 00:00:00 2001 From: Will Dembinski Date: Sun, 24 Nov 2024 17:55:29 -0800 Subject: [PATCH] Readme Edits | Just cleanup edits (#4102) * Readme edits to support the team --------- Co-authored-by: Jack Gerrits --- docs/design/01 - Programming Model.md | 16 ++++--- docs/design/02 - Topics.md | 8 ++-- docs/design/03 - Agent Worker Protocol.md | 2 +- docs/design/04 - Agent and Topic ID Specs.md | 48 ++++++++++---------- 4 files changed, 39 insertions(+), 35 deletions(-) diff --git a/docs/design/01 - Programming Model.md b/docs/design/01 - Programming Model.md index 732a46c6aeb..6bfa9f9766a 100644 --- a/docs/design/01 - Programming Model.md +++ b/docs/design/01 - Programming Model.md @@ -6,23 +6,27 @@ The programming model is basically publish-subscribe. Agents subscribe to events ## Events Delivered as CloudEvents -Each event in the system is defined using the [CloudEvents Specification](https://cloudevents.io/). This allows for a common event format that can be used across different systems and languages. In CloudEvents, each event has a Context Attributes that must unique *id* (eg a UUID) a *source* (a unique urn or path), a *type* (the namespace of the event - prefixed with a reverse-DNS name. The prefixed domain dictates the organization which defines the semantics of this event type: e.g *com.github.pull_request.opened* or -*com.example.object.deleted.v2*), and optionally fields describing the data schema/content-type or extensions. +Each event in the system is defined using the [CloudEvents Specification](https://cloudevents.io/). This allows for a common event format that can be used across different systems and languages. In CloudEvents, each event has "Context Attributes" that must include: + +1. *id* - A unique id (eg. a UUID). +2. *source* - A URI or URN indicating the event's origin. +3. *type* - The namespace of the event - prefixed with a reverse-DNS name. + - The prefixed domain dictates the organization which defines the semantics of this event type: e.g `com.github.pull_request.opened` or `com.example.object.deleted.v2`), and optionally fields describing the data schema/content-type or extensions. ## Event Handlers -Each agent has a set of event handlers, that are bound to a specific match against a CloudEvents *type*. Event Handlers could match against an exact type or match for a pattern of events of a particular level in the type heirarchy (eg: *com.Microsoft.AutoGen.Agents.System.\** for all Events in the *System* namespace) Each event handler is a function that can change state, call models, access memory, call external tools, emit other events, and flow data to/from other systems. Each event handler can be a simple function or a more complex function that uses a state machine or other control logic. +Each agent has a set of event handlers, that are bound to a specific match against a CloudEvents *type*. Event Handlers could match against an exact type or match for a pattern of events of a particular level in the type heirarchy (eg: `com.Microsoft.AutoGen.Agents.System.*` for all Events in the `System` namespace) Each event handler is a function that can change state, call models, access memory, call external tools, emit other events, and flow data to/from other systems. Each event handler can be a simple function or a more complex function that uses a state machine or other control logic. ## Orchestrating Agents -If is possible to build a functional and scalable agent system that only reacts to external events. In many cases, however, you will want to orchestrate the agents to achieve a specific goal or follow a pre-determined workflow. In this case, you will need to build an orchestrator agent that manages the flow of events between agents. +It is possible to build a functional and scalable agent system that only reacts to external events. In many cases, however, you will want to orchestrate the agents to achieve a specific goal or follow a pre-determined workflow. In this case, you will need to build an orchestrator agent that manages the flow of events between agents. ## Built-in Event Types The AutoGen system comes with a set of built-in event types that are used to manage the system. These include: -* System Events - Events that are used to manage the system itself. These include events for starting and stopping the Agents, sending messages to all agents, and other system-level events. -* ? insert other types here ? +- *System Events* - Events that are used to manage the system itself. These include events for starting and stopping the Agents, sending messages to all agents, and other system-level events. +- *Insert other types here* ## Agent Contracts diff --git a/docs/design/02 - Topics.md b/docs/design/02 - Topics.md index aca577e748f..7d7149c37c9 100644 --- a/docs/design/02 - Topics.md +++ b/docs/design/02 - Topics.md @@ -17,16 +17,16 @@ This document does not specify RPC/direct messaging A topic is identified by two components (called a `TopicId`): - [`type`](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) - represents the type of event that occurs, this is static and defined in code - - SHOULD use reverse domain name notation to avoid naming conflicts. For example: `com.example.my-topic`. + - SHOULD use reverse domain name notation to avoid naming conflicts. For example: `com.example.my-topic`. - [`source`](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) - represents where the event originated from, this is dynamic and based on the message itself - - SHOULD be a URI + - SHOULD be a URI Agent instances are identified by two components (called an `AgentId`): - `type` - represents the type of agent, this is static and defined in code - - MUST be a valid identifier as defined [here](https://docs.python.org/3/reference/lexical_analysis.html#identifiers) except that only the ASCII range is allowed + - MUST be a valid identifier as defined [here](https://docs.python.org/3/reference/lexical_analysis.html#identifiers) except that only the ASCII range is allowed - `key` - represents the instance of the agent type for the key - - SHOULD be a URI + - SHOULD be a URI For example: `GraphicDesigner:1234` diff --git a/docs/design/03 - Agent Worker Protocol.md b/docs/design/03 - Agent Worker Protocol.md index 49d9e867191..81a9b9b7e97 100644 --- a/docs/design/03 - Agent Worker Protocol.md +++ b/docs/design/03 - Agent Worker Protocol.md @@ -22,7 +22,7 @@ Agents are never explicitly created or destroyed. When a request is received for ## Worker protocol flow -The worker protocol has three phases, following the lifetime of the worker: initiation, operation, and termination. +The worker protocol has three phases, following the lifetime of the worker: initialization, operation, and termination. ### Initialization diff --git a/docs/design/04 - Agent and Topic ID Specs.md b/docs/design/04 - Agent and Topic ID Specs.md index 22a8a08894f..ee872ab2ac1 100644 --- a/docs/design/04 - Agent and Topic ID Specs.md +++ b/docs/design/04 - Agent and Topic ID Specs.md @@ -8,23 +8,23 @@ This document describes the structure, constraints, and behavior of Agent IDs an #### type -* Type: `string` -* Description: The agent type is not an agent class. It associates an agent with a specific factory function, which produces instances of agents of the same agent `type`. For example, different factory functions can produce the same agent class but with different constructor perameters. -* 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: - * `code_reviewer` - * `WebSurfer` - * `UserProxy` +- Type: `string` +- Description: The agent type is not an agent class. It associates an agent with a specific factory function, which produces instances of agents of the same agent `type`. For example, different factory functions can produce the same agent class but with different constructor perameters. +- 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: + - `code_reviewer` + - `WebSurfer` + - `UserProxy` #### key -* Type: `string` -* Description: The agent key is an instance identifier for the given agent `type` -* Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~). -* Examples: - * `default` - * A memory address - * a UUID string +- Type: `string` +- Description: The agent key is an instance identifier for the given agent `type` +- Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~). +- Examples: + - `default` + - A memory address + - a UUID string ## Topic ID @@ -32,16 +32,16 @@ This document describes the structure, constraints, and behavior of Agent IDs an #### type -* 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. -* Examples: - * `GitHub_Issues` +- 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. +- Examples: + - `GitHub_Issues` #### source -* Type: `string` -* Description: Topic source is the unique identifier for a topic within a topic type. It is typically defined by application data. -* Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~). -* Examples: - * `github.com/{repo_name}/issues/{issue_number}` \ No newline at end of file +- Type: `string` +- Description: Topic source is the unique identifier for a topic within a topic type. It is typically defined by application data. +- Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~). +- Examples: + - `github.com/{repo_name}/issues/{issue_number}`