{"id":31769944,"url":"https://github.com/aniketmishr/pocket-agent","last_synced_at":"2025-10-10T02:55:52.550Z","repository":{"id":311655337,"uuid":"1044439858","full_name":"aniketmishr/pocket-agent","owner":"aniketmishr","description":"Pocket Agent is your personal AI assistant on Telegram. It can answer your quick questions, help with complex tasks, and even manage daily routines, all from your pocket.","archived":false,"fork":false,"pushed_at":"2025-08-25T19:12:08.000Z","size":757,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-25T20:37:28.810Z","etag":null,"topics":["ai","ai-agents","chatbot","portia-ai","telegrambot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aniketmishr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-25T17:27:32.000Z","updated_at":"2025-08-25T19:14:17.000Z","dependencies_parsed_at":"2025-08-25T20:37:33.852Z","dependency_job_id":"0135647f-2f21-4a81-a8dc-ac924b374383","html_url":"https://github.com/aniketmishr/pocket-agent","commit_stats":null,"previous_names":["aniketmishr/pocket-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aniketmishr/pocket-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aniketmishr%2Fpocket-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aniketmishr%2Fpocket-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aniketmishr%2Fpocket-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aniketmishr%2Fpocket-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aniketmishr","download_url":"https://codeload.github.com/aniketmishr/pocket-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aniketmishr%2Fpocket-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002527,"owners_count":26083403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","chatbot","portia-ai","telegrambot"],"created_at":"2025-10-10T02:55:50.646Z","updated_at":"2025-10-10T02:55:52.546Z","avatar_url":"https://github.com/aniketmishr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pocket Agent 🤖\n\n\u003cimg src=\"assets/agent_pic.jpeg\" alt=\"Pocket Agent Demo\" width=\"400\"/\u003e\n\n\n## What is Pocket Agent?\n\nPocket Agent is your **personal AI assistant in your pocket** – simple, accessible, and powerful. You can talk to it anytime, even from your mobile through Telegram. It can handle everything from simple queries to complex tasks, boring chores, and even multi-step workflows by connecting to your favorite tools.\n\nUnlike niche agents built for very specific use cases, Pocket Agent is designed for **everyone**. Whether you want quick information, tool integration, or daily workflows, it’s here to make life easier (as it should be!).\n\n---\n\n| Image 1 | Image 2 |\n|---------|---------|\n| ![img1](assets/img1.jpeg) | ![img2](assets/img2.jpeg) |\n\n| Image 3 | Image 4 |\n|---------|---------|\n| ![img3](assets/img3.jpeg) | ![img4](assets/img4.jpeg) |\n\n---\n\n## Demo Video 🎥\n\n[![Pocket Agent Demo](https://img.youtube.com/vi/ZcSaIaX0p0o/0.jpg)](https://www.youtube.com/watch?v=ZcSaIaX0p0o)\n\n---\n\n## The Problem It Solves\n\nMost AI agents today are either too complex for general users or limited in what they can do. Pocket Agent solves this by:\n\n* Being **easy to use** via Telegram commands.\n* Keeping **humans in control** with clarification before important actions.\n* Seamlessly **connecting to multiple tools** with OAuth.\n* Supporting **ready-to-use workflows** for everyday tasks.\n\n---\n\n## Technical Details ⚙️\n\nPocket Agent is built using:\n\n* [telegram-python-bot](https://github.com/python-telegram-bot/python-telegram-bot)\n* [Portia Python SDK](https://github.com/portiaAI/portia-python-sdk)\n\n### Core Concepts from Portia AI\n\n1. **Spectrum of Autonomy**\n\n   * Full autonomy agents using `portia.run`.\n   * Built-in workflows using **PlanBuilderV2** with controllability.\n\n2. **OAuth**\n\n   * Secure connections to external tools like Google Docs, Notion, and more.\n\n3. **Clarification**\n\n   * Human-in-the-loop confirmation before executing important actions, ensuring agents remain controllable and safe.\n\n---\n\n## Telegram Commands 📱\n\n* `/start` → Start the Pocket Agent bot.\n* `/help` → List available commands.\n* `/workflow` → Run built-in workflows using Portia’s PlanBuilderV2.\n\n### How it Works\n\n* **Simple queries** → handled by a lightweight LLM call.\n* **Complex queries** → handled by `portia.run`, which can plan and execute actions.\n* **OAuth required?** → The bot will send a friendly clarification request to connect your tool.\n* **Important step?** → The bot always asks for confirmation before taking action (human in the loop).\n\n---\n\n## My Learnings from this Hackathon 📚\n\nBefore this hackathon, I knew very little about AI agents. Now, I have a **solid understanding of how agents work**, and how to build them to solve not just my own problems but also those of friends and family.\n\nI also learned:\n\n* How to build Telegram bots.\n* How to use `asyncio` (a bit confusing at first, but very powerful!).\n* How to design agents that are **controllable, safe, and useful**.\n\n---\n\n## Installation Guide 🛠️\n\n### Requirements\n\n* Python 3.9+\n* [OpenAI API Key](https://platform.openai.com/)\n* Telegram Bot (created via [BotFather](https://core.telegram.org/bots#6-botfather))\n\n### Steps\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/aniketmishr/pocket-agent.git\n   cd pocket-agent\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. Set up environment variables:\n\n   ```bash\n        PORTIA_API_KEY = \"YOUR-PORTIA-API-KEY\"\n        OPENAI_API_KEY = \"YOUR-OPENAI-API-KEY\"\n        TELEGRAM_BOT_TOKEN = \"YOUR-TELEGRAM-BOT-TOKEN\"\n        TELEGRAM_USERNAME = \"YOUR-TELEGRAM-USER-NAME\"\n   ```\n\n4. Run the bot:\n\n   ```bash\n   python main.py\n   ```\n\n---\n\n## Future Work 🚀\n\n1. Add **streaming support** for faster responses.\n2. Build **new workflows** for more everyday tasks.\n3. Add **file support** (upload, process, summarize).\n4. Scale to **multiple users** with better session handling.\n5. Allow **workflow scheduling** for automation.\n\n---\n\n### ⭐ Pocket Agent – AI in your pocket, power at your fingertips.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faniketmishr%2Fpocket-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faniketmishr%2Fpocket-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faniketmishr%2Fpocket-agent/lists"}