i-am-bee · pilartomas · Feb 5, 2026 · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026
diff --git a/docs/development/deploy-agents/building-agents.mdx b/docs/development/deploy-agents/building-agents.mdx
@@ -3,17 +3,18 @@ title: "Build New Agents"
 description: "Start building your own agent with a simple Hello World example"
 ---
 
-To help you get started quickly, we’ve created a ready-to-use starter repository. You can clone it and start coding right away—no setup headaches or boilerplate required. This guide walks you through running your first “Hello World” agent and then customizing it to make it your own.
+To help you get started quickly, we’ve created a ready-to-use starter repository. The starter repo provides you basic scaffolding, a GitHub workflow, and a Dockerfile.
+You can clone it and start coding right away—no setup headaches or boilerplate required. Then customize the agent with your own logic.
 
 ## Prerequisites
 
-- Agent Stack installed ([Quickstart](../introduction/quickstart))
+- Agent Stack installed ([Quickstart](/stable/introduction/quickstart)) and the platform running with `agentstack platform start`
 - [uv](https://docs.astral.sh/uv/) package manager (should be already installed if you followed the quickstart)
 
-## Start From Template
+## 1.  Start From Template
 
 <Steps>
-<Step title="Use the official starter template">
+<Step title="Use the Official Starter Template">
 <Tabs>
 <Tab title="Clone directly">
 ```bash
@@ -29,7 +30,7 @@ cd my-agent
 </Tabs>
 </Step>
 
-<Step title="Test the Template Agent">
+<Step title="Run the Server and Autoregister with Agent Stack">
 
 ```bash
 uv run server
@@ -43,7 +44,7 @@ uv run watchfiles agentstack_agents.agent.run
 </Tip>
 
 </Step>
-<Step title="Run your agent">
+<Step title="Run Your Agent">
 
 In another terminal:
 
@@ -57,9 +58,9 @@ You should see: "Ciao Alice!" 🎉
 
 With your first agent running, you can now modify it to do anything you want.
 
-## Implement Your Agent Logic
+## 2. Implement Your Agent Logic
 
-Navigate to [src/agentstack_agents/agent.py](https://github.com/i-am-bee/agentstack-starter/blob/main/src/agentstack_agents/agent.py) and replace the example with your agent logic.
+In the starter repo, navigate to [src/agentstack_agents/agent.py](https://github.com/i-am-bee/agentstack-starter/blob/main/src/agentstack_agents/agent.py) and replace the example with your agent logic.
 
 The starter example is minimal and intended for demonstration purposes only:
 
@@ -92,69 +93,65 @@ if __name__ == "__main__":
 
 <Steps title="Building Your First Agent: Step-by-Step">
 
-<Step title="Start a server">
-An agent is essentially an HTTP server. Create a `Server` instance and run it using `run()`.
-</Step>
-
-<Step title="Mark your agent function">
-Add the `@server.agent` decorator to your function so the platform recognizes it as an agent.
-</Step>
+<Step title="Start and Configure the Server">
+An agent is essentially an HTTP server. Use `server.run()` to define how your agent listens for requests:
+- Host: Defaults to `127.0.0.1` (localhost).
+- Port: Defaults to `8000`. If you run multiple agents on the same machine, ensure each has a unique port.
 
-<Step title="Name your agent">
-The function name becomes the agent’s name in the platform.
 </Step>
 
-<Step title="Describe your agent">
-Write a docstring for the function; it will be extracted and shown as the agent’s description in the platform.
-</Step>
-
-<Step title="Understand the function arguments">
-- **First argument:** an [A2A `Message`](https://a2a-protocol.org/latest/specification/#64-message-object).
-- **Second argument:** a `RunContext` object with run details (e.g., `task_id`, `context_id`).
+<Step title="Mark Your Agent Function">
+Add the `@server.agent` decorator to your function so the platform recognizes it as an agent.
 </Step>
 
-<Step title="Extract text from Message">
-Use `get_message_text()` to quickly extract the text content from a `Message`.
+<Step title="Name and Describe Your Agent">
+- Identity: The function name (e.g., example_agent) becomes the agent’s unique identifier. 
+- Metadata: Write a clear docstring. The SDK extracts this text to serve as the agent’s description in UIs and registries, helping understand what your agent does.
 </Step>
 
-<Step title="Make it an async generator">
-The agent function should be asynchronous and yield results as they’re ready.
+<Step title="Understand the Function Arguments">
+- First argument: An [A2A `Message`](https://a2a-protocol.org/latest/specification/#64-message-object). Use `get_message_text(input)` to pull the raw string from the user. This is where you would typically pass data into your LLM or custom processing logic.
+- Second argument: A `RunContext` object with run details provides metadata about the current execution (e.g., `task_id`, `context_id`). Use this if your agent logic needs to track session state or reference specific task parameters.
 </Step>
 
-<Step title="Send responses easily">
-- Yield an `AgentMessage` (a handy wrapper around A2A Message) for convenience.
-- Or yield a plain `str`, which will be automatically converted into an A2A Message.
+<Step title="Stream Responses via Async Generator">
+Agents should be async and use `yield`. This allows the server to stream responses back to the client in real time. Yield an `AgentMessage` (a handy wrapper around A2A Message) for convenience or a plain `str`, which will be automatically converted into an A2A Message.
 </Step>
 
 </Steps>
 
-## Starting from Scratch
-
-If you prefer not to use the starter repo:
-- Create an empty Python project
-- Install `agentstack-sdk`
-- Copy the example code above
+## Manual Project Configuration
 
-The starter repo mainly provides basic scaffolding, a GitHub workflow, and a Dockerfile — all optional.
+If you prefer not to use our starter template, you must ensure your project includes these core components to integrate correctly with the Agent Stack platform.
+- The SDK Inegration
+    - Add agentstack-sdk to your project dependencies.
+    - Your code must initialize a Server() instance from the SDK.
+    - You need a designated function that calls server.run(host, port). This is what allows the platform (and Docker) to start your agent.
+- Agent logic remains the same as in the [Implement Your Agent Logic](https://agentstack.beeai.dev/stable/deploy-agents/building-agents#implement-your-agent-logic) section
+- Containerization Requirements
+    - If you plan to deploy your agent to the platform (rather than just running it locally), your repository must contain a `Dockerfile`
+- Git and Platform Metadata
+    - The repository must be accessible to the Agent Stack orchestrator if you are using the `agentstack add` command via URL.
+    - Use Git tags (e.g., v1.0.0) if you want to manage stable releases of your agent.
 
 ## Next Steps
 
 After building your agent, you can enhance it and learn more:
 
 <CardGroup cols={2}>
-<Card title="Agent Details" icon="id-card" href="../agent-integration/agent-details">
+<Card title="Agent Details" icon="id-card" href="/stable/agent-integration/agent-details">
 Customize your agent's name, description, and how it appears in the UI
 </Card>
 
-<Card title="Working with Messages" icon="comment" href="../agent-integration/messages">
+<Card title="Working with Messages" icon="comment" href="/stable/agent-integration/messages">
 Learn how agents and clients communicate through structured messaging
 </Card>
 
-<Card title="Multi-Turn Conversations" icon="comments" href="../agent-integration/multi-turn">
+<Card title="Multi-Turn Conversations" icon="comments" href="/stable/agent-integration/multi-turn">
 Understand how to handle multi-turn conversations and maintain context
 </Card>
 
-<Card title="Working with Files" icon="file" href="../agent-integration/files">
+<Card title="Working with Files" icon="file" href="/stable/agent-integration/files">
 Work with files to provide inputs or store outputs for your agent
 </Card>
 </CardGroup>
diff --git a/docs/development/deploy-agents/wrap-existing-agents.mdx b/docs/development/deploy-agents/wrap-existing-agents.mdx
@@ -27,8 +27,11 @@ The Agent Stack server wraps your existing agent code and exposes it through the
 ### 1. Install the SDK
 
 ```bash
-pip install agentstack-sdk
+uv add agentstack-sdk
 ```
+<Tip>
+  If you are starting a new `uv` project, run `uv init` to set up the project structure before adding packages.
+</Tip>
 
 ### 2. Create a Server Wrapper
 
@@ -74,7 +77,7 @@ if __name__ == "__main__":
 ### 3. Run Your Server
 
 ```bash
-python server.py
+uv run server.py
 ```
 
 Your agent will automatically register with Agent Stack!
@@ -86,7 +89,7 @@ uv run watchfiles agentstack_agents.agent.run
 ```
 </Tip>
 
-## Integration Patterns
+## Advanced Implementations
 
 ### Streaming Responses
 

diff --git a/docs/development/introduction/quickstart.mdx b/docs/development/introduction/quickstart.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Quickstart"
-description: "Get a running instance in minutes and explore pre-built agents"
+description: "Get Agent Stack up and running in minutes. Then explore running pre-built agents."
 ---
 
 ## Prerequisites
@@ -22,19 +22,26 @@ Open the terminal and run this command to install Agent Stack:
 sh -c "$(curl -LsSf https://raw.githubusercontent.com/i-am-bee/agentstack/install/install.sh)"
 ```
 
-This interactive script installs Agent Stack CLI, downloads and starts the platform, prompts you to configure your LLM API key, then launches the web interface.
+<Info> 
+
+The installer sets up `uv` and the `agentstack-cli` on your host machine. Agent Stack uses a Virtual Machine (managed via a bundled [Lima](https://github.com/lima-vm/lima) binary) to keep your host machine clean. The Kubernetes cluster running the Agent Stack server, agent containers, and associated storage and services live entirely inside the VM and not on your host directly. 
+
+
+For details on what happens under the hood, refer to the Manual Install section or read the [`install.sh`](https://github.com/i-am-bee/agentstack/blob/install/install.sh) source code.
+
+</Info>
 
 <Accordion title="Manual Install">
 
 <Steps>
 <Step title="Install uv">
 
-Follow the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
+Follow the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/). Agent Stack uses `uv` to manage its own internal Python environment.
 
 </Step>
 <Step title="Linux only: Install QEMU">
 
-Install QEMU via package manager ([instructions](https://www.qemu.org/download/)).
+On Linux, Lima requires QEMU. Install it via these ([instructions](https://www.qemu.org/download/)).
 
 </Step>
 <Step title="Install Agent Stack">
@@ -45,7 +52,7 @@ Open a new terminal and run:
 uv python install --quiet --python-preference=only-managed --no-bin 3.13 && uv tool install --refresh --force --python-preference=only-managed --python=3.13 agentstack-cli && agentstack self install
 ```
 
-Follow the interactive prompts to finish installation and setup.
+Follow the interactive prompts to finish setup and  optionally start the VM.
 
 </Step>
 </Steps>
@@ -165,12 +172,12 @@ Follow the interactive prompts to finish the installation and setup.
 ## Usage
 
 ```sh
-agentstack ui                     # Launch web interface
-agentstack list                   # See what agents are available
-agentstack run chat "Hi!"         # Send a message to chat agent
-agentstack run chat               # Try interactive mode
-agentstack info chat              # View agent details
-agentstack --help                 # See all options
+agentstack ui                          # Launch web interface
+agentstack list                        # See what agents are available
+agentstack run chat "Hi, who are you"  # Send a message to chat agent
+agentstack run chat                    # Try interactive mode
+agentstack info chat                   # View agent details
+agentstack --help                      # See all options
 ```
 
 ## Platform Management

diff --git a/docs/stable/deploy-agents/building-agents.mdx b/docs/stable/deploy-agents/building-agents.mdx
@@ -3,17 +3,18 @@ title: "Build New Agents"
 description: "Start building your own agent with a simple Hello World example"
 ---
 
-To help you get started quickly, we’ve created a ready-to-use starter repository. You can clone it and start coding right away—no setup headaches or boilerplate required. This guide walks you through running your first “Hello World” agent and then customizing it to make it your own.
+To help you get started quickly, we’ve created a ready-to-use starter repository. The starter repo provides you basic scaffolding, a GitHub workflow, and a Dockerfile.
+You can clone it and start coding right away—no setup headaches or boilerplate required. Then customize the agent with your own logic.
 
 ## Prerequisites
 
-- Agent Stack installed ([Quickstart](/stable/introduction/quickstart))
+- Agent Stack installed ([Quickstart](/stable/introduction/quickstart)) and the platform running with `agentstack platform start`
 - [uv](https://docs.astral.sh/uv/) package manager (should be already installed if you followed the quickstart)
 
-## Start From Template
+## 1.  Start From Template
 
 <Steps>
-<Step title="Use the official starter template">
+<Step title="Use the Official Starter Template">
 <Tabs>
 <Tab title="Clone directly">
 ```bash
@@ -29,7 +30,7 @@ cd my-agent
 </Tabs>
 </Step>
 
-<Step title="Test the Template Agent">
+<Step title="Run the Server and Autoregister with Agent Stack">
 
 ```bash
 uv run server
@@ -43,7 +44,7 @@ uv run watchfiles agentstack_agents.agent.run
 </Tip>
 
 </Step>
-<Step title="Run your agent">
+<Step title="Run Your Agent">
 
 In another terminal:
 
@@ -57,9 +58,9 @@ You should see: "Ciao Alice!" 🎉
 
 With your first agent running, you can now modify it to do anything you want.
 
-## Implement Your Agent Logic
+## 2. Implement Your Agent Logic
 
-Navigate to [src/agentstack_agents/agent.py](https://github.com/i-am-bee/agentstack-starter/blob/main/src/agentstack_agents/agent.py) and replace the example with your agent logic.
+In the starter repo, navigate to [src/agentstack_agents/agent.py](https://github.com/i-am-bee/agentstack-starter/blob/main/src/agentstack_agents/agent.py) and replace the example with your agent logic.
 
 The starter example is minimal and intended for demonstration purposes only:
 
@@ -92,50 +93,46 @@ if __name__ == "__main__":
 
 <Steps title="Building Your First Agent: Step-by-Step">
 
-<Step title="Start a server">
-An agent is essentially an HTTP server. Create a `Server` instance and run it using `run()`.
-</Step>
+<Step title="Start and Configure the Server">
+An agent is essentially an HTTP server. Use `server.run()` to define how your agent listens for requests:
+- Host: Defaults to `127.0.0.1` (localhost).
+- Port: Defaults to `8000`. If you run multiple agents on the same machine, ensure each has a unique port.
 
-<Step title="Mark your agent function">
-Add the `@server.agent` decorator to your function so the platform recognizes it as an agent.
 </Step>
 
-<Step title="Name your agent">
-The function name becomes the agent’s name in the platform.
-</Step>
-
-<Step title="Describe your agent">
-Write a docstring for the function; it will be extracted and shown as the agent’s description in the platform.
-</Step>
-
-<Step title="Understand the function arguments">
-- **First argument:** an [A2A `Message`](https://a2a-protocol.org/latest/specification/#64-message-object).
-- **Second argument:** a `RunContext` object with run details (e.g., `task_id`, `context_id`).
+<Step title="Mark Your Agent Function">
+Add the `@server.agent` decorator to your function so the platform recognizes it as an agent.
 </Step>
 
-<Step title="Extract text from Message">
-Use `get_message_text()` to quickly extract the text content from a `Message`.
+<Step title="Name and Describe Your Agent">
+- Identity: The function name (e.g., example_agent) becomes the agent’s unique identifier. 
+- Metadata: Write a clear docstring. The SDK extracts this text to serve as the agent’s description in UIs and registries, helping understand what your agent does.
 </Step>
 
-<Step title="Make it an async generator">
-The agent function should be asynchronous and yield results as they’re ready.
+<Step title="Understand the Function Arguments">
+- First argument: An [A2A `Message`](https://a2a-protocol.org/latest/specification/#64-message-object). Use `get_message_text(input)` to pull the raw string from the user. This is where you would typically pass data into your LLM or custom processing logic.
+- Second argument: A `RunContext` object with run details provides metadata about the current execution (e.g., `task_id`, `context_id`). Use this if your agent logic needs to track session state or reference specific task parameters.
 </Step>
 
-<Step title="Send responses easily">
-- Yield an `AgentMessage` (a handy wrapper around A2A Message) for convenience.
-- Or yield a plain `str`, which will be automatically converted into an A2A Message.
+<Step title="Stream Responses via Async Generator">
+Agents should be async and use `yield`. This allows the server to stream responses back to the client in real time. Yield an `AgentMessage` (a handy wrapper around A2A Message) for convenience or a plain `str`, which will be automatically converted into an A2A Message.
 </Step>
 
 </Steps>
 
-## Starting from Scratch
-
-If you prefer not to use the starter repo:
-- Create an empty Python project
-- Install `agentstack-sdk`
-- Copy the example code above
-
-The starter repo mainly provides basic scaffolding, a GitHub workflow, and a Dockerfile — all optional.
+## Manual Project Configuration
+
+If you prefer not to use our starter template, you must ensure your project includes these core components to integrate correctly with the Agent Stack platform.
+- The SDK Inegration
+    - Add agentstack-sdk to your project dependencies.
+    - Your code must initialize a Server() instance from the SDK.
+    - You need a designated function that calls server.run(host, port). This is what allows the platform (and Docker) to start your agent.
+- Agent logic remains the same as in the [Implement Your Agent Logic](https://agentstack.beeai.dev/stable/deploy-agents/building-agents#implement-your-agent-logic) section
+- Containerization Requirements
+    - If you plan to deploy your agent to the platform (rather than just running it locally), your repository must contain a `Dockerfile`
+- Git and Platform Metadata
+    - The repository must be accessible to the Agent Stack orchestrator if you are using the `agentstack add` command via URL.
+    - Use Git tags (e.g., v1.0.0) if you want to manage stable releases of your agent.
 
 ## Next Steps