begin.mdx

Overview

The begin.mdx file documents the Begin component, which serves as the starting point in a workflow for an agent within the system. This component is automatically included whenever a new agent is created—either from a template or from scratch—and is mandatory, meaning there can be only one Begin component per workflow and it cannot be deleted.

The primary purpose of the Begin component is to set an opening greeting in conversational workflows and configure input parameters (global variables) that the agent requires to operate. It manages how the workflow is triggered and defines the starting context for user interaction.

Detailed Documentation

Begin Component

Purpose

Initializes the workflow by welcoming users or accepting initial inputs.
Defines global variables (input parameters) that configure the agent’s behavior.
Specifies the mode of operation (conversational or task-based).

Usage

Automatically placed on the canvas when creating an agent.
Click the component to open the Configuration window to customize the greeting, mode, and variables.

Configuration Details

Mode

Defines how the workflow is triggered:

Conversational: The agent is triggered by a conversation.
Task: The agent starts automatically without any conversational trigger.

Opening Greeting

Applicable only in conversational mode.
A message displayed as the agent’s first communication to the user.
Can be a welcome message or instructions to guide user interaction.

Global Variables

Global variables are parameters collected from the user or client to customize the agent’s processing. They are configured within the Begin component and can be mandatory or optional.

Attributes of Global Variables

Attribute	Description
Name (Required)	Descriptive label for the variable to clarify its usage.
Type (Required)	Defines the kind of input expected. Options include: Single-line text Paragraph text Dropdown options (requires at least one dropdown option) File upload Number Boolean (toggle on/off)
Key (Required)	Unique identifier used to reference the variable programmatically.
Optional	Toggle to mark the variable as optional (if not required).

Notes on File Upload Variables

Uploaded files are not stored in a knowledge base.
Uploaded file content is passed as plain text to the agent but is subject to token count limits imposed by the model provider.
If the file exceeds the model's token limit, content will be truncated.
File size limits configured for knowledge base uploads do not apply here.

Interaction with APIs

To programmatically pass parameters to the Begin component, clients can use:

HTTP API: The Converse with agent endpoint.
Python SDK: The Converse with agent method.

This allows external applications or services to initiate conversations or tasks with pre-defined global variable values.

Important Implementation Details

The Begin component is the only component present by default and cannot be removed.
It acts as the single entry point for user interaction or task execution.
Global variables provided here are accessible throughout the workflow as global inputs.
The mode setting determines the workflow’s trigger mechanism, influencing how the agent starts processing.
File uploads as variables require careful management of token limits to avoid truncation.

Frequently Asked Questions (FAQ)

Is the uploaded file stored in a knowledge base?

No. Files uploaded via the Begin component inputs are not stored or processed with knowledge base models (OCR, DLR, TSR) or chunking methods in RAGFlow.

What is the file size limit for uploads?

There is no explicit file size limit enforced by the agent itself, but model providers impose token limits (e.g., 8k to 128k tokens). Uploaded files exceeding these limits will have their content truncated.

Are Docker environment variables relevant for file upload limits here?

No. Environment variables such as MAX_CONTENT_LENGTH and client_max_body_size affect uploads to knowledge bases or File Management only and do not apply to Begin component uploads.

Example Usage

Suppose you create an agent to assist users with onboarding. The Begin component’s configuration might look like:

Mode: Conversational
Opening greeting: "Welcome! Please tell me your name to get started."
Global variables:
- Name: user_name
  Type: Single-line text
  Key: userName
  Optional: No
- Name: profile_picture
  Type: File upload
  Key: profilePic
  Optional: Yes

The agent will start by greeting the user and require the userName variable while optionally accepting a file upload for the profile picture.

Mermaid Diagram: Begin Component Structure

classDiagram
    class BeginComponent {
        +mode: String
        +openingGreeting: String
        +globalVariables: List<GlobalVariable>
        +configureMode(mode: String)
        +setOpeningGreeting(greeting: String)
        +addGlobalVariable(variable: GlobalVariable)
    }

    class GlobalVariable {
        +name: String
        +type: String
        +key: String
        +optional: Boolean
    }

    BeginComponent "1" o-- "*" GlobalVariable : contains

Interaction with the System

The Begin component is the entry point for all agents.
It interfaces with the UI to allow configuration of greetings and variables.
It interacts with backend APIs (HTTP and Python) to accept parameters and start workflows.
The global variables defined here are referenced throughout the agent's workflow components.
The mode setting influences whether the agent listens for conversational inputs or runs as a task.

Summary

The begin.mdx file provides comprehensive documentation of the Begin component, emphasizing its role as the mandatory starting point in agent workflows. It covers configuration options including modes, greetings, and global variables, with detailed explanations of each. The component integrates tightly with client APIs and establishes the initial conditions for agent interaction.

This documentation aids developers and users in understanding how to configure and utilize the Begin component effectively, ensuring consistent agent behavior and proper parameter management from the outset.