From 0032d1e410ee5686bee50eac5c7c2e7a9d5843fc Mon Sep 17 00:00:00 2001 From: IremOztimur Date: Wed, 18 Feb 2026 15:57:16 +0300 Subject: [PATCH] docs: standardize README format for devops bot and changelog writer --- .../devops_telegram_bot/README.md | 173 +++++++++--------- .../git_changelog_writer/README.md | 124 ++++++------- 2 files changed, 143 insertions(+), 154 deletions(-) diff --git a/examples/autonomous_agents/devops_telegram_bot/README.md b/examples/autonomous_agents/devops_telegram_bot/README.md index d96c7a4..22ec457 100644 --- a/examples/autonomous_agents/devops_telegram_bot/README.md +++ b/examples/autonomous_agents/devops_telegram_bot/README.md @@ -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/ @@ -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`). diff --git a/examples/multi_agent/git_changelog_writer/README.md b/examples/multi_agent/git_changelog_writer/README.md index f8e9bf6..c3d762e 100644 --- a/examples/multi_agent/git_changelog_writer/README.md +++ b/examples/multi_agent/git_changelog_writer/README.md @@ -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.