Allow defining workflows with declarative DSL / dispatch

[ianmacartney]

For agents whose top-level behavior is a pre-defined graph.

Desired features:

• Max depth / max loop iterations to avoid infinite loops
• Easy forking & joining
  • join on all tasks in the workflow
  • create a semaphore, add tasks, check if all tasks are done
• “Pause” for user input
• Read the output of any parent step, by name or by traversing graph
• Allow returning a status (e.g. expected failure) return value, and optionally a mutation handle to call exactly once and args for it (if you want more than the state in the graph journal)

Sample syntax

• In the s.doWhatTheLLMSaid (brain) mutation, it does addChild for all LLM tool calls / other actions, waiting for them to finish before continuing. The whole loop could be run from a brain mutation.
• In the future, we could add inline mutation functions, since .define is registering a mutation & can get called as the step, with a cursor pointing to the step it should execute & with what context.

import { WorkflowManager, workflowBrain, chain, loop, parallel } from "@convex-dev/workflow";

const workflow = new WorkflowManager(components.workflow, {
  workpool: components.workpool, // you can share it between agents
});

// for conciseness
const s = internal.mySteps;

export const support = workflow.define({
 name: "supportOrchestrator",
 args: { userId: v.id("users"), initialComplaint: v.string() },
 steps: chain()
   .mutation(s.createThread) // args are typed as workflow initial args
   .parallel([
     chain().action(s.investigateUserHistory), 
     chain().action(s.detectProductOutage)
   ])
   .loop({
     maxIterations: 10,
     steps: chain()
	       .action(s.askLLMWhatToDo)
	       .mutation(s.doWhatTheLLMSaid), // this step dispatches children
     shouldContinue: s.askLLMToContinue
   })
   .action(s.askLLMForNextStep)
   .mutation(s.updateStatusAndDispatch)
 )
});

[ianmacartney]

Implementation thoughts:

Agents + Steps: brain + body

Simplify agents to a “brain” that is a mutation and decides “what do I do next?” and the ability to enqueue work (in the workpool, say) as children. The agent is considered “active” until its children are all done and it hasn’t decided to do anything else.

That work can be a single action / mutation (for instance to call an LLM to ask it what it thinks), or a “workflow.” A workflow, like an agent, decides what to do next, but is a “dumb agent” in that it doesn’t have dynamic dispatch via code. It has a static config/blueprint. It is itself a “step” with a number of children steps. In fact, each of the workflow “control flow primitives” are actually just “dumb agent” conveniences using the same dispatch primitives as agents & workflow.

• chain/serial is a “dumb agent” that keeps adding child steps for each step in its list, when the previous one finishes, until it’s gone through its whole list, after which it considers itself done. It fails on the first failed step. Its return value is the final return value.
• parallel is a “dumb agent” that adds a child step for all of its list at once, then considers itself done when they’re all done. It will run each branch to success/failure, then return failure if any failed. The arguments to all parallel steps must match, and the return value is an array of the union of return values.
  • map does the same, but calls a single function once per argument.
• loop is a “dumb agent” that runs a given step (which might encompass other steps via serial/parallel/etc), then a continueIf step, until the latter is false, or maxIterations are met. The argument and return type are that of the given step (overall step, which might have many chained steps)
• if is a “dumb agent” that runs a check step, and if it succeeds runs a given step. The return value is either the return value of the embedded step or null.

When a child finishes, the onComplete is called in the parent step. This allows the parent to progress state (e.g. find the next serial step to enqueue). The agent can update its state, and is marked as “done” when there are no active children and nothing has been enqueued. This can propagate up many ancestors that are all “done” at that point.

Say the root of this tree is a customer service agent which had kicked off a workflow to decide what to say to the customer.

[ianmacartney]

Dispatch Option

const workflow = new Workflow(components.workflow, {
  workpool: components.workpool, // you can share it between agents
});

// for conciseness
const w = internal.myWorkflows;

const support = workflow.define({
  name: "supportOrchestrator",
  args: { userId: v.id("users"), initialComplaint: v.string() },
  dispatch: async (ctx, args) => {
    const { agentId, addChild, initialArgs } = ctx;
    // decide what to do next
    switch (args.event.kind) {
      "start":
        // kick off a whole workflow
        await addChild(w.initialResponseWorkflow, initialArgs);
        break;
      "childFinished":
        // Decide if anything is to be done next
	      break;
      "externalEvent":
        // If a human responded, etc.
        break;
    }
  }