This article breaks down the one-shot agent architecture, explains why aggressive context engineering paired with single-turn execution produces more consistent structured output for well-scoped tasks, and walks through building a working one-shot agent system using Node.js and React.

Table of Contents

• Why Bet Against Agentic Loops
• What Are One-Shot 'Minions'? Core Concepts Explained
• Architecture Deep Dive: How Minions Work at Scale
• Implementing a One-Shot Agent System in Node.js
• Building a Simple Dashboard in React
• When to Use One-Shot Agents vs. Multi-Turn Agents
• Implementation Checklist and Production Considerations
• Simplicity as a Scaling Strategy

Why Bet Against Agentic Loops

AI engineering in 2025 is saturated with multi-step agentic architectures. Frameworks like LangChain, CrewAI, and AutoGPT promote chains of reasoning where models loop, reflect, and iterate toward a solution. An alternative bet is gaining traction: one-shot agents that execute a single LLM call per task. Stripe's internal AI system, reportedly called "Minions," relies on one-shot agents for well-defined work. The design thesis is that this approach outperforms complex conversational loops for well-defined tasks on latency and cost, though no public Stripe engineering post details the system's internals or benchmarks. The one-shot agent pattern, when applied at scale, can process high volumes of tasks across documentation, support, and internal tooling. Benchmark reliability, latency, and cost against multi-turn alternatives for your own workloads before committing.

The "Minions" architecture described in this article was reconstructed by the author from publicly available descriptions and interpretation. Specific implementation details and performance claims attributed to Stripe have not been independently verified against a primary source. The patterns and code that follow are the author's reference implementation of the one-shot agent concept.

This article breaks down the one-shot agent architecture, explains why aggressive context engineering paired with single-turn execution produces more consistent structured output for well-scoped tasks, and walks through building a working one-shot agent system using Node.js and React. The system includes a context assembly pipeline, structured task definitions, an orchestration layer for parallel dispatch, and a lightweight dashboard for reviewing execution results.

The core insight is worth stating plainly: investing engineering effort into what goes into the prompt yields far better returns than investing in how many times the model reasons.

What Are One-Shot 'Minions'? Core Concepts Explained

The Minion Model: Single-Turn Task Execution

A "minion" in this architecture is a narrowly scoped AI agent designed to perform exactly one task in a single LLM call. Unlike traditional agents that maintain conversational state across multiple turns, a minion receives a fully assembled context payload, executes once against a precise task definition, and returns a structured result. There is no memory between invocations, no iterative refinement loop, and no open-ended exploration. Each minion is stateless, disposable, and purpose-built for a specific class of work.

The lifecycle is minimal: receive context, execute once, return result. This simplicity is the architecture's defining feature.

Why 'One-Shot' Beats Conversational Loops

Multi-step agent chains suffer from error compounding. Each reasoning step introduces a probability of deviation, and over multiple turns those probabilities multiply. A five-step chain where each step has 95% accuracy yields roughly 77% end-to-end reliability (0.95⁵ ≈ 0.774). One-shot execution carries its own per-call failure rate, which you must measure per task. The advantage holds when single-turn reliability exceeds the compounded multi-step rate for a given task.

Latency drops proportionally: a single LLM call takes one round-trip instead of five, excluding context assembly time, which you should measure separately for your workload. Cost per task drops when context assembly is cheaper than cumulative re-injection across multi-turn calls, so measure both sides before drawing conclusions.

One-shot execution does fail, however, when the task genuinely requires clarification, exploration of ambiguous inputs, or iterative refinement based on intermediate results. Open-ended research, complex negotiation, and multi-document synthesis with conflicting sources still benefit from multi-turn architectures.

Context, Task Definition, and Execution

The architecture rests on three principles that trade off against each other. Context engineering does the heavy lifting: the quality of the context assembled before the LLM call determines the quality of the output, which means your upfront data pipeline is where most engineering time goes. Precise task definition replaces open-ended reasoning; the model receives exactly what to produce, in what format, with explicit constraints, so it has no room to wander. Execution is deterministic in structure even though model output is probabilistic: the system wraps the LLM call in strict input/output contracts and validation, catching drift at the boundary rather than mid-conversation.

