Project Management

Overview

Projects are the top-level organizational unit in the Inkeep Agent Framework. Each project contains its own agents, tools, and resources. This allows you to separate different applications or environments within a single tenant.

Creating a Project

There are two ways to create a new project:

Using the Project Dialog

When you have existing projects, you can create a new one using the "Create Project" button in the project switcher at the bottom of the sidebar.

First Project Creation

If you don't have any projects yet, you'll be automatically redirected to the project creation page when you log in. You can also access it directly at /{tenantId}/projects/new.

Project Fields

When creating a project, you'll need to provide:

Project ID: A unique identifier for your project. This must:
- Start and end with lowercase alphanumeric characters
- May contain hyphens in the middle
- Cannot be changed after creation
- Examples: my-project, production-v2, test-env1
Project Name: A friendly display name for your project (up to 100 characters)
Description: A brief description of what the project is for (up to 500 characters)

Project Structure

Each project can contain:

Agents: Collections of AI agents that work together
API Keys: Authentication keys for accessing your agents via API
MCP Servers: Model Context Protocol servers for external tools
Data Components: Reusable data structures for your agents
Artifact Components: Reusable UI components for agent outputs
Credentials: Secure storage for API keys and authentication tokens

Project-Level Configuration

Projects can define default configurations that cascade down to all agents and Sub Agents within the project. This provides a consistent baseline while allowing specific overrides where needed.

Model Settings

Define default models at the project level that all agents and Sub Agents will inherit:

// Project configuration
{
  id: "my-project",
  name: "My AI Project",
  models: {
    base: {
      model: "anthropic/claude-sonnet-4-5",
      providerOptions: {
        temperature: 0.7,
        maxTokens: 4096
      }
    },
    structuredOutput: {
      model: "openai/gpt-4.1-mini",
      providerOptions: {
        temperature: 0.1,
        maxTokens: 2048
      }
    },
    summarizer: {
      model: "openai/gpt-4.1-nano",
      providerOptions: {
        temperature: 0.3,
        maxTokens: 1024
      }
    }
  }
}

StopWhen Configuration

Configure default stopping conditions to prevent infinite loops:

{
  id: "my-project",
  stopWhen: {
    transferCountIs: 5,    // Max transfers between Sub Agents per conversation
    stepCountIs: 20        // Max tool calls + LLM responses per Sub Agent execution
  }
}

Configuration Inheritance

The framework uses a cascading inheritance system with specific rules for different configuration types:

Model Inheritance - Partial Cascading

Project → Agent → Sub Agent

The framework supports partial cascading, meaning each level can override specific model types while inheriting others. This provides maximum flexibility while maintaining sensible defaults.

How Partial Cascading Works

Each model type (base, structuredOutput, summarizer) cascades independently:

// Project Level - Sets defaults for all agents
Project: {
  models: {
    base: { model: "anthropic/claude-sonnet-4-5" },
    structuredOutput: { model: "openai/gpt-4.1-mini" },
    summarizer: { model: "openai/gpt-4.1-nano" }
  }
}

// Agent Level - Partially overrides project defaults
Agent: {
  models: {
    base: { model: "openai/gpt-4.1" }  // Override: use different base model
    // structuredOutput: INHERITED from project (openai/gpt-4.1-mini)
    // summarizer: INHERITED from project (openai/gpt-4.1-nano)
  }
}

// Sub Agent Level - Can override any inherited model
Sub Agent: {
  models: {
    summarizer: { model: "anthropic/claude-haiku-4-5" }  // Override: use faster summarizer
    // base: INHERITED from Agent (openai/gpt-4.1)
    // structuredOutput: INHERITED from project (openai/gpt-4.1-nano)
  }
}

Final Resolution Example

In the above example, the Sub Agent ends up with:

base: gpt-4.1 (from Agent)
structuredOutput: gpt-4.1-mini (from project)
summarizer: claude-3.5-haiku (from Sub Agent)

Provider Options Override

When a model is overridden at any level, the entire configuration (including provider options) is replaced:

