vitepress-template

Appearance

Agent Types and Responsibilities ​

**Referenced Files in This Document** - [[base_agent.py]](file/bi-chat/bi-chat/src/agents/base-agent.py) - [[manager_agent.py]](file/bi-chat/bi-chat/src/agents/manager-agent.py) - [[data_agent.py]](file/bi-chat/bi-chat/src/agents/data-agent.py) - [[general_agent.py]](file/bi-chat/bi-chat/src/agents/general-agent.py) - [[knowledge_agent.py]](file/bi-chat/bi-chat/src/agents/knowledge-agent.py) - [[database.py]](file/bi-chat/bi-chat/src/tools/database.py) - [[neo4j_client.py]](file/bi-chat/bi-chat/src/db/neo4j-client.py) - [[agent_registry.py]](file/bi-chat/bi-chat/src/core/agent-registry.py) - [[schemas.py]](file/bi-chat/bi-chat/src/core/schemas.py)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document explains the multi-agent system’s individual agent types and their responsibilities. It focuses on:

  • ManagerAgent: Intelligent task routing and decision-making, including intent classification and expert selection.
  • UnifiedDataAgent: SQL generation, execution, and analysis, integrated with StarRocks and knowledge graph entity/indicator retrieval.
  • GeneralAgent: Web search and information gathering for external real-time data.
  • KnowledgeAgent: Neo4j-backed knowledge graph queries and semantic reasoning for business definitions.
  • BaseAgentHelper: Shared functionality and inheritance patterns used across all agent implementations.

It also provides code-level insights via file references and diagrams that map to actual source files.

Project Structure ​

The multi-agent system is implemented under bi-chat/bi_chat/src/agents with supporting modules for tools, databases, and schemas. The agents inherit from a common helper and collaborate via a central ManagerAgent that orchestrates routing and planning.

Diagram sources

Section sources

Core Components ​

  • BaseAgentHelper: Provides unified LLM initialization, robust streaming and tool-call parsing, JSON parsing, conversation history loading, and progress reporting integration. All agents inherit from this helper to reuse shared infrastructure.
  • ManagerAgent: Orchestrates intent classification, expert routing, and task planning. It uses AgentRegistry to enumerate experts and Schemas to enforce structured outputs.
  • UnifiedDataAgent: Executes ReAct loops to search for entities/indicators, perceive schema context, and safely execute SQL against StarRocks via a sandbox, returning standardized DataArtifact outputs.
  • GeneralAgent: Performs web search and local calculations using registered tools, with strict anti-hallucination rules and tool-first behavior.
  • KnowledgeAgent: Queries the Neo4j knowledge graph for business definitions and semantic context, then synthesizes structured answers.

Section sources

Architecture Overview ​

The system centers around ManagerAgent for orchestration and BaseAgentHelper for shared capabilities. UnifiedDataAgent integrates with StarRocks via a sandbox and with Neo4j for entity/indicator perception. GeneralAgent leverages public APIs and web search. KnowledgeAgent accesses Neo4j for semantic definitions.

Diagram sources

Detailed Component Analysis ​

ManagerAgent: Intelligent Routing and Decision-Making ​

Responsibilities:

  • Analyzes user queries and historical context to classify intent (data_query, general_query, metadata_query, clarification).
  • Selects target expert agents (UnifiedDataAgent, GeneralAgent, KnowledgeAgent, ComplexTaskHandler, etc.) based on strict internal vs. external data isolation rules.
  • Generates initial plans and replans tasks with explicit dependencies and execution modes (parallel, dag, sequential).
  • Enforces schema-driven JSON outputs and caches decisions for reproducibility.

Key behaviors:

  • Uses AgentRegistry to build expert profiles for routing prompts.
  • Leverages Schemas (ManagerDecision, TaskPlan, SubTask) to constrain outputs and ensure structured planning.
  • Implements caching for LLM decisions to reduce latency and improve consistency.

Code example references:

Diagram sources

Section sources

UnifiedDataAgent: SQL Generation, Execution, and Analysis ​

