Skip to content

docs: standardize README format for devops bot and changelog writer #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IremOztimur wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: standardize README format for devops bot and changelog writer #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 89 additions & 84 deletions examples/autonomous_agents/devops_telegram_bot/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,48 +1,103 @@
# 🛠️ DevOps Agent — Telegram-Controlled Sysadmin Bot
# DevOps Telegram Bot

A DevOps automation agent built with the **Upsonic AI Agent Framework**. This example demonstrates how to use `AutonomousAgent` with the Telegram interface to create a chat-based sysadmin bot that can read logs, check disk usage, create backups, and run shell commands — all from your phone.

## Features

- **Telegram Integration**: Full bidirectional chat interface via Telegram Bot API
- **Autonomous Agent**: Powered by Upsonic's `AutonomousAgent` with filesystem and shell access
- **Workspace Sandboxing**: Agent is restricted to a dedicated `workspace/` directory for safe operation
- **Chat Mode**: Maintains conversation context across messages using `InterfaceMode.CHAT`
- **Ngrok Tunneling**: Exposes the local server to the internet for Telegram webhook delivery
- **Custom Identity**: Agent personality and behavior defined via `AGENTS.md` and `SOUL.md` in the workspace

## Prerequisites

- Python 3.10+
- Anthropic API key
- Telegram bot token (via BotFather)
- ngrok account and authtoken

## Installation

1. **Navigate to this directory**:
```bash
cd examples/autonomous_agents/devops_telegram_bot
```

2. **Install dependencies**:
```bash
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
```

3. **Create a Telegram bot**:
- Open Telegram → search **@BotFather** → send `/newbot`
- Follow the prompts and copy the bot token
- Search **@userinfobot** → send any message → copy your user ID

4. **Start ngrok**:
```bash
ngrok config add-authtoken YOUR_NGROK_TOKEN
ngrok http 8000
```
Copy the `https://xxxx.ngrok-free.app` URL.

5. **Set up environment variables**:
```bash
cp .env.example .env
```
Edit `.env` with your values:
```
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_WEBHOOK_URL=https://xxxx.ngrok-free.app
ANTHROPIC_API_KEY=your-api-key
```

## Usage

Run the bot server:

> "I built a bot that manages my server from Telegram — and it only took 50 lines of Python."

A Telegram bot powered by Upsonic's `AutonomousAgent` that can read logs, check disk usage,
create backups, and run shell commands — all from your phone.

## Architecture

```
You (Telegram) → Telegram API → ngrok tunnel → FastAPI (port 8000) → Upsonic AutonomousAgent → workspace/
```bash
uv run bot.py
```

## Stack
The server starts on `http://0.0.0.0:8000` and registers the Telegram webhook automatically.

| Tool | Role |
|----------|-------------------------------------------|
| Upsonic | AutonomousAgent with filesystem + shell |
| Telegram | Chat interface (via BotFather) |
| ngrok | Expose localhost to the internet |
**Example messages to send your bot:**

---
| Message | What happens |
|---|---|
| `Check disk usage` | Agent runs `df -h`, returns formatted result |
| `Find all log files larger than 50KB` | Agent searches workspace, lists matching files |
| `Create a backup of the app directory` | Agent tars `app/` into `backups/`, confirms |
| `Read the last 20 lines of error.log and tell me what's wrong` | Agent reads and analyzes log content |
| `List all running processes using port 8000` | Agent runs shell command, returns results |
| `Show me the app config` | Agent reads `config.yaml`, explains it |

## 🗂️ Project Structure
Send `/reset` to clear conversation context.

## Project Structure

```
devops_telegram_bot/
├── bot.py # Main bot server (~50 lines)
├── bot.py # Main bot server
├── .env # API keys (you fill this in)
├── .env.example # Template for .env
├── requirements.txt # Python dependencies
├── setup.sh # One-command setup script
│
└── workspace/ # Agent's sandboxed home
├── AGENTS.md # Agent personality & behavior
├── AGENTS.md # Agent personality and behavior
├── SOUL.md # Agent identity
├── USER.md # Who the user is
├── memory/ # Agent's daily memory logs
│
├── logs/ # Fake logs for demo
├── logs/ # Sample logs for demo
│ ├── error.log # Application error log
│ ├── access.log # Nginx-style access log
│ └── app-debug.log # Debug log (large file)
│ └── app-debug.log # Debug log
│
├── app/ # Fake app directory for backup demo
├── app/ # Sample app directory for backup demo
│ ├── main.py
│ ├── config.yaml
│ └── utils/
Expand All @@ -51,70 +106,20 @@ devops_telegram_bot/
└── backups/ # Where backups get stored
```

