agent.ts

Overview

The agent.ts file defines TypeScript interfaces and type aliases that model the data structures for a complex flow-based system, likely related to AI agent workflows, DSL (Domain Specific Language) components, and conversational or task automation flows. This file primarily contains type definitions for various nodes, forms, and graph representations used in the system, focusing on configuration, flow control, agent logs, and interaction with components.

These types enable strongly-typed development of components interacting with AI agents, switch conditions, categorization items, retrieval processes, code execution, and agent prompts, among others. They serve as a foundational contract for the system's data flow, facilitating flow construction, execution, and logging.

Detailed Descriptions

Interfaces and Types

1. ICategorizeItem

Represents an item that can be categorized within the system.

• Properties:

  • name: string — Name of the categorize item.

  • description?: string — Optional description of the item.

  • examples?: { value: string }[] — Optional array of example values.

  • index: number — Index position in a list or order.

  • to: string[] — Array of string identifiers indicating next nodes or targets.

  • uuid: string — Unique identifier.

Usage Example:

const categoryItem: ICategorizeItem = {
  name: "Urgent",
  index: 1,
  to: ["node_2"],
  uuid: "abc-123"
};

2. ICategorizeItemResult

A mapped record keyed by string, representing categorize items but omitting name, examples, and uuid fields from ICategorizeItem. The examples property here is simplified to an array of strings.

• Type: Record<string, Omit<ICategorizeItem, 'name' | 'examples' | 'uuid'> & { examples: string[] }>

This type is used to represent processed categorize results keyed by some identifier.

3. ISwitchCondition, ISwitchItem, and ISwitchForm

These interfaces model conditional branching logic within flows.

• ISwitchItem

  • cpn_id: string — Component ID to evaluate.

  • operator: string — Operator used for condition (e.g., ==, >, <).

  • value: string — Value for comparison.

• ISwitchCondition

  • items: ISwitchItem[] — List of conditions.

  • logical_operator: string — Logical operator to combine items (AND, OR).

  • to: string[] — Target nodes if condition is met.

• ISwitchForm

  • conditions: ISwitchCondition[] — List of switch conditions.

  • end_cpn_ids: string[] — Component IDs considered terminal or endpoints.

  • no: string — Default target if no conditions match.

4. DSL, DSLComponents, IOperator, and IOperatorNode

These interfaces describe the Domain Specific Language (DSL) structure used to define flows and operators in the system.

• DSLComponents
  A mapping from string keys to IOperator objects.

• IOperator
  Represents a node/operator in the flow:

  • obj: IOperatorNode — The operator node data.

  • downstream: string[] — IDs of downstream operators.

  • upstream: string[] — IDs of upstream operators.

  • parent_id?: string — Optional parent operator ID.

• IOperatorNode
  Details of the operator:

  • component_name: string — Name/type of the component.

  • params: Record<string, unknown> — Parameters for the operator.

• DSL
  The overall DSL data structure:

  • components: DSLComponents — Collection of operators.

  • history: any[] — History of changes or executions.

  • path?: string[] — Optional path the flow takes.

  • answer?: any[] — Optional answers or results.

  • graph?: IGraph — Graph representation of the flow.

  • messages?: Message[] — Conversation or system messages.

  • reference?: IReference[] — References used.

  • globals: Record<string, any> — Global variables.

  • retrieval: IReference[] — Retrieval references.

5. IFlow and IFlowTemplate

Represent a flow and its template in the system.

• IFlow
  Contains metadata and the DSL describing the flow:

  • avatar?: string — Optional avatar image.

  • canvas_type: null — Type of canvas (null here).

  • create_date, update_date: string — Dates.

  • create_time, update_time: number — Timestamps.

  • description: null

  • dsl: DSL — The DSL data.

  • id: string — Flow identifier.

  • title: string — Flow title.

  • user_id: string — Owner user ID.

  • permission: string — Permission level.

  • nickname: string — User nickname.

  • operator_permission: number — Permission related to operators.

• IFlowTemplate
  Similar to IFlow, but used as a template with minor differences.

6. Various Form Interfaces

These interfaces define the forms for different operators in the flow.

