Project Structure
Copy page
Learn how to organize your Inkeep Agent projects for optimal development and deployment
Overview
Inkeep Agent projects follow a standardized directory structure that enables the CLI to automatically discover and manage your Agents, Sub Agents, tools, and configurations. This convention-based approach simplifies project organization and deployment workflows.
Standard Project Layout
Core Files
inkeep.config.ts
The configuration file at the workspace root that defines settings for all projects in this workspace:
Important: This file lives at the workspace/repository root level, not inside individual project directories.
index.ts
The project entry point inside each project directory that exports your project definition:
Directory Conventions
/agents/
Contains agent definitions. Each file typically exports one agent:
/tools/
Tool definitions that can be used by Sub Agents:
/data-components/
Data components for structured UI output:
/external-agents/
External agent definitions:
/environments/
Environment-specific configurations for different deployment stages:
File Discovery Process
The CLI automatically discovers files using these patterns:
-
Config Discovery: Searches for
inkeep.config.ts:- Starts from current working directory
- Traverses upward through parent directories until found
- Looks at the same level as
package.jsonandtsconfig.json - Can be overridden with
--configflag
-
Project Discovery: Once config is found:
- Uses the config file's directory as the workspace root
- Scans for project subdirectories containing
index.ts - Each project directory is treated as a separate agent project
-
Resource Discovery: Within each project directory:
- Excludes
node_modules/and.git/ - Categorizes files by directory name and content
- Processes dependencies and relationships
- Excludes
-
File Categorization:
- Index files:
index.ts,main.ts(project entry points) - Agent files: Files in
/agents/directory - Sub Agent files: Files containing Sub Agent definitions
- Tool files: Files in
/tools/directory - Data component files: Files in
/data-components/directory - External agent files: Files in
/external-agents/directory - Environment files: Files in
/environments/directory
- Index files:
Best Practices
Naming Conventions
- Use kebab-case for file names:
customer-support-agent.ts - Use camelCase for variable names:
customerSupportAgent - Use descriptive IDs:
id: 'customer-support-router'
File Organization
- One primary export per file: Each file should export one main resource
- Group related functionality: Keep related Sub Agents in the same Agent file
- Separate concerns: Keep tools, data components, and agents in separate directories
- Environment isolation: Use separate files for different environments
Dependencies
- Explicit imports: Import all dependencies explicitly
- Circular dependency avoidance: Structure imports to prevent circular references
- Type safety: Use TypeScript for all configuration files
Troubleshooting
Common Issues
Config file not found:
- Ensure
inkeep.config.tsexists at your workspace root (same level aspackage.json) - CLI searches upward from current directory - make sure you're in or below the workspace
- Use
--configflag to specify custom location if needed
Invalid project structure:
- Check that you're running from within a project directory (containing
index.ts) - Verify Agent files are in the project's
/agents/subdirectory - Ensure exports are properly named and typed
Missing dependencies:
- Ensure all imported files exist within the project directory
- Check relative file paths and extensions
- Verify imports use correct paths relative to project root
Validation
Use the CLI to validate your project structure:
Migration from Legacy Structures
If migrating from older project structures:
- Move config to workspace root: Ensure
inkeep.config.tsis at same level aspackage.json - Create project directories: Organize agents into project subdirectories
- Create standard subdirectories: Add
/agents/,/tools/,/data-components/within each project - Move files appropriately: Organize existing files into correct project and subdirectories
- Update imports: Fix import paths after restructuring
- Test compilation: Run
inkeep push --jsonto validate structure - Update CI/CD: Adjust build scripts for new workspace structure
This standardized structure ensures your projects work seamlessly with the Inkeep CLI and can be easily shared, deployed, and maintained across different environments.