Architecture Deep Dive: How Minions Work at Scale

The Context Assembly Pipeline

This approach front-loads intelligence into the prompt rather than the loop. Before any LLM call fires, a context assembly pipeline gathers relevant data from multiple sources, scores each piece for relevance, and prunes the result to fit within the model's token budget. This is where the real engineering happens.

Node.js 18 LTS or later is recommended (verify with node --version). You will also need npm 9+ and an OpenAI API key with access to the gpt-4o model.

The four fetch* functions below are stubs. You must implement them against your own data sources (database, search index, API, etc.). They illustrate the assembly pipeline's interface.

// Code Example 1: Context assembly with relevance scoring and token truncation

// Stub implementations — replace these with your actual data source adapters
async function fetchUserHistory(userId) {
  // TODO: Fetch from your user activity store
  // Must return an array of objects with { summary: string, recencyScore: number }
  return [];
}

async function fetchAccountMetadata(userId) {
  // TODO: Fetch from your accounts service
  // Must return an object with account details
  return {};
}

async function fetchRelevantDocs(taskType) {
  // TODO: Fetch from your documentation/knowledge base
  // Must return an array of objects with { text: string, relevanceScore: number }
  return [];
}

async function fetchRecentApiLogs(userId, options = {}) {
  // TODO: Fetch from your API logging system
  // options.limit controls max rows returned — implementations MUST honour this parameter.
  // Must return an array of objects with { summary: string, errorRelevance: number }
  return [];
}

async function assembleContext(userId, taskType, tokenBudget = 6000) {
  const sources = await Promise.all([
    fetchUserHistory(userId),
    fetchAccountMetadata(userId),
    fetchRelevantDocs(taskType),
    fetchRecentApiLogs(userId, { limit: 50 }),
  ]);

  const [userHistory, accountMeta, docs, apiLogs] = sources;

  const scoredChunks = [
    ...userHistory.map(h => ({ content: h.summary, source: 'history', score: h.recencyScore })),
    ...docs.map(d => ({ content: d.text, source: 'docs', score: d.relevanceScore })),
    ...apiLogs.map(l => ({ content: l.summary, source: 'api_logs', score: l.errorRelevance })),
    { content: JSON.stringify(accountMeta), source: 'account', score: 1.0 },
  ];

  scoredChunks.sort((a, b) => b.score - a.score);

  let tokenCount = 0;
  const selected = [];
  for (const chunk of scoredChunks) {
    const chunkTokens = estimateTokens(chunk.content);
    if (tokenCount + chunkTokens > tokenBudget) break;
    selected.push(chunk);
    tokenCount += chunkTokens;
  }

  return {
    chunks: selected,
    totalTokens: tokenCount,
    sourcesUsed: [...new Set(selected.map(s => s.source))],
  };
}

// WARNING: This is an ASCII approximation only (~4 chars per token for English text).
// For production use with multilingual or code-heavy content, use the tiktoken library
// (https://github.com/openai/tiktoken) for accurate token counting.
function estimateTokens(text) {
  return Math.ceil(text.length / 4);
}

The tokenBudget parameter (defaulting to 6000) should be tuned based on your model's context window and how much of that window you need to reserve for the system prompt, task input, and output tokens. For gpt-4o with a 128k context window, 6000 is conservative; adjust based on your prompt structure.

Task Definition as a Contract

Minion task definitions function as strict contracts between the orchestration layer and the LLM. Each definition specifies the task type, required input fields, expected output format, constraints the model must respect, and criteria for evaluating success. This mirrors the discipline of API contract design and eliminates the vague prompts that make multi-turn agents wander.

