Blueprints

What are Blueprints?

Blueprints are JSON configuration files that define a complete FloTorch infrastructure setup. They allow you to:

• Package Complete Setups: Define providers, guardrails, configs, models, tools, agents, and workflows in a single file

• Reuse Configurations: Share and deploy the same infrastructure across multiple workspaces

• Use Variables: Make blueprints flexible by using variables for models, providers, knowledge bases, and memory systems

• Version Control: Store blueprints in version control systems (GitHub) or as templates in FloTorch Console

• Validate Before Deploy: Check for conflicts and errors before deploying to your workspace

Video Tutorial

In this video, we walk through Blueprints in FloTorch.

Blueprint Structure

A blueprint is a JSON object with the following structure:

{
  "name": "my-blueprint",
  "description": "A complete AI infrastructure setup",
  "variables": {
    "myModel": {
      "variable": "model",
      "type": "Chat",
      "required": true
    },
    "myProvider": {
      "variable": "provider",
      "type": "LLM",
      "providerSlug": "openai"
    }
  },
  "schema": {
    "providers": [...],
    "guardrails": [...],
    "configs": [...],
    "models": [...],
    "tools": [...],
    "agents": [...],
    "workflows": [...]
  },
  "conflicts": "SKIP"
}

Blueprint Components

1. Metadata:

• name: Unique identifier for the blueprint

• description: Optional description of the blueprint’s purpose

2. Variables:

• Define placeholders that can be mapped to existing resources during deployment

• Supported variable types: model, provider, knowledge_base, memory

• Variables make blueprints reusable across different workspaces

3. Schema:

• providers: Provider configurations (OpenAI, Anthropic, etc.)

• guardrails: Content moderation and safety guardrails

• configs: Model configuration settings

• models: Model definitions with versions

• tools: MCP (Model Context Protocol) tools (may require API keys - see Tool Requirements section)

• agents: AI agent definitions with versions

• workflows: Workflow definitions with agent orchestration

4. Conflict Resolution:

• UPDATE: Update existing resources (not currently supported)

• SKIP: Skip resources that already exist

• ABORT: Abort deployment if conflicts are found

Creating a Blueprint

Method 1: From URL

Blueprints can be loaded from a URL pointing to a JSON file. Supported domains include:

• github.com (and subdomains)

• flotorch.cloud (and subdomains)

• flotorch.ai (and subdomains)

• localhost (for development)

To deploy a blueprint from a URL:

1. Navigate to the Blueprints page in FloTorch Console

2. Click on Create Blueprint or use the URL: /blueprints/create?source=<your-blueprint-url>

3. The blueprint will be automatically loaded and validated

4. Select a workspace and proceed with validation and deployment

Method 2: From Template ID

Blueprints can also be loaded from template IDs stored in FloTorch Console:

1. Navigate to the Blueprints page

2. Use the URL: /blueprints/create?source=<template-id>

3. The template blueprint will be loaded automatically

Method 3: Manual JSON Upload

You can create a blueprint by writing a JSON file following the blueprint schema:

1. Create a JSON file with the blueprint structure

2. Host it on a supported domain (GitHub, etc.)

3. Use the URL method to deploy it

Tool Requirements and API Keys

Some blueprints include tools (MCP tools) that require external API keys to function properly. It’s important to be aware of these requirements before deploying a blueprint.

Firecrawl Tool

If a blueprint uses the Firecrawl tool, you will need to provide your own Firecrawl API key for the tool to work correctly.

Important Notes:

• Blueprints using Firecrawl tool require your personal Firecrawl API key
• The API key must be configured in your workspace after deployment
• Without a valid API key, the Firecrawl tool will not function

Getting Your Firecrawl API Key:

1. Visit Firecrawl to sign up or log in to your account
2. Navigate to your account dashboard or API settings
3. Generate or copy your Firecrawl API key
4. Configure the API key in your FloTorch workspace settings for the deployed tool

For more information about Firecrawl and API key setup, visit Firecrawl Documentation.

Other Tool Requirements

When deploying blueprints that include tools, always check:

• Tool Dependencies: Review which tools are included in the blueprint
• API Key Requirements: Some tools may require API keys or authentication
• Configuration: Ensure all required tool settings are configured after deployment

