Building AI Agents That Actually Work

An AI agent is an LLM with the ability to take actions. Instead of just generating text, it can call APIs, query databases, send messages, trigger workflows, and make decisions in a loop. The promise is automation: a system that handles tasks without constant human supervision.

The reality is more nuanced. Agents work brilliantly for well-scoped tasks with clear boundaries. They fall apart spectacularly when given vague goals, unrestricted tool access, and no guardrails. The difference between a demo agent and a production agent is not the LLM — it is everything around the LLM.

What an Agent Actually Is

Strip away the hype and an agent has four components:

LLM (the brain — decides what to do) + Tools (MCP servers — GitHub, databases, search, etc.) + Channels (Telegram bot, Discord bot, webhooks) + Triggers (cron schedules, events, user messages)

The LLM receives input (a user message, a scheduled trigger, an event). It decides which tools to call. It calls them through MCP servers. It gets results back. It decides what to do next. This loop continues until the task is done or the agent decides to stop.

Simple in theory. The devil is in every single detail.

Building an Agent on Zubnet

On the platform, creating an agent involves four steps. Each one has decisions that will determine whether your agent works reliably or becomes a source of 3 AM pages.

1. Create the Agent

Give it a name, pick a model, and write a system prompt.

The model matters more than you think. For agents that need to call tools reliably, use a strong reasoning model. Claude Sonnet 4, GPT-4.1, or Gemini 2.5 Pro. Smaller models save money but make worse tool-calling decisions, and a bad tool call in an agent is not just a wrong answer — it is a wrong action.

The system prompt is your agent’s constitution. Be explicit about:

• What the agent should do (and what it should never do)
• When to use each tool and when to skip them
• How to handle errors and ambiguity
• When to ask the user for clarification vs. making a decision
• What tone to use in messages

The #1 mistake in agent system prompts:

Being too vague. “You are a helpful assistant that manages our GitHub repo” will lead to an agent that creates random issues, closes things it should not, and merges PRs without review. “You can create GitHub issues when users report bugs in the #bugs channel. You must never close issues, merge PRs, or modify repository settings.” — that is a system prompt that produces a reliable agent.

2. Connect a Channel

Channels are how agents communicate with the world. On Zubnet, you can connect:

• Telegram — paste your bot token from @BotFather
• Discord — paste your bot token from the Discord Developer Portal
• Webhooks — any HTTP endpoint that can send/receive JSON

The channel determines where the agent lives. A Telegram bot agent responds in Telegram chats. A Discord bot agent lives in your Discord server. A webhook agent responds to API calls.

Choose one channel to start. Do not try to build a multi-channel agent on day one. Get it working reliably on one platform first.

3. Add Tools (MCP Servers)

Tools are what make agents more than chatbots. On Zubnet, tools are provided by MCP (Model Context Protocol) servers. We have 117 of them. Some examples:

• GitHub — search repos, create issues, read files, list PRs
• PostgreSQL / MySQL — query databases (read-only if you are smart)
• Brave Search — search the web
• Filesystem — read and write files
• Slack — send messages, read channels

Activate the servers you need, configure their credentials (API keys, database URLs), and the agent can use them.

The principle of least privilege applies here:

Only give agents the tools they actually need. An agent that can search GitHub does not need database write access. An agent that sends daily summaries does not need filesystem access. Every unnecessary tool is a surface area for things to go wrong.

4. Set Triggers

Triggers determine when the agent activates:

• User message — responds when someone messages the bot (default for chat agents)
• Cron schedule — runs at set times (e.g., “every day at 9 AM”)
• Event — fires when something specific happens (webhook payload matches a pattern)

Cron-triggered agents are great for recurring tasks: daily standup summaries, weekly analytics reports, monitoring checks. Event-triggered agents handle reactive workflows: new GitHub issue → triage and label it, new support ticket → draft a response.

The Hard Parts

Building the agent takes 20 minutes. Making it reliable takes weeks. Here is where production agents actually fail:

Error Handling: When the LLM Hallucinates a Tool Call

LLMs sometimes call tools with wrong parameters, call tools that do not exist, or call the right tool in the wrong context. Your agent needs to handle all of these gracefully.

On Zubnet, failed tool calls return error messages to the LLM, which can then decide what to do. But you need to tell it what to do in the system prompt:

If a tool call fails:
1. Do NOT retry the same call with the same parameters
2. Analyze the error message
3. If it is a permission error, tell the user you cannot do that
4. If it is a rate limit, wait and try once more
5. If it is an unknown error, summarize what happened and ask for help
6. Never retry more than twice total

