Best practices · AI
Best Practices for Building AI Agents
Opens with creditsVendor-neutral best practices for building AI agents, checked against Anthropic's engineering guidance on agents, tools and context, the MCP specification's security best practices and the OWASP Top 10 for Agentic Applications. It covers choosing between workflows and agents, designing tools, managing context and memory, running a reliable agent loop, securing agents and MCP servers, and evaluating agent behaviour.
Written by Tauseef Fayyaz6 chapters, 24 practicesAbout 18 min24 quiz questionsReviewed 13 October 2026What you will learn
6 chapters · about 18 min
1Choosing between a workflow and an agentAgents trade cost and predictability for flexibility. These practices help you pick the simplest design that solves the problem.4 practices · 3 min
2Designing tools an agent can use wellAnthropic calls the tool layer the agent-computer interface and recommends investing in it as much as in a human interface. These practices make tools easy to choose and hard to misuse.4 practices · 3 min
- Context, memory and long-running tasksAn agent's context fills with every tool result it reads, and quality drops as it fills. These practices keep the context focused across long tasks.4 practices · 3 minOpens with credits
- Running a reliable agent loopAn agent is a loop of model calls and tool calls. These practices make the loop stop at the right time, recover from errors and keep people in control of risky steps.4 practices · 3 minOpens with credits
- Agent security, identity and MCPAgents act with real credentials on content they did not write. These practices follow the OWASP Top 10 for Agentic Applications and the MCP security best practices.4 practices · 3 minOpens with credits
- Evaluating and observing agentsAn agent can reach the right result by many paths, and the same task can pass once and fail the next time. These practices make agent quality measurable.4 practices · 3 minOpens with credits
About this guide
An AI agent is a language model that uses tools in a loop, deciding its own next step from what each tool returns. That freedom is what makes agents useful for open-ended work, and it is also what makes them hard to build well. Agents cost more than a single model call, they compound their own mistakes, and every tool you hand them is something an attacker can try to use. These best practices for building AI agents are about getting the benefit without the surprises.
The guide starts with the question most teams skip: does this task need an agent at all? Anthropic's engineering team, after working with many teams building agents, recommends starting with the simplest solution and adding complexity only when it clearly helps. Often a fixed workflow of model calls, or a single call with retrieval, does the job more cheaply and predictably.
When you do need an agent, most of the quality comes from two places: the tools you give it and the context you put in front of it. Two chapters cover those in detail, including how to write tool descriptions a model can follow and how to keep long-running agents from drowning in their own history.
Security follows the OWASP Top 10 for Agentic Applications and the Model Context Protocol's security best practices, since many agents now reach their tools through MCP servers. The last chapter covers evaluating agents, which needs different methods from evaluating a single prompt because the same task can succeed by many different paths.
Common questions
What is the difference between an AI agent and a workflow?
In a workflow, model calls and tools run along code paths you define in advance. In an agent, the model decides its own next step and which tools to use, in a loop, based on what each step returns. Workflows are cheaper and more predictable; agents suit open-ended tasks whose steps cannot be known in advance.
Should I use a multi-agent system?
Usually not at first. Start with one agent and good tools, and add more agents only when evals show a benefit, such as independent research that can run in parallel or work that needs an isolated context. Each handoff between agents is another thing to test and another place to fail.
How do I write good tools for an AI agent?
Build a few task-shaped tools rather than one per API endpoint, describe each as if onboarding a new hire, use clear parameter names and strict schemas, and design arguments so mistakes are hard to make. Return concise, meaningful results and errors that say how to fix the call.
What is the OWASP Top 10 for Agentic Applications?
It is the OWASP GenAI Security Project's list of the most critical security risks for agentic AI systems, published for 2026. It includes agent goal hijack, tool misuse, identity and privilege abuse, agentic supply chain vulnerabilities and memory and context poisoning, among others.
How do I evaluate an AI agent?
Write unambiguous tasks with reference solutions, run several trials per task from a clean environment, and grade the final outcome rather than the exact path. Report pass^k when users need consistent results, and read transcripts to tell agent failures from grader bugs. Twenty to fifty tasks from real failures is a good start.
Sources (8)
Checked against these, last on 13 October 2026.
- Building effective agents, Anthropic Engineeringwww.anthropic.com/engineering/building-effective-agents
- Writing effective tools for agents, Anthropic Engineeringwww.anthropic.com/engineering/writing-tools-for-agents
- Effective context engineering for AI agents, Anthropic Engineeringwww.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Demystifying evals for AI agents, Anthropic Engineeringwww.anthropic.com/engineering/demystifying-evals-for-ai-agents
- Prompting best practices, Anthropic docsplatform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
- OWASP Top 10 for Agentic Applications for 2026, OWASP GenAI Security Projectgenai.owasp.org/resource/owasp-top-10-for-agentic-applications/
- Security Best Practices (MCP specification 2026-07-28), Model Context Protocolmodelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices
- Evaluation best practices, OpenAI docsdevelopers.openai.com/api/docs/guides/evaluation-best-practices
Related on Sefism
Picked from the other libraries by shared topics.
Cheat sheets
See all- AI agents and MCP cheat sheetTool calling, MCP servers, evals.
- GenAI app architecture cheat sheetHow a production GenAI app fits together: request flow, layers, RAG, agent loop, memory, caching, guards, evals, tracing, folder layout and launch checklist.
- AI evals cheat sheetEvals for LLM apps and agents: golden datasets, metrics, LLM-as-judge and its biases, RAG and agent metrics, offline and online evals, CI, human review, tools.
Best practices
See all- Best Practices for Building LLM AppsHow to build LLM apps and agents that hold up in production: prompts, evals, prompt injection, tool permissions, cost, logging and privacy.
- Best Practices for AI Coding AssistantsHow to get reliable code from AI coding assistants and agents: instruction files, task prompts, verification, review, security, dependencies and session hygiene.
Checklists
See allProject structures
See all- AI agent with an MCP server project structureFor developers who want to give AI assistants safe access to their own data or API. A TypeScript MCP server built on the official SDK, organised by feature (tasks, projects) with each feature owning its tools, resources and prompts, served over stdio for local hosts and Streamable HTTP with OAuth for remote ones, plus a small agent and the evals that prove a model can use it.
- Python AI agent with LangGraph project structureFor Python developers moving from "call a model in a loop" to an agent that can pause, resume and be debugged. It starts from the official LangGraph template (langgraph.json, a src/agent package, unit and integration tests) and grows into a customer support agent with typed state, one file per node and tool, human approval before refunds, evals that score whole trajectories, tracing, auth and a deployable server image.
Career questions
See all- How do I start learning AI agents as a software engineer?Start with one LLM API and plain code: a loop that calls the model, lets it pick a tool, runs the tool and feeds the result back. Build one small agent that does a real task end to end, add evaluation and guardrails, and only then reach for a framework. Agents are software engineering first.
- Should I learn LangGraph, CrewAI or the OpenAI Agents SDK first, or build AI agents without a framework?Build one small agent without a framework first: the tool-calling loop is about fifty lines and every framework wraps it. Then learn one framework deeply, chosen by what your project needs: LangGraph for explicit state and approvals, the OpenAI Agents SDK for quick assistants with handoffs, the Claude Agent SDK for agents that work on files.
- What is MCP, and do I need to learn it?MCP, the Model Context Protocol, is an open standard for connecting AI applications to tools and data. You do not need to study it in depth, but if you build with LLMs, writing one small MCP server takes an afternoon and teaches you how agents really use tools. Learn the concepts; skip the hype.
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com