If you’re unsure about tool requirements, check the blueprint description or contact the blueprint author.

Blueprint Variables

Variables allow you to make blueprints flexible by referencing existing resources in your workspace. This is particularly useful when you want to reuse existing providers, models, or knowledge bases.

Variable Types

1. Model Variables:

{
  "variables": {
    "chatModel": {
      "variable": "model",
      "type": "Chat",
      "required": true
    }
  }
}

2. Provider Variables:

{
  "variables": {
    "llmProvider": {
      "variable": "provider",
      "type": "LLM",
      "providerSlug": "openai",
      "required": true
    }
  }
}

3. Knowledge Base Variables:

{
  "variables": {
    "kbVar": {
      "variable": "knowledge_base",
      "required": false
    }
  }
}

4. Memory Variables:

{
  "variables": {
    "memoryVar": {
      "variable": "memory",
      "required": false
    }
  }
}

Using Variables in Blueprints

Variables can be referenced in the blueprint schema using the format variables.<variableName>:

In Agent Model References:

{
  "schema": {
    "agents": [
      {
        "name": "my-agent",
        "versions": [
          {
            "version": 1,
            "modelName": "variables.chatModel"
          }
        ]
      }
    ]
  }
}

In Provider References:

{
  "schema": {
    "configs": [
      {
        "name": "my-config",
        "providerName": "variables.llmProvider"
      }
    ]
  }
}

In Workflow Resources:

