Integrating Atomic Actions: Connecting Your Workflows to External Services

In today's digital landscape, business doesn't happen in a vacuum. It's a complex dance between dozens of specialized applications: payment gateways, CRMs, marketing platforms, databases, and communication tools. The real power comes from making these services talk to each other. But anyone who has tried to build and maintain these connections knows the pain of brittle scripts and tangled code.

What if you could treat every piece of business logic—every external API call—as a clean, reusable, and robust building block?

This is the core principle behind action.do. We believe in "Business As Code"—transforming your operational logic into flawless, scalable, and observable atomic actions. These actions are the fundamental components for building powerful, AI-powered agentic workflows. Let's explore how you can use them to securely and reliably connect your workflows to the external services that power your business.

What is an Atomic Action? The Foundation of Integration

Before we connect to anything, let's clarify what we're building with. An atomic action is a self-contained, single-purpose function designed to perform one specific task perfectly.

It does one thing, like processing a payment or sending an email.
It has clear inputs and predictable outputs.
It is independently testable, observable, and reusable.

Think of it as the ultimate microservice, but purpose-built for automation and agentic systems. Instead of a monolithic function that tries to do everything, you encapsulate each logical step. This modularity is the key to building automations that are easy to understand, maintain, and scale.

The Anatomy of an Action: A Practical Example

Theory is great, but code tells the real story. Let's break down how to create an atomic action that integrates with an external payment provider like Stripe.

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

// Define an atomic action to process a payment
const processPayment = Do.action('process-payment', {
  // 1. Define the API Contract with typed inputs
  inputs: {
    customerId: 'string',
    amount: 'number',
  },
  
  // 2. Encapsulate the business logic in the handler
  handler: async ({ inputs, context }) => {
    // Connect to a payment provider like Stripe
    console.log(`Processing payment of $${inputs.amount} for ${inputs.customerId}`);
    
    // 3. securely call the external service (secrets managed by .do)
    // const stripe = new Stripe(context.secrets.STRIPE_API_KEY);
    // await stripe.charges.create(...);
    
    // 4. Return a structured, predictable result
    return { success: true, transactionId: `txn_${context.runId}` };
  },
});

// Execute the action securely via the .do API
const result = await processPayment.run({
  customerId: 'cust_12345',
  amount: 49.99,
});

console.log(result);
// Output: { success: true, transactionId: 'txn_...' }

Let's dissect this process-payment action:

The Contract (inputs): We declare that this action requires a customerId (string) and an amount (number). This strong typing prevents errors and makes the action's purpose immediately clear to any developer or AI agent using it.
The Logic (handler): This is the heart of the action. It's an async function where you write the code to perform the task. Here, you would use an SDK or a fetch call to communicate with the external payment gateway's API.
Secure Connections (context): Notice we don't hardcode API keys. Secrets like STRIPE_API_KEY are managed securely through the .do platform and injected into the action's context at runtime. This is a critical security best practice that prevents credentials from ever being exposed in your codebase.
The Result: The action returns a simple, structured object. This output can be logged, analyzed, or, most importantly, passed as an input to the next action in a larger workflow.

From a Single Action to an Agentic Workflow

An atomic action is powerful on its own, but its true potential is unlocked when composed into a sequence. This is the essence of an agentic workflow.

A single action is designed to be atomic; it shouldn't call other actions directly. Instead, you use a workflow.do to orchestrate them. This enforces a clean separation of concerns and creates a visual, stateful process.

Imagine an e-commerce order fulfillment workflow:

process-payment Action: The action we just built is triggered. If it succeeds, it passes the transactionId and customerId to the next step.
update-crm Action: This action takes the customerId as input and calls the Salesforce API to update the customer's record with their latest purchase information.
send-receipt-email Action: This action uses the transactionId and customer details to call the SendGrid API, sending a transactional email to the customer.

Each step is a distinct, reliable action.do. The workflow manages the state, error handling, and data flow between them, turning discrete business tasks into a seamless, automated process.

The Possibilities Are Limitless

While this example focuses on a payment provider, an action can encapsulate any piece of logic you can code. It's the universal adapter for your business operations.

You can create atomic actions to:

Query a database: Fetch user data from PostgreSQL or a document from MongoDB.
Transform data: Parse a CSV, resize an image, or sanitize user input.
Integrate with third-party APIs: Post a message to Slack, create a ticket in Jira, or get data from a weather API.
Run ML models: Send data to a machine learning model for inference and get a prediction back.
Interact with legacy systems: Create a clean, modern API wrapper around an old internal tool.

By encapsulating external service interactions within atomic actions, you're not just writing code; you're building a library of robust, reusable business capabilities. You're creating the building blocks for more intelligent, maintainable, and powerful business automation.