// Code Example 2: Structured task definition schema
const taskDefinition = {
  taskType: 'classify_support_ticket',
  version: '1.3.0',
  input: {
    required: ['ticketText', 'customerTier', 'productArea'],
    optional: ['previousTicketIds', 'accountAge'],
  },
  output: {
    format: 'json',
    schema: {
      category: { type: 'string', enum: ['billing', 'technical', 'account', 'fraud', 'other'] },
      priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
      suggestedAction: { type: 'string', maxLength: 500 },
      confidence: { type: 'number', min: 0, max: 1 },
    },
  },
  constraints: [
    'Classify based solely on the provided ticket text and customer context.',
    'Do not hallucinate product features not mentioned in the context.',
    'If confidence is below 0.6, set suggestedAction to "escalate_to_human".',
  ],
  evaluation: {
    successCriteria: 'Valid JSON matching output schema with confidence > 0',
    timeout: 10000,
  },
};

The Orchestrator Layer

The orchestrator accepts high-level requests, decomposes them into discrete minion tasks, dispatches those tasks in parallel, and aggregates results. This uses fan-out/fan-in execution, meaning multiple minions run simultaneously. Partial failures are expected and handled gracefully.

Unbounded parallel dispatch can trigger OpenAI rate-limit errors (HTTP 429) and rack up significant API costs when many subtasks fan out at once. The implementation below uses the p-limit npm package to cap concurrency and wraps each task in a timeout to prevent hung requests from blocking indefinitely.

// Code Example 3: Orchestrator with parallel dispatch, concurrency limit, and per-task timeout
// Requires: npm install p-limit
import pLimit from 'p-limit';

const CONCURRENCY_LIMIT = parseInt(process.env.MINION_CONCURRENCY ?? '5', 10);
const TASK_TIMEOUT_MS = parseInt(process.env.MINION_TIMEOUT_MS ?? '15000', 10);

function withTimeout(promise, ms, label) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(
      () => reject(new Error(`Task "${label}" timed out after ${ms}ms`)),
      ms
    );
    promise.then(
      val => { clearTimeout(timer); resolve(val); },
      err => { clearTimeout(timer); reject(err); }
    );
  });
}

async function orchestrate(request, minionRegistry) {
  const tasks = decompose(request);

  // Validate all task types before dispatching any
  const unknownTypes = tasks
    .filter(t => !minionRegistry[t.taskType])
    .map(t => t.taskType);
  if (unknownTypes.length > 0) {
    throw new Error(`Unknown task types: ${unknownTypes.join(', ')}`);
  }

  const limit = pLimit(CONCURRENCY_LIMIT);

  const dispatched = tasks.map(task => {
    const minion = minionRegistry[task.taskType];
    const startTime = Date.now();

    return limit(() =>
      withTimeout(minion.execute(task), TASK_TIMEOUT_MS, task.taskType)
        .then(result => ({
          taskType: task.taskType,
          status: 'fulfilled',
          result,
          durationMs: Date.now() - startTime,
        }))
        .catch(err => {
          // Attach taskType to the rejection so allSettled can recover it
          const tagged = new Error(err.message);
          tagged.taskType = task.taskType;
          return Promise.reject(tagged);
        })
    );
  });

  const outcomes = await Promise.allSettled(dispatched);

  return {
    results: outcomes.map(o =>
      o.status === 'fulfilled'
        ? o.value
        : {
            taskType: o.reason?.taskType ?? 'unknown',
            status: 'rejected',
            error: o.reason?.message ?? String(o.reason),
          }
    ),
    summary: {
      total: outcomes.length,
      succeeded: outcomes.filter(o => o.status === 'fulfilled').length,
      failed: outcomes.filter(o => o.status === 'rejected').length,
    },
  };
}

function decompose(request) {
  if (!Array.isArray(request?.subtasks)) {
    throw new Error('Request must include a subtasks array');
  }
  // Map a high-level request to individual minion tasks
  return request.subtasks.map(sub => ({
    taskType: sub.type,
    input: sub.payload,
    context: request.sharedContext,
  }));
}

