Agent and Workflow System

Relevant source files

• agent/canvas.py
• agent/component/agent_with_tools.py
• agent/component/base.py
• agent/component/categorize.py
• agent/component/llm.py
• agent/component/message.py
• agent/tools/base.py
• common/mcp_tool_call_conn.py
• internal/agent/component/llm.go
• internal/dao/user_canvas.go
• internal/dao/user_canvas_test.go
• internal/entity/api_token.go
• internal/handler/agent.go
• internal/handler/agent_test.go
• internal/handler/agent_wait_for_user_test.go
• internal/service/agent.go
• internal/service/agent_run_e2e_test.go
• internal/service/agent_test.go
• rag/prompts/generator.py

The Agent and Workflow System provides a visual programming environment for creating AI-powered workflows and autonomous agents. It implements a graph-based execution engine that orchestrates component pipelines, manages conversational state, and enables multi-step reasoning with tool use. This system bridges visual workflow design with backend execution through a Domain-Specific Language (DSL).

This system is implemented in both Python (the primary engine) and a Go port using the eino framework for high-performance scheduling and workflow execution. The Go port provides a native, efficient execution environment for agents, leveraging Go's concurrency features.

For information about LLM integration and model management, see LLM Integration System. For details about the REST API layer, see Backend API System.

Canvas DSL and Graph Model

The workflow system is built on a JSON-based DSL that represents workflows as directed graphs with support for loops and branching. Each workflow is called a "canvas" and is stored as a serialized DSL document.

DSL Structure

The DSL consists of components, history, and global state. The Graph class in agent/canvas.py is the primary entity responsible for parsing this structure agent/canvas.py48-87 The frontend represents this visually using a collection of nodes (e.g., beginNode, retrievalNode) and edges.

Components Section: Each component contains:

• obj: Component configuration with component_name and params agent/canvas.py53-56
• downstream: Array of component IDs to execute next agent/canvas.py57
• upstream: Array of component IDs that precede this component agent/canvas.py58

For a detailed explanation of the DSL structure and its evolution, see Canvas Engine and DSL.

Sources: agent/canvas.py48-87

Graph Class Architecture

The Graph class agent/canvas.py48 provides the foundation for DSL-based execution. It parses the DSL using normalize_chunker_dsl agent/canvas.py94 instantiates component objects via component_class agent/canvas.py104-114 and manages the execution path.

Graph-to-Code Mapping:

Sources: agent/canvas.py48-114 internal/service/agent.go36-46

Component System Architecture

Components are the building blocks of workflows. The system uses a factory pattern for dynamic component registration and parameter validation.

Component Base Classes

Component Entity Space:

ComponentParamBase agent/component/base.py43-54:

• Defines parameters with validation.
• Implements recursive configuration updates update() agent/component/base.py136-186
• Handles max_retries and delay_after_error for execution resilience agent/component/base.py49-50

ComponentBase [agent/component/base.py:28] (referenced in agent/canvas.py:31):

• Provides lifecycle methods and context management.
• Implements variable resolution and I/O management via set_output() and get_input().

For a detailed look at the component architecture, including the factory pattern and dynamic registration, see Component System Architecture.

Sources: agent/component/base.py43-186 agent/canvas.py30-31 agent/component/llm.py86

State and Variable Management

The Canvas maintains multiple levels of state and provides a variable resolution system. This system allows components to access global variables, environment variables, and outputs from other components.

Variable System

Variable Types:

• sys.*: System variables (query, user_id, conversation_turns, files, history, date).
• env.*: User-defined workflow variables.
• component_id@output_key: Reference to specific component outputs.

The variable resolution logic handles both system globals and inter-component references. The Message component resolves these via get_kwargs agent/component/message.py153-180 and _stringify_message_value agent/component/message.py103-143

Variable Resolution Flow

Python Variable Resolution:

• If the expression is sys.* or env.*, it looks up the value in the globals dictionary agent/canvas.py80-86
• Components use string_format to resolve variables within prompts agent/component/llm.py129-134
• Message component supports streaming resolution via _stream() agent/component/message.py188-220

Go Variable Resolution:

• Managed by CanvasState in internal/agent/runtime/state.go with concurrent RWMutex design.

