Typescript sdk

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

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
│   ├── graphs/               # Agent graph definitions
│   │   ├── main-graph.ts
│   │   └── support-graph.ts
│   ├── tools/                # Tool definitions
│   │   ├── search-tool.ts
│   │   └── calculator-tool.ts
│   ├── data-components/      # Data component definitions
│   │   ├── user-profile.ts
│   │   └── product-catalog.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 { mainGraph } from './graphs/main-graph';
import { supportGraph } from './graphs/support-graph';
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',
  graphs: () => [mainGraph, supportGraph],
  tools: () => [searchTool, calculatorTool],
  dataComponents: () => [userProfile],
});

Directory Conventions

/graphs/

Contains agent graph definitions. Each file typically exports one graph:

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

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

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

export const customerSupportGraph = agentGraph({
  defaultAgent: routerAgent,
  agents: [routerAgent, billingAgent],
});

/tools/

Tool definitions that can be used by 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 managing structured data:

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

export const customerData = dataComponent({
  id: 'customer-data',
  name: 'Customer Information',
  description: 'Customer profile and interaction history',
  schema: {
    type: 'object',
    properties: {
      customerId: { type: 'string' },
      name: { type: 'string' },
      email: { type: 'string' }
    }
  }
});

/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:

  1. 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
  2. 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
  3. Resource Discovery: Within each project directory:

    • Excludes node_modules/ and .git/
    • Categorizes files by directory name and content
    • Processes dependencies and relationships
  4. 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

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:

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 graphs found in project
  • 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:

Error: Cannot resolve import './graphs/missing-graph'
  • 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:

  1. Move config to workspace root: Ensure inkeep.config.ts is at same level as package.json
  2. Create project directories: Organize agents into project subdirectories
  3. Create standard subdirectories: Add /graphs/, /tools/, /data-components/ within each project
  4. Move files appropriately: Organize existing files into correct project and subdirectories
  5. Update imports: Fix import paths after restructuring
  6. Test compilation: Run inkeep push --json to validate structure
  7. 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.