Your First Atomic Action: A Guide to Using the action.do SDK

In the world of software and business automation, complexity is the enemy of progress. As workflows grow, they can become tangled, brittle, and difficult to manage. What if you could break down every complex business process into its simplest, most fundamental components?

Enter the "atomic action."

At action.do, we believe that the future of automation lies in defining, triggering, and managing discrete, single-purpose tasks. These atomic actions are the reliable, reusable building blocks for creating sophisticated Services-as-Software.

This guide will walk you through exactly what an atomic action is and how you can define and execute your very first one using the action.do SDK.

What Exactly is an Atomic Action?

Think of an atomic action as the smallest, indivisible unit of work in any business process. It’s a single, self-contained task that does one thing and does it well. It’s not the entire sequence of onboarding a customer; it's the single step of 'sending the welcome email' or 'updating the CRM record'.

• A Workflow is the entire recipe.
• An Atomic Action is a single instruction in that recipe, like "add 1 cup of flour."

Each action is designed like a pure function in programming: it accepts a structured set of inputs (e.g., a user's email address and name) and returns a predictable, structured output (e.g., a message ID and status). This predictability makes them incredibly robust and easy to integrate into larger, more complex agentic workflows.

Building Your First Action: "Send Welcome Email"

Let's dive into the code. The best way to understand the power of atomic actions is to build one. We'll create a simple action called send-welcome-email using the action.do TypeScript SDK.

The Code

Here is a complete example of defining and running an action.

import { Do } from '@do-inc/sdk';

// Initialize the platform client
const platform = new Do({ apiKey: 'YOUR_API_KEY' });

// Define a simple, atomic action: send an email
const sendWelcomeEmail = platform.action('send-welcome-email', {
  description: 'Sends a welcome email to a new user.',
  handler: async (inputs: { email: string, name: string }) => {
    // Business logic for the action would go here
    // e.g., calling your email provider's API
    console.log(`Sending welcome email to ${inputs.name} at ${inputs.email}`);
    return { success: true, messageId: 'xyz-123' };
  },
});

// Execute the action via the SDK
const result = await sendWelcomeEmail.run({
  email: 'alex@example.com',
  name: 'Alex',
});

console.log(result);
// Expected output: { success: true, messageId: 'xyz-123' }

Breaking it Down

Let's look at what's happening in this snippet.

1. Initialization:

   import { Do } from '@do-inc/sdk';
   const platform = new Do({ apiKey: 'YOUR_API_KEY' });
   

   First, we import the necessary Do client from the SDK and initialize it with our unique API key. This authenticates our requests and connects us to the action.do platform.

2. Definition (platform.action):

   const sendWelcomeEmail = platform.action('send-welcome-email', { ... });
   

   This is the core of the action.do platform. We're defining a new action with a unique identifier, 'send-welcome-email'. This name is how we'll reference and trigger this specific piece of business logic later.

3. The Handler (handler):

   handler: async (inputs: { email: string, name: string }) => {
     console.log(`Sending welcome email to ${inputs.name} at ${inputs.email}`);
     return { success: true, messageId: 'xyz-123' };
   },
   

   The handler is the function that contains your actual business logic.

   • Inputs: It receives a single inputs object. Defining types for these inputs ensures your action is predictable and easy to use.
   • Logic: Inside the handler, you'd perform the task. Here, we're simply logging to the console, but in a real-world scenario, you would be making an API call to your email service (like SendGrid, Mailgun, or Resend).
   • Outputs: The return value is the structured output of the action. This output can then be used by the next step in a larger workflow.

4. Execution (.run()):

   const result = await sendWelcomeEmail.run({
     email: 'alex@example.com',
     name: 'Alex',
   });
   

   Defining an action doesn't run it. To execute the task, you call the .run() method on the action object, passing in the required inputs. The action.do platform then invokes your handler with these inputs and returns the result. This simple run command can be triggered from anywhere in your application—a serverless function, a webhook, or another part of your business process automation.

Frequently Asked Questions (FAQ)

Q: What is an 'atomic action' in the context of .do?
A: An atomic action is the smallest, indivisible unit of work in a business process. Think of it as a single, self-contained task like 'send an invoice,' 'update a CRM record,' or 'verify user identity.' These actions are the fundamental building blocks for creating services on the .do platform.

Q: How is an action.do different from a full workflow?
A: An action.do represents a single step, while a workflow orchestrates multiple actions in a sequence or based on specific logic. You compose workflows by connecting various action.do agents together to model a complete business process and deliver a Service-as-Software.

Q: Can actions accept inputs and produce outputs?
A: Yes. Every action is designed like a function. It accepts a structured set of inputs (e.g., customer details, order ID) and returns a structured output (e.g., a confirmation status, a user ID). This makes them predictable, reliable, and easy to integrate into larger systems.

Q: What kind of tasks are suitable for an action.do?
A: Any discrete business task is a perfect candidate. Examples include sending notifications (email, SMS), performing a calculation, querying a database, calling an external API, or updating a record in a system of record. If you can define it as a single, repeatable function, you can build it as an action.do.

Get Started Today

You've just seen how simple it is to encapsulate a critical business task into a manageable and executable unit. By adopting this atomic approach to task execution, you can build more resilient, scalable, and maintainable workflow automation.

Ready to build, trigger, and automate? Get your API key and start defining your first atomic action with action.do today.