// Project defines base model with options
Project: {
  models: {
    base: {
      model: "claude-sonnet-4-0",
      providerOptions: {
        temperature: 0.7,
        maxTokens: 4096
      }
    }
  }
}

// Agent completely overrides the base model settingsuration
Agent: {
  models: {
    base: {
      model: "claude-sonnet-4-0", // Same model
      providerOptions: {
        temperature: 0.3,  // New temperature
        maxTokens: 2048    // New maxTokens - project maxTokens is NOT inherited
      }
    }
  }
}

Fallback to Base Model

Important: structuredOutput and summarizer only fall back to the base model when there's nothing to inherit from higher levels (project/agent).

System Defaults

Supported Providers: The framework supports Anthropic, OpenAI, and Google models.

API Keys: You need the appropriate API key for the provider you choose to use:

ANTHROPIC_API_KEY for Anthropic models
OPENAI_API_KEY for OpenAI models
GOOGLE_GENERATIVE_AI_API_KEY for Google models

// No higher-level defaults - fallback to base occurs
Project: {
  // No models configured
}

Agent: {
  // No models configured
}

Sub Agent: {
  models: {
    base: {
      model: "gpt-4.1-2025-04-14",
      providerOptions: {
        temperature: 0.7,
        maxTokens: 2048
      }
    }
    // No structuredOutput or summarizer specified
  }
}

Final Resolution with Fallback:

base: gpt-4.1-2025-04-14 with specified provider options (from Agent)
structuredOutput: gpt-4.1-2025-04-14 with same provider options (falls back to Agent's base)
summarizer: gpt-4.1-2025-04-14 with same provider options (falls back to Agent's base)

Contrast with Inheritance:

// Project has summarizer configured - inheritance takes priority
Project: {
  models: {
    summarizer: {
      model: "gpt-4.1-mini";
    }
  }
}

Sub Agent: {
  models: {
    base: {
      model: "gpt-4.1";
    }
  }
}

Final Resolution with Inheritance:

base: gpt-4.1 (from Sub Agent)
summarizer: gpt-4.1-mini (inherited from project - NO fallback to Sub Agent's base)
structuredOutput: Falls back to Sub Agent's base gpt-4.1 (no inheritance available, so fallback occurs)

StopWhen Inheritance

StopWhen settings inherit from Project → Agent → Sub Agent:

transferCountIs: Project or Agent level
stepCountIs: Project or Sub Agent level

// Project sets defaults
Project: {
  stopWhen: {
    transferCountIs: 5,   // Max transfers per conversation
    stepCountIs: 15      // Max steps per Sub Agent
  }
}

// Agent can override transfer limit, inherits step limit
Agent: {
  stopWhen: {
    transferCountIs: 8    // Override: allow more transfers in this Agent
    // stepCountIs: 15 (inherited from project)
  }
}

// Individual Sub Agent can override its own step limit
Sub Agent: {
  stopWhen: {
    stepCountIs: 25      // This Sub Agent can take more steps
    // transferCountIs not applicable at Sub Agent level
  }
}

Switching Between Projects

Use the project switcher in the bottom left of the sidebar to quickly switch between projects. The switcher shows:

The project name (or ID if no name is set)
The project ID
A brief description (if provided)

API Access

Projects can be accessed programmatically via the CRUD API:

// List all projects
GET /tenants/{tenantId}/crud/projects

// Get a specific project
GET /tenants/{tenantId}/crud/projects/{projectId}

// Create a new project
POST /tenants/{tenantId}/crud/projects
{
  "id": "my-project",
  "name": "My Project",
  "description": "A project for my AI agents"
}

// Update a project
PATCH /tenants/{tenantId}/crud/projects/{projectId}
{
  "name": "Updated Name",
  "description": "Updated description"
}

// Delete a project
DELETE /tenants/{tenantId}/crud/projects/{projectId}

Best Practices

Use descriptive IDs: Choose project IDs that clearly indicate their purpose (e.g., customer-support, internal-tools)
Separate by environment: Create different projects for development, staging, and production
Document your projects: Use the description field to explain what each project is for
Organize by application: Group related agents and tools within the same project

Next Steps

After creating a project, you can:

On this page