{"sourceUrl":null,"sourceType":"file","contentType":"Explainer","apex":{"id":"n1","type":"APEX","label":"AI Agents: What they are and how to Build","text":"This guide explains AI agents, their spectrum, and how to build a custom agent with Claude Code and Telegram without writing code yourself.","children":[{"id":"n2","type":"CONC","label":"What Makes Something an Agent","text":"An AI agent performs tasks autonomously, differing from a simple chat by possessing specific capabilities.","parentId":"n1","children":[{"id":"n3","type":"DETL","label":"Chat interaction example","text":"Asking Claude 'what should I post today?' is a chat, not an agent.","parentId":"n2","children":[]},{"id":"n4","type":"EXMP","label":"Agentic interaction example","text":"An agent finds trending AI topics, picks high-engagement ones, drafts a post in your style, and saves it to a file without user interaction.","parentId":"n2","children":[]},{"id":"n5","type":"JUST","label":"Agent core components","text":"An agent has three things a regular chat does not: callable tools, persistent memory, and a loop running until a task is finished.","parentId":"n2","children":[{"id":"n6","type":"DETL","label":"Agent tools","text":"Agent tools include search, file systems, code execution, and external APIs.","parentId":"n5","children":[]},{"id":"n7","type":"DETL","label":"Agent memory","text":"Agent memory persists across tasks, not just within one session.","parentId":"n5","children":[]},{"id":"n8","type":"DETL","label":"Agent loop","text":"An agent's loop keeps running until the task is finished, not just until one response is generated.","parentId":"n5","children":[]}]},{"id":"n9","type":"INSG","label":"Agent involvement","text":"The more tools, memory, and loops an agent has, the less human involvement is required.","parentId":"n2","children":[]},{"id":"n10","type":"INSG","label":"Agent vs Model distinction","text":"The difference between an agent and a non-agent is not the underlying model but the structure surrounding it.","parentId":"n2","children":[]}]},{"id":"n11","type":"CONC","label":"The Spectrum: From Chat to Agent","text":"AI tools exist on a spectrum from basic chat to fully autonomous agents, defined by their capabilities and human involvement.","parentId":"n1","children":[{"id":"n12","type":"SUBC","label":"Basic Chat","text":"At one end, a basic chat involves asking Claude a question, getting an answer, and the session ends without tools or ongoing goals.","parentId":"n11","children":[]},{"id":"n13","type":"SUBC","label":"Slightly Agentic (Claude with tools)","text":"One step up, Claude with tools enabled is slightly agentic, as it decides to use features like web search or file reading independently.","parentId":"n11","children":[]},{"id":"n14","type":"SUBC","label":"Multi-step Workflows","text":"Further up, multi-step workflows involve Claude breaking a given goal into steps, executing each, checking results, and delivering a finished output without human involvement.","parentId":"n11","children":[]},{"id":"n15","type":"SUBC","label":"Fully Autonomous Agents","text":"At the top, fully autonomous agents run on a schedule, monitor inputs, call external services, and complete complex tasks without human intervention after the goal is set.","parentId":"n11","children":[]},{"id":"n16","type":"JUST","label":"Difference on spectrum","text":"The distinction between the bottom and top of the spectrum lies in the surrounding structure, including callable tools, context-carrying memory, and continuous task loops.","parentId":"n11","children":[]}]},{"id":"n17","type":"CONC","label":"Types of Agents You Can Build Today","text":"Various types of AI agents can be built, each designed for specific tasks and situations.","parentId":"n1","children":[{"id":"n18","type":"EXMP","label":"Research agent","text":"A research agent gathers information, reads sources, extracts key points, and delivers structured summaries based on a question.","parentId":"n17","children":[]},{"id":"n19","type":"EXMP","label":"Writing agent","text":"A writing agent creates content based on defined style, tone, format, audience, and topic, handling drafts, rewrites, and edits.","parentId":"n17","children":[]},{"id":"n20","type":"EXMP","label":"Code agent","text":"A code agent writes, runs, debugs, and improves code, managing implementation and debugging loops based on the desired functionality.","parentId":"n17","children":[]},{"id":"n21","type":"EXMP","label":"Business agent","text":"A business agent handles repetitive business tasks like drafting emails, processing customer requests, qualifying leads, and generating reports, running on autopilot.","parentId":"n17","children":[]},{"id":"n22","type":"EXMP","label":"Personal agent","text":"A personal agent manages schedules, organizes tasks, prepares briefings, and handles daily planning work.","parentId":"n17","children":[]}]},{"id":"n23","type":"DCSN","label":"Agent Building Project","text":"This guide will walk through building a Telegram bot using Claude Code, with Claude as its brain, running on a remote server.","parentId":"n1","children":[{"id":"n24","type":"DETL","label":"Claude Code functionality","text":"Claude Code writes all necessary code based on plain English descriptions, allowing direct communication with the bot via Telegram once set up.","parentId":"n23","children":[]},{"id":"n25","type":"STAT","label":"Setup time","text":"The entire setup process for the agent takes approximately 10-20 minutes and requires no coding knowledge.","parentId":"n23","children":[]}]},{"id":"n26","type":"CONC","label":"Agent System Prompt Templates","text":"Ready-made system prompt templates are provided for different agent types, to be pasted into Prompt 2 during setup using Claude Code.","parentId":"n1","children":[{"id":"n27","type":"DETL","label":"Template adjustment","text":"Users should adjust any details in the templates to match their specific situation.","parentId":"n26","children":[]},{"id":"n28","type":"SUBC","label":"Research Agent Template","text":"This template defines the research agent's job as gathering, analyzing, and synthesizing information.","parentId":"n26","children":[{"id":"n29","type":"DETL","label":"Research task steps","text":"When given a research task, the agent identifies sub-questions, searches for information, evaluates sources, extracts direct answers, and delivers a structured summary.","parentId":"n28","children":[]},{"id":"n30","type":"DETL","label":"Research summary format","text":"The summary should use headers, bullet points, and clear sections, explicitly stating uncertainties and avoiding filler.","parentId":"n28","children":[]}]},{"id":"n31","type":"SUBC","label":"Writing Agent Template","text":"This template defines the writing agent's job as writing content in a specified voice and style.","parentId":"n26","children":[{"id":"n32","type":"DETL","label":"Writing style rules","text":"The writing style should be conversational, direct, use short sentences/paragraphs, include specific numbers/examples, and end with a call to action/thought.","parentId":"n31","children":[]},{"id":"n33","type":"DETL","label":"Writing task steps","text":"When given a writing task, the agent asks for topic/audience/length, writes a first draft, reviews against style rules, and delivers a final version.","parentId":"n31","children":[]},{"id":"n34","type":"DETL","label":"Introduction rule","text":"The agent should never add unnecessary introductions and always start with the most important point.","parentId":"n31","children":[]}]},{"id":"n35","type":"SUBC","label":"Code Agent Template","text":"This template defines the code agent's job as writing, debugging, and improving code.","parentId":"n26","children":[{"id":"n36","type":"DETL","label":"Coding task steps","text":"When given a coding task, the agent confirms understanding, writes clear code, identifies edge cases, and systematically debugs errors.","parentId":"n35","children":[]},{"id":"n37","type":"DETL","label":"Code rules","text":"Code rules include writing clean, readable code with meaningful variable names, including error handling, explaining sections in plain language, and asking clarifying questions if unsure.","parentId":"n35","children":[]}]},{"id":"n38","type":"SUBC","label":"Business Email Agent Template","text":"This template defines the business email agent's job as writing professional emails.","parentId":"n26","children":[{"id":"n39","type":"DETL","label":"Communication style rules","text":"The communication style should be direct, respectful, without formalities, get to the point, and close with a clear next step.","parentId":"n38","children":[]},{"id":"n40","type":"DETL","label":"Email task steps","text":"When given an email task, the agent identifies the goal, writes a subject line, drafts the email in 3-5 short paragraphs, and ends with one clear action item.","parentId":"n38","children":[]},{"id":"n41","type":"DETL","label":"Email output format","text":"The agent should always write ready-to-send emails, not templates with blanks.","parentId":"n38","children":[]}]},{"id":"n42","type":"SUBC","label":"Personal Planning Agent Template","text":"This template defines the personal planning agent's job as organizing work and priorities.","parentId":"n26","children":[{"id":"n43","type":"DETL","label":"Task handling steps","text":"When tasks/goals are shared, the agent identifies urgency, suggests realistic sequences, estimates time, and flags items for delegation/elimination.","parentId":"n42","children":[]},{"id":"n44","type":"DETL","label":"Project description steps","text":"When a project is described, the agent breaks it into next actions, identifies the most important first step, and creates a simple checklist.","parentId":"n42","children":[]},{"id":"n45","type":"DETL","label":"Planning rule","text":"The agent should keep planning practical, provide only the plan, and avoid motivational filler.","parentId":"n42","children":[]}]}]},{"id":"n46","type":"CONC","label":"Prerequisites for Agent Setup","text":"To build your AI agent, you will need a Claude API key, a Telegram bot token, and a Linux-based Virtual Private Server (VPS).","parentId":"n1","children":[{"id":"n47","type":"DETL","label":"Claude API Key","text":"A Claude API key from console.anthropic.com is a developer key, charged per usage instead of a fixed monthly fee.","parentId":"n46","children":[{"id":"n48","type":"STAT","label":"Claude API cost estimate","text":"For a personal bot sending 50 messages a day, the Claude API cost is $1-5 per month, depending on the chosen model.","parentId":"n47","children":[]}]},{"id":"n49","type":"DETL","label":"Telegram Bot Token","text":"A Telegram bot token needs to be obtained from BotFather.","parentId":"n46","children":[]},{"id":"n50","type":"DETL","label":"VPS Requirements","text":"A Linux-based VPS is required, with 1 CPU, 1GB RAM, and 20GB storage being sufficient for a personal Telegram bot.","parentId":"n46","children":[{"id":"n51","type":"STAT","label":"VPS cost estimate","text":"Basic VPS plans from providers like DigitalOcean, Hetzner, or Vultr cost around $4 to $6 per month.","parentId":"n50","children":[]},{"id":"n52","type":"DETL","label":"Claude Code installation","text":"Once the VPS server is set up, install Claude Code by running npm i -g @anthropic-ai/claude-code in the terminal.","parentId":"n50","children":[]}]},{"id":"n53","type":"DCSN","label":"Claude Model Selection","text":"The choice of Claude model impacts performance and cost for the bot.","parentId":"n46","children":[{"id":"n54","type":"CMPR","label":"Claude Models for Bots","text":"Different Claude models offer varying performance and cost suitable for personal bots and complex analytical agents.","table":{"cols":["Model","Use Case","Cost Efficiency","Answer Quality"],"rows":[{"label":"Sonnet 4.6","cells":["Most personal bots","Affordable for daily use","Strong enough for any task"]},{"label":"Haiku 4.5","cells":["Minimize cost","Lowest cost","—"]},{"label":"Opus 4.8","cells":["Complex analytical agent","—","Critical"]}]},"parentId":"n53","children":[]}]}]},{"id":"n55","type":"SUBC","label":"Initial Agent Setup","text":"The first step involves launching Claude Code in the VPS terminal and pasting a prompt to build the Telegram bot.","parentId":"n1","children":[{"id":"n56","type":"DETL","label":"Agent Personality Prompt","text":"A prompt is provided to define the agent's personality, instructing Claude Code to build a Telegram bot using the Claude API as its brain.","parentId":"n55","children":[{"id":"n57","type":"DETL","label":"Requirements for bot","text":"The bot requirements include Python language, python-telegram-bot library, claude-sonnet-4-6 model, message handling, conversation history per user, and /start and /clear commands.","parentId":"n56","children":[]},{"id":"n58","type":"DETL","label":"File creation and API keys","text":"Claude Code should create main bot file, requirements.txt, and a .env file, reading API keys from environment variables.","parentId":"n56","children":[]}]},{"id":"n59","type":"SUBC","label":"Deploy as Background Service","text":"The bot should be deployed as a systemd service to run automatically on a Linux server.","parentId":"n55","children":[{"id":"n60","type":"DETL","label":"Service requirements","text":"The service should start automatically on boot, restart on crashes, load environment variables from .env, and save logs to a file.","parentId":"n59","children":[]},{"id":"n61","type":"DETL","label":"Terminal commands","text":"The exact terminal commands for installing and starting the service should also be provided.","parentId":"n59","children":[]}]},{"id":"n62","type":"SUBC","label":"Add Persistent Memory","text":"A prompt is provided to fix the issue of the bot losing conversation history upon restart by adding persistent memory.","parentId":"n55","children":[{"id":"n63","type":"DETL","label":"Memory implementation","text":"Conversation history for each user should be saved to a JSON file on disk, with a maximum length of the last 20 messages.","parentId":"n62","children":[]}]}]},{"id":"n64","type":"CONC","label":"Adding Agent Skills","text":"Skills are capabilities added to the bot over time by giving Claude Code new prompts, which then writes the necessary code.","parentId":"n1","children":[{"id":"n65","type":"SUBC","label":"Skill: Web search","text":"The web search skill allows the agent to look up real-time information instead of only answering from its memory.","parentId":"n64","children":[{"id":"n66","type":"DETL","label":"Web search implementation","text":"Web search capability should be added using the Tavily API, and Claude's tool use feature should be implemented cleanly.","parentId":"n65","children":[]},{"id":"n67","type":"DETL","label":"Web search decision","text":"The bot should decide on its own when to search for current information or answer from memory.","parentId":"n65","children":[]}]},{"id":"n68","type":"SUBC","label":"Skill: Save notes","text":"The save notes skill allows the agent to save ideas, tasks, and research findings to a file and retrieve them later.","parentId":"n64","children":[{"id":"n69","type":"DETL","label":"Note-saving features","text":"A note-saving feature should be added, triggered by phrases like \"save this,\" \"remember this,\" or \"note:\", along with /notes and /clearnotes commands.","parentId":"n68","children":[]}]},{"id":"n70","type":"SUBC","label":"Skill: Restrict to your account only","text":"This skill restricts bot usage to only the owner's account, preventing others from consuming API credits.","parentId":"n64","children":[{"id":"n71","type":"DETL","label":"User restriction implementation","text":"User restriction should be added, using the Telegram user ID from the .env file as ALLOWED_USER_ID, and responding with \"This bot is private\" to unauthorized users.","parentId":"n70","children":[]},{"id":"n72","type":"DETL","label":"User ID discovery","text":"Instructions should be provided on how to find the Telegram user ID, either through the bot or otherwise.","parentId":"n70","children":[]}]},{"id":"n73","type":"SUBC","label":"Skill: Track API costs","text":"This skill adds a cost tracker to monitor Claude API charges per token, keeping the user aware of their spending.","parentId":"n64","children":[{"id":"n74","type":"DETL","label":"Cost tracking implementation","text":"Basic cost tracking should be added, logging input and output tokens after each Claude API response, maintaining a running total in a costs.json file.","parentId":"n73","children":[]},{"id":"n75","type":"DETL","label":"Cost command","text":"A /costs command should be added to display total tokens used today and overall.","parentId":"n73","children":[]}]},{"id":"n76","type":"SUBC","label":"Skill: Scheduled daily briefing","text":"This skill enables the agent to send a daily message every morning without being prompted.","parentId":"n64","children":[{"id":"n77","type":"DETL","label":"Daily briefing content","text":"Every day at 8:00 am, the bot should send a message containing a motivational one-liner, a reminder for the top priority, and a random productivity/AI fact.","parentId":"n76","children":[]},{"id":"n78","type":"DETL","label":"Briefing implementation","text":"The briefing should be sent to the Telegram user ID from the .env file, using schedule or APScheduler library.","parentId":"n76","children":[]}]}]},{"id":"n79","type":"CONC","label":"Agent Management Tips","text":"Several useful tips are provided for managing and maintaining the AI agent after its initial setup.","parentId":"n1","children":[{"id":"n80","type":"DETL","label":"Updating agent personality","text":"To update the agent's personality, open the main bot file, change the system prompt variable, save, and restart the service with sudo systemctl restart your-bot-name.","parentId":"n79","children":[]},{"id":"n81","type":"DETL","label":"Checking bot status","text":"To check if the bot is running, use sudo systemctl status your-bot-name; \"active (running)\" means it's working, \"failed\" indicates logs should be checked.","parentId":"n79","children":[]},{"id":"n82","type":"DETL","label":"Reading logs","text":"Logs can be read using journalctl -u your-bot-name -n 50 to view the last 50 lines and find error messages.","parentId":"n79","children":[]},{"id":"n83","type":"DETL","label":"Adding new skills","text":"To add a new skill, open Claude Code in the project folder, describe the feature, and Claude Code will integrate it, indicating if a restart is needed.","parentId":"n79","children":[]}]},{"id":"n84","type":"CONC","label":"Agent Memory Problem","text":"The most common problem with AI agents is losing context between sessions, during long tasks, or after many messages, leading to mistakes or repeated work.","parentId":"n1","children":[{"id":"n85","type":"SUBC","label":"Ways Memory Problem Happens","text":"The memory problem manifests in three main ways, impacting the agent's ability to maintain context.","parentId":"n84","children":[{"id":"n86","type":"DETL","label":"Context limit exceeded","text":"Long tasks can exceed Claude's context limit, causing the agent to lose the original goal, past decisions, and constraints from the conversation's beginning.","parentId":"n85","children":[]},{"id":"n87","type":"DETL","label":"Session restart","text":"When a session is closed and reopened, the agent starts from zero, losing all previous context.","parentId":"n85","children":[]},{"id":"n88","type":"DETL","label":"Mid-task interruption","text":"If the agent is interrupted mid-task, it has no way of knowing where it stopped, leading to potential rework.","parentId":"n85","children":[]}]},{"id":"n89","type":"SUBC","label":"Solutions for Memory Problem","text":"Four methods can fix the agent's memory problem and maintain context across tasks and sessions.","parentId":"n84","children":[{"id":"n90","type":"DCSN","label":"Progress notes","text":"Instruct the agent to write a progress note after every major step, detailing what was done, decided, and needs to happen, to restore full context in new sessions.","parentId":"n89","children":[]},{"id":"n91","type":"DCSN","label":"Regular summaries","text":"Ask the agent to summarize its current status every 10 to 15 messages to compress context and prevent overflow.","parentId":"n89","children":[]},{"id":"n92","type":"DCSN","label":"Conversation compression","text":"Before conversations become too long, ask the agent to compress everything into a short summary and continue from there to keep the thread intact.","parentId":"n89","children":[]},{"id":"n93","type":"DCSN","label":"System prompt key facts","text":"Add key facts that the agent always needs directly to the system prompt in the bot code, ensuring this information is always in context.","parentId":"n89","children":[]},{"id":"n94","type":"DETL","label":"Checkpoint Prompt","text":"A prompt is provided for the agent to write a brief checkpoint, covering completed items, key decisions, remaining tasks, and necessary context for continuation, under 200 words.","parentId":"n89","children":[]},{"id":"n95","type":"DETL","label":"Memory File Prompt","text":"A specific format is provided for the memory note to be written after each major step, including what was done, key decisions, current state, and next steps.","parentId":"n89","children":[]},{"id":"n96","type":"DETL","label":"Context Recovery Prompt","text":"A prompt for resuming a task from a previous session instructs the agent to confirm understanding, identify the next step, and ask questions based on a pasted memory note.","parentId":"n89","children":[]},{"id":"n97","type":"DETL","label":"Rolling Summary Prompt","text":"A prompt is provided for compressing a long conversation into a summary of the original goal, what has been done, what was found, and key decisions made.","parentId":"n89","children":[]}]}]}]},"slug":"ai-agents-what-they-are-and-how-to-build-d4bd1c","sharedAt":{"_seconds":1780938604,"_nanoseconds":46000000},"title":"AI Agents: What they are and how to Build"}