Go Harness Agent Framework

Relevant source files

• go.mod
• go.sum
• 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/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/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/common/error_code.go
• internal/dao/user_canvas.go
• internal/dao/user_canvas_test.go
• internal/engine/infinity/chunk.go
• internal/engine/infinity/client.go
• internal/engine/infinity/client_test.go
• internal/engine/infinity/common.go
• internal/engine/infinity/document.go
• internal/engine/infinity/metadata.go
• internal/entity/api_token.go
• internal/handler/agent.go
• internal/handler/agent_test.go
• internal/handler/agent_wait_for_user_test.go
• internal/harness/core/interrupt.go
• internal/service/agent.go
• internal/service/agent_run_e2e_test.go
• internal/service/agent_test.go

The internal/harness package in RAGFlow provides a standalone Go framework for building stateful multi-agent applications. This framework underpins the Go agent port, enabling advanced behaviors like ReAct reasoning loops, sub-agent delegation, human-in-the-loop interrupts, and persistent checkpointing.

Three-Layer Architecture

The framework is structured into three layers that bridge the gap between low-level graph execution and high-level chat interactions.

Layer 1: Graph Engine

This foundational layer provides the core execution environment for agent workflows, utilizing a graph-based model for state transitions.

• Pregel BSP Execution: The engine uses a Bulk Synchronous Parallel model. Computation proceeds in supersteps where nodes process inputs and write to channels for the next superstep. This is implemented via the eino framework's compose package internal/agent/canvas/scheduler.go32
• StateGraph Builder: Workflows are constructed as directed graphs using a StateGraph pattern. Nodes represent components (e.g., LLM, Retrieval), and edges represent the execution path internal/agent/canvas/scheduler.go32
• Checkpointing: Stateful execution is supported through persistent state management. The CanvasState can be serialized and managed concurrently using an RWMutex to ensure consistency across execution steps internal/agent/runtime/state.go1-50

Sources:

• internal/agent/canvas/scheduler.go32
• internal/agent/runtime/state.go1-50

Layer 2: AgentCore ADK

The Agent Development Kit (ADK) provides high-level abstractions for agent logic and tool orchestration.

• ReActAgent: Implemented via specialized components, this provides a multi-turn "Reasoning and Acting" loop. It handles model calls, tool selection, and observation gathering internal/agent/component/llm.go1-11
• Tool Registry: A centralized factory for resolving tool names into executable instances. It supports over 20 built-in tools including arxiv, duckduckgo, code_exec, and exesql internal/agent/tool/registry.go33-68
• Workflow Orchestration: Complex DSL structures (like loops and parallel nodes) are expanded into sub-graphs. The scheduler handles the orchestration of these components, including parallelNode and Iteration types internal/handler/agent_test.go224-230

Sources:

• internal/agent/component/llm.go1-11
• internal/agent/tool/registry.go33-68
• internal/handler/agent_test.go224-230

Layer 3: Push-based AgentLoop

The topmost layer handles real-time interaction, streaming, and external event mapping.

• AgentLoop: Manages the lifecycle of a chat session. It consumes user input, triggers the graph engine via RunAgent, and pushes events (messages, thinking deltas, or errors) back to the client internal/service/agent.go84-91
• Streaming & Thinking Protocol: Supports streaming "thinking" steps (reasoning) separately from the final answer. The agentMessageDeltaEmitter handles the emission of content and thinking deltas, including the parsing of <think> tags internal/service/agent.go100-113

Sources:

• internal/service/agent.go84-91
• internal/service/agent.go100-113

System Data Flow

The following diagram illustrates how a user request traverses the framework layers to trigger specific code entities.

Diagram: Request Flow through Harness Layers

Sources:

• internal/service/agent.go84-91
• internal/service/agent.go149-163
• internal/agent/component/llm.go36-39
• internal/agent/tool/registry.go80-93
• internal/agent/runtime/state.go1-50

Tool Integration and Registry

Tools are the primary way agents interact with the outside world. The internal/agent/tool package provides a unified interface for tool registration and invocation.

Registry Mechanism

The registry.go file maintains a map of Factory functions. Each factory captures node-level configuration (like API keys or search limits) and returns an einotool.BaseTool internal/agent/tool/registry.go31-33

Tool Name	Factory Function	Key Features
retrieval	buildRetrievalTool	Knowledge base search with similarity thresholds internal/agent/tool/registry.go52
code_exec	NewCodeExecTool	Sandbox execution for Python/JS internal/agent/tool/registry.go37
arxiv	buildArxivTool	Academic paper search with sort/top_n params internal/agent/tool/registry.go35
execute_sql	buildExeSQLTool	Secure SQL execution against registered DBs internal/agent/tool/registry.go42
email	buildEmailTool	SMTP integration for sending notifications internal/agent/tool/registry.go41
keenable	buildKeenableTool	Keenable API integration internal/agent/tool/registry.go49
github	buildGitHubTool	GitHub API integration internal/agent/tool/registry.go44
pubmed	buildPubMedTool	PubMed search internal/agent/tool/registry.go50
wikipedia	buildWikipediaTool	Wikipedia search internal/agent/tool/registry.go65
google_scholar	buildGoogleScholarTool	Google Scholar search internal/agent/tool/registry.go46
yahoo_finance	buildYahooFinanceTool	Yahoo Finance data retrieval internal/agent/tool/registry.go67

Component Wrappers

To make tools available on the agent canvas, they are wrapped in Component interfaces. For example, retrievalComponent applies DSL-level defaults (like kb_ids) before calling the underlying RetrievalTool internal/agent/component/universe_a_wrappers.go126-138

Diagram: Tool Registry and Adapter Architecture

Sources:

• internal/agent/tool/registry.go33-68
• internal/agent/tool/registry.go80-93
• internal/agent/component/universe_a_wrappers.go126-138
• internal/agent/component/universe_a_wrappers.go167-183

Core Framework Components

The framework includes several specialized components that handle logic and output:

• Retrieval Component: Delegates to the RetrievalTool while handling legacy input patterns (like UserFillUp) and merging node-level parameters with runtime inputs internal/agent/component/universe_a_wrappers.go126-140
• LLM Component: A standard wrapper for single-turn model calls. It manages system/user prompts, model parameters (temperature, top_p), and supports reasoning modes like "thinking" internal/agent/component/llm.go36-100
• Interrupt & Human-in-the-loop: The framework supports execution interrupts, allowing agents to pause for user confirmation or input before proceeding internal/harness/core/interrupt.go1-15

State Management

The CanvasState is the source of truth during execution. It stores component outputs, user inputs, and global variables. The framework ensures thread-safe access to this state during the asynchronous execution of the graph internal/agent/runtime/state.go1-50

Sources:

• internal/agent/component/universe_a_wrappers.go126-140
• internal/agent/component/llm.go36-100
• internal/agent/runtime/state.go1-50
• internal/harness/core/interrupt.go1-15