An agent that starts a workflow

The agent owns the conversation and offloads the slow work. A tool starts an enrich-profile workflow and returns right away, so the user does not wait while the background job runs. Swap start for startAndWait when the agent needs the result before it replies.

The whole agent is a single deep-agents/onboarder/index.ts file. It builds on the agent examples and the workflow examples, so both halves should look familiar.

import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { defineDeepAgent } from '@stackbone/sdk/deep';
import { stackbone } from '@stackbone/sdk';

const enrichProfile = tool(
  async ({ userId }: { userId: string }) => {
    const handle = await stackbone.workflows.start('enrich-profile', { userId });
    // `queued` means the workflow is serial and an earlier run holds the lock,
    // so there is no run id yet. It starts on its own when the lock frees.
    return JSON.stringify({ status: handle.status, runId: handle.runId ?? null });
  },
  {
    name: 'enrich_profile',
    description: 'Start background enrichment for a user profile.',
    schema: z.object({ userId: z.string() }),
  },
);

export default defineDeepAgent({
  name: 'onboarding',
  model: 'openai/gpt-4o-mini',
  tools: [enrichProfile],
});

Its instruction — help new users get set up, call enrich_profile with the user's id and say the enrichment is running in the background — is a prompt in the catalogue keyed onboarding, written and published in Studio. See Prompts.

start resolves as soon as the run is accepted, so the tool hands the model an acceptance status rather than the workflow's answer. See serial execution for the queued case.

If the agent needs the workflow's result before it replies, swap start for startAndWait. It suspends until the workflow finishes, then returns the output validated against the target's outputSchema:

const profile = await stackbone.workflows.startAndWait<{ tier: string }>('enrich-profile', {
  userId,
});
return JSON.stringify({ tier: profile.tier });

Both live on the stackbone.workflows namespace. There is no top-level startWorkflow import to reach for.

What's next

• A workflow that delegates a turn to an agent: the same two pieces, with the workflow in charge.
• Draft with an agent, then gate the send on a human: an agent draft behind a human approval.
• What is a workflow agent: the model behind this flow.