For more in-depth information on state management and variable resolution, see State and Variable Management.

Sources: agent/canvas.py80-86 agent/component/message.py103-180 agent/component/llm.py129-134

Agent Components and ReAct Loop

The Agent component implements the ReAct (Reasoning + Acting) pattern for autonomous multi-step task execution with tool use. This allows agents to dynamically decide which tools to use based on the current task and context.

Agent Implementation

Agent Component agent/component/agent_with_tools.py74-75:

• Inherits from LLM agent/component/llm.py86 and ToolBase agent/tools/base.py29
• Loads tool components using _load_tool_obj() agent/component/agent_with_tools.py136-148
• Binds tools to the LLMBundle for model-driven tool calling agent/component/agent_with_tools.py114-116
• Supports MCP (Model Context Protocol) tool integration via MCPServerService agent/component/agent_with_tools.py104-112

Tool Calling Infrastructure:

• LLMToolPluginCallSession agent/tools/base.py50-51: Manages the execution session for tool plugins.
• MCPToolCallSession agent/component/agent_with_tools.py107: Handles connections to external MCP servers.
• AgentParam: Defines metadata for the agent, including max_rounds for the ReAct loop agent/component/agent_with_tools.py45-72

For a comprehensive overview of the Agent component, ReAct loop, and tool system, see Agent Tools and ReAct Loop.

Sources: agent/component/agent_with_tools.py45-148 agent/tools/base.py50-92 agent/component/llm.py86

Workflow Execution and Streaming

The execution engine processes components while supporting dynamic branching and streaming responses. This ensures a responsive user experience, especially for long-running LLM operations.

• Message Streaming: The Message component supports asynchronous generation using _stream() agent/component/message.py188 yielding content chunks as variables are resolved.
• Prompt Generation: The system formats retrieved knowledge using kb_prompt rag/prompts/generator.py139 to inject context into LLM prompts, ensuring they fit within token limits via message_fit_in rag/prompts/generator.py69
• Dynamic Branching: The Categorize component agent/component/categorize.py90 uses LLM classification to determine the next execution path via the _next output agent/component/categorize.py150
• Task Cancellation: Execution state is monitored for cancellation signals via has_canceled agent/canvas.py36 Components check this status frequently during long-running tasks agent/component/categorize.py102
• Go Execution: The Go port uses emitAgentMessageEvents internal/service/agent.go93 and agentMessageDeltaEmitter internal/service/agent.go100 to handle thinking protocols and SSE event generation.

For detailed information on how workflows are executed and how streaming is handled, see Workflow Execution and Streaming.

Sources: agent/component/message.py188 rag/prompts/generator.py69-139 agent/component/categorize.py90-150 agent/canvas.py36 internal/service/agent.go93-163

Child Pages

• Canvas Engine and DSL — Document the Canvas class, DSL structure (v1 and v2 schemas), graph-based execution model, and how workflows are stored and loaded. Covers both the Python canvas.py and the Go-native DSL package (internal/agent/dsl/) with v1/v2 converter.
• Component System Architecture — Explain the component base classes, parameter validation, the component factory pattern, and dynamic registration in both Python (agent/component/) and Go (internal/agent/component/).
• Built-in Components — Document the standard component library including LLM, Retrieval, Tool, Categorize, Generate, Message, Switch, Iteration, and Agent components.
• Workflow Execution and Streaming — Explain the path-based execution algorithm, streaming support, SSE event generation during workflow runs, and the eino-based Go scheduler (internal/agent/canvas/scheduler.go) with workflowx loop/parallel extensions.
• State and Variable Management — Document the variable resolution system (sys.*, env.*, component@output), global state management, and context handling. Covers both Python canvas state and the Go CanvasState (internal/agent/runtime/state.go) with its concurrent RWMutex design.
• Agent Tools and ReAct Loop — Explain the Agent component's ReAct pattern, tool calling mechanism, MCP integration, multi-step reasoning, the plugin system for custom LLM tools, and the Go tool registry (internal/agent/tool/) with 20+ built-in tools (arxiv, duckduckgo, code_exec, retrieval, exesql, etc.).
• Canvas API and Management — Detail the canvas CRUD endpoints, version management, replica system, conversation session handling, and agent templates.