Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-04-25 Updated 2026-04-25

Orchestration Research

1. LibreChat Agent Handoffs and Mixture-of-Agents Capabilities

R6: Ralph Wiggum pattern, R8/R9: Project/Task Runner agents, R10: Single-Responsibility agents

1.1 Finding

LibreChat has recently implemented (early 2026 / late 2025) robust native support for “Agent Handoffs” (recursive handoffs, sending context back and forth) and “Mixture-of-Agents” (multiple agents invoked in sequences). Discussions on GitHub (e.g. #8372, #3101, #5960, #12706) confirm that handoffs are live on the main branch. They allow highly composable multi-agent patterns, though UI support for advanced orchestration (like a node-based interface) is still evolving.

1.2 Options

  1. Leverage LibreChat’s native handoffs entirely: Design our master and sub-agents within LibreChat’s UI/YAML config using the handoff mechanism. External scripts would only be needed for the initial cron trigger (R1).
    • Pros: Stays fully within the LibreChat ecosystem. Avoids building a parallel orchestrator. Uses proven, built-in memory and API features.
    • Cons: Limited by LibreChat’s current orchestration UI and API exposed for external manipulation. May struggle with complex state tracking outside of a chat session.
  2. External orchestration scripts wrapping LibreChat: Write custom TS scripts that call the LibreChat Agents API.
    • Pros: Ultimate flexibility. Can implement specific loops, retries (R6), and state management.
    • Cons: Re-implements some multi-agent logic that LibreChat is actively building.

1.3 Recommendation

Option 2 for the outer orchestration loop (cron, project discovery, state tracking), but bridging into Option 1 where possible (letting LibreChat handle the inter-agent handoffs for specific multi-step generation tasks). The master scripts should treat LibreChat as an engine to execute well-defined workflows, handling the durable state themselves.

1.4 Decision

Pending

2. Mastra.ai Integration

Additional Requirements (Research Phase)

2.1 Finding

Mastra.ai is a new, TypeScript-native framework specifically designed for “agentic workflows”. It provides robust step-based workflow primitives (sequential, parallel, branching, looping), persistent state, observability, and sub-agent orchestration. It differs from tools like LangChain or Temporal by being specifically tuned for TS+AI memory orchestration.

2.2 Options

  1. Integrate Mastra as the Orchestrator: Use Mastra to define the workflows, calling LibreChat’s API for the actual inference/agent execution.
    • Pros: Mastra provides durable execution, pausing, and the workflow DAG (branching, looping) out of the box. Highly aligned with JS/TS architecture. Solves the complex orchestration requirements instantly.
    • Cons: Introduces a new framework dependency. Mastra has its own memory and integration patterns that might conflict with or duplicate LibreChat’s features.
  2. Build custom TS scripts without Mastra: Stick to raw Typescript calling the LibreChat API.
    • Pros: Full control, minimal dependencies.
    • Cons: Have to reinvent durable state, graph execution, and error recovery for agent workflows.

2.3 Recommendation

Option 1. Exploring Mastra for the outer orchestration layer (defining the graph of how agents interact, handling cron resumes, and tracking state) while using LibreChat for the actual LLM connections and chat UI history. Mastra’s TS focus makes it ideal for building the external engine we need before LibreChat builds its own node-based UI.

2.4 Decision

Pending

3. Database vs. Filesystem for State

Additional Requirements (Research Phase)

3.1 Finding

Agent orchestration requires tracking complex multi-agent states, pending tasks, human-in-the-loop pauses, and project phases across cron executions.

3.2 Options

  1. Continue using filesystem (Markdown/YAML):
    • Pros: Easy to read/edit by humans. Simple. No DB setup required. Agents like MCP uvilo-filesystem already excel at this.
    • Cons: Concurrency issues with multiple agents writing to MD files simultaneously. Slower to query across many projects. Complex state changes might lead to merge conflicts in the workspace.
  2. Migrate to a Database (e.g., Neon Postgres/SQLite):
    • Pros: Solves concurrency, atomicity, and queryability. Crucial if we want a GUI to reflect real-time agent states.
    • Cons: Moving away from local file tracking breaks current agent paradigms slightly, requires managing schema and DB connections.

3.3 Recommendation

Option 1. Keep filesystem-based state for now to minimize scope and maximize current MCP tool usage. Develop a structured JSON or structured Markdown convention specifically for the Orchestrator to prevent concurrency issues, perhaps leaning on Todo/checklist MCP (R4) with an SQLite backend to manage specific atomic states, while keeping overall project docs in Markdown.

3.4 Decision

Pending

4. GUI Implementation

Additional Requirements (Research Phase)

4.1 Finding

Building a GUI for managing the orchestration (Cron CRUD, browser, launcher) requires a framework capable of rapid prototyping and integration with the backend TS scripts / DB.

4.2 Options

  1. Fork LibreChat: Add the orchestration UI directly into LibreChat.
    • Pros: Unified experience.
    • Cons: Huge maintenance burden. Merge conflicts with upstream. LibreChat is complex.
  2. Stand-alone TanStack Start App: Build a new web app connecting to the same workspace or DB.
    • Pros: Clean slate. Tailored exactly to Uvilo’s needs. Easy deployment to Vercel/Railway.
    • Cons: Two UIs for users to switch between.

4.3 Recommendation

Option 2. A bespoke, lightweight TanStack Start or Next.js app that serves as the “Uvilo Control Center”, communicating with the orchestration TS scripts and providing the UI requested in the requirements, leaving LibreChat as the pure chat and agent execution engine.

4.4 Decision

Pending