Agent Design

Agent design is the art and science of creating useful AI agents. It’s the process of iteratively figuring out exactly what an agent should do, what problem it solves, how it does its work, how success is measured, and how it interacts with humans and systems. Good design is often the difference between an agent that provides real value and one that falls short. Most failures aren’t about technology—they’re about design.

​

Simple vs complex agents

For simple agents, you don’t need much of a design process. Just create an agent and tell it what to do:

“Do a competitor analysis every Monday morning and send me a report.”

Provide some basic context, iterate on the report format, and you’re done. This conversational approach works well for personal assistants and straightforward automations. But for more complex agents—especially those that handle external communication, work with sensitive data, or fit into team workflows—a structured approach pays off. You’ll save time by thinking things through before building.

​

The Agent Design Canvas

We’ve evolved the Agent Design Canvas as a tool to guide the design process. It’s a framework for thinking through all the critical aspects of agent design before you start building. The canvas is perfect for both individual brainstorming and team workshops. It ensures you don’t miss important considerations, everyone aligns on what the agent should do, and you spot weaknesses during design instead of after building.

​

How to use it

The boxes are there to raise questions in your mind—you don’t need to strictly fill in each one. Skip boxes that feel irrelevant. Add boxes that are missing for your context. For example, a security-sensitive agent might need a “What could go wrong?” box for risks and mitigation strategies. Some teams keep the canvas alive as a living document that evolves with the agent. Others use it only for bootstrapping, then set it aside once the agent is running (or keep it as a record of the original design). Either approach is fine. The canvas is just a tool.

​

The ten aspects of agent design

Let’s walk through each section of the canvas. For each aspect, we’ll explain the key questions and show an example from a Manuscript Screening Agent that helps a publishing team filter incoming submissions.

​

Purpose

The foundation of everything. Get specific about what problem you’re solving and who benefits. Key questions:

• Who would benefit, and how?
• What is the precise use case? (Give examples)
• What is out of scope for this version?

Manuscript Screener: Editorial team saves time by focusing only on high-quality submissions. The agent screens incoming manuscripts to the public submission inbox. Out of scope: filtering among the high-quality submissions (humans do that).

​

Triggers

What wakes the agent up? Every agent needs an activation mechanism. Key questions:

• What event starts the agent?
• Is it manual, scheduled, or event-driven?

Manuscript Screener: Triggered by incoming email from the public manuscript submission address.

​

Action plan (human & AI)

This is the heart of the design. Create numbered steps showing the workflow, clearly indicating which steps the AI performs and where humans are involved. What are the specific steps? Who does what—agent or human? Where are the handoffs, review points, and approvals?

Manuscript Screener:

1. Agent: Receives email with manuscript and reads the cover letter and first 5 pages
2. Agent: Reviews content quality and sets a score (yes/maybe/no)
3. Agent: Summarizes the recommendation with reasoning and emails it to the human
4. Human: Reviews the assessment and takes the best manuscripts for further review

​

Interfaces

How do humans and the agent interact? The interface choice can determine whether an agent actually gets used. How will humans and AI interact? Chat, email, Slack, shared documents, approval widgets? What are the functional requirements on the interface?

Manuscript Screener: Email only. Human receives reports via email from the agent. No other interface needed.

​

Capabilities

What tools and integrations does the agent need to do its job? What integrations are needed? What other tools are required? Apply the principle of least privilege: give agents only the capabilities they need—no more. An agent without email access can’t accidentally send a bad email.

Manuscript Screener: Receive email, send email, access/read documents.

​

Impact

Define success in business terms. This helps you evaluate whether the agent is worth building and provides a metric for ongoing improvement. What is the measurable gain to the organization once the agent is working?

Manuscript Screener: Screening efficiency increased by 80%, allowing the editorial team to focus on high-quality manuscripts.

​

Input

What data or documents does the agent receive? This is the part of the agent’s context that varies with each run. What data or documents are provided? What format should inputs be in?

Manuscript Screener: Each incoming email includes the email body, plus a manuscript and cover letter as attachments.

​

