Skip to main content

Project Layout

There is no required folder structure for Culvii Kit projects. However, keeping your definitions organized makes your codebase easier to navigate and maintain.

Group related files together:

  • agents in one place
  • workflows in one place
  • shared tools in one place
  • model refs in one place

Minimal layout​

If you only have a few definitions, keep it simple. A flat structure works well.

src/
  culvii/
    agent.ts
    workflow.ts

As your project grows, you will want to separate concerns. This layout scales well for multiple agents and workflows.

src/
  culvii/
    agents/
      planner.ts
      research.ts
      index.ts
    workflows/
      status-workflow.ts
      customer-follow-up.ts
      index.ts
    tools/
      workflow-tools.ts
    models.ts
    index.ts

Why this matters​

  • Agents: Keeping each agent in its own file (planner.ts, research.ts) makes it easy to find and update their specific prompts and tools.
  • Models: Centralizing model definitions (models.ts) allows you to update a model version (like moving from gpt-4 to gpt-4o) in one place, rather than hunting through multiple agent files.
  • Workflows: Separate workflow files prevent massive, hard-to-read files.
  • Barrel files: Using index.ts files to export your definitions creates a clean API for the rest of your application to consume.

Naming conventions​

Use stable, descriptive IDs and names for your agents and workflows.

// Good
id: 'research'
name: 'Research'

// Avoid
id: 'research-prod-v2-final'
name: 'Research for Q3 Demo'

Stable IDs ensure that your metrics, logs, and database records remain consistent even if the agent's purpose evolves slightly.

Security​

Never hardcode provider credentials (like API keys) in your definition files. Keep them in your environment variables or a secure secrets manager.