• IGenerateForm
  Parameters for generation-based operators, such as LLM prompts.

  • max_tokens?: number — Max tokens for generation.

  • temperature?: number — Sampling temperature.

  • top_p?: number

  • presence_penalty?: number

  • frequency_penalty?: number

  • cite?: boolean — Whether to cite sources.

  • prompt: number — Enum or ID for prompt type.

  • llm_id: string — Language model ID.

  • parameters: { key: string; component_id: string } — Parameters linking to components.

• ICategorizeForm extends IGenerateForm
  Adds:

  • category_description: ICategorizeItemResult — Category descriptions.

  • items: ICategorizeItem[] — Items to categorize.

• IRelevantForm extends IGenerateForm
  Adds:

  • yes: string and no: string — Responses for relevance.

• ISwitchForm
  Defines switch logic (duplicated interface in the file; the second overrides the first):

  • conditions: ISwitchCondition[]

  • end_cpn_id: string

  • no: string

• IBeginForm

  • prologue?: string — Optional introductory text.

• IRetrievalForm
  Parameters for retrieval operations.

  • similarity_threshold?: number

  • keywords_similarity_weight?: number

  • top_n?: number

  • top_k?: number

  • rerank_id?: string

  • empty_response?: string

  • kb_ids: string[] — Knowledge base IDs.

• ICodeForm
  For code execution:

  • arguments: Record<string, string>

  • lang: string — Programming language.

  • script?: string

  • outputs: Record<string, { value: string; type: string }> — Output variables and types.

• IAgentForm
  Complex agent configuration form:

  • sys_prompt: string — System prompt text.

  • prompts: Array<{ role: string; content: string }> — Conversation prompts.

  • max_retries: number

  • delay_after_error: number

  • visual_files_var: string

  • max_rounds: number

  • exception_method: Nullable<'comment' | 'go'> — Exception handling method.

  • exception_comment: any

  • exception_goto: any

  • tools: Array<{ name: string; component_name: string; params: Record<string, any> }> — Tools used by the agent.

  • mcp: Array<{ mcp_id: string; tools: Record<string, Record<string, any>> }> — MCP (Multi-Component Processor?) configurations.

  • outputs: { structured_output: Record<string, Record<string, any>>; content: Record<string, any> } — Output data.

7. Node Data and Node Types

• BaseNodeData<TForm>
  Generic node data structure with:

  • label: string — Operator type label.

  • name: string — Operator name.

  • color?: string — Optional color for UI.

  • form?: TForm — Optional form data.

• BaseNode<T>
  Extends Node from @xyflow/react, wrapping BaseNodeData<T>.

• Specific node type aliases (e.g., IBeginNode, IRetrievalNode, IGenerateNode, etc.)
  These are specializations of BaseNode with respective form types.

• RAGFlowNodeType
  Union type of all relevant node types used in the flow graph.

8. Graph and Trace Interfaces

• IGraph
  Represents the flow graph:

  • nodes: RAGFlowNodeType[] — List of nodes.

  • edges: Edge[] — List of edges (connections), using Edge type imported from @xyflow/react.

• ITraceData
  Trace data for components:

  • component_id: string — Component identifier.

  • trace: Array<Record<string, any>> — Array of trace objects.

9. Agent Logs Interfaces

• IAgentLogMessage
  Represents a message in an agent log:

  • content: string — Message content.

  • role: 'user' | 'assistant' — Message role.

  • id: string — Unique message ID.

• IAgentLogResponse
  Represents a full agent log session:

  • id: string

  • message: IAgentLogMessage[]

  • update_date, create_date: string

  • update_time, create_time: number

  • round: number — Conversation round count.

  • thumb_up: number — Likes or positive feedback.

  • errors: string — Error messages.

  • source: string — Source identifier.

  • user_id: string

  • dsl: string — DSL data as string.

  • reference: IReference

• IAgentLogsResponse
  Response containing multiple sessions:

  • total: number

  • sessions: IAgentLogResponse[]

• IAgentLogsRequest
  Request parameters for querying logs:

  • Optional filters: keywords, to_date, from_date, orderby, desc, page, page_size.

Important Implementation Details

• Type Safety for Flows and Components:
  This file provides strongly typed interfaces to guarantee consistency when constructing, manipulating, and executing flow graphs involving AI agents and other components.

• DSL-Centric Design:
  The DSL interfaces (DSL, IOperator, etc.) encapsulate the flow logic, operators, and their relationships, centralizing flow structure.

