Project Structure

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

workspace-root/               # Repository/workspace root
├── package.json              # Workspace package.json
├── tsconfig.json             # TypeScript configuration
├── inkeep.config.ts          # Inkeep configuration file
├── my-agent-project/         # Individual project directory
│   ├── index.ts              # Project entry point
│   ├── agents/               # Agent definitions
│   │   ├── main-agent.ts
│   │   └── support-agent.ts
│   ├── tools/                # Tool definitions
│   │   ├── search-tool.ts
│   │   └── calculator-tool.ts
│   ├── data-components/      # Data component definitions
│   │   ├── user-profile.ts
│   │   └── product-catalog.ts
│   ├── external-agents/      # External agent definitions
│   │   ├── exernal-agent-example.ts
│   └── environments/         # Environment-specific configurations
│       ├── index.ts
│       ├── development.env.ts
│       ├── staging.env.ts
│       └── production.env.ts
└── another-project/          # Additional projects can coexist
    ├── index.ts
    └── ...

Core Files

`inkeep.config.ts`

The configuration file at the workspace root that defines settings for all projects in this workspace:

// Located at workspace root, same level as package.json
import { defineConfig } from '@inkeep/agents-cli/config';

export default defineConfig({
  tenantId: 'my-company',
  agentsManageApiUrl: 'http://localhost:3002',
  agentsRunApiUrl: 'http://localhost:3003',
});

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:

// Located inside project directory (e.g., my-agent-project/index.ts)
import { project } from '@inkeep/agents-sdk';
import { mainAgent } from './agents/main-agent';
import { supportAgent } from './agents/support-agent';
import { searchTool } from './tools/search-tool';
import { calculatorTool } from './tools/calculator-tool';
import { userProfile } from './data-components/user-profile';

export const myProject = project({
  id: 'my-agent-project',
  name: 'My Agent Project',
  description: 'A comprehensive multi-agent system',
  subAgents: () => [mainAgent, supportAgent],
  tools: () => [searchTool, calculatorTool],
  dataComponents: () => [userProfile],
});

Directory Conventions

`/agents/`

Contains agent definitions. Each file typically exports one agent:

// agents/customer-support.ts
import { agent, subAgent } from '@inkeep/agents-sdk';

const routerSubAgent = subAgent({
  id: 'support-router',
  name: 'Support Router',
  prompt: 'Route customer inquiries to appropriate specialists',
});

const billingSubAgent = subAgent({
  id: 'billing-specialist',
  name: 'Billing Specialist',
  prompt: 'Handle billing and payment inquiries',
});

export const customerSupportAgent = agent({
  defaultSubAgent: routerSubAgent,
  subAgents: () => [routerSubAgent, billingSubAgent],
});

`/tools/`

Tool definitions that can be used by Sub Agents:

// tools/database-query.ts
import { tool } from '@inkeep/agents-sdk';

export const databaseQueryTool = tool({
  id: 'db-query',
  name: 'Database Query Tool',
  description: 'Execute SQL queries against the database',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string' },
      database: { type: 'string' }
    }
  },
  // Tool implementation...
});

`/data-components/`

Data components for structured UI output:

// data-components/customer-data.ts
import { dataComponent } from '@inkeep/agents-sdk';
import { z } from 'zod';

export const customerData = dataComponent({
  id: 'customer-data',
  name: 'Customer Information',
  description: 'Customer profile and interaction history',
  props: z.object({
    customerId: z.string().describe("Customer ID"),
    name: z.string().describe("Customer name"),
    email: z.string().describe("Customer email"),
  }),
});

`/external-agents/`

External agent definitions:

import { externalAgent } from '@inkeep/agents-sdk';

export const exernalAgentExample = externalAgent({
  id: 'exernal-agent-example',
  name: 'Exernal Agent Example',
  description: 'An example external agent',
  baseUrl: 'https://api.example.com/agents/support',
  credentialReference: myCredentialReference,
});

`/environments/`

Environment-specific configurations for different deployment stages:

// environments/production.env.ts
import { registerEnvironmentSettings } from '@inkeep/agents-sdk';
import { CredentialStoreType } from '@inkeep/agents-core';

export const production = registerEnvironmentSettings({
  credentials: {
    "openai-prod": {
      id: "openai-prod",
      type: CredentialStoreType.memory,
      credentialStoreId: "memory-default",
      retrievalParams: {
        key: "OPENAI_API_KEY_PROD",
      },
    },
  },
});

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 and tsconfig.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
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

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:

Error: Could not find inkeep.config.ts in current directory or parent directories

Ensure inkeep.config.ts exists at your workspace root (same level as package.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:

Warning: No agents found in project

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:

Error: Cannot resolve import './agents/missing-agent'

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:

# Validate project without pushing
inkeep push --json

# Check config resolution
inkeep config get

Migration from Legacy Structures

If migrating from older project structures:

Move config to workspace root: Ensure inkeep.config.ts is at same level as package.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 --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.

On this page