Beyond the Basics: Advanced Concepts in Atomic Action Design

You've grasped the core concept: on the .do platform, the atomic action is the fundamental building block of any powerful agentic workflow. It's the single, indivisible, and executable unit of work. You've probably already built a few simple actions, like the sendWelcomeEmail example, and seen how they can be triggered to perform tasks.

But as you move from simple scripts to orchestrating complex, mission-critical business processes, the design of your actions becomes paramount. Building robust, scalable, and maintainable systems isn't just about what your actions do—it's about how they are designed to handle the complexities of the real world.

Let's move beyond the basics and explore four advanced principles that will transform your atomic actions from simple functions into resilient, enterprise-grade components.

1. The Principle of Idempotency: Designing for Retries

In a distributed system, you must assume that things will fail. A network request might time out, a third-party API could be temporarily unavailable, or a message queue might deliver the same event twice. Idempotency is the property of an action where executing it multiple times with the same input has the exact same effect as executing it only once.

Why it matters: Imagine a non-idempotent action to "charge a customer $10." If a network hiccup causes your workflow to retry that action, you've just double-charged your customer. An idempotent design prevents this. It ensures that no matter how many times an action is retried, the outcome remains correct.

How to achieve it:

• Check State Before Acting: Before creating a resource, check if a resource with the same unique identifier already exists.
• Use Unique Keys: Process payments or requests using a unique transactionId or idempotencyKey. If your action receives a request with a key it has already processed, it can simply return the original result without re-executing the logic.

Let's enhance our email example to be idempotent.

import { Action } from '@do-co/agent';
import { db } from './database'; // Fictional database client

const sendWelcomeEmail = new Action('send-welcome-email', {
  title: 'Send Welcome Email',
  description: 'Sends a welcome email, ensuring it is only sent once.',
  input: {
    userId: { type: 'string', required: true },
    idempotencyKey: { type: 'string', required: true }, // e.g., the trigger event ID
  },
  async handler({ userId, idempotencyKey }) {
    // 1. Check if this action has already been completed
    const existingLog = await db.findLog({ key: idempotencyKey });
    if (existingLog) {
      console.log(`Idempotency key ${idempotencyKey} already processed. Skipping.`);
      return { success: true, messageId: existingLog.messageId, status: 'skipped' };
    }

    // 2. Fetch user details
    const user = await db.findUser({ id: userId });
    if (!user) {
        return { success: false, error: 'User not found' };
    }

    // 3. Perform the action
    console.log(`Sending email to ${user.email}...`);
    const message = `Welcome to the platform, ${user.name}!`;
    const messageId = `msg_${Date.now()}`; // From actual email service

    // 4. Log the completion with the idempotency key
    await db.createLog({ key: idempotencyKey, messageId });
    
    return { success: true, messageId, status: 'sent' };
  },
});

2. Finding the Right Granularity: Not Too Big, Not Too Small

The "atomic" in atomic action is a crucial clue. An action should do one thing and do it well. But what constitutes "one thing"?

• Too Coarse (Monolithic): An action called onboardNewUser that creates a database record, sends a welcome email, provisions a sub-domain, and notifies a Slack channel is too big. It's hard to test, impossible to reuse in other contexts, and a failure in one step (e.g., Slack is down) could prevent the user from being created at all.
• Too Fine (Microscopic): Actions like validateEmailFormat or connectToDatabase are too small. They represent implementation details, not meaningful business steps. This leads to cluttered, complex workflows that are difficult to read and manage.

The Guideline: A well-designed action represents a single, logical business operation that you might want to retry or reuse independently.

Instead of one monolithic onboardNewUser action, you should create several smaller, atomic actions:

• createUserRecord
• sendWelcomeEmail
• provisionSubdomain
• sendSlackNotification

Your agentic workflow then becomes the composer, orchestrating these reusable "LEGO bricks" in the correct sequence and handling the logic between them.

3. Designing for Failure: Structured Error Handling

Things go wrong. An API key is invalid, a database is unreachable, or input data is malformed. A robust action doesn't just crash; it provides clear, structured information about the failure back to the workflow engine.

This allows the orchestrating agent to make intelligent decisions:

• Is this a retriable error? A temporary network timeout or a 503 Service Unavailable API response should probably trigger a retry with exponential backoff.
• Is this a permanent error? An Invalid API Key or User Not Found error is not going to be fixed by a retry. The workflow should stop that path and potentially trigger a different compensating action, like alerting a human.

How to achieve it: Your action's handler should catch exceptions and return a consistent, structured error object. This turns unknown exceptions into predictable data that the system can act upon.

// ... inside an Action handler
async handler({ to, name }) {
  try {
    const response = await emailService.send({
      to,
      subject: 'Welcome!',
      body: `Welcome to the platform, ${name}!`,
    });
    return { success: true, messageId: response.id };
  } catch (error) {
    // Check for a specific, retriable error type
    if (error.code === 'RATELIMIT_EXCEEDED') {
      return { 
        success: false, 
        error: { 
          code: 'TRANSIENT_ERROR', 
          message: 'Email service rate limit exceeded.',
        }
      };
    }
    // Return a generic permanent error for everything else
    return { 
      success: false, 
      error: { 
        code: 'PERMANENT_ERROR', 
        message: error.message 
      }
    };
  }
}

4. Composability and Reusability: Think Like a Library Author

The ultimate goal is to build a library of custom actions that represent your unique business operations. To make this library powerful, every action must be designed for maximum reusability.

• Stateless by Default: An action should not hold state between executions. All the data it needs to perform its job should be passed in via its input schema. This ensures that the action can be scaled horizontally and run anywhere without side effects.
• Generic Inputs: Avoid hardcoding environment-specific details (userId-123, test.api.com). These should be passed in as inputs or configured via environment variables. The action's job is to perform a business capability, not to know the full context of the workflow it's a part of.
• Well-Defined Schemas: The input schema you define is the public contract for your action. Be descriptive and use strong types. A well-defined schema makes the action self-documenting and enables the .do platform to provide validation and better tooling for you and your agents.

Build Your Foundation

By embracing idempotency, finding the right granularity, handling errors gracefully, and designing for reusability, you elevate your use of the .do platform. You move from simply automating tasks to engineering resilient, scalable, and maintainable "business as code."

The next time you write new Action(), take a moment to consider these principles. A little thought upfront will pay massive dividends as your agentic workflows grow in complexity and importance.