Aller au contenu

Assistants

Assistants are AI agents that can be customized with functions, knowledge bases, and configuration. Each assistant has its own instructions, prompt starters, and optional custom functions.

Note: Functions deployed directly to an assistant (not through Global Skills) are called "Assistant Skills". These are tied to the assistant's lifecycle - when you delete an assistant, its Assistant Skills are automatically deleted. Global Skills added to an assistant remain available for other assistants.

Creating Assistants

Using the Forra CLI

The Forra CLI is the recommended way to manage assistants from your development environment.

1. Initialize Your Assistant Project

# Initialize a new assistant project with scaffolding
forracli assistants init -d my_assistant
cd my_assistant

This creates a project structure with an assistants.json configuration file, sample functions, and templates.

2. Configure Your Assistant

Edit the assistants.json file to define your assistant:

{
  "assistants": [
    {
      "name": "Customer Support Assistant",
      "id": "customer_support_v1",
      "description": "Assists customers with order inquiries and support tickets",
      "instructions_text": "You are a helpful customer support assistant. Help users with their orders and create tickets when needed.",
      "allowed_functions": ["all"],
      "use_system_prompt": true,
      "prompt_starters_text": [
        "Check my order status",
        "Create a support ticket"
      ],
      "package_info": {
        "package_path": "functions",
        "package_file_name": "assistant_functions.zip"
      },
      "global_skills": []
    }
  ]
}

3. Build Your Functions Skills

Write your functions using the Forra SDK decorators. See the Functions Getting Started guide for details on creating functions.

4. Deploy Your Assistant

# Synchronize assistants from configuration file
forracli assistants synchronize -f assistants.json

This will create or update your assistants in Forra.

Assistant Configuration Reference

Required Fields

  • name - Display name for the assistant
  • description - Brief description of the assistant's purpose
  • instructions_text or instructions_path - System instructions for the assistant's behavior

Optional Fields

  • id - Unique identifier for the assistant. This is an alias used locally only. The server side id is generated at creation.
  • allowed_functions - Array of function names or ["all"] to allow all functions or [] to allow no functions
  • use_system_prompt - Whether to use Forra's default system prompt (default: true)
  • prompt_starters_text - Array of suggested prompts shown to users
  • prompt_starters_path - Array of file paths containing prompt starters
  • assistant_files - Knowledge base files with descriptions (visible in chat)
  • assistant_assets - Code-execution-only files (available to scripts, not chat knowledge UI)
  • avatar_path - Path to assistant avatar image
  • package_info - Configuration for bundling functions directly with the assistant project
  • package_path - Directory containing functions to be packaged
  • package_file_name - Name for the packaged zip file
  • When configured, functions are automatically packaged and deployed with the assistant
  • ui_url - URL for custom application (development)
  • ui_info - Configuration for bundled application
  • ui_path - Directory containing built application
  • ui_package_file_name - Name for the UI package zip
  • ui_build_cmd - Command to build the UI
  • global_skills - Array of global skill server IDs to attach to the assistant

Instructions

You can provide instructions inline or from a file:

{
  "instructions_text": "Direct instructions text here"
}

Or:

{
  "instructions_path": "instructions.md"
}

Note: If both instructions_text and instructions_path are provided, instructions_text takes precedence.

Prompt Starters

You can provide prompt starters inline or from files:

{
  "prompt_starters_text": [
    "What can you help me with?",
    "Show me recent orders"
  ]
}

Or:

{
  "prompt_starters_path": [
    "starters/greeting.md",
    "starters/orders.md"
  ]
}

Note: If both prompt_starters_text and prompt_starters_path are provided, prompt_starters_text takes precedence.

Knowledge Base Files

Add files that the assistant can reference in chat:

{
  "assistant_files": [
    {
      "filepath": "product_catalog.pdf",
      "description": "Complete product catalog with specifications and pricing"
    },
    {
      "filepath": "support_procedures.md",
      "description": "Internal support procedures and escalation guidelines"
    }
  ]
}

Asset Files

Add files available only to code execution (not listed in chat knowledge):

{
  "assistant_assets": [
    {
      "filepath": "data.csv",
      "description": "Dataset used by custom functions"
    }
  ]
}

Including Functions with Assistant

Functions can be included with your assistant using the package_info configuration in assistants.json:

{
  "package_info": {
    "package_path": "functions",
    "package_file_name": "assistant_functions.zip"
  }
}

This automatically packages and deploys functions from the specified directory when you run forracli assistants synchronize.

Alternatively, you can deploy functions directly to an existing assistant without using assistants.json. Refer to the Deployment Guide for detailed instructions on using forracli functions deploy.

Managing Assistants

Listing Assistants

View all assistants you have access to:

forracli assistants list

Updating an Assistant

Update your assistants.json and re-synchronize:

forracli assistants synchronize -f assistants.json

Note: When you update an assistant's functions, only that assistant is affected.

Adding Global Skills to Assistants

Assistants can use Global Skills in addition to their own functions. Global Skills are tenant-wide skills that can be shared across multiple assistants.

Using assistants.json

You can specify global skills directly in your assistants.json configuration:

{
  "assistants": [
    {
      "name": "Customer Support Assistant",
      "id": "customer_support_v1",
      "description": "Assists customers with order inquiries",
      "instructions_text": "You are a helpful customer support assistant.",
      "global_skills": [
        "550e8400-e29b-41d4-a716-446655440000",
        "660e8400-e29b-41d4-a716-446655440001"
      ]
    }
  ]
}

The global_skills array contains server-side UUIDs of global skills. To get these IDs: - View them in the web interface under Skills > Global Skills - Use the API to list available global skills

When you run forracli assistants synchronize -f assistants.json, the CLI will: - Add any missing global skills to the assistant - Remove any global skills not in the configuration - Leave assistant-owned skills unchanged

Note: The skill IDs are server-generated UUIDs, not local aliases. Make sure the skills exist before adding them to your configuration.

Using the Web Interface

Alternatively, you can manage global skills through the web interface:

  1. Navigate to the assistant's settings
  2. Go to the Skills section
  3. Click Add Global Skills
  4. Select from available global skills
  5. Click Add

Next Steps