Knowledge & state

What background information and external connections does the agent need? Any external systems to connect to? What context or domain knowledge is needed? Does the agent maintain and modify any state?

Manuscript Screener: Agent needs examples of what “great,” “just-good-enough,” and “not-really-good-enough” levels of quality look like.

​

Output

What does the agent deliver? Be specific about format and destination. What are the deliverables? What format should they be in? Consider using templates or examples.

Manuscript Screener: Agent’s review of incoming manuscripts is aligned with how the human user would evaluate them.

​

Success

How do you know the agent is working? Define both immediate success and ongoing evaluation. What is the definition of done? How do you know if the agent became better or worse over time?

Manuscript Screener: Agent reviews 100% of incoming submissions within 24 hours and provides consistent scoring. Target pass rate: ~40%.

​

Prototype early

The canvas is useful, but don’t spend too long thinking before you actually try something. Build a minimum version of the agent directly in the platform—even if you have to fake things.

• Fake data: If you don’t have access to real data yet, use fake data. You can even ask the agent to generate realistic test data for you.
• Fake integrations: Ask the agent to simulate connections to systems you don’t have access to yet. “Pretend you received this email and tell me what you would do.”
• Quick integrations: Use the HTTP capability to test various API integrations before committing to a full setup.

The goal is to get anything working to understand what’s possible, what’s easy, and what’s hard. An early prototype teaches you more than hours of theoretical design. The platform is optimized for quick starts—a useful first prototype can often be built in 30 minutes.

​

The agent owner

In a team context, every agent needs a clearly defined owner—think of them as the agent’s “boss.” An agent may interact with many people, and those people will have feedback and ideas for improvement. But it’s usually best for one person (or an owner pair) to be responsible for the agent’s behavior. They tweak the instructions, they follow up when something goes wrong, they decide when to expand or change the agent’s role. Without a defined owner, you risk one of two failure modes:

• Nobody improves the agent — Issues pile up, the agent drifts, and eventually it stops being useful
• Everybody improves the agent — Like an intern with no clear boss, receiving conflicting instructions from multiple people, the poor agent becomes confused and unreliable

The owner typically drives the design process. Sometimes you’ll have a separate “agent designer” who acts as a coach or consultant—we often play this role with our customers, where someone on their team owns the agent while one of our project leads guides the design process. But at the end of the day, a human must always be responsible for what an agent does. AI cannot take responsibility away from humans. One person can own several agents, or even a whole team of agents. Think of it like an editor-in-chief at a newspaper: they can’t review or micromanage everything the journalists write (that would be wildly inefficient), but they’re still responsible for the end result. They create the necessary guardrails, do the necessary oversight, hire the right people, and follow up when things go wrong. The human owner of an agent plays a similar role.

​

Using the canvas in practice

For team workshops: Get everyone in the same room, work through the canvas together, and reach alignment before building. This can take 1–4 hours depending on complexity, but saves days of misalignment later. For solo design: Use it as a checklist to ensure you’ve thought through all aspects before implementation. For complex agents: Any section of the canvas could mean significant time figuring out the right solution. That’s normal—better to discover complexity during design than during building.

​

Common pitfalls the canvas prevents

​

Keeping instructions clean

One common mistake is dumping everything you can think of into the agent’s context. This creates a low signal-to-noise ratio, leading to confused agents and low-quality output. Limit context to what the agent actually needs—remove anything that’s just “good to know.” During the creation process, it’s OK and normal for instructions to get a bit messy as you iterate. But then clean them up: simplify, clarify, remove redundancy. The agent can help with this—ask it to review its own instructions and suggest improvements. Don’t worry about breaking things when you simplify. Instructions are version controlled—if you ask the agent to clean up and the results aren’t what you wanted, you can always roll back to a previous version.

​

Iteration is essential

AI agents need human feedback to become good. They improve through iteration and guidance—more like new team members who need coaching than software that just runs. This is why the best agent creators are often the actual users, not IT departments. Only the user knows when things change, when performance has drifted, or when new requirements emerge.

​

FAQ

​

Learn more