• Node Abstraction:
  Nodes are abstracted as generic base types (BaseNode) with customizable forms, allowing flexible extension for different operator types.

• Agent Configuration:
  The comprehensive IAgentForm interface encapsulates various runtime parameters for agent execution, including error handling, retry logic, and tool integrations.

• Graph Model Integration:
  The graph structure (IGraph) uses nodes and edges from @xyflow/react, implying visual or interactive flow canvas integration.

• Logging and Tracing:
  The agent logging interfaces support detailed traceability of agent interactions for debugging or audit purposes.

Interaction with Other System Parts

• @xyflow/react
  The Node and Edge types are imported from the @xyflow/react package, indicating that this file integrates with a React-based flow visualization or editor component.

• ./chat
  Imports Message and IReference from a chat module, showing dependency on chat or conversational data structures.

• Flow Execution and UI:
  The types here are likely consumed by both the backend (flow execution engine) and the frontend (visual flow editor and UI), enabling seamless data exchange.

• Agent Runtime:
  Forms like IAgentForm specify runtime parameters for AI agents, suggesting integration with AI model services.

• Logging System:
  The logging interfaces indicate that this module interacts with a logging or monitoring system for agent activity.

Usage Examples

Defining a Switch Condition

const condition: ISwitchCondition = {
  items: [
    { cpn_id: "comp1", operator: "==", value: "yes" },
    { cpn_id: "comp2", operator: ">", value: "10" }
  ],
  logical_operator: "AND",
  to: ["next_node"]
};

Constructing a Generate Node

const generateNode: IGenerateNode = {
  id: "node1",
  data: {
    label: "Generate",
    name: "Text Generation",
    form: {
      max_tokens: 100,
      temperature: 0.7,
      prompt: 1,
      llm_id: "gpt-4",
      parameters: { key: "input", component_id: "comp1" }
    }
  },
  position: { x: 0, y: 0 }
};

Building a Flow Graph

const graph: IGraph = {
  nodes: [generateNode /*, other nodes */],
  edges: [{ id: "e1", source: "node1", target: "node2" }]
};

Mermaid Diagram: Class Diagram of Key Interfaces

classDiagram
    class ICategorizeItem {
        +string name
        +string description?
        +Array~{value: string} examples?
        +number index
        +string[] to
        +string uuid
    }

    class ISwitchItem {
        +string cpn_id
        +string operator
        +string value
    }

    class ISwitchCondition {
        +ISwitchItem[] items
        +string logical_operator
        +string[] to
    }

    class ISwitchForm {
        +ISwitchCondition[] conditions
        +string[] end_cpn_ids
        +string no
    }

    class IOperatorNode {
        +string component_name
        +Record~string, unknown~ params
    }

    class IOperator {
        +IOperatorNode obj
        +string[] downstream
        +string[] upstream
        +string parent_id?
    }

    class DSL {
        +DSLComponents components
        +any[] history
        +string[] path?
        +any[] answer?
        +IGraph graph?
        +Message[] messages?
        +IReference[] reference?
        +Record~string, any~ globals
        +IReference[] retrieval
    }

    class IAgentForm {
        +string sys_prompt
        +Array~{role: string, content: string} prompts
        +number max_retries
        +number delay_after_error
        +string visual_files_var
        +number max_rounds
        +Nullable~'comment' | 'go'~ exception_method
        +any exception_comment
        +any exception_goto
        +Array~{name: string, component_name: string, params: Record~string, any~} tools
        +Array~{mcp_id: string, tools: Record~string, Record~string, any~~} mcp
        +{structured_output: Record~string, Record~string, any~~, content: Record~string, any~} outputs
    }

    ICategorizeItemResult <|-- ICategorizeItem
    ISwitchForm --> ISwitchCondition
    ISwitchCondition --> ISwitchItem
    IOperator --> IOperatorNode
    DSL --> IOperator
    IAgentForm --> DSL

Summary

The agent.ts file is a foundational TypeScript module that defines the data models for an AI agent flow system. It includes interfaces for categorization, conditional branching, DSL components, flow templates, various operator forms, graph structures, and agent logs. These definitions facilitate consistent flow construction, execution, and monitoring in an interactive AI workflow platform, likely integrated with React UI components and conversational AI services.

This file does not include executable logic but provides the critical types that power the system's flow definition, validation, and runtime configuration.

End of Documentation