Responsibilities:

  • Acts as the data expert for internal BI queries.
  • Uses ReAct loop to think, act (tool use), and observe until finishing with a standardized DataArtifact.
  • Integrates with StarRocks via a sandbox and enforces safe SQL subset (SELECT, SHOW, DESCRIBE).
  • Retrieves schema context from Neo4j to avoid hallucinations and guide table selection.

Capabilities:

  • Entity/indicator search to discover relevant business entities and metrics.
  • Database introspection (list tables, describe table) to understand schema.
  • Safe SQL execution with truncation and summary generation.
  • Artifact collection for downstream summarization and visualization.

Code example references:

Diagram sources

Section sources

GeneralAgent: Web Search and Information Gathering ​

Responsibilities:

  • Handles external real-time queries (weather, stock prices, news, exchange rates).
  • Operates without direct access to internal databases; relies on tools and web search.
  • Enforces strict anti-hallucination rules and tool-first behavior.

Capabilities:

  • Mathematical calculations, Wikipedia queries, web search, and currency exchange rate retrieval.
  • Iterative tool loop with streaming LLM responses and tool-call parsing.
  • Incorporates prior internal artifacts when available to synthesize richer answers.

Code example references:

Diagram sources

Section sources

KnowledgeAgent: Neo4j Integration for Knowledge Graph Queries ​

Responsibilities:

  • Answers questions about business definitions, metrics, and entities using the knowledge graph.
  • Synthesizes structured, Markdown-formatted answers based on graph retrieval.

Capabilities:

  • Keyword-based retrieval from Neo4j.
  • Structured prompting to ensure precise definitions and data paths.
  • Progress reporting for visibility.

Code example references:

Diagram sources

Section sources

BaseAgentHelper: Common Functionality and Inheritance Patterns ​

Responsibilities:

  • Unified LLM model initialization with shared singletons and robust wrapper.
  • Streaming LLM calls with retry logic, chunk parsing, and tool-call extraction.
  • JSON parsing helpers and conversation history loading from memory or persistence.
  • Progress reporting integration for agent lifecycle and tool execution.

Key patterns:

  • Inheritance from AgentBase to integrate with AgentScope ecosystem.
  • Shared formatter and memory instances.
  • Centralized error handling and network resilience for LLM calls.

Code example references:

Diagram sources

Section sources

Dependency Analysis ​

  • ManagerAgent depends on AgentRegistry for expert profiles and Schemas for structured outputs.
  • UnifiedDataAgent depends on database tools and Neo4j client for schema/entity perception and SQL execution.
  • GeneralAgent depends on public API tools and web search capabilities.
  • KnowledgeAgent depends on Neo4j client for graph retrieval.
  • All agents depend on BaseAgentHelper for shared LLM and progress reporting infrastructure.

Diagram sources

Section sources

Performance Considerations ​

  • UnifiedDataAgent uses a sandbox to restrict SQL to safe operations and limits displayed rows to reduce token overhead.
  • ManagerAgent caches LLM decisions to avoid repeated routing computations.
  • BaseAgentHelper’s streaming and retry logic minimize connection failures and improve responsiveness.
  • KnowledgeAgent and UnifiedDataAgent leverage graph retrieval to reduce hallucinations and unnecessary database scans.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

Common issues and resolutions:

  • LLM connectivity errors: BaseAgentHelper’s retry mechanism handles transient network failures during streaming calls.
  • JSON parsing failures: UnifiedDataAgent validates ReActStep and falls back to robust JSON parsing; ensure tool outputs conform to expected schemas.
  • SQL safety violations: Database tools reject non-query statements and DDL/DML operations; verify SQL follows allowed patterns.
  • Neo4j connectivity: Neo4jClient performs health checks and raises explicit exceptions; confirm credentials and URI configuration.

Section sources

Conclusion ​

The multi-agent system achieves clear separation of concerns: ManagerAgent governs routing and planning, UnifiedDataAgent ensures safe and accurate internal data retrieval, GeneralAgent provides reliable external information, and KnowledgeAgent enriches understanding via Neo4j. BaseAgentHelper standardizes shared capabilities across all agents, enabling consistent behavior, robustness, and maintainability.