Implementing a One-Shot Agent System in Node.js

Setting Up the Project Structure

Node.js 18 LTS or later is recommended. Verify with node --version.

The project separates code into four directories: /context for the context assembly engine, /tasks for task definition schemas, /minions for individual minion implementations, and /orchestrator for the dispatch and aggregation logic.

// package.json
{
  "name": "minion-system",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "start": "node server.js" },
  "dependencies": {
    "express": "^4.18.2",
    "openai": "^4.52.0",
    "cors": "^2.8.5",
    "dotenv": "^16.3.1",
    "p-limit": "^5.0.0"
  }
}

Folder structure:
/context       — ContextEngine class and source adapters
/tasks         — Task definition schemas (JSON/JS)
/minions       — Minion class and specific minion implementations
  registry.js  — Exports minionRegistry (see below)
/orchestrator  — Orchestrate, decompose, aggregate logic
  index.js     — Exports orchestrate function
server.js      — Express entry point
.env           — OPENAI_API_KEY=sk-...
.env.example   — OPENAI_API_KEY=sk-your-key-here
                  ALLOWED_ORIGINS=http://localhost:5173
                  MINION_CONCURRENCY=5
                  MINION_TIMEOUT_MS=15000

Security: Never hard-code API keys in source files. Create a .env file containing OPENAI_API_KEY=sk-... and ensure .env is listed in your .gitignore. The dotenv package loads this into process.env at startup.

// server.js
import 'dotenv/config';
import express from 'express';
import cors from 'cors';
import { orchestrate } from './orchestrator/index.js';
import { minionRegistry } from './minions/registry.js';

if (!process.env.OPENAI_API_KEY) {
  throw new Error('OPENAI_API_KEY environment variable is not set. Aborting.');
}

const ALLOWED_ORIGINS = (process.env.ALLOWED_ORIGINS || '')
  .split(',')
  .map(o => o.trim())
  .filter(Boolean);

const app = express();

app.use(cors({
  origin: ALLOWED_ORIGINS.length > 0
    ? (origin, cb) => {
        if (!origin || ALLOWED_ORIGINS.includes(origin)) return cb(null, true);
        cb(new Error(`Origin ${origin} not allowed`));
      }
    : false,
}));

app.use(express.json({ limit: '64kb' }));