Without these instructions, agents get stuck in retry loops, burning tokens and time on the same failing call over and over.

Rate Limits: Frequency Caps

An agent connected to a busy Discord server with 500 active users can receive hundreds of messages per minute. Without rate limiting, it will:

• Exhaust your API token budget in hours
• Hit provider rate limits and start returning errors
• Generate so many responses that the channel becomes unusable

Set frequency caps. On Zubnet, you can configure:

• Max responses per minute (per channel)
• Max tokens per hour (budget control)
• Cooldown period between responses to the same user
• Queue depth limit (drop messages when too far behind)

Permissions: Restrict What Agents Can Do

This is the one that will save you from disasters. Agents should have the minimum permissions needed for their job.

• Database tools: read-only unless writes are specifically needed
• GitHub tools: read + create issues, but not close/merge/delete
• Filesystem tools: specific directories only, never /
• Messaging tools: specific channels only, never DMs to executives

Think about it this way: what is the worst thing this agent could do with the tools it has? If the answer makes you nervous, reduce the permissions.

Graceful Degradation

When a tool is down, the agent should not crash. It should acknowledge the limitation and do what it can without that tool. Include this in your system prompt:

If a tool is unavailable or returning errors:
- Acknowledge it to the user: "I cannot access GitHub right now"
- Do what you can without that tool
- Never make up data to compensate for a missing tool
- Suggest the user try again later

Real Examples

Example 1: Support Bot

A Telegram bot that answers customer questions using your knowledge base.

• Model: Claude Sonnet 4 (strong at following instructions)
• Tools: Brave Search (for docs), PostgreSQL (read-only, for account lookups)
• Channel: Telegram
• Trigger: User message
• Rate limit: 30 responses/min, 2s cooldown per user

System prompt focuses on: answer from docs first, escalate to human if unsure, never share other customers’ data, never make promises about features or timelines.

Example 2: Daily Summary Agent

A Discord bot that posts a morning summary of what happened overnight.

• Model: GPT-4.1 (good at structured summaries)
• Tools: GitHub (read PRs and issues), Slack (read channels)
• Channel: Discord (#daily-summary channel)
• Trigger: Cron, every weekday at 9:00 AM
• Rate limit: 1 message per trigger (it only fires once)

System prompt focuses on: summarize PRs merged, issues opened/closed, and key Slack discussions. Keep it under 500 words. Use bullet points. Tag relevant team members.

Example 3: Content Monitor

An agent that watches for specific events and alerts the team.

• Model: Gemini 2.5 Pro (fast, good at classification)
• Tools: Brave Search (monitor mentions), Slack (send alerts)
• Channel: Webhook (triggered by monitoring service)
• Trigger: Event (incoming webhook with search results)
• Rate limit: 10 alerts/hour (prevent alert fatigue)

System prompt focuses on: classify mentions as positive/negative/neutral, only alert on negative or critical, include source URL and one-sentence summary.

Testing: Start Small

Zubnet agents have two modes:

• Quick mode — simplified setup, good for testing. Limited tool configuration, basic triggers. Use this to validate that your agent concept works at all.
• Advanced mode — full configuration, production-ready. Detailed system prompts, granular rate limits, permission controls, multiple triggers.

Always start in quick mode. Get the basic behavior right. Then graduate to advanced mode and add the guardrails.

Testing checklist before going live:

• Send 20 normal messages — does it respond correctly?
• Send 5 messages it should refuse — does it refuse?
• Disable a tool — does it degrade gracefully?
• Send 50 messages in 1 minute — does rate limiting work?
• Send a message in a language it should not support — does it handle it?
• Ask it to do something outside its scope — does it stay in lane?

The Uncomfortable Truth About Agents

Agents are not magic. They are LLMs in a loop with tool access. They make mistakes. They will sometimes do the wrong thing. The question is not “will my agent make an error?” — it is “what happens when it does?”

The agents that work in production are the ones with:

• Tight scope (“do this one thing well”)
• Explicit boundaries (“never do these things”)
• Limited permissions (least privilege, always)
• Rate limits and budget caps (prevent runaway costs)
• Human escalation paths (“when in doubt, ask a human”)
• Monitoring and logs (so you know what happened)

Build boring agents. The exciting demo agent that can do everything is the one that will embarrass you in production. The boring agent that does one thing reliably, refuses everything else, and escalates when confused — that is the one your team will actually trust.

Agents on Zubnet are available to all users. Start with a simple Telegram or Discord bot, get it right, then expand. The infrastructure handles the hard parts — you focus on the system prompt, the tools, and the guardrails.

Ready to build? Create your first agent at zubnet.com