Creating a Foundation Folder

A foundation folder is your agent’s source of truth. The agent indexes these files to ground planning and execution with your domain knowledge, APIs, and rules.

Quick Start

Use CLI for Multiple Handbooks

The OneMCP CLI makes it easy to manage multiple foundation folders (handbooks) with individual configurations:

# Install CLI
curl -sSL https://raw.githubusercontent.com/Gentoro-OneMCP/onemcp/main/cli/install.sh | bash
 
# Create multiple handbooks
onemcp handbook init ecommerce-api
onemcp handbook init customer-support
 
# Switch between handbooks
onemcp handbook use ecommerce-api
onemcp chat  # Chat with current handbook
 
# Or chat directly with a specific handbook
onemcp chat customer-support

Use Default Foundation (Docker)

The Docker image includes default foundation content from the ACME Analytics Server handbook:

# Run with included example foundation
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=your-key \
  admingentoro/gentoro:latest

This provides:

• Agent instructions for sales analytics API queries
• Documentation on data models and query examples
• OpenAPI specifications for the analytics API
• Sample queries and regression tests
• Pre-configured knowledge base state

Create Your Own Foundation

Create a new directory with the required structure:

mkdir my-foundation
cd my-foundation

Or use the CLI to create a properly structured handbook:

onemcp handbook init my-handbook
cd ~/handbooks/my-handbook

Required Files

1. Agent.md (Required)

Your high-level agent instructions and operating principles:

# Customer Support Agent
 
## Purpose
Assist customers with product inquiries and troubleshooting.
 
## Behavior
- Always be polite and professional
- Gather context before suggesting solutions
- Use available tools to look up account information
 
## Tools
- search_knowledge_base: Find relevant documentation
- get_account_info: Retrieve customer account details
- create_ticket: Create support tickets when needed

2. docs/ Directory (Required)

Markdown documentation with domain knowledge:

mkdir docs
echo "# Product Overview" > docs/overview.md
echo "# API Documentation" > docs/api-guide.md

At least one .md or .mdx file is required. Add:

• Product/service overviews
• Domain concepts and terminology
• How-to guides
• FAQs and troubleshooting

3. apis/ Directory (Required)

OpenAPI specifications (YAML or JSON) for services the agent should call:

mkdir apis
# Add your OpenAPI spec file
cp my-service.openapi.yaml apis/

Requirements:

• Valid OpenAPI 3.0+ or Swagger 2.0
• At least one endpoint defined
• Proper info section with title and version

4. rules/ Directory (Optional)

Business rules, policies, or constraints:

mkdir rules
echo "# Refund Policy" > rules/refunds.md
echo "# Data Privacy Rules" > rules/privacy.md

Use freeform Markdown or YAML to document:

• Business policies
• Compliance requirements
• Operational constraints
• Decision-making rules

5. regression/ Directory (Optional)

Test cases for regression testing:

mkdir regression

Add YAML files with test queries and expected behaviors.

Complete Directory Structure

• my-foundation
  • Agent.md
  • docs
    • overview.md
    • api-guide.md
    • troubleshooting.md
  • apis
    • customer-api.openapi.yaml
    • product-api.openapi.yaml
  • rules
    • refund-policy.md
    • privacy-rules.md
  • regression
    • customer-queries.yaml
  • state

Note: The state/ directory is auto-generated when the agent runs and contains the indexed knowledge base state. The knowledge-base-state.json file includes a signature of your foundation content and cached entries for fast startup.

Run With Your Foundation

Mount your foundation folder at /var/foundation:

docker run --rm \
  -p 8080:8080 \
  -v "$(pwd):/var/foundation" \
  -e OPENAI_API_KEY=your-key \
  admingentoro/gentoro:latest

The agent will:

1. Index all files on startup
2. Build a knowledge base from your docs
3. Parse OpenAPI specs for tool generation
4. Use this context during planning and execution

Best Practices

Agent.md Tips

• Be specific about the agent’s purpose and scope
• Define clear behavioral guidelines
• List available tools and when to use them
• Include example scenarios if helpful

Documentation Tips

• Organize by topic or service
• Use clear headings and structure
• Include examples and code snippets
• Keep docs up-to-date with your services

OpenAPI Spec Tips

• Use descriptive operation IDs and summaries
• Include detailed parameter descriptions
• Provide example requests/responses
• Document error responses

Rules Tips

• Keep rules concise and actionable
• Use examples to clarify edge cases
• Organize by category (compliance, business logic, etc.)
• Update rules as policies change

Validate Your Foundation

Before running your agent, validate your foundation structure:

docker run --rm \
  -v "$(pwd):/var/foundation" \
  -e APP_ARGS="--process=validate" \
  admingentoro/gentoro:latest

This checks for:

• Required files (Agent.md, docs/, apis/)
• Valid OpenAPI specifications
• Proper file formats
• Common issues and warnings

See the Foundation Validation guide for details.

Next Steps

• Managing Multiple Handbooks - Organize multiple AI agents
• Validate your foundation - Ensure your foundation is correct
• Run with Docker - Deploy your agent
• Learn about Retrieval concepts - How agents find information