Context

Ever since the fall of last year, I have transitioned my part time job to doing agent development. As my organization gets ramped up in utilizing LLMs and agents to automate tasks, I have come to a realization that not a lot of people actually understand what to build in the first place. In fact, I had that problem of building the wrong things initially in terms of agents / systems. So I would like to shed some light on some of the pitfalls I encountered, some decisions that were made, and just some thoughts that I think would have helped me when I was going through this process.

Note: This article was written by me (without AI). All thoughts are my own.

How to decide when to build an agent

agents agents agents! - Steve Ballmer

When building an agent, the first thing to ask yourself is whether you need an agent, a skill, an MCP Server, or a tool. I find too many people building things that could have just have been solved with a skill, or just an MCP server. Agentic development involves a lot of careful design and reasoning. For example, connectivity to other tools, internet access, whether the agent can use skill, compaction, context windows, etc. If your end goal is to build a system that automates a certain task, why not just piggy-back on an existing agent or harness?

I’d like to prove my point with a few examples:

Case #1:

An engineer says: I want to build an agent to do code reviews for me!

An engineer building their own agent will have to:

Figure out how the loop / prompting will work to crawl through the code change
Figure out which API calls will have to be exposed as tools to the agent
Figure out context limits
Figure out compaction
Figure out optimizations regarding tool calls
Figure out how to use sub-agents

Compared to an engineer piggy-backing off an existing agent/harness (e.g claude code, hermes)

Build a skill to describe how to do a code review
Add the necessary scripts to pull the code review down

And soon, the tradeoff between getting something that’s barely working and would take an engineer 1+ month to create VS just describing a workflow just isn’t worth it.

Case #2:

A director says: I want an agent that will summarize my email for me every day!

I don’t even have to write out the stuff I already mentioned above. Soon you realize building an agent is like building a full harness. A full system with nuts and bolts and considerations that someone will have to maintain, keep track of, etc. Most of the times, building a skill is fine. Building MCP servers is fine.

So then… when should we want to build an agent?

And to be honest, only when you are 100% clear of the job the agent should be responsible for. That is, most of the times the functions of an agent are blurred; especially presented in the form of a chatbot. I see people asking a SQL generation agent to tell them the weather, or a database agent to find out what jira tickets are assigned to them. Agents like chatGPT and claude have become so ubiquitous that we assume all agents should be able to do anything — and that is the greatest misconception!

For the case examples above, we can build agents for them. It’s just simply the tradeoff in time and effort. In 99% of cases, I would advise against building your own agent and just piggy-backing off an existing harness. In addition to being clear of the job the agent should be responsible for, you need to have operational requirements to do so. Thing such as:

An agent that can only connect to certain tools
Unecessary context that pre-exists in other harnesses
Telemetry, trust
Air-gapped networks that cause existing harnesses to be non-functional
Platform requirements

So what advice would I give myself if I were building an agent a year ago

STOP! No I’m really serious.. Stop and think. Of the hundreds of agents I spun up, they would all be boiled down 1 agent. Of the handful of agents I have reduced all our agents down to, here are some design considerations that would be helpful:

When doing needle in a haystack search, don’t just throw everything into the context

needle in haystack

Utilize techniques such as RLMs and RAG to assist an agent into finding the right answer. RLMs is not immediately intuitive when building agents. But when you stop and think about it, we humans do the same thing. We don’t read through a 10000+ line document! We look for tiny bits and pieces of information. Either through ctrl+f or searching keywords and then reading that sentence! Let agents (well really the LLM) do the same! Don’t treat them as omnipotent devices just yet!

Make your agent extensible via skills & MCPs

Just as I noted above, most people shoudn’t be writing agents. If you’re writing an agent, make it extensible with skills and MCPs. That means, figure out how you will read skills. is it from a local directory? A git repo? A registry? Figure these things out! Because anthropic and openai sure have!

Feedback is important, monitor your traces and optimize

I’ve learned so much just by monitoring the traces of the agent during production agent execution and optimizing the agent. Do this frequently — audit your agent’s performance and traces, figure out where you can improve. I guarantee you, the things you will realize on how users are using the agent will blow your mind.

Evaluations and testing

Evaluate your agents output. Build evaluation sets. You’re a developer right? You know how to write tests. Agent tests are similar too. But they should be grounded on real work examples. Test your agent early, and often. Build regression sets - because the agent will regress at some point from your tiny tiny system prompt change.

Scaling

This is probably the last thing I considered - because when testing locally, I was just a single person. A deployed agent will have to scale to the number of users / sessions thrown towards the agent continuously, for all tasks - and perform 100% of the time. Think of things like how sessions for your agent will be shared. Can they be shared? What about artifacts. What about compute resources when the agent is running. What about network bandwith? Network limits? Agents run and execute way faster than humans would. So can your infra scale to that extent? Utilize things like kubernetes, session services, a unified frontend.

Security

Build agents that are resilient. Towards prompt injections, sensitive information disclosure, etc. All from the OWASP GenAI LLM Top 10. Build these systems in place. Make sure your agent straight up doesn’t have the connectivity (at the network level and also at the tool level) to systems it should never have access to. Use sandboxing. Code execution is very dangerous. Even more so if the agent can author code then execute it. Use secure interpreters if you really have to.

Change… management?

change management meme The last bit I want to talk about is that — it doesn’t matter if your agent solves world hunger. You need to communicate, deliver, and perform. If nobody knows about the agent, it’ll never be used. If you don’t deliver it properly in an easy way people can use, the barrier of entry becomes too high and nobody will use it. And if the agent doesn’t give a valid output or makes an error, people lose trust in it. The barrier is high for many people in using agents. Guide, let people know that it’s a learning process for all of you. And with feedback, the agent you wrote will get better over time. As the old saying goes, “Rome wasn’t build in a day…”

Closing remarks

I’m sure I’ll write about agentic stuff more on my blog. Recently, I picked up herdr and switched to it over tmux. Tmux served me well this past decade — I just think herdr is way better for agentic development. Though I wish they had multi-session support (like the old tmux a -t <name>) — I’m just waiting for individual sessions as well!