Agentic workflows are the future of automation. They promise to connect disparate systems, orchestrate complex business logic, and empower AI to execute multi-step tasks. But as these workflows grow in complexity, they risk becoming opaque "black boxes." When a process fails deep within a chain of API calls and function executions, how do you find the root cause? You're flying blind.
The answer isn't to add more console.log statements after the fact. The answer is to build for insight from the very beginning. This is the core principle of Observability-Driven Development (ODD), and it's the foundation upon which the .do platform is built. By embracing ODD, you can move from debugging in the dark to optimizing with clarity.
Imagine a customer onboarding workflow:
This seems straightforward, but it's a chain of dependencies across multiple services. If the user never gets the welcome email, where did it fail? Was the email service API down? Was the API key invalid? Did the database action pass the wrong email address? Without intrinsic observability, you’re left digging through server logs, API dashboards, and database records—a time-consuming and frustrating scavenger hunt.
Observability-Driven Development isn't just about monitoring; it's a design philosophy. It means architecting your system using components that are inherently "askable." Instead of just logging errors, an observable system provides the data you need to ask new questions about its state and performance without having to ship new code.
This is often framed around the three pillars of observability:
When you design with ODD, you stop guessing and start knowing.
The action.do framework is purpose-built for ODD. It starts with the concept of the atomic action: the smallest, indivisible unit of work in your agentic workflow. Instead of being a simple function call, an Action is a managed, enterprise-grade component with observability baked in.
Here's how an action.do primitive provides the three pillars of observability out-of-the-box:
Every Action you define automatically generates structured logs for its entire lifecycle. When you execute an action, the system logs the start time, end time, inputs, outputs (or error), and duration. You don't have to write a single extra line of logging code to capture this critical context.
Consider our send-email action. By simply wrapping the logic in new Action, you gain this rich logging for every single execution.
import { Action } from '@do-co/core';
// Define the input for our action
interface SendEmailInput {
to: string;
subject: string;
body: string;
}
// Define the output of our action
interface SendEmailOutput {
messageId: string;
status: 'sent' | 'failed';
}
// This action is now an observable unit
const sendEmail = new Action<SendEmailInput, SendEmailOutput>({
name: 'send-email',
description: 'Sends a transactional email.',
handler: async (input) => {
// ... integration with email provider
console.log(`Sending email to ${input.to}...`);
const messageId = `msg_${Date.now()}`;
return { messageId, status: 'sent' };
},
});
Because each action is a discrete, named unit (send-email, create-support-ticket, update-database-record), the .do platform can effortlessly aggregate performance metrics for you. You can immediately answer questions like:
This transforms a simple function into a measured and managed component, allowing you to identify and fix performance hotspots before they impact your business.
This is where ODD truly shines for agentic workflows. Since a workflow is just a series of orchestrated atomic actions, the .do platform can automatically stitch together the execution of each action into a single, cohesive trace.
Let's revisit our failed onboarding flow. With action.do, you wouldn't be hunting through logs. You'd look at a single trace for that user's onboarding event and see:
Workflow Trace: user-onboarding-12345
1. Action: create-user | Status: Success | Duration: 55ms
- Input: { email: 'test@example.com', ... }
- Output: { userId: 'usr_abcde', ... }
2. Action: send-email | Status: Failed | Duration: 150ms
- Input: { to: 'test@example.com', subject: 'Welcome!', ... }
- Error: "API Key Invalid"
3. Action: update-crm | Status: Skipped
- Reason: Previous action 'send-email' failed.
The root cause is instantly identified. An invalid API key in the send-email action caused the failure. The diagnosis took seconds, not hours. This is the power of building with observable components.
Complex automations and agentic workflows demand a new way of thinking about software development. Guesswork and manual debugging simply don't scale. By adopting an Observability-Driven Development mindset, you build resilience, clarity, and confidence directly into your automated processes.
The .do platform provides the building blocks for this modern approach. By defining your business processes as a series of atomic actions, you get logging, metrics, and tracing for free. You move from building black boxes to building transparent, manageable, and optimizable systems.
Execute. Measure. Automate. Build your next agentic workflow on a foundation of clarity with action.do.