app.post('/run-task', async (req, res) => {
  try {
    const result = await orchestrate(req.body, minionRegistry);
    res.json(result);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3001, () => console.log('Minion system running on port 3001'));

The Minion Registry

The orchestrator and server both import minionRegistry, which maps task type strings to Minion instances. You must create this file and register each minion your system supports.

// minions/registry.js
import { Minion } from './Minion.js';

// Import your task definitions
// import { classifySupportTicketDef } from '../tasks/classifySupportTicket.js';

// Register each task type to a Minion instance
export const minionRegistry = {
  // Example:
  // classify_support_ticket: new Minion(classifySupportTicketDef),
};

// Add entries here as you define new task types and their corresponding task definitions.

Building a Context Engine

The ContextEngine class provides a reusable interface for composing context from heterogeneous sources. Each source adapter fetches and formats its data, and the engine enforces a strict token budget to prevent context overflow.

// Code Example 5: Reusable ContextEngine class
export class ContextEngine {
  constructor() {
    this.sources = [];
  }

  addSource(name, fetchFn, priority = 1) {
    this.sources.push({ name, fetchFn, priority });
    return this;
  }

  async build(params) {
    const fetched = await Promise.all(
      this.sources.map(async (src) => {
        try {
          const data = await src.fetchFn(params);
          return { name: src.name, data, priority: src.priority };
        } catch (err) {
          console.warn(`Context source "${src.name}" failed: ${err.message}`);
          return { name: src.name, data: null, priority: 0 };
        }
      })
    );
    return fetched.filter(s => s.data !== null).sort((a, b) => b.priority - a.priority);
  }

  truncate(contextParts, tokenBudget) {
    let totalTokens = 0;
    const result = [];

    for (const part of contextParts) {
      const serialized = typeof part.data === 'string' ? part.data : JSON.stringify(part.data);
      // ASCII approximation — use tiktoken for multilingual/code content
      const tokens = Math.ceil(serialized.length / 4);

      if (totalTokens + tokens > tokenBudget) {
        const remainingBudget = tokenBudget - totalTokens;
        if (remainingBudget > 100) {
          const charBudget = remainingBudget * 4;
          // Always truncate to a plain string to avoid broken JSON injection.
          // If the source was an object, the truncated form is explicitly marked
          // as a string fragment, not valid JSON.
          const truncatedText =
            Array.from(serialized).slice(0, charBudget).join('') + '…[truncated]';
          result.push({ ...part, data: truncatedText, truncated: true });
          totalTokens += remainingBudget;
        }
        break;
      }

      result.push({ ...part, truncated: false });
      totalTokens += tokens;
    }

    return { parts: result, totalTokens };
  }
}

Creating Your First Minion

The Minion class wraps a single LLM call with the pre-assembled context and task definition. It constructs a system prompt from the task constraints, injects context into the user message, makes one API call, and validates the structured output against the task's output schema.

Ensure OPENAI_API_KEY is set in your environment (via .env file with dotenv, or export OPENAI_API_KEY=sk-... in your shell). The new OpenAI() constructor reads from process.env.OPENAI_API_KEY. Never hard-code API keys in source.

// Code Example 6: Minion class with LLM call and output validation
// minions/Minion.js
import OpenAI from 'openai';

export class Minion {
  constructor(taskDefinition, client = new OpenAI()) {
    this.taskDef = taskDefinition;
    this.openai = client;
  }

  async execute(task) {
    const systemPrompt = [
      `You are a specialized agent for task: ${this.taskDef.taskType}`,
      `Output format: ${this.taskDef.output.format}`,
      `Output schema: ${JSON.stringify(this.taskDef.output.schema)}`,
      ...this.taskDef.constraints.map(c => `Constraint: ${c}`),
      'Respond ONLY with valid JSON matching the schema. No explanation.',
    ].join('
');

    const userMessage = [
      '## Context',
      typeof task.context === 'string' ? task.context : JSON.stringify(task.context),
      '## Task Input',
      JSON.stringify(task.input),
    ].join('
');

    const startTime = Date.now();
    // Note: response_format: { type: 'json_object' } requires a compatible model
    // (gpt-4o, gpt-4-turbo, gpt-3.5-turbo-1106+). Verify support at
    // https://platform.openai.com/docs/guides/structured-outputs
    const response = await this.openai.chat.completions.create({
      model: this.taskDef.model || 'gpt-4o',
      messages: [
        { role: 'system', content: systemPrompt },
        { role: 'user', content: userMessage },
      ],
      temperature: 0.1,
      max_tokens: this.taskDef.output.maxTokens || 1000,
      response_format: { type: 'json_object' },
    });

    // Guard: OpenAI can return empty choices on content-filter or quota errors
    const choice = response.choices?.[0];
    if (!choice?.message?.content) {
      throw new Error(
        `Minion "${this.taskDef.taskType}" received no content from model ` +
        `(finish_reason: ${choice?.finish_reason ?? 'none'})`
      );
    }

    const raw = choice.message.content;
    const tokensUsed = response.usage?.total_tokens ?? 0;

    let parsed;
    try {
      parsed = JSON.parse(raw);
    } catch {
      throw new Error(`Minion "${this.taskDef.taskType}" returned invalid JSON: ${raw.slice(0, 200)}`);
    }

    const validation = this.validate(parsed);
    if (!validation.valid) {
      throw new Error(`Output validation failed: ${validation.errors.join(', ')}`);
    }

    return { data: parsed, tokensUsed, durationMs: Date.now() - startTime };
  }

  validate(output) {
    const errors = [];
    const schema = this.taskDef.output.schema;

    for (const [key, rules] of Object.entries(schema)) {
      if (!(key in output)) { errors.push(`Missing field: ${key}`); continue; }
      if (rules.enum && !rules.enum.includes(output[key])) {
        errors.push(`${key}: "${output[key]}" not in [${rules.enum.join(', ')}]`);
      }
      if (rules.type === 'number' && typeof output[key] !== 'number') {
        errors.push(`${key}: expected number, got ${typeof output[key]}`);
      }
      if (rules.type === 'number' && typeof rules.min === 'number' && output[key] < rules.min) {
        errors.push(`${key}: ${output[key]} is below minimum ${rules.min}`);
      }
      if (rules.type === 'number' && typeof rules.max === 'number' && output[key] > rules.max) {
        errors.push(`${key}: ${output[key]} exceeds maximum ${rules.max}`);
      }
      if (rules.type === 'string' && typeof rules.maxLength === 'number'
          && typeof output[key] === 'string' && output[key].length > rules.maxLength) {
        errors.push(`${key}: length ${output[key].length} exceeds maxLength ${rules.maxLength}`);
      }
    }

    return { valid: errors.length === 0, errors };
  }
}

Wiring It Together: The Orchestration Layer

The final piece connects the Express endpoint to the orchestrator, adding per-minion timing and token usage logging to the response.

// Code Example 7: Complete Express route handler with logging
// orchestrator/handler.js
import { orchestrate } from './index.js';
import { minionRegistry } from '../minions/registry.js';

export async function runTaskHandler(req, res) {
  const requestStart = Date.now();

  try {
    const result = await orchestrate(req.body, minionRegistry);

    const minionMetrics = result.results.map(r => ({
      taskType: r.taskType,
      status: r.status,
      durationMs: r.durationMs || null,
      tokensUsed: r.result?.tokensUsed || null,
    }));

    const totalDuration = Date.now() - requestStart;
    const totalTokens = minionMetrics.reduce((sum, m) => sum + (m.tokensUsed || 0), 0);

    console.log(`[run-task] ${result.summary.succeeded}/${result.summary.total} succeeded | ${totalDuration}ms | ${totalTokens} tokens`);

    res.json({
      ...result,
      metrics: {
        totalDurationMs: totalDuration,
        totalTokens,
        perMinion: minionMetrics,
      },
    });
  } catch (err) {
    console.error(`[run-task] Fatal error: ${err.message}`);
    res.status(500).json({ error: err.message });
  }
}

// In server.js, you can use this handler instead of the inline one:
// import { runTaskHandler } from './orchestrator/handler.js';
// app.post('/run-task', runTaskHandler);

Building a Simple Dashboard in React

Visualizing Minion Execution

A lightweight React component provides a way to submit tasks, review each minion's execution status and metrics after task completion.

This component uses a single fetch call and displays results after completion. It does not stream execution status in real time. For live updates during execution, consider adding WebSocket or Server-Sent Events support.

// Code Example 8: MinionDashboard React component
// Requires a React project (e.g., via Vite: npm create vite@latest dashboard -- --template react)
import { useState, useRef } from 'react';

const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:3001';

export function MinionDashboard() {
  const [taskInput, setTaskInput] = useState('');
  const [minionResults, setMinionResults] = useState([]);
  const [metrics, setMetrics] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const abortRef = useRef(null);

  async function submitTask() {
    // Cancel any in-flight request before starting a new one
    if (abortRef.current) abortRef.current.abort();
    const controller = new AbortController();
    abortRef.current = controller;

    setLoading(true);
    setError(null);
    setMinionResults([]);
    setMetrics(null);

    let payload;
    try {
      payload = JSON.parse(taskInput);
    } catch {
      setError('Invalid JSON in task input.');
      setLoading(false);
      return;
    }

    try {
      const response = await fetch(`${API_BASE}/run-task`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
        signal: controller.signal,
      });

      if (!response.ok) throw new Error(`Server returned ${response.status}`);
      const data = await response.json();

      setMinionResults(data.results || []);
      setMetrics(data.metrics || null);
    } catch (err) {
      if (err.name === 'AbortError') return; // Intentional cancellation — do not surface
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div style={{ maxWidth: 800, margin: '2rem auto', fontFamily: 'system-ui' }}>
      <h1>Minion Dashboard</h1>
      <textarea
        rows={8}
        style={{ width: '100%', fontFamily: 'monospace', fontSize: 14 }}
        value={taskInput}
        onChange={e => setTaskInput(e.target.value)}
        placeholder="Paste task JSON here..."
      />
      <button onClick={submitTask} disabled={loading} style={{ marginTop: 8 }}>
        {loading ? 'Running...' : 'Submit Task'}
      </button>

      {error && <p style={{ color: 'red' }}>Error: {error}</p>}

      {minionResults.length > 0 && (
        <table
          style={{
            marginTop: 16,
            width: '100%',
            borderCollapse: 'collapse',
            border: '1px solid #ccc',
          }}
        >
          <thead>
            <tr>
              <th>Task Type</th>
              <th>Status</th>
              <th>Duration (ms)</th>
              <th>Tokens Used</th>
            </tr>
          </thead>
          <tbody>
            {minionResults.map((r, i) => (
              <tr
                key={`${r.taskType}-${i}`}
                style={{ background: r.status === 'fulfilled' ? '#e6ffe6' : '#ffe6e6' }}
              >
                <td>{r.taskType}</td>
                <td>{r.status === 'fulfilled' ? '✅ Success' : '❌ Failed'}</td>
                <td>{r.durationMs ?? 'N/A'}</td>
                <td>{r.result?.tokensUsed ?? 'N/A'}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}

      {metrics && (
        <div style={{ marginTop: 16, padding: 12, background: '#f5f5f5' }}>
          <strong>Total Duration:</strong> {metrics.totalDurationMs}ms |{' '}
          <strong>Total Tokens:</strong> {metrics.totalTokens}
        </div>
      )}
    </div>
  );
}

When to Use One-Shot Agents vs. Multi-Turn Agents

The Decision Framework

The decision between one-shot and multi-turn is structural, not ideological. Tasks with well-defined inputs, predictable output shapes, and clear success criteria are strong candidates for one-shot execution. Classification, extraction, transformation, and routing tasks all fit this profile.

Multi-turn agents earn their complexity when the task genuinely requires clarification from the user, when intermediate results change the direction of the work, or when the search space is too large to compress into a single context window. Open-ended research, multi-document synthesis with conflicting information, and interactive debugging sessions still warrant conversational loops.

A practical hybrid exists: a thin conversational wrapper that collects missing inputs from the user, then dispatches one-shot minions for the actual work. This captures the reliability of single-turn execution while accommodating ambiguous initial requests.

Real-World Use Cases

Document classification and structured data extraction are the strongest fits because inputs and outputs are fully specifiable upfront. A minion receives a document, a schema describing what to extract, and returns structured JSON. Code review is similarly well-suited: the minion receives a diff and coding standards as context, then returns annotated feedback in a single pass.

Customer support ticket routing, data validation across pipeline stages, and content moderation follow the same pattern, though each introduces its own edge cases around ambiguous inputs. In every case the key characteristic is that you can fully specify the task before execution begins.

A practical hybrid exists: a thin conversational wrapper that collects missing inputs from the user, then dispatches one-shot minions for the actual work. This captures the reliability of single-turn execution while accommodating ambiguous initial requests.

Implementation Checklist and Production Considerations

One-Shot Agents vs. Multi-Turn Agents

Simplicity as a Scaling Strategy

Not every problem requires an agentic loop. Start with the simplest agent architecture that could solve the problem, validate it against real workloads, and only add complexity when single-turn execution demonstrably fails. That is a more disciplined engineering approach than defaulting to multi-step agents, and it scales without the operational burden of managing conversational state and compounding errors.