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 | src/greeter-agent.culvii.ts | Just an agent, no workflow around it. |
agent-workflow (default) | src/greeter-agent.culvii.ts + src/greeting-workflow.culvii.ts | A workflow that invokes an agent through a core.agent step. |
agent-workflow-tool | src/research-agent.culvii.ts + src/research-workflow.culvii.ts | An agent that calls a workflow as a tool via defineWorkflowTool(). |
multi-agent | src/coordinator-agent.culvii.ts + src/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, and --skill [agent] optionally installs the Culvii authoring skill bundle for your AI coding agent. All four templates also generate package.json, tsconfig.json, .gitignore, and culvii.yaml.
In the generated agent, replace YOUR_CREDENTIAL_ID with a credential ID from culvii integration list or 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';
function createWorkflow() {
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);
return new Workflow({
id: 'status-workflow',
name: 'Status Workflow',
steps: [trigger, setStatus],
});
}
createWorkflow();
Use this when the path is explicit and you author it: this step, then that step, branch here. culvii dev and culvii deploy discover resources when their constructors run in evaluated .culvii.ts entrypoints. Construct resources inside named functions called at the bottom of the file, rather than relying on export as a substitute. 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, createAgentModelConfigFromRef } from '@culvii/kit';
function createAgent() {
return new MultiAgentEngine({
id: 'planner',
name: 'Planner',
role: 'primary',
systemPrompt: 'Coordinate the user request.',
// You can use the helper function:
model: createAgentModelConfigFromRef('openai/gpt-4o', 'my-openai-credential'),
// Or the raw object:
// model: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'my-openai-credential' },
secondaryAgents: [],
});
}
createAgent();
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. You can use culvii integration list in the CLI or the Console's Integrations tab to inspect available credential IDs.
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.