Go Agent Port

Relevant source files

• internal/agent/canvas/loop_subgraph.go
• internal/agent/canvas/node_body.go
• internal/agent/canvas/scheduler.go
• internal/agent/component/agent.go
• internal/agent/component/agent_test.go
• internal/agent/component/fixture_stubs.go
• internal/agent/component/invoke.go
• internal/agent/component/invoke_test.go
• internal/agent/component/llm.go
• internal/agent/component/message.go
• internal/agent/component/message_test.go
• internal/agent/component/production_chain_fixes_test.go
• internal/agent/component/tool_component_test.go
• internal/agent/component/universe_a_wrappers.go
• internal/agent/component/verify_p1_test.go
• internal/agent/dsl/errors.go
• internal/agent/dsl/extract.go
• internal/agent/dsl/extract_test.go
• internal/agent/runtime/context.go
• internal/agent/runtime/context_test.go
• internal/agent/runtime/state.go
• internal/agent/runtime/state_test.go
• internal/agent/sandbox/self_managed.go
• internal/agent/tool/arxiv.go
• internal/agent/tool/arxiv_test.go
• internal/agent/tool/email.go
• internal/agent/tool/github.go
• internal/agent/tool/github_test.go
• internal/agent/tool/google_scholar.go
• internal/agent/tool/google_scholar_test.go
• internal/agent/tool/keenable.go
• internal/agent/tool/keenable_test.go
• internal/agent/tool/pubmed.go
• internal/agent/tool/pubmed_test.go
• internal/agent/tool/registry.go
• internal/agent/tool/registry_test.go
• internal/agent/tool/wikipedia.go
• internal/agent/tool/wikipedia_test.go
• internal/agent/tool/yahoo_finance.go
• internal/agent/tool/yahoo_finance_test.go
• internal/dao/user_canvas.go
• internal/dao/user_canvas_test.go
• internal/entity/api_token.go
• internal/entity/models/llm.go
• internal/entity/models/llm_test.go
• internal/handler/agent.go
• internal/handler/agent_component.go
• internal/handler/agent_component_test.go
• internal/handler/agent_test.go
• internal/handler/agent_wait_for_user_test.go
• internal/handler/auth.go
• internal/handler/bot.go
• internal/handler/bot_test.go
• internal/harness/core/interrupt.go
• internal/router/agent_routes.go
• internal/service/agent.go
• internal/service/agent_run_e2e_test.go
• internal/service/agent_test.go
• internal/service/bot.go
• internal/service/bot_completion.go
• internal/service/bot_completion_history_test.go
• internal/service/chat_pipeline_test.go
• internal/service/think_tag.go
• internal/service/think_tag_test.go

The Go Agent Port is a high-performance, native reimplementation of the RAGFlow agent canvas system. Built using the eino framework, it transitions workflow execution from Python interpretation to a Go-native graph orchestration model. This port includes a DSL (Domain Specific Language) conversion layer, a concurrent runtime state manager, and a comprehensive registry of tools and components.

High-Level Architecture

The Go Agent system provides a native scheduler that handles the complex topology of agent workflows, including parallel execution and loops. It leverages the eino framework for graph construction and the internal/harness package for stateful multi-agent capabilities.

System Topology Diagram

The following diagram bridges the Natural Language Space (User Concepts) to the Code Entity Space (Go Implementation).

Title: Go Agent Runtime Architecture

Sources: internal/service/agent.go35-44 internal/agent/component/universe_a_wrappers.go17-31 internal/agent/runtime/state.go1-20

DSL and Schema Management

The system supports two versions of the Agent DSL. The Go port includes a converter to ensure backward compatibility with canvases created in the Python-based editor.

• DSL v1: Legacy format used by the initial Python implementation.
• DSL v2: Optimized format for graph-based execution in Go.
• Converter: Located in internal/agent/dsl/, it transforms entity.JSONMap structures into executable graph definitions. The AgentService uses dslpkg to handle these transformations during the Compile and Run phases internal/service/agent.go44

Sources: internal/handler/agent.go40-41 internal/service/agent.go44

Canvas Scheduler and Topology

The internal/agent/canvas/ package contains the core logic for building the execution graph and scheduling nodes using the eino framework.

Key Functions and Extensions