---

## 🚀 Setup Roadmap

### Step 1: Create the Telegram Bot (3 min)

1. Open Telegram → search **@BotFather** → send `/newbot`
2. Pick a name: `DevOps Agent`
3. Pick a username: `your_devops_agent_bot`
4. **Copy the bot token**
5. Search **@userinfobot** → send any message → **copy your user ID**

### Step 2: Start ngrok (2 min)

```bash
# Install ngrok: https://ngrok.com/download
ngrok config add-authtoken YOUR_NGROK_TOKEN
ngrok http 8000
```

Copy the `https://xxxx.ngrok-free.app` URL.

### Step 3: Configure environment (1 min)

```bash
cp .env.example .env
# Edit .env with your actual values:
# TELEGRAM_BOT_TOKEN=...
# TELEGRAM_WEBHOOK_URL=https://xxxx.ngrok-free.app
# OPENAI_API_KEY=...
```

### Step 4: Install & Run (2 min)

```bash
# Option A: with uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
uv run bot.py
## How It Works

# Option B: with pip
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python bot.py
```
1. **Bot Server**: `bot.py` starts a FastAPI server that handles incoming Telegram webhook events.

### Step 5: Demo It 🎬
2. **AutonomousAgent**: The agent loads its personality from `workspace/AGENTS.md`, its identity from `workspace/SOUL.md`, and any accumulated memory from `workspace/memory/`.

Open Telegram and send these messages to your bot:
3. **Telegram Interface**: `TelegramInterface` in `CHAT` mode wraps the agent, maintaining conversation context across messages for a natural back-and-forth experience.

| Message | What happens |
|--------------------------------------------------|-------------------------------------------------|
| `Check disk usage` | Agent runs `df -h`, returns formatted result |
| `Find all log files larger than 50KB` | Agent searches workspace, lists matching files |
| `Create a backup of the app directory` | Agent tars `app/` into `backups/`, confirms |
| `Read the last 20 lines of error.log and tell me what's wrong` | Agent reads + analyzes log content |
| `List all running processes using port 8000` | Agent runs shell command, returns results |
| `Show me the app config` | Agent reads `config.yaml`, explains it |
4. **Tool Execution**: The agent has access to filesystem tools (read, list, write files within the workspace) and shell execution capabilities to run system commands.

---
5. **Webhook Delivery**: ngrok tunnels requests from Telegram's servers to your local bot server, enabling development without a public IP.

## 🔒 Security Notes
## Security Notes

- The agent is **sandboxed** to the `workspace/` directory
- File operations outside workspace are **blocked**
- Use `TELEGRAM_USER_ID` to lock the bot to your account only
- The agent uses `trash` over `rm` by default (defined in AGENTS.md)
- The agent is sandboxed to the `workspace/` directory — file operations outside it are blocked.
- Set `TELEGRAM_USER_ID` in `.env` to restrict the bot to your account only.
- The agent uses `trash` over `rm` by default (defined in `AGENTS.md`).
124 changes: 54 additions & 70 deletions examples/multi_agent/git_changelog_writer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,112 +1,96 @@
# Git Changelog Writer

This example demonstrates how to use **Upsonic's Sequential Team mode** to turn raw `git log` output into a ready-to-post Twitter/X update — using two AI agents that pass context automatically.
A multi-agent pipeline built with the **Upsonic AI Agent Framework**. This example demonstrates how to use `Team` with `mode="sequential"` to turn raw `git log` output into a ready-to-post Twitter/X update — two agents pass context automatically, no glue code required.

## Overview
## Features

The pipeline has two agents:
- **Sequential Team**: Two agents run in sequence with automatic context handover (`mode="sequential"`)
- **Tech Lead Agent**: Filters noise commits (`chore`, `docs`) and extracts user-facing changes from `feat` and `fix` entries
- **Growth Hacker Agent**: Converts the technical summary into a developer-native Twitter/X post (max 280 characters)
- **No Glue Code**: Output from Agent A flows into Agent B automatically — no variable passing or string parsing

1. **Tech Lead** — Reads raw commit messages, filters out noise (`chore`, `docs`), and produces a clean technical summary of user-facing changes.
2. **Growth Hacker** — Takes that summary and writes a developer-native Twitter/X post. No hashtags, no corporate tone, no emoji spam.
## Prerequisites

The key idea: `mode="sequential"` handles the context handover between agents. You don't pass variables or parse strings — the output of Agent A flows into Agent B automatically.
- Python 3.10+
- OpenAI API key

---
## Installation

## Setup
1. **Navigate to this directory**:
```bash
cd examples/multi_agent/git_changelog_writer
```

