Getting Started with action.do: Your First Atomic Action

In the world of agentic workflows and complex automation, the biggest challenges often boil down to reliability, reusability, and managing complexity. How do you build sophisticated systems that are easy to understand, debug, and scale? The answer lies in breaking them down to their smallest, most fundamental components.

Enter action.do.

We believe that every complex process is just a series of simple, well-defined tasks. action.do provides the framework to define, execute, and manage these tasks as atomic actions—the core building blocks of modern automation. This is your first step towards mastering business-as-code and building truly robust agentic workflows.

What is an Atomic Action?

Think of an atomic action as a single Lego brick. It's a self-contained, indivisible unit of work designed to perform one specific task perfectly.

In the context of .do, an atomic action is the smallest, indivisible unit of work in a workflow. It represents a single, well-defined task, like 'send an email' or 'create a user record', ensuring that it either completes successfully or fails entirely, without leaving the system in a partial, inconsistent state.

This "all-or-nothing" principle is what makes them so powerful. An action doesn't get halfway done. It either succeeds or it fails, giving you predictable and reliable behavior every single time. This approach transforms chaotic scripts into a library of clean, testable, and reusable building blocks.

Simple. Atomic. Powerful.

Building Your First Action: send-welcome-email

Let's get our hands dirty and create our first action. The "Hello, World!" of any user-centric system is the welcome email. We'll encapsulate this logic into a reusable action.do.

Here is the complete code for our action. We'll break it down piece by piece below.

import { action } from '@do-sdk/core';

export const sendWelcomeEmail = action({
  // The unique, API-callable name for this action
  name: 'send-welcome-email',

  // A human-readable description for documentation
  description: 'Sends a welcome email to a new user.',

  // Defines the data contract for this action
  inputs: {
    to: { type: 'string', required: true },
    name: { type: 'string', required: true }
  },

  // The core logic that executes the task
  handler: async ({ inputs, context }) => {
    const { to, name } = inputs;
    
    // Your email sending logic (e.g., with SendGrid, SES, etc.) would go here
    console.log(`Sending welcome email to ${name} at ${to}`);
    
    // Return a structured result
    return { success: true, messageId: 'xyz-123' };
  },
});

Deconstructing the Action

Let's walk through the key parts of this definition:

1. name: 'send-welcome-email': This is the unique identifier for your action. It's how you'll call it from an API or reference it within a larger workflow.do. Choose a clear, descriptive, kebab-case name.
2. description: '...': Good documentation is crucial for reusable code. This field explains what the action does, making it easy for you and your team to understand its purpose at a glance.
3. inputs: { ... }: This is the action's contract. It defines exactly what data the action needs to run. By specifying to and name as required strings, action.do automatically handles validation. If a call is made without these inputs, it will fail immediately with a clear error—no need for manual validation boilerplate in your handler.
4. handler: async ({ inputs, context }) => { ... }: This is the heart of your action—the logic that gets executed.
   • The handler receives an object containing the validated inputs. We safely destructure to and name.
   • Inside, you can write any Node.js/TypeScript code you need. This could involve making API calls to third-party services (like an email provider), interacting with a database, or performing any custom business logic.
   • Finally, you return a result. This structured output can then be used by the next step in a workflow or returned to the original caller.

The Power of Reusability

Congratulations! You've just defined a powerful, API-callable action. It's more than just a function; it's a standardized, managed, and reusable component of your automation infrastructure.

Now, instead of duplicating email-sending logic everywhere, you can simply call the send-welcome-email action from anywhere:

• In a "New User Signup" workflow.
• In an "Admin-Created User" automation.
• In a "Re-engage Trial User" sequence.

This is the essence of the Don't Repeat Yourself (DRY) principle applied to business processes. By building a library of atomic actions, you create a robust foundation for all your agentic workflows.

Frequently Asked Questions

Q: How is an action.do different from a full workflow.do?

A: An action.do represents a single task. A workflow.do is a collection of one or more actions orchestrated to achieve a larger business process. Actions are the building blocks; workflows are the blueprints that connect them.

Q: Can I reuse actions across different workflows?

A: Absolutely. Actions are designed to be modular and reusable. You can define an action once, like 'generate-report', and call it from any number of different workflows, promoting DRY (Don't Repeat Yourself) principles in your automations.

Q: What kind of logic can I put inside an action's handler?

A: The handler can contain any Node.js/TypeScript logic. This includes making API calls to third-party services, performing data transformations, interacting with databases, or executing any custom business logic required to complete the task.

Your Next Steps

You've taken the first step by understanding the power of a single atomic action. You've seen how to define a clear contract, encapsulate logic, and create a reusable building block for sophisticated automation.

Now, think about your own processes. What single, repeatable task could you turn into an action? Generating an invoice? Creating a project in your task manager? Resizing an image?

Ready to turn your complex processes into simple, repeatable tasks? Explore the action.do platform and build your first agentic workflow today.