• Runner: The canvas.Runner internal/agent/canvas/scheduler.go1-30 manages the lifecycle of a workflow run, producing SSE events for the frontend.
• Scheduler: Implements the eino-based scheduling logic, handling the transition between nodes internal/agent/canvas/scheduler.go1-30
• Workflow Extensions: The system uses workflowx to handle complex control flows like loops and parallel node execution. The Go port collapses the Python-era LoopItem into the workflowx.AddLoopNode wrapper internal/agent/canvas/loop_subgraph.go1-30
• Streaming: Supports real-time delta emission for thinking and content, handled by agentMessageDeltaEmitter to support <think> tag protocols internal/service/agent.go99-112

Sources: internal/service/agent.go99-189 internal/agent/canvas/scheduler.go1-30 internal/agent/canvas/loop_subgraph.go1-30

Component and Tool Registry

The Go port implements a modular registry system for components and tools, allowing for dynamic instantiation based on DSL definitions.

Component Registry (internal/agent/component/)

Components are the primary building blocks of the canvas. The registry handles P0 and P1 components including agent, begin, llm, retrieval, and switch internal/agent/component/verify_p1_test.go33-38

• Agent Component: A multi-turn ReAct agent powered by eino/flow/agent/react internal/agent/component/agent.go2-7 It supports citation grounding via Cite internal/agent/component/agent.go98-104 and history optimization internal/agent/component/agent.go91-92
• Message Component: The terminal output node. It handles Jinja2 template resolution, TTS (audio) synthesis, and memory persistence internal/agent/component/message.go45-59
• Universe A Wrappers: Specialized adapters for Retrieval and CodeExec that bridge the canvas-facing Component interface to underlying tools internal/agent/component/universe_a_wrappers.go17-25
• Fixture Stubs: For testing, the system provides stubs (e.g., RetrievalStub, TavilySearchStub, ExeSQLStub) that echo stable outputs without requiring network or DB access internal/agent/component/fixture_stubs.go48-180

Tool Registry (internal/agent/tool/)

The tool registry internal/agent/tool/registry.go33-68 manages 20+ built-in tools:

• Search: google, duckduckgo, arxiv, wikipedia, searxng, tavily internal/agent/tool/registry.go35-62
• Finance/Data: akshare, yahoo_finance, tushare, jin10 internal/agent/tool/registry.go34-63
• Execution: execute_sql (alias exesql) and code_exec internal/agent/tool/registry.go37-43

Sources: internal/agent/component/agent.go68-131 internal/agent/component/message.go31-59 internal/agent/tool/registry.go33-68 internal/agent/component/verify_p1_test.go33-38

Runtime State Management

The CanvasState in internal/agent/runtime/ manages variable resolution and execution context during a workflow run.

Entity	Role	Source
runtime.CanvasState	Thread-safe storage for workflow variables using RWMutex.	internal/agent/runtime/state.go1-20
ResolveTemplateForDisplay	Resolves Jinja2-style templates for UI display.	internal/agent/component/message.go186-187
RunEvent	Event channel for streaming execution updates to the client.	internal/service/agent.go85-86

Sources: internal/agent/runtime/state.go1-20 internal/agent/component/message.go166-187 internal/service/agent.go83-86

Phased Migration and API Handling

The Go AgentHandler mirrors the Python API logic, providing endpoints for canvas management and execution while maintaining a hybrid proxy scheme.

Title: Agent API Interaction

Sources: internal/handler/agent.go130-199 internal/service/agent.go67-90

Key Implementation Details

• IDOR Protection: AgentHandler uses AgentService.loadCanvasForUser (via LoadCanvasByID) to ensure users can only access authorized agent resources, mirroring the Python UserCanvasService.get_by_id logic internal/service/agent.go67-72
• Error Normalization: mapAgentError normalizes service-layer errors (e.g., ErrUserCanvasNotFound) into the standard {code, data, message} response envelope used by the frontend internal/handler/agent.go201-208
• Webhook Support: RunAgentWithWebhook allows external payloads to be injected into the Begin component via the execution context as state.Sys["webhook_payload"] internal/service/agent.go73-82
• File Handling: agentFileService handles file uploads and URL-based downloads for agent context internal/handler/agent.go49-59
• SSE Response Logic: WriteChatbotFrame and WriteChatbotRunEvent translate internal RunEvent objects into Python-compatible SSE envelopes for the iframe SDK and frontend React components internal/service/bot_completion.go98-162 internal/service/bot_completion.go181-197

Sources: internal/handler/agent.go49-59 internal/handler/agent.go201-208 internal/service/agent.go67-90 internal/service/bot_completion.go98-197