{
  "schema": {
    "workflows": [
      {
        "name": "my-workflow",
        "graph": {
          "nodes": [
            {
              "id": "agent-1",
              "type": "agent",
              "agentName": "my-agent",
              "agentResources": [
                {
                  "resourceType": "KNOWLEDGE_BASE",
                  "resourceId": "variables.kbVar"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Validating a Blueprint

Before deploying a blueprint, you should validate it to check for:

• Errors: Missing dependencies, invalid references, structural issues

• Conflicts: Resources that already exist in the target workspace

• Dependencies: Missing providers, models, or other resources

Validation Process

1. Load the Blueprint: Load from URL, template ID, or upload JSON

2. Select Workspace: Choose the target workspace for deployment

3. Map Variables (if any): If the blueprint contains variables, you’ll be prompted to map them to existing resources

4. Validate: Click the Validate Blueprint button

5. Review Results: Check the validation summary:

   • Total Resources: Total number of resources in the blueprint

   • To Create: Resources that will be created

   • To Skip: Resources that already exist (will be skipped)

   • Errors: Issues that need to be resolved

Validation Results

The validation process provides detailed feedback:

Errors:

• Missing provider references

• Invalid model references

• Structural validation failures

• Unmapped variables

Conflicts:

• Resources that already exist in the workspace

• These will be skipped during deployment (if conflict mode is SKIP)

Resources to Create:

• List of all resources that will be created

• Organized by type (providers, models, agents, etc.)

Deploying a Blueprint

Once a blueprint is validated successfully, you can deploy it to your workspace.

Deployment Process

1. Validate First: Always validate before deploying

2. Map Variables: If variables are present, ensure all are mapped

3. Deploy: Click the Deploy to Workspace button

4. Review Results: Check the deployment summary

Deployment Results

The deployment process creates all resources in a single transaction:

Created Resources:

• Providers (with encrypted credentials)

• Guardrails

• Configs (linked to providers)

• Models (with versions, configs, and guardrails)

• Tools (MCP tools)

• Agents (with versions and tools)

• Workflows (with nodes, edges, and resources)

Skipped Resources:

• Resources that already exist (based on conflict resolution mode)

Errors:

• Transaction failures

• Missing dependencies

• Validation errors during deployment

Deployment Order

Resources are created in the following order to respect dependencies:

1. Providers - Created first (no dependencies)

2. Guardrails - Created second (may reference providers)

3. Configs - Created third (depend on providers)

4. Models - Created fourth (depend on configs and guardrails)

5. Tools - Created fifth (no dependencies)

6. Agents - Created sixth (depend on models and tools)

7. Workflows - Created last (depend on agents)

Variable Mapping

When a blueprint contains variables, you need to map them to existing resources in your workspace before validation or deployment.

Mapping Process

1. Detect Variables: The system automatically detects all variables in the blueprint

2. Open Mapping Form: When you click Validate or Deploy, a mapping form opens

3. Select Resources: For each variable, select the corresponding resource from your workspace:

   • Model Variables: Select from existing models of the specified type

   • Provider Variables: Select from existing providers of the specified type

   • Knowledge Base Variables: Select from existing knowledge bases

   • Memory Variables: Select from existing memory systems

4. Submit Mapping: Once all variables are mapped, submit the form

5. Automatic Replacement: Variables are automatically replaced in the blueprint

Variable Mapping Requirements

• All required variables must be mapped

• Optional variables can be skipped (if not required)

• Variable types must match (e.g., Chat model variable can only map to Chat models)

• Provider variables can include hints (e.g., providerSlug: "openai") to help with selection

Conflict Resolution

Blueprints support three conflict resolution modes:

1. SKIP (Default):

• Resources that already exist are skipped

• Deployment continues with remaining resources

• No errors are thrown for conflicts

2. UPDATE:

• Existing resources are updated (not currently fully supported)

• Use with caution

3. ABORT:

• Deployment is aborted if any conflicts are found

• No resources are created

• Useful for ensuring clean deployments

Blueprint Best Practices

1. Use Variables for Flexibility

Make blueprints reusable by using variables for resources that may vary across workspaces:

{
  "variables": {
    "primaryModel": {
      "variable": "model",
      "type": "Chat"
    }
  },
  "schema": {
    "agents": [
      {
        "versions": [
          {
            "modelName": "variables.primaryModel"
          }
        ]
      }
    ]
  }
}

2. Provide Clear Descriptions

Add descriptions to help users understand the blueprint’s purpose:

{
  "name": "customer-support-setup",
  "description": "Complete customer support infrastructure with RAG-enabled agent and content moderation"
}

3. Organize Resources Logically

Group related resources together and use consistent naming:

{
  "schema": {
    "providers": [
      { "name": "openai-primary", ... },
      { "name": "openai-fallback", ... }
    ],
    "models": [
      { "name": "chat-primary", ... },
      { "name": "chat-fallback", ... }
    ]
  }
}

4. Test Before Sharing

Always validate and test blueprints in a development workspace before sharing:

1. Validate the blueprint structure

2. Deploy to a test workspace

3. Verify all resources are created correctly

4. Test the deployed agents and workflows

5. Version Your Blueprints

Store blueprints in version control (GitHub) for:

• Change tracking

• Collaboration

• Rollback capabilities

• Documentation

6. Document Dependencies

Clearly document any external dependencies or prerequisites:

{
  "name": "advanced-workflow",
  "description": "Requires: OpenAI provider, existing knowledge base, and memory system"
}

7. Use Conflict Resolution Appropriately

Choose the right conflict resolution mode:

• SKIP: For idempotent deployments (can run multiple times)

• ABORT: For strict deployments (fail if anything exists)

• UPDATE: For updating existing resources (use carefully)

Blueprint Examples

Example 1: Simple Agent Blueprint

{
  "name": "simple-chat-agent",
  "description": "A simple chat agent with OpenAI",
  "schema": {
    "providers": [
      {
        "name": "openai-provider",
        "type": "LLM",
        "options": {
          "id": "openai",
          "secrets": {
            "apiKey": "your-api-key"
          }
        }
      }
    ],
    "configs": [
      {
        "name": "gpt-4-config",
        "providerName": "openai-provider",
        "providerModelName": "gpt-4"
      }
    ],
    "models": [
      {
        "name": "chat-model",
        "type": "Chat",
        "versions": [
          {
            "version": "1",
            "configs": [
              {
                "name": "gpt-4-config",
                "weight": 100,
                "order": 1
              }
            ]
          }
        ]
      }
    ],
    "agents": [
      {
        "name": "chat-agent",
        "versions": [
          {
            "version": 1,
            "modelName": "chat-model",
            "systemPrompt": "You are a helpful assistant."
          }
        ]
      }
    ]
  },
  "conflicts": "SKIP"
}

Example 2: Blueprint with Variables

{
  "name": "flexible-agent-setup",
  "description": "Agent setup with variable model and provider",
  "variables": {
    "chatModel": {
      "variable": "model",
      "type": "Chat",
      "required": true
    },
    "llmProvider": {
      "variable": "provider",
      "type": "LLM",
      "providerSlug": "openai"
    }
  },
  "schema": {
    "configs": [
      {
        "name": "model-config",
        "providerName": "variables.llmProvider",
        "providerModelName": "gpt-4"
      }
    ],
    "agents": [
      {
        "name": "flexible-agent",
        "versions": [
          {
            "version": 1,
            "modelName": "variables.chatModel",
            "systemPrompt": "You are a helpful assistant."
          }
        ]
      }
    ]
  },
  "conflicts": "SKIP"
}

Example 3: Complete Workflow Blueprint

{
  "name": "customer-support-workflow",
  "description": "Complete customer support workflow with RAG",
  "variables": {
    "knowledgeBase": {
      "variable": "knowledge_base",
      "required": true
    }
  },
  "schema": {
    "providers": [
      {
        "name": "openai-provider",
        "type": "LLM",
        "options": {
          "id": "openai"
        }
      }
    ],
    "models": [
      {
        "name": "support-model",
        "type": "Chat",
        "versions": [
          {
            "version": "1",
            "configs": [
              {
                "name": "gpt-4-config",
                "weight": 100,
                "order": 1
              }
            ]
          }
        ]
      }
    ],
    "agents": [
      {
        "name": "support-agent",
        "versions": [
          {
            "version": 1,
            "modelName": "support-model",
            "systemPrompt": "You are a customer support agent."
          }
        ]
      }
    ],
    "workflows": [
      {
        "name": "support-workflow",
        "graph": {
          "nodes": [
            {
              "id": "start",
              "type": "start"
            },
            {
              "id": "agent-1",
              "type": "agent",
              "agentName": "support-agent",
              "agentVersion": "latest",
              "agentResources": [
                {
                  "resourceType": "KNOWLEDGE_BASE",
                  "resourceId": "variables.knowledgeBase"
                }
              ]
            },
            {
              "id": "end",
              "type": "end"
            }
          ],
          "edges": [
            {
              "id": "e1",
              "source": "start",
              "target": "agent-1"
            },
            {
              "id": "e2",
              "source": "agent-1",
              "target": "end"
            }
          ]
        }
      }
    ]
  },
  "conflicts": "SKIP"
}

Troubleshooting

Common Issues

1. Validation Errors:

• Missing Provider: Ensure all referenced providers exist or are defined in the blueprint

• Invalid Model Reference: Check that model names match exactly (case-sensitive)

• Unmapped Variables: Map all required variables before validation

2. Deployment Failures:

• Transaction Errors: Check database connectivity and permissions

• Missing Dependencies: Ensure all dependencies are created in the correct order

• Variable Not Replaced: Verify all variables are mapped before deployment

• Missing API Keys: If the blueprint includes tools (e.g., Firecrawl), ensure you have obtained and configured the required API keys in your workspace. Visit Firecrawl to get your Firecrawl API key if needed.

3. Conflict Resolution:

• Resources Skipped: Check if resources already exist with the same name

• Deployment Aborted: Review conflict resolution mode (change to SKIP if needed)

Getting Help

If you encounter issues:

1. Review the validation errors carefully

2. Check the blueprint structure against the schema

3. Verify all variable mappings are correct

4. Ensure workspace permissions allow resource creation

5. Check the deployment logs for detailed error messages

Permissions

Blueprint deployment requires workspace admin or manager permissions:

• Workspace Admins: Can deploy blueprints

• Workspace Managers: Can deploy blueprints

• Workspace Developers: Cannot deploy blueprints

• Workspace Members: Cannot deploy blueprints

Limitations

• UPDATE Conflict Mode: Not fully supported for all resource types

• Variable Types: Limited to model, provider, knowledge_base, and memory

• Source Domains: Only specific domains are allowed for URL-based blueprints

• Transaction Size: Very large blueprints may timeout (consider splitting into smaller blueprints)