New Guide Article : "Microbots : Introduction, Installation Guide and Creating Your First MicroBot" and structural changes in blog by shivashanmugam · Pull Request #132 · microsoft/microbots

shivashanmugam · 2026-04-17T11:38:37Z

Changes with this PR

Create Getting Started Article

Creation of new sections in Guide
Bots. Tools,

Fix of paths in

From : microbots/copilot-bot/
To : microbots/advanced/bots/copilot-bot/

From : microbots/blog/guides/tesseract_ocr_tool_use/
To : microbots/advanced/tools/tesseract_ocr_tool_use/

From : /microbots/authentication/
To : microbots/advanced/authentication/

Added Introduction, Getting Started, Advanced Section, Rename "Blogs" to "Blog"

codecov-commenter · 2026-04-17T11:40:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.95%. Comparing base (d41a0a9) to head (43f89c7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #132   +/-   ##
=======================================
  Coverage   64.95%   64.95%           
=======================================
  Files          34       34           
  Lines        2374     2374           
=======================================
  Hits         1542     1542           
  Misses        832      832

Flag	Coverage Δ
integration	`34.49% <ø> (ø)`
ollama_local	`32.05% <ø> (-0.17%)`	⬇️
slow-browser	`26.83% <ø> (ø)`
slow-other	`38.37% <ø> (-0.17%)`	⬇️
unit	`59.18% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

0xba1a · 2026-04-20T10:26:01Z

@@ -0,0 +1,9 @@
+"use strict";


We don't need to add output files and log files. Only initial source files are sufficient as it can be used by the reader

Removed the build.log and app.js which was output of tsc app.ts

0xba1a · 2026-04-20T10:29:24Z

+!!! note
+    For advanced authentication options (Azure AD tokens, managed identity, service principals), see the [Authentication Guide](../advanced/authentication.md).
+
+## Install Microbots


This needs detailed walkthrough - Python installation, venv creation and microbots installation. Also, in Windows, we need to do it inside wsl.

Added python installation in Install Microbots prerequisites Section

0xba1a · 2026-04-20T10:31:43Z

+
+### Step 1: Prepare a sample project
+
+Create a project folder with a TypeScript file that has a syntax error. When the TypeScript compiler (`tsc`) tries to convert it to JavaScript, it fails — and the error output is captured in a log file.


User can create it or they can simply clone your example folder and follow the instructions step-by-step

Added detailed instruction on creating project and create files inside and expected project structure

0xba1a · 2026-04-20T10:32:03Z

+
+Create `code/app.ts` with a deliberate syntax error:
+
+```typescript title="code/app.ts"


Please use line number feature of snippet plugin

Added line number feature in code/app.ts

0xba1a · 2026-04-20T10:33:32Z

+
+```bash title="Terminal"
+cd code
+tsc app.ts > build.log 2>&1


Log files are naturally ignored by .gitignore. So, it will not be visible after deployment. Because sharing original log file may explose system related information. So, please use snippet of the log file here.

Removed build.log reference

0xba1a · 2026-04-20T10:33:53Z

+This produces the following build log:
+
+```log title="code/build.log"
+--8<-- "docs/examples/microbots_introduction/code/build.log"


build.log will not be checke-in to the git repo

Removed build.log reference

0xba1a · 2026-04-20T10:34:59Z

+    └── build.log
+```
+
+### Step 2: Analyze logs with a LogAnalysisBot


Considering this is going to be the very first blog for the user, we need to add more details here. The flow of agent creation and agent run. Individual arguments of Agent initialization and run function has to be explained.

Added detailed code walkthrough which can be expanded which will have each function call and arguments which it will accept ( mainly the Microbots Instance creation and run function )

0xba1a · 2026-04-20T10:36:57Z

+
+1. **Created a Docker container** with the `code` folder mounted using the appropriate permissions.
+2. **Sent your task** to the LLM along with a system prompt tailored to the bot type.
+3. **Executed commands** inside the container as directed by the LLM (e.g., `cat`, `grep`, `sed`).


Please import logging and set logging config to print INFO log in the LogAnalysisBot.py. So, user can see the individual command the LLM runs. Also, you can point them how to read the logs with some examples here.

Enabled logging info in code and added the full log output when user is interested to see

0xba1a · 2026-04-21T08:42:13Z

+
+**Install Python:**
+
+- **Windows:** Download the latest installer from [python.org](https://www.python.org/downloads/). During installation, check **"Add Python to PATH"**.


Did you verify running microbots on Windows without WSL. If not, you can only mention this guide for Linux setup. We'll update it soon for Windows setup.

There was issue with logAnalysisBot in windows. I have removed all windows instruction and created new ticket for windows microbots issue. Directly in windows it is not working https://github.com/microsoft/microbots/issues/138
.

But it works in wsl. Verified with Fedora 42 in windows with docker installed inside the wsl

0xba1a · 2026-04-21T08:43:30Z

+    sudo apt update && sudo apt install python3 python3-pip python3-venv
+
+    # Fedora
+    sudo dnf install python3 python3-pip


python3-venv is missing for Fedora. Please create a simple Fedora container and verify your steps whether they are valid.

Already python-3-venv is not mentioned as installation dependency in fodora. It is only mentioned for ubuntu and debian.
.
Also verified this example of microbots in fedora and ubuntu

0xba1a · 2026-04-21T08:45:09Z

+Create a `.env` file in the root of your application with:
+
+```env title=".env"
+OPEN_AI_END_POINT=https://your-resource-name.openai.azure.com


With reference Kavya's internal chat, END_POINT value should be enclosed in double quotes. Please verify.

Converted the endpoints with Double quotes

0xba1a · 2026-04-21T08:48:06Z

+├── log_analysis_bot.py
+└── code/
+    ├── app.ts
+    ├── app.js


Will app.js present if ts file compilation fails?

Yes. app.js will be present even if compilation fails

0xba1a · 2026-04-21T08:50:06Z

+
+from dotenv import load_dotenv
+
+load_dotenv()


load_dotenv() will be used if environment variables are stored in a file named .env. As in your example, you are explicitely setting env variables, you may not need .env

Removed. Conveyed microbots will load variables in .env automatically in place. No need to explicitly load environment variables unless having a .env file

0xba1a · 2026-04-21T08:54:03Z

+    |----------|------|----------|-------------|
+    | `model` | `str` | Yes | The LLM to use, in the format `<provider>/<model_name>`. Supported providers include `azure-openai`, `anthropic`, and `ollama`. |
+    | `folder_to_mount` | `str` | Yes | Path to the local folder the bot can access. For `LogAnalysisBot`, this is mounted as **read-only** inside the Docker container so the bot can read source files but never modify them. |
+    | `environment` | `any` | No | A custom execution environment. Defaults to a `LocalDockerEnvironment` if not provided. |


You don't need to mention all the possible arguments here. Please explain only those arguments. In parallel, you can generate an auto documentation and link to the class definition of LogAnalysisBot.

Added references to LogAnalysisBot Class

0xba1a · 2026-04-21T08:59:56Z

+    | Argument | Type | Default | Description |
+    |----------|------|---------|-------------|
+    | `file_name` | `str` | — | **(Required)** Path to the log file to analyze. The file is copied into the container as read-only. |
+    | `max_iterations` | `int` | `20` | Maximum number of LLM reasoning/command loops before the bot stops. Each iteration is one round of the LLM issuing a command and receiving its output. |


max_iteration can be removed from here as it is not used in the code

Removed max_iterations, Direct reference to the method

0xba1a · 2026-04-21T09:01:42Z

+
+    When `run()` is called, it:
+
+    1. Copies the log file into the Docker container at a dedicated `/var/log/` path.


This detailed explanation will not make sense until someone understood the agentic architecture and Microbot's internals. So, you can simply mention that the Agent is invoked by run. Once agent completes, the result will be available in result.result.

Removed, Just added the reference to run Method

0xba1a · 2026-04-21T09:02:48Z

+    ```
+    Prints the bot's root-cause analysis.
+
+The `my_bot.run()` method returns a `BotRunResult` object with the following fields:


BotRunResult should be a link to the BotRunResult class documentation. In python document generation is easier. That document you should create and make corresponding link.

Added references to "BotRunResult

0xba1a · 2026-04-21T09:04:50Z

+```text title="Terminal output"
+(.venv) $ python3 log_analysis_bot.py
+
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🗂️  Created working directory at /home/sikannan/MICROBOTS_WORKDIR_18da47d7


Giving the complete terminal output is not advised as it may reveal some machine related secrets. You can simply mention how to run the code, where the user can find the log and how to interpret the log with snippets of log

Added addition step with snippets of log out along with note conveying "they skip the step if not required"

…with-microbots

Co-authored-by: Copilot <copilot@github.com>

…with-microbots

0xba1a · 2026-05-22T13:37:35Z

I appreciate this document. It's a good start for anyone who wants to write a blog. Also, these points will be helpful while reviewing or setting-up an AI auto-reviewer.

Good idea. Should have a AI auto-reviewer for blogs with this Technical Writing Guidelines document being as reference. Will keep in pipeline of one of the microbots blog management task

0xba1a · 2026-05-22T13:38:28Z

+
+## Step 1 — Create the Sample Project
+
+From the root of your `microbots-introduction` project, create a `code/` folder:


Please mention that this sample code and LogAnalysisBot code are available Microbot's example directory from where the user can download/clone and use it for following this document.

0xba1a · 2026-05-22T13:39:23Z

+
+`code/build.log` should contain:
+
+```log title="code/build.log"


Please enable line numbers for this file

0xba1a · 2026-05-22T13:41:49Z

+expected ';' before '}' token". Fix by adding a semicolon: `return a + b;`.
+```
+
+Continue with [Conclusion](../conclusion.md).


Please have a proper conclusion as such, "we have created a buggy code and successfully analyzed it with Microbots. As per the analysis, the LogAnalysisBot has correctly identified the bug in the code and and explained the solution too".

And give a starting point for the next article - "Please read the next article for understanding what happens behind the scene and how to debug Microbots code with Log"

0xba1a · 2026-05-22T13:44:34Z

We can have a better name than "Conclusion". - depicting what this article actually discusses.

Additionally, have a section on how to enable Microbots logs with Python logging and how to read it. If you find it making the article longer, you can make it as the fifth page of this article series.

0xba1a · 2026-05-22T13:59:00Z

+
+## Step 2 — Installing Docker
+
+On macOS, install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and launch it.


Please install Windows setup link too.

Also, please mention for Windows, they've to install docker on Windows, and run the code in WSL. A separate article will be add here for Windows setup later.

0xba1a · 2026-05-22T14:00:04Z

+```bash title="Terminal"
+sudo systemctl enable --now docker
+sudo usermod -aG docker $USER
+newgrp docker


Can you please confirm the steps. The previous command adds the user to docker group. But the new-group is created after adding a user to it!

0xba1a · 2026-05-22T14:00:23Z

+
+A "Hello from Docker!" message confirms the daemon is reachable.
+
+Continue with the [Microbot Installation](installation-guide.md) guide.


A simple conclusion is appropriate here.

0xba1a · 2026-05-22T14:02:45Z


 ## ✨ LLM Support

 Azure OpenAI Models — add environment variables in a `.env` file:


This section is misleading as if Microbots supports only Azure-OpenAI. Please mention all the LLMs supported by Microbots and link to the env variable page which specifies what set of env variables need to be set for what LLM provider.

0xba1a · 2026-05-22T14:04:00Z

I think Introduction and ReadMe can be same file. Try using a softlink if git supports it.

microbots intro

9a1040a

shivashanmugam changed the title ~~microbots intro~~ New Guide Article : "Microbots : Introduction, Installation Guide and Creating Your First MicroBot" and structural changes in blog Apr 17, 2026

shivashanmugam requested a review from 0xba1a April 17, 2026 12:39

0xba1a requested changes Apr 20, 2026

View reviewed changes

shivashanmugam added 3 commits April 20, 2026 16:55

removing app.js file from the examples folder

31097a8

fix pr comments

8eaac5d

remove the os import

41cb5a2

shivashanmugam requested a review from 0xba1a April 21, 2026 08:50

0xba1a requested changes Apr 21, 2026

View reviewed changes

shivashanmugam and others added 3 commits April 27, 2026 09:55

Merge remote-tracking branch 'origin/main' into siva/getting-started-…

69a627e

…with-microbots

fix comments

c1272af

Co-authored-by: Copilot <copilot@github.com>

change python to python3

06b333b

Co-authored-by: Copilot <copilot@github.com>

shivashanmugam requested a review from 0xba1a April 29, 2026 06:29

shivashanmugam added 10 commits May 18, 2026 11:23

changes getting started

441a4e1

update getting started with minimal text as suggessted

a7f4714

first bot changes

b459d87

Merge remote-tracking branch 'origin/main' into siva/getting-started-…

7efb73c

…with-microbots

change blog to blog posts

206175a

fix title and quick start icon

a35b180

remove home markdown file

11dea06

update getting started

0b1ae73

getting-started changes

8dc76e3

remove unwanted image

43f89c7

0xba1a requested changes May 22, 2026

View reviewed changes


		### Step 1: Prepare a sample project

		Create a project folder with a TypeScript file that has a syntax error. When the TypeScript compiler (`tsc`) tries to convert it to JavaScript, it fails — and the error output is captured in a log file.


		Create `code/app.ts` with a deliberate syntax error:

		```typescript title="code/app.ts"


		Install Python:

		- Windows: Download the latest installer from [python.org](https://www.python.org/downloads/). During installation, check "Add Python to PATH".


		When `run()` is called, it:

		1. Copies the log file into the Docker container at a dedicated `/var/log/` path.


		## Step 1 — Create the Sample Project

		From the root of your `microbots-introduction` project, create a `code/` folder:


		`code/build.log` should contain:

		```log title="code/build.log"


		## Step 2 — Installing Docker

		On macOS, install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and launch it.


		A "Hello from Docker!" message confirms the daemon is reachable.

		Continue with the [Microbot Installation](installation-guide.md) guide.


		## ✨ LLM Support

		Azure OpenAI Models — add environment variables in a `.env` file:

Conversation

shivashanmugam commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes with this PR

Uh oh!

codecov-commenter commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivashanmugam Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivashanmugam Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivashanmugam Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivashanmugam Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

shivashanmugam commented Apr 17, 2026 •

edited

Loading

codecov-commenter commented Apr 17, 2026 •

edited

Loading

shivashanmugam Apr 21, 2026 •

edited

Loading

shivashanmugam Apr 21, 2026 •

edited

Loading

shivashanmugam Apr 28, 2026 •

edited

Loading

shivashanmugam Apr 28, 2026 •

edited

Loading