Building Agents

This guide teaches you how to create agents that deliver real value and work reliably in your workflows. You'll learn the chat-first approach to building automations and how to iterate effectively.

Thinking About Agents as Roles

Think of agents like roles or employees—each agent has a specific job to do, and that job consists of several tasks. Each task is an action.

For example, a "Marketing Assistant" agent might have actions for generating weekly reports, analyzing campaign performance, and monitoring social media mentions. A "Sales Reporter" agent might have actions for daily deal summaries, weekly revenue reports, and monthly pipeline analysis. Each action handles one specific task that contributes to the agent's overall role.

This structure helps you organize your automations clearly. Even large agents with many actions stay simple because each action does one thing well.

Starting with Your First Action

After creating your agent, start with a single action—one thing your agent can do. Get that first action working well, then add more actions later as you identify additional tasks your agent should handle.

Starting with one action lets you focus on getting it right before adding complexity. Once your first action works reliably, you can add a second action for another related task, then a third, and so on. This approach keeps your agent manageable and makes it easier to understand what each part does.

Starting Simple

Start with the smallest version you can describe in a few sentences. Don't try to build everything at once—begin with a focused, simple action that does one thing well.

When creating your first action, describe the simplest version that solves your problem. For example, instead of "Analyze all customer feedback and create a comprehensive report with sentiment analysis, categorization, and trend detection", start with "Create a document listing the last 10 customer feedback messages from Intercom". Once that works, you can add complexity step by step.

Building Iteratively

Take one step at a time and make your actions more complex gradually. Iterative development is the best way to build reliable automations.

After your first simple action works, use the chat interface to add one feature at a time. For example, if you started with listing feedback messages, your next step might be "Add sentiment analysis to each message". Then "Group messages by sentiment". Then "Add a summary at the top". Each step builds on the previous one, making it easier to understand what changed and catch issues early.

Use chat to refine your actions incrementally. Ask questions like "What does this code do?" to understand changes, or request specific improvements like "Add error handling" or "Make the report include charts". Run the action, review results, chat again to improve, and repeat until it does exactly what you need.

Testing Changes Safely

Before you make any updates that affect your systems, always start by having the action create a document of the changes so you can review them first.

When your action will modify data or make changes in external systems, test it carefully before running it at scale. Start by having it create a document showing what changes it would make, then review that document to ensure everything looks correct.

Test in real life by processing just one update first. Check that it works correctly in your system, then test with 5 updates, then 10, until you're confident it works in all edge cases. Only then should you run it at full scale or schedule it to run automatically.