### 1. Install dependencies
2. **Install dependencies**:
```bash
uv sync
```

```bash
uv sync
```
3. **Set up environment variables**:
```bash
export OPENAI_API_KEY="your-api-key"
```

### 2. Configure OpenAI API Key

Set your OpenAI API key as an environment variable:
## Usage

```bash
export OPENAI_API_KEY="your_openai_api_key_here"
uv run main.py
```

Or create a `.env` file in the project root:
## Project Structure

```bash
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
```

---

## Run the Example

```bash
uv run examples/multi_agent/git_changelog_writer/main.py
git_changelog_writer/
├── main.py # Sequential Team pipeline
└── README.md # This file
```

### Example Output
## How It Works

**Agent A (Tech Lead)** filters and summarizes:
1. **Input**: A changelog or `git log --oneline` string is passed to the first task. The example ships with mock data — swap it for real `git log` output in production.

```
Summary of User-Facing Changes:
2. **Agent A (Tech Lead)**: Reads the commits, ignores housekeeping tags (`chore`, `docs`), and produces a clean technical summary of user-facing `feat` and `fix` entries.

1. New Feature: Dark Mode Support
- What Changed: The user interface now offers dark mode support.
- Why Users Care: More comfortable for extended usage and low-light environments.
3. **Context Handover**: Upsonic's `mode="sequential"` automatically injects Agent A's output into Agent B's task context. No manual wiring needed.

2. New Feature: Smart Caching Layer
- What Changed: A smart caching layer was introduced to optimize performance.
- Why Users Care: Dashboard load times are 3x faster.
4. **Agent B (Growth Hacker)**: Applies strict tone and formatting rules to write a single Twitter/X post (max 280 characters) that reads like an engineer sharing something useful, not a marketing announcement.

3. Bug Fix: Database Connection Timeout
- What Changed: Resolved a timeout issue under heavy load.
- Why Users Care: Improved reliability during peak usage.
5. **Output**: `tasks[-1].response` contains the final tweet.

4. Bug Fix: Real-Time Notifications
- What Changed: Fixed a race condition affecting notifications.
- Why Users Care: Notifications are now delivered accurately and timely.
```
## Example Output

**Agent B (Growth Hacker)** turns it into a tweet:
**Agent A (Tech Lead)** summarizes:

```
Dark mode now available across our UI. 🌙

UI enhancements + performance upgrades with these latest updates.
Summary of User-Facing Changes:

- 🌙 Dark Mode support
- 🚀 Dashboard 3x speed boost with smart caching
- 🔧 Database timeout fix for heavy loads
- 🛠️ Real-time notifications now more reliable
1. New Feature: Telegram Interface
- What Changed: Full Telegram bot interface for agents via webhook.
- Why Users Care: Agents can now be used over Telegram chat.

Changelog: [link]
2. Bug Fix: LLM Usage Tracking
- What Changed: Fixed tracking for direct LLM call metrics.
- Why Users Care: Accurate usage data in dashboards.
```

---

## How It Works
**Agent B (Growth Hacker)** turns it into a tweet:

1. **Input**: A string of `git log --oneline` output (mock data in the script, swap for real git later).
2. **Agent A**: Analyzes commits, ignores housekeeping (`chore`/`docs`), extracts user-facing value from `feat` and `fix` entries.
3. **Context Handover**: Upsonic's Sequential Team automatically passes Agent A's output into Agent B's context.
4. **Agent B**: Applies tone and formatting rules to produce a single, post-ready tweet.
5. **Output**: `tasks[-1].response` gives you the final tweet directly.
```
Upsonic v0.72.0 is out.

---
New Telegram interface so your agents can run over chat.
CLI now starts interfaces directly — no programmatic setup.

## File Structure
- Telegram bot interface (webhook, messages, media)
- CLI + interface compatibility
- LLM usage tracking fix

```bash
examples/multi_agent/git_changelog_writer/
├── main.py # Sequential Team pipeline
└── README.md # This file
Changelog: [link]
```

---

## Notes

- **No glue code**: `mode="sequential"` handles all context passing between agents.
- **Tone-tuned**: Agent B's instructions use specific constraints ("no hashtags", "no 'we're thrilled'") rather than vague guidelines like "be professional."
- **Tone-tuned**: Agent B's instructions use specific constraints ("no hashtags", "no 'we're thrilled'") rather than vague guidelines.
- **Extendable**: Add more agents to the list (e.g., Editor, Translator) — context still flows automatically.
- **Cost**: ~$0.01 per run (both agents combined).
- **Extendable**: Add more agents to the list (e.g., Editor, Translator) — the context still flows automatically.