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, graphs, 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
/graphs/
Contains agent graph definitions. Each file typically exports one graph:
/tools/
Tool definitions that can be used by agents:
/data-components/
Data components for managing structured data:
/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.json
andtsconfig.json
- Can be overridden with
--config
flag
-
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) - Graph files: Files in
/graphs/
directory - Agent files: Files containing agent definitions
- Tool files: Files in
/tools/
directory - Data component files: Files in
/data-components/
directory - Environment files: Files in
/environments/
directory
- Index files:
Best Practices
Naming Conventions
- Use kebab-case for file names:
customer-support-graph.ts
- Use camelCase for variable names:
customerSupportGraph
- 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 agents in the same graph file
- Separate concerns: Keep tools, data components, and graphs 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.ts
exists at your workspace root (same level aspackage.json
) - CLI searches upward from current directory - make sure you're in or below the workspace
- Use
--config
flag to specify custom location if needed
Invalid project structure:
- Check that you're running from within a project directory (containing
index.ts
) - Verify graph files are in the project's
/graphs/
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.ts
is at same level aspackage.json
- Create project directories: Organize agents into project subdirectories
- Create standard subdirectories: Add
/graphs/
,/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 --json
to 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.