code.mdx

Overview

The Code component is a versatile integration module within the Agent framework that allows users to embed and execute custom Python or JavaScript code snippets dynamically. This enables sophisticated data processing workflows by extending the Agent's capabilities through user-defined logic. The component leverages sandboxed execution environments to securely run arbitrary code, ensuring system safety and stability.

Key highlights:

• Supports both Python and JavaScript code execution.

• Utilizes gVisor for container runtime isolation.

• Executes code within the RAGFlow Sandbox, a secure pluggable execution backend.

• Allows multiple input variables and customizable output definitions.

• Designed for dynamic data processing scenarios within the Agent.

Detailed Explanations

Component Purpose

The Code component is primarily intended for scenarios requiring complex or custom logic that cannot be achieved through standard Agent configurations alone. By embedding Python or JavaScript code, users can implement advanced processing steps, API calls, data transformations, or other specialized computations within their workflows.

Configuration Sections

1. Input Variables

• Purpose: Define the input parameters your code will consume.

• Usage: Use the UI to add multiple input variables, which become accessible within your code snippet.

• Example: If you add variables arg1 and arg2, these can be referenced in your Python function or JavaScript async function.

2. Code Field

• Purpose: Enter your source code here.

• Supported Languages: Python and JavaScript.

Python Example

def main(arg1: str, arg2: str) -> dict:
    return {
        "result": arg1 + arg2,
    }

• Explanation: Defines a main function that takes two string arguments and returns a dictionary with the concatenated result.

JavaScript Example

const axios = require('axios');
async function main(args) {
  try {
    const response = await axios.get('https://github.com/infiniflow/ragflow');
    console.log('Body:', response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

• Explanation: An async function main that performs an HTTP GET request using axios and logs the response.

3. Return Values

• Purpose: Define output variables so that the Agent can consume the results of your code execution.

• Behavior: After successful execution, output variables are auto-populated with your code's returned data.

4. Output

• Automatically populated based on the return values defined.

Prerequisites and Environment Setup

The Code component depends on a secure and isolated execution environment, which requires proper installation and configuration of:

1. gVisor: An isolation layer to sandbox container runtimes, protecting the host system.

2. RAGFlow Sandbox: A pluggable backend that executes the code safely within containers.

3. Additional Dependencies (Optional): If your code requires extra Python or JavaScript packages, they must be installed in the Sandbox images.

4. RAGFlow Configuration: Ensure sandbox-specific settings are enabled in the .env file.

5. Service Restart: Any configuration changes require restarting the RAGFlow services.

Troubleshooting Common Issues

Frequently Asked Questions

How to Import My Own Python or JavaScript Packages Into Sandbox?

For Python:

1. Navigate to the Sandbox directory.

2. Append your package (e.g., openpyxl) to sandbox_base_image/python/requirements.txt.

3. Rebuild the image using make (or make build for build-only).

4. Enter the container and verify installation via Python import.

For JavaScript:

1. Navigate to sandbox_base_image/nodejs.

2. Use npm install <package> to add packages (e.g., lodash).

3. Rebuild the image using make.

4. Enter the container and verify via npm list <package> or by checking node_modules.

Implementation Details and Algorithms

• Sandboxed Execution: The component delegates code execution to isolated containers managed by RAGFlow Sandbox, which uses gVisor for enhanced security.

• Input/Output Mapping: Inputs defined in the Agent UI are passed as parameters or argument objects to the user code. The return value(s) from the code execution are mapped back to output variables for downstream consumption.

• Language Support: Both Python and JavaScript runtimes are supported with pre-configured base images. Users can extend functionality by installing additional packages into these images.

• Error Handling: Users should implement their own error handling within code snippets. The sandbox environment captures and reports runtime errors without affecting the host or Agent stability.

Interaction with Other System Components

• The Code component communicates with RAGFlow Sandbox, which manages containerized execution of user code.

• gVisor acts as a low-level sandboxing mechanism ensuring container isolation.

• The component is integrated into the Agent workflow, receiving inputs from prior components and passing outputs downstream.

• Configuration changes in the .env file within the ragflow/docker directory affect how the sandbox and Code component behave.

• Logs and execution results can be monitored via standard Agent or Sandbox logging facilities.

Visual Diagram

flowchart TD
    A[Agent Workflow] --> B[Code Component]
    B --> C[RAGFlow Sandbox Executor]
    C --> D[gVisor Isolation Layer]
    D --> E[Container Runtime (Docker)]
    E --> F[Python / JavaScript Runtime]
    F --> G[User Code Execution]
    G --> F
    F --> C
    C --> B
    B --> H[Output Variables]

Diagram Explanation:

• The Agent workflow triggers the Code component.

• The Code component sends code and inputs to the RAGFlow Sandbox Executor.

• The Sandbox Executor runs code inside containers isolated by gVisor.

• Containers run either Python or JavaScript runtimes.

• User code executes and returns results back through the chain, to be consumed by subsequent Agent components.

Usage Example

Suppose you want to concatenate two strings in Python:

1. Add input variables: arg1, arg2.

2. Enter the following code in the code editor:

def main(arg1: str, arg2: str) -> dict:
    return {"result": arg1 + arg2}

3. Define the output variable result.

4. Run the Agent workflow. The output variable result will contain the concatenated string.

This example demonstrates how simple it is to embed custom logic securely and flexibly into your Agent workflows.

Summary

The code.mdx file documents the Code component, a powerful extension point within the Agent framework for running custom Python or JavaScript code securely inside sandboxed containers. It guides users through setup, configuration, troubleshooting, and extending runtime environments with additional packages, enabling complex and dynamic data processing capabilities.