Getting Started

Scaffold a project

Use the CLI to scaffold a working Kit project instead of assembling one by hand.

npm install -g @culvii/cli
culvii init my-culvii-project
cd my-culvii-project
npm install

culvii init asks what to scaffold. Pick a template based on what you're building:

Template	Generates	Use for
agent-only	greeter-agent.culvii.ts	Just an agent, no workflow around it.
agent-workflow (default)	greeter-agent.culvii.ts + greeting-workflow.culvii.ts	A workflow that invokes an agent through a core.agent step.
agent-workflow-tool	research-agent.culvii.ts + research-workflow.culvii.ts	An agent that calls a workflow as a tool via defineWorkflowTool().
multi-agent	coordinator-agent.culvii.ts + coordination-workflow.culvii.ts	A primary agent delegating to a secondary.

Skip the interactive prompts by passing flags directly. This is useful for CI or scripting:

culvii init my-culvii-project --template agent-workflow-tool --provider anthropic --yes

--here scaffolds into the current directory instead of a new subdirectory. All four templates also generate package.json and tsconfig.json.

In the generated agent, replace YOUR_CREDENTIAL_ID with a credential ID from the Console's Integrations tab and YOUR_MODEL_ID with the provider model ID you want to use. See Credentials if that's unfamiliar. Then run:

culvii login
culvii whoami
culvii dev

See the Quick Start for the complete first-run path, including deploying to sandbox.

Workflow and Step

Culvii Kit gives you two building blocks. You author both in TypeScript; the platform runs them.

A Workflow is a graph of Step instances, wired together with connectTo():

import { Step, Workflow } from '@culvii/kit';

const trigger = new Step({ name: 'Manual Trigger', type: 'manualTrigger' });
const setStatus = new Step({
  name: 'Set Status',
  type: 'core.set',
  params: { values: { status: 'ready' } },
});

trigger.connectTo(setStatus);

export const statusWorkflow = new Workflow({
  id: 'status-workflow',
  name: 'Status Workflow',
  steps: [trigger, setStatus],
});

Use this when the path is explicit and you author it: this step, then that step, branch here. See Building Workflows.

MultiAgentEngine

A MultiAgentEngine defines a primary agent (and optionally secondaries it can delegate to). Instead of a fixed path, the model decides which tools to call and in what order:

import { MultiAgentEngine } from '@culvii/kit';

export const planner = new MultiAgentEngine({
  id: 'planner',
  name: 'Planner',
  role: 'primary',
  systemPrompt: 'Coordinate the user request.',
  model: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'my-openai-credential' },
  secondaryAgents: [],
});

Use this when you can't enumerate the steps up front. The right tool depends on what the last one returned. credentialId is never a raw API key. See Credentials for where it actually comes from, and MultiAgentEngine for the rest.

Combining them

A workflow can invoke a deployed agent through a core.agent step; an agent can call a workflow as a tool via defineWorkflowTool(). Nesting between the two is capped at three levels. See Composing agents and workflows for the patterns and the exact limit.