Composing agents and workflows
The core idea
Workflows and agents call into each other, but not symmetrically. The shapes are different, and knowing which one you're building matters.
A workflow is a deterministic graph you author: this step, then that step, branch here. Reach for one when the structure is known ahead of time: explicit branches, a human approval step, a fixed sequence you want operators to see the shape of, not just the outcome. "First fetch the vendor, then screen it, then if it fails route to rejection" is workflow logic; it's yours, not the model's.
An agent (a MultiAgentEngine primary, optionally with secondaries) is the opposite: the model decides which tools to call and in what order, constrained by what you gave it. Reach for one when you can't enumerate the steps up front. The right tool to call depends on what the previous one returned, or you want the LLM to reason its way to something you validate afterward rather than something you dictated in advance.
The two meet through a core.agent step: it doesn't inline agent logic, it just references a deployed agent by key, sends it a prompt, and waits for a structured response.
The three real composition patterns
1. A workflow step invokes a deployed agent
const screenVendor = new Step({
name: 'Screen Vendor',
type: 'core.agent',
params: { agentReferenceKey: 'vendor-analyst', prompt: '={{$json}}' },
})
fetchVendor.connectTo(screenVendor)
The step pauses the workflow branch on the agent channel and resumes once the agent produces a response matching the expected output schema.
2. An agent calls a workflow as a tool
Wrap an existing workflow with defineWorkflowTool() and attach it to an agent's tools:
const runVendorScreen = defineWorkflowTool({
name: 'runVendorScreen',
description: 'Run the vendor screening workflow for a given vendor ID.',
workflowId: 'vendor-screen',
triggerNodeName: 'Manual Trigger',
})
From the agent's side this looks like any other tool call. The model decides when to reach for it. When invoked, the agent execution suspends durably, launches the target workflow, and resumes automatically with the workflow's output once the child workflow finishes — including after any human-in-the-loop pause.
3. A primary agent delegates to a secondary agent
This is Culvii's actual "agent calls agent" shape. It isn't a generic tool wrapper, it's a first-class field on MultiAgentEngine:
new MultiAgentEngine({
id: 'procurement-coordinator',
name: 'Procurement Coordinator',
role: 'primary',
systemPrompt: 'Coordinate procurement. Delegate vendor risk checks to Risk Analyst.',
model: { provider: 'anthropic', modelId: 'claude-sonnet-4-5', credentialId: 'anthropic-credential' },
secondaryAgents: [
{
id: 'risk-analyst',
name: 'Risk Analyst',
role: 'secondary',
systemPrompt: 'Assess vendor risk given the details the coordinator provides.',
model: { provider: 'anthropic', modelId: 'claude-haiku-4-5', credentialId: 'anthropic-credential' },
},
],
})
The secondary's id is part of the delegation contract. Write its prompt as a narrow job description, not a general-purpose assistant.
How deep you can nest
A reference chain (workflow calls agent calls workflow calls agent, and so on) is capped at three nodes. Only two shapes are valid:
workflow → agent → workflow: the primary agent's workflow tool has to point at a leaf workflow, one with nocore.agentnode inside it. (Secondary agents cannot declare workflow tools).agent → workflow → agent: the workflow'score.agentnode has to point at a leaf agent, and that leaf's primary agent cannot own any workflow tools.
What matters is the chain. Anything deeper than three, a fourth level in either direction, fails validation. This isn't a style preference: culvii dev reports it live as a sync error, and culvii deploy rejects it the same way, both pointing at "fix the reference chain" before anything ships.
Anti-patterns
- One agent with every permission granted, no workflow around it. If you can articulate the structure, put it in a workflow. It's what gives operators visibility and gives you testability per step.
- A workflow that's just a wrapper around one agent step and nothing else. Deploy the agent directly.
What actually gets audited
Deploys and administrative changes land in the audit log, while workflow runs, agent execution events, tool waits, and model calls are recorded in the platform's execution and model-accounting tables — attributed to the user or trigger that initiated the run rather than a separate per-agent cryptographic identity yet. See Identity and audit attribution for the honest version of that story.