🧰 Agent System Design

The Agent System in LLMaven is the backbone of its multi-agent architecture. It is designed to support flexible, intelligent orchestration of tasks across documentation, code, data, pipelines, and human-in-the-loop workflows. This page outlines the principles, structure, and logic behind the design of LLMaven's agents.

🔄 Design Goals

The Agent System is designed to:

1. Decentralize functionality via task-specialized agents.
2. Enable non-deterministic reasoning through agent collaboration.
3. Support structured, typed interactions using the A2A Protocol.
4. Allow injection of new capabilities via tools, memory, and plugins.
5. Maintain modularity and fault isolation through containerized deployment.
6. Embrace graph-based thinking as a foundational system design principle.

🔮 Agents Are Just Graphs

Viewing AI agents as graphs provides a powerful mental model for designing complex, modular systems. Each agent is composed of interconnected nodes, each with a specific role in the decision-making and task-execution process. This abstraction allows us to:

• Modularize functionality for easier testing and maintenance
• Scale complexity by connecting simple components
• Improve resilience through explicit fallback and error-handling paths
• Enable transparency by visualizing the flow of logic and information

This graph-centric approach turns complexity into clarity and makes building, debugging, and extending agents dramatically easier.

🧬 General Agent Node Types

Each agent can be viewed as a directed graph of functional node types, each fulfilling a distinct responsibility:

1. LLM Node

• Purpose: Reasoning, generation, and decision-making
• Examples: Planning, content generation, summarization
• Why it's useful: Acts as the "brain" of the agent. Handles ambiguity, coordination, and generation.

2. Tool Node

• Purpose: Executes external tools or APIs
• Examples: Web search, code execution, data queries (via MCPs)
• Why it's useful: Extends agent capability beyond text, enabling real-world actions and integrations.

3. Control Node

• Purpose: Branching logic and deterministic rules
• Examples: Routing flows, conditional logic, rule-based filtering
• Why it's useful: Introduces predictability into otherwise flexible agent reasoning. Useful for business logic.

4. Memory Node

• Purpose: Handles state persistence and context recall
• Examples: Short-term vector stores (Qdrant), long-term graphs (Neo4j), chat history
• Why it's useful: Supports personalized, evolving interactions and persistent context.

5. Guardrail Node

• Purpose: Enforce constraints and validate outputs
• Examples: Content moderation, safety filters, output format checkers
• Why it's useful: Ensures outputs align with quality, safety, or compliance standards.

6. Fallback Node

• Purpose: Respond to errors or failures
• Examples: Retry logic, default behaviors, escalation paths
• Why it's useful: Ensures graceful degradation rather than crashing or halting on failure.

7. User Input Node

• Purpose: Incorporate human judgment
• Examples: Confirmation dialogs, clarification prompts, manual approvals
• Why it's useful: Adds accountability, improves safety, and enables nuanced decision-making where automation falls short.

🏋️ Building with the Blueprint

Designing agents as graphs allows for intentional planning and scalable complexity. Here's how to build with this model:

1. Start simple: Begin with the core path from input to output, using only LLM + Tool + Guardrail.
2. Layer on complexity: Add Control, Memory, and Fallback nodes as edge cases emerge.
3. Modularize breakpoints: Turn repeated logic (e.g., filtering, validation) into shared node types.
4. Design for failure: Assume every node might fail. Handle errors explicitly with Fallback logic.
5. Balance autonomy and oversight: Use User Input nodes to govern critical decisions.
6. Visualize the flow: Use node-graph diagrams to debug and explain behavior.

By treating every agent as a graph of interoperable components, LLMaven ensures both flexibility and structure in its multi-agent system design.

🛀 Core Agent Roles

Each agent is a containerized microservice deployed via Helm + Kubernetes. All agents speak a shared language through the Agent-to-Agent Protocol (A2A) and communicate via JSON-based message passing with schema validation.

✏️ Supervisor Agent

Purpose: Planning and orchestration.
Function: Interprets user input, queries tool availability, and sequences sub-agents to complete tasks.
Notes: Central to coordinating multi-agent workflows.

📖 Docs Agent

Purpose: Extract, structure, and reason over documentation and long-term memory.
Function: Interfaces with Neo4j using:

• Graffiti MCP (temporal knowledge graph)
• Cypher MCP (query execution)
• Neo4j MCP (node/edge editing)

Notes: Maintains and updates a temporal knowledge graph.

💻 Coding Agent

Purpose: Interact with GitHub repositories.
Function: Uses GitHub MCP to:

• Open/create issues
• Evaluate pull requests
• Modify code with context

Notes: Uses GitHub auth tokens passed from OpenWebUI.

📊 Data Agent

Purpose: Manage internal and external data.
Function: Interacts with MinIO, Azure Blob, or other sources via:

• Azure MCP
• MinIO MCP
• (Future) AWS S3 MCP, GCP MCP

Notes: Provides data to other agents during analysis or synthesis.

⚙️ Pipeline Agent

Purpose: Execute analysis pipelines and invoke user-defined logic.
Function: Connects to MCP Gateway, which dispatches calls to custom MCPs.
Notes: Enables users to write their own tools, maintaining extensibility.

🚀 Multi-Agent System Flow

1. Input Prompt is received via OpenWebUI.

2. Supervisor Agent plans required steps and delegates them to sub-agents.

3. Each sub-agent:

   • Validates inputs.
   • Retrieves memory if needed.
   • Uses LLM to reason or generate.
   • Invokes tools or requests human input.
   • Passes results through guardrails.

4. Results are aggregated by the supervisor and returned to the user.

This allows for non-linear, adaptive processing tailored to complex research workflows.

📚 Future Directions

• Authentication Agent for internal permissioning.
• Evaluation Agent for dynamic metric analysis.
• Fine-Tuned RSE Model as a standalone agent and guardrail.
• Dynamic Agent Spawning using task-based requirements.

LLMaven’s agent system is designed not just to execute tasks, but to think, reason, and evolve alongside research needs.

“We’re building agents that reason like researchers. Because science deserves more than static scripts.”