Merge getting started into guides; update references; add figure for agent life cycle (#599)

* refactor documentation layout

* lint

* update

python/packages/autogen-core/docs/drawio/agent-lifecycle.drawio

@@ -0,0 +1,58 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36 Edg/128.0.0.0" version="24.7.14">
+  <diagram name="Page-1" id="BpcakA4WUE9FyC1enh28">
+    <mxGraphModel dx="1038" dy="700" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-18" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;dashed=1;" vertex="1" parent="1">
+          <mxGeometry x="500" y="270" width="180" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-4" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="d0PH4c4Y_FGDyQ-Diqay-1" target="d0PH4c4Y_FGDyQ-Diqay-2">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-1" value="Message" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="155" y="345" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-6" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="d0PH4c4Y_FGDyQ-Diqay-2" target="d0PH4c4Y_FGDyQ-Diqay-3">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-2" value="Agent ID&lt;div&gt;type=&quot;code_reviewer&quot;&lt;/div&gt;&lt;div&gt;key=&quot;review/343&quot;&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
+          <mxGeometry x="275" y="330" width="150" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-3" value="CodeReviewerAgent" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="520" y="330" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-7" value="Auto-created by runtime if not exist" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="530" y="287" width="120" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-8" value="Delivered to" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="430" y="330" width="70" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-9" value="Sent to" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="210" y="330" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-10" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="d0PH4c4Y_FGDyQ-Diqay-11" target="d0PH4c4Y_FGDyQ-Diqay-13">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-11" value="Message" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="155" y="445" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="d0PH4c4Y_FGDyQ-Diqay-13" target="d0PH4c4Y_FGDyQ-Diqay-14">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-13" value="Agent ID&lt;div&gt;type=&quot;code_reviewer&quot;&lt;/div&gt;&lt;div&gt;key=&quot;review/423&quot;&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
+          <mxGeometry x="275" y="430" width="150" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-14" value="CodeReviewerAgent" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="520" y="430" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-16" value="Delivered to" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="430" y="430" width="70" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="d0PH4c4Y_FGDyQ-Diqay-17" value="Sent to" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="210" y="430" width="60" height="30" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

python/packages/autogen-core/docs/src/index.md

@@ -40,7 +40,7 @@ Key features of AGNext include:
 - Observable, traceable & debuggable -->
 
 ```{seealso}
-To start quickly, read the [Quick Start](user-guide/getting-started/quickstart) guide and follow the tutorial sections. To learn about the core concepts of AGNext, begin with [Agent and Multi-Agent Application](user-guide/core-concepts/agent-and-multi-agent-application).
+To start quickly, read the [Quick Start](user-guide/guides/quickstart) guide and follow the tutorial sections. To learn about the core concepts of AGNext, begin with [Agent and Multi-Agent Application](user-guide/core-concepts/agent-and-multi-agent-application).
 ```
 
 ```{toctree}

python/packages/autogen-core/docs/src/user-guide/core-concepts/agent-identity-and-lifecycle.md

@@ -1,6 +1,6 @@
 # Agent Identity and Lifecycle
 
-In AGNext, the agent runtime manages agents' identities
+The agent runtime manages agents' identities
 and lifecycles.
 Application does not create agents directly, rather,
 it registers an agent type with a factory function for
@@ -49,6 +49,8 @@ When a runtime delivers a message to an agent instance given its ID,
 it either fetches the instance,
 or creates it if it does not exist.
 
+![Agent Lifecycle](agent-lifecycle.svg)
+
 The runtime is also responsible for "paging in" or "out" agent instances
 to conserve resources and balance load across multiple machines.
 This is not implemented yet.

python/packages/autogen-core/docs/src/user-guide/core-concepts/api-layers.md

@@ -0,0 +1,28 @@
+# API Layers
+
+The API consists of the following layers:
+
+- {py:mod}`autogen_core.base`
+- {py:mod}`autogen_core.application`
+- {py:mod}`autogen_core.components`
+
+The following diagram shows the relationship between the layers.
+
+![Layers](layers.svg)
+
+The {py:mod}`autogen_core.base` layer defines the
+core interfaces and base classes for agents, messages, and runtime.
+This layer is the foundation of the framework and is used by the other layers.
+
+The {py:mod}`autogen_core.application` layer provides concrete implementations of
+runtime and utilities like logging for building multi-agent applications.
+
+The {py:mod}`autogen_core.components` layer provides reusable components for building
+AI agents, including type-routed agents, AI model clients, tools for AI models,
+code execution sandboxes, and memory stores.
+
+The layers are loosely coupled and can be used independently. For example,
+you can swap out the runtime in the {py:mod}`autogen_core.application` layer with your own
+runtime implementation.
+You can also skip the components in the {py:mod}`autogen_core.components` layer and
+build your own components.

python/packages/autogen-core/docs/src/user-guide/core-concepts/application-stack.md

@@ -4,14 +4,14 @@ AGNext is designed to be an unopinionated framework that can be used to build
 a wide variety of multi-agent applications. It is not tied to any specific
 agent abstraction or multi-agent pattern.
 
-The following diagram shows the AGNext application stack.
+The following diagram shows the application stack.
 
-![AGNext Application Stack](agnext-application-stack.svg)
+![Application Stack](application-stack.svg)
 
 At the bottom of the stack is the base messaging and routing facilities that
 enable agents to communicate with each other. These are managed by the
 agent runtime, and for most applications, developers only need to interact
-with the high-level APIs provided by the runtime (see [Agent and Agent Runtime](../getting-started/agent-and-agent-runtime.ipynb)).
+with the high-level APIs provided by the runtime (see [Agent and Agent Runtime](../guides/agent-and-agent-runtime.ipynb)).
 
 At the top of the stack, developers need to define the
 types of the messages that agents exchange. This set of message types
@@ -20,7 +20,7 @@ implementation of the contracts determines how agents handle messages.
 The behavior contract is also sometimes referred to as the message protocol.
 It is the developer's responsibility to implement the behavior contract.
 Multi-agent patterns emerge from these behavior contracts
-(see [Multi-Agent Design Patterns](../getting-started/multi-agent-design-patterns.md)).
+(see [Multi-Agent Design Patterns](../guides/multi-agent-design-patterns.md)).
 
 ## An Example Application
 
@@ -30,7 +30,7 @@ Coder Agent, Executor Agent, and Reviewer Agent.
 The following diagram shows the data flow between the agents,
 and the message types exchanged between them.
 
-![Code Generation Example](agnext-code-gen-example.svg)
+![Code Generation Example](code-gen-example.svg)
 
 In this example, the behavior contract consists of the following:
 

python/packages/autogen-core/docs/src/user-guide/core-concepts/architecture.md

@@ -17,7 +17,7 @@ In the Python API, an example of standalone runtime is the {py:class}`~autogen_c
 
 The following diagram shows the standalone runtime in the framework.
 
-![Standalone Runtime](agnext-architecture-standalone.svg)
+![Standalone Runtime](architecture-standalone.svg)
 
 Here, agents communicate via messages through the runtime, and the runtime manages
 the _lifecycle_ of agents.
@@ -33,7 +33,7 @@ Distributed runtime is suitable for multi-process applications where agents
 may be implemented in different programming languages and running on different
 machines.
 
-![Distributed Runtime](agnext-architecture-distributed.svg)
+![Distributed Runtime](architecture-distributed.svg)
 
 A distributed runtime, as shown in the diagram above,
 consists of a _host servicer_ and multiple _workers_.
@@ -45,32 +45,3 @@ They advertise to the host servicer the agents they run and manage the agents' l
 Agents work the same way as in the standalone runtime so that developers can
 switch between the two runtime types with no change to their agent implementation.
 
-
-## API Layers
-
-The API consists of the following layers:
-
-- {py:mod}`autogen_core.base`
-- {py:mod}`autogen_core.application`
-- {py:mod}`autogen_core.components`
-
-The following diagram shows the relationship between the layers.
-
-![AGNext Layers](agnext-layers.svg)
-
-The {py:mod}`autogen_core.base` layer defines the
-core interfaces and base classes for agents, messages, and runtime.
-This layer is the foundation of the framework and is used by the other layers.
-
-The {py:mod}`autogen_core.application` layer provides concrete implementations of
-runtime and utilities like logging for building multi-agent applications.
-
-The {py:mod}`autogen_core.components` layer provides reusable components for building
-AI agents, including type-routed agents, AI model clients, tools for AI models,
-code execution sandboxes, and memory stores.
-
-The layers are loosely coupled and can be used independently. For example,
-you can swap out the runtime in the {py:mod}`autogen_core.application` layer with your own
-runtime implementation.
-You can also skip the components in the {py:mod}`autogen_core.components` layer and
-build your own components.

python/packages/autogen-core/docs/src/user-guide/core-concepts/topic-and-subscription.md

@@ -1,6 +1,6 @@
 # Topic and Subscription in Broadcast
 
-In AGNext, there are two ways for runtime to deliver messages,
+There are two ways for runtime to deliver messages,
 direct messaging or broadcast. Direct messaging is one to one: the sender
 must provide the recipient's agent ID. On the other hand,
 broadcast is one to many and the sender does not provide recpients'
@@ -15,7 +15,7 @@ This section focuses on the core concepts in broadcast: topic and subscription.
 ## Topic
 
 A topic defines the scope of a broadcast message.
-In essence, AGNext agent runtime implements a publish-subscribe model through
+In essence, agent runtime implements a publish-subscribe model through
 its broadcast API: when publishing a message, the topic mus be specified.
 It is an indirection over agent IDs.
 

python/packages/autogen-core/docs/src/user-guide/index.md

@@ -7,7 +7,7 @@ myst:
 
 # User Guide
 
-AGNext is a flexible framework for building multi-agent systems. Begin with the [installation](getting-started/installation.md) guide to set up the framework on your machine. Then, follow the [quickstart](getting-started/quickstart) guide to get started with building your first multi-agent application.
+AGNext is a flexible framework for building multi-agent systems. Begin with the [installation](guides/installation.md) guide to set up the framework on your machine. Then, follow the [quickstart](guides/quickstart) guide to get started with building your first multi-agent application.
 
 ```{danger}
 This project and documentation is a work in progress. If you have any questions or need help, please reach out to us on GitHub.
@@ -18,8 +18,8 @@ This project and documentation is a work in progress. If you have any questions
 :maxdepth: 1
 :hidden:
 
-getting-started/installation
-getting-started/quickstart
+guides/installation
+guides/quickstart
 ```
 
 ```{toctree}
@@ -30,6 +30,7 @@ getting-started/quickstart
 
 core-concepts/agent-and-multi-agent-application
 core-concepts/architecture
+core-concepts/api-layers
 core-concepts/application-stack
 core-concepts/agent-identity-and-lifecycle
 core-concepts/topic-and-subscription
@@ -41,26 +42,32 @@ core-concepts/faqs
 :caption: Framework
 :maxdepth: 1
 :hidden:
-getting-started/agent-and-agent-runtime
-getting-started/message-and-communication
-getting-started/model-clients
-getting-started/tools
 
+guides/agent-and-agent-runtime
+guides/message-and-communication
+guides/model-clients
+guides/tools
+guides/logging
+guides/distributed-agent-runtime
+guides/telemetry
+guides/command-line-code-executors
 ```
 
 ```{toctree}
 :caption: Multi-Agent Design Patterns
 :maxdepth: 1
 :hidden:
-getting-started/multi-agent-design-patterns
-getting-started/group-chat
-getting-started/reflection
+
+guides/multi-agent-design-patterns
+guides/group-chat
+guides/reflection
 ```
 
 ```{toctree}
 :caption: Cookbook
 :maxdepth: 1
 :hidden:
+
 cookbook/azure-openai-with-aad-auth
 cookbook/termination-with-intervention
 cookbook/extracting-results-with-an-agent
@@ -70,14 +77,3 @@ cookbook/llamaindex-agent
 cookbook/local-llms-ollama-litellm
 
 ```
-
-```{toctree}
-:caption: Guides
-:maxdepth: 1
-:hidden:
-guides/logging
-guides/distributed-agent-runtime
-guides/telemetry
-guides/command-line-code-executors
-
-```