archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Libre Agents Spec

Purpose

Implement Alternative E: Master Agent + Programmatic Sync from the Research doc to solve the agent-model binding problem. One master agent serves as the single source of truth; a sync script propagates its configuration to N model-variant agents.

Design Decisions

All open questions resolved. Decisions recorded here for reference.

#	Decision	Choice
Q1	Master agent visibility	Usable — the master agent IS the GLM 5 Turbo variant, users chat with it directly
Q2	MongoDB access	Environment variable `MONGO_URI` (Railway service env)
Q3	ModelSpecs in v1	Yes — include ModelSpecs configuration in this project
Q4	Existing duplicate agents	Update in-place by name, preserving `_id` — never delete, never create with new ID
Q5	Naming convention	`Uvilo Agent <Model>` (e.g., “Uvilo Agent GLM 5 Turbo”)
Q6	Auto MCP sync	No — MCP servers still need manual addition to the master agent via Agent Builder

Architecture Overview

┌───────────────────────────────────────────────────────────────┐
│  Agent Builder UI                                             │
│  ┌───────────────────────────┐                                │
│  │ Uvilo Agent GLM 5 Turbo   │  ← Master agent (also usable)  │
│  │ Turbo (agent_s5VyS1...)   │    Only agent edited manually  │
│  │ (all tools, instructions, │                                │
│  │  capabilities)            │                                │
│  └───────────┬───────────────┘                                │
│              │                                                │
│              ▼                                                │
│  ┌───────────────────────────┐                                │
│  │ update-agents.ts          │  ← TypeScript sync script         │
│  │ reads agent-sync.yaml     │    (reads master from MongoDB, │
│  │ connects via MONGODB_URI  │    updates variants in-place)  │
│  └───────────┬───────────────┘                                │
│              │                                                │
│              ▼                                                │
│  ┌───────────────────────────────────────────────────┐        │
│  │  Variant Agents (updated in-place, same _id)      │        │
│  │  ┌────────────────────┐ ┌────────────────────┐    │        │
│  │  │ Uvilo Agent        │ │ Uvilo Agent        │    │        │
│  │  │ Opus 4.6           │ │ Sonnet 4.6         │    │        │
│  │  └────────────────────┘ └────────────────────┘    │        │
│  │  ┌────────────────────┐ ┌────────────────────┐    │        │
│  │  │ Uvilo Agent        │ │ Uvilo Agent        │    │        │
│  │  │ GPT 5.1            │ │ GPT 5.4            │    │        │
│  │  └────────────────────┘ └────────────────────┘    │        │
│  │  (identical config to master, different model)    │        │
│  └───────────────────────────────────────────────────┘        │
│              │                                                │
│              ▼                                                │
│  ┌───────────────────────────┐                                │
│  │ ModelSpecs (librechat.    │  ← Curated model picker UI     │
│  │ yaml)                     │    All 5 agents listed         │
│  └───────────────────────────┘                                │
└───────────────────────────────────────────────────────────────┘

Components

1. Master Agent

The single agent edited manually via the Agent Builder UI. It is also a fully functional, usable agent — users pick it from the model picker and chat with it directly.

Property	Value
Name	`Uvilo Agent GLM 5 Turbo`
Agent ID	`agent_s5VyS1DBdUsGcsRxaw8x3`
Provider	`OpenRouter`
Model	`z-ai/glm-5-turbo`

Contains:

System instructions — the full Uvilo assistant prompt
MCP server bindings — all configured servers
Deferred tool configuration — which tools load eagerly vs. on demand
Capabilities — Code Interpreter, File Search, Actions, Artifacts
Agent-level settings — temperature, max tokens, etc.

2. Variant Config File

A YAML file defining the master agent and all model variants. Lives in the repo at Forge/Configs/agent-sync.yaml.

# Forge/Configs/agent-sync.yaml
master_agent_name: "Uvilo Agent GLM 5 Turbo"

variants:
  - name: "Uvilo Agent GLM 5 Turbo"
    id: "agent_s5VyS1DBdUsGcsRxaw8x3"
    provider: "OpenRouter"
    model: "z-ai/glm-5-turbo"
  - name: "Uvilo Agent Opus 4.6"
    id: "agent_fJDpWR5hjKH0CBLav1YrC"
    provider: "anthropic"
    model: "claude-opus-4-6"
  - name: "Uvilo Agent Sonnet 4.6"
    id: "agent_zU45aNu760dOxWiG3HOJ_"
    provider: "anthropic"
    model: "claude-sonnet-4-6"
  - name: "Uvilo Agent GPT 5.1"
    id: "agent_rIUhG9GzxyXZg9bj7TDaN"
    provider: "openAI"
    model: "gpt-5.1"
  - name: "Uvilo Agent GPT 5.4"
    id: "agent_7nCIWSbZtMz94BOH5bOvt"
    provider: "openAI"
    model: "gpt-5.4"

Each variant has an id field:

Master agent: ID is known and hardcoded (agent_s5VyS1DBdUsGcsRxaw8x3). This entry is a no-op during sync (it’s the source, not a target).
Existing variants: IDs are populated from the first schema discovery run. The script looks up agents by id directly for precise updates.

Why ID-based lookup matters: Using _id directly (instead of finding by name) guarantees the script updates the exact right agent document. Name-only lookup is fragile — if someone renames an agent or creates a new one with the same name, the script could update the wrong document and break conversation links.

Adding a new model variant = add an entry with id: null, run /update-agents, paste the reported ID into the config, then update librechat.yaml ModelSpecs.

3. Sync Script (`update-agents.ts`)

A Python script that:

Reads agent-sync.yaml for variant definitions
Connects to MongoDB via MONGODB_URI environment variable
Finds the master agent document by name
For each variant (except the master itself):
- If id is set: looks up the agent directly by _id for a precise update
- If id is null: searches for an existing agent by name, or creates a new one
- If found: updates the agent document in-place using $set on _id, preserving all conversation references
- If not found: inserts a new agent document (cloned from master with model/provider overridden)
Outputs a summary: which agents were created, updated, or skipped — and the ID of any newly created agents
Generates ModelSpecs YAML entries for all variants (writes to stdout)
If any new agent IDs were reported, prompts the user to update agent-sync.yaml with them before the next run

Critical: the script NEVER deletes agents and NEVER creates a new agent when one with that name already exists. Existing agents are always updated in-place to preserve conversation history.

Synced Fields

Copied from master to each variant on every sync:

Field	Behavior
`name`	Set from variant config (not copied from master)
`model`	Set from variant config (not copied from master)
`provider`	Set from variant config (not copied from master)
`instructions`	Copied from master
`tools`	Copied from master (flat list of 378 tool ID strings)
`model_parameters`	Copied from master (nested dict: temperature, max_tokens, top_p, etc.)
`tool_options`	Copied from master (per-tool deferred loading config, 334 entries)
`mcpServerNames`	Copied from master (18 MCP server names)
`artifacts`	Copied from master (`"default"`)
`description`	Copied from master
`category`	Copied from master (`"general"`)
`end_after_tools`	Copied from master
`hide_sequential_outputs`	Copied from master
`is_promoted`	Copied from master
`support_contact`	Copied from master
`actions`	Copied from master (empty array)
`agent_ids`	Copied from master (empty array)
`edges`	Copied from master (empty array)
`conversation_starters`	Copied from master (empty array)
`tool_kwargs`	Copied from master (empty array)
`projectIds`	Copied from master (empty array)

Excluded Fields

Never overwritten on existing variants:

Field	Reason
`_id`	Unique identifier (ObjectId) — preserved to maintain conversation links
`id`	Agent ID string — preserved to maintain conversation links
`conversations`	Conversation history belongs to each variant
`createdAt`	Original creation timestamp
`updatedAt`	Set automatically by MongoDB
`author`	Owner — preserved
`versions`	Version history — unique per agent
`__v`	Mongoose version key — preserved

Provider → Endpoint Mapping

The script maps provider names to LibreChat endpoint identifiers:

Provider	Endpoint
`anthropic`	`anthropic`
`openAI`	`openAI`
`OpenRouter`	`OpenRouter`
`openrouter`	`openrouter`
`google`	`google`

4. MongoDB Access

Connection: via MONGO_URI environment variable (set on Railway service env)
Connection string: mongodb://mongo:<password>@mongodb.railway.internal:27017
Database: test
Collection: agents
Library: pymongo (installed via uv pip install pymongo)
Operations: find_one (lookup by name or id), update_one with $set (in-place update), insert_one (new agent)

5. ModelSpecs Configuration

Added to librechat.yaml to present all variant agents as a clean curated model picker. Each agent gets a ModelSpecs entry with its agent ID.

modelSpecs:
  enforce: false
  prioritize: true
  list:
    - name: "Uvilo Agent GLM 5 Turbo"
      label: "GLM 5 Turbo"
      endpoint: "agents"
      agent_id: "agent_s5VyS1DBdUsGcsRxaw8x3"
      preset:
        default: true
    - name: "Uvilo Agent Opus 4.6"
      label: "Opus 4.6"
      endpoint: "agents"
      agent_id: "<id from script output>"
      preset:
        default: true
    - name: "Uvilo Agent Sonnet 4.6"
      label: "Sonnet 4.6"
      endpoint: "agents"
      agent_id: "<id from script output>"
      preset:
        default: true
    - name: "Uvilo Agent GPT 5.1"
      label: "GPT 5.1"
      endpoint: "agents"
      agent_id: "<id from script output>"
      preset:
        default: true
    - name: "Uvilo Agent GPT 5.4"
      label: "GPT 5.4"
      endpoint: "agents"
      agent_id: "<id from script output>"
      preset:
        default: true

Agent IDs for non-master variants are populated after the first script run. The script outputs a ready-to-paste ModelSpecs snippet.

6. `/update-agents` Command

Registered in instructions.md as a command the assistant can execute:

Trigger: User says /update-agents or assistant runs it after editing the master agent
Execution: run("npx tsx /workspace/erik/uvilo-os/Forge/Skills/Update_Agents/scripts/update-agents.ts")
Output: Summary of what was created/updated/skipped + ModelSpecs snippet if agent IDs changed
Post-run: If ModelSpecs need updating, the assistant copies the snippet to librechat.yaml and reminds the user to /deploy-config + /redeploy

Data Flow

User edits Master Agent in Agent Builder UI
                    │
                    ▼
User runs /update-agents
                    │
                    ▼
Script reads agent-sync.yaml
                    │
                    ▼
Script connects to MongoDB via MONGODB_URI
                    │
                    ▼
Script reads master agent document by name
  └── verify master exists, capture its _id
                    │
                    ▼
For each non-master variant in config:
  ├── If variant.id is set:
  │   ├── find_one({ _id: variant.id })
  │   ├── If found → update_one({ _id }, { $set: synced_fields })
  │   └── If NOT found → Error: "Agent {variant.id} not found. Was it deleted?"
  └── If variant.id is null:
      ├── find_one({ name: variant.name })
      ├── If found → update_one({ _id }, { $set: synced_fields }), report ID
      └── If missing → insert_one(cloned_doc), report new ID
                    │
                    ▼
Output results summary
  └── Output ModelSpecs YAML snippet (for librechat.yaml)
                    │
                    ▼
Assistant updates librechat.yaml if ModelSpecs changed
                    │
                    ▼
User runs /deploy-config + /redeploy

File Structure

Forge/
├── Configs/
│   ├── agent-sync.yaml          # Variant configuration (version-controlled)
│   └── librechat.yaml           # Updated with ModelSpecs entries
├── Scripts/
│   └── update-agents.ts         # Sync script (version-controlled)
└── FORGE.md                     # Agent instructions (inlined into agents)

Implementation Steps

Phase 1: Schema Discovery

1.1 Connect to MongoDB and inspect the master agent document (agent_s5VyS1DBdUsGcsRxaw8x3)
1.2 Document all fields present in the agent schema
1.3 Confirm field names for synced fields (instructions, tools, capabilities, etc.)
1.4 Confirm provider → endpoint mapping from the master agent’s document
1.5 Identify any additional fields not in the current synced/excluded tables
1.6 Update this spec’s field tables with confirmed schema

Confirmed schema (Phase 1 results):

Env var: MONGO_URI (not MONGODB_URI)
Database: test (not librechat)
Connection: mongodb.railway.internal:27017 (internal Railway network)
Master agent provider: OpenRouter (not z-ai)
Master agent model: z-ai/glm-5-turbo
Model parameters nested in model_parameters dict (not top-level fields)
tool_options (not deferredTools) holds per-tool deferred loading config
mcpServerNames tracks MCP server bindings (18 servers)
tools is a flat list of 378 tool ID strings
artifacts field: "default"
versions is a list of version history entries
Empty arrays: actions, agent_ids, edges, conversation_starters, tool_kwargs, projectIds
Agent id field (string, e.g. agent_s5VyS1...) is separate from _id (ObjectId)

Phase 2: Script Development

Phase 3: Integration

3.1 Register /update-agents command in instructions.md
3.2 Run script to get all agent IDs
3.3 Populate ModelSpecs in librechat.yaml with actual agent IDs
3.4 Deploy config and redeploy LibreChat
3.5 Verify: all 5 agents appear in the model picker via ModelSpecs
3.6 Verify: each agent has the correct model and all tools are available
3.7 Verify: existing conversations are still accessible under their agents

Phase 4: Documentation

4.1 Update Knowledge index with agent management notes
4.2 Add operational lesson: “To add a new model, edit agent-sync.yaml, run /update-agents, update ModelSpecs in librechat.yaml, then /deploy-config + /redeploy”
4.3 Mark spec as status: approved

Error Handling

Scenario	Behavior
`MONGO_URI` not set	Error: “MONGO_URI environment variable not set.”
MongoDB connection failure	Error: report connection details, suggest checking env var
Master agent not found	Error: “Master agent ‘Uvilo Agent GLM 5 Turbo’ not found in MongoDB.”
Master agent ID mismatch	Warning: “Master agent found but ID differs from expected agent_s5VyS1DBdUsGcsRxaw8x3. Using found ID.”
Variant config has unknown provider	Warning: skip that variant, continue with others
Variant ID set but agent not found	Error: “Agent {id} not found. Was it deleted?” — stops processing that variant
Variant ID is null, no agent by name	Info: create new agent, report its ID for config update
Variant ID is null, agent found by name	Info: update in-place, report ID for config update
Partial failure (some variants fail)	Report which succeeded and which failed; don’t roll back successes
Script run with no changes	Info: “All variants are up to date.”

Safety Properties

Idempotent: Running the script N times produces the same result as running it once
Non-destructive: Existing agents are updated in-place; _id and conversations are never touched
Never deletes: The script has no delete logic — agents are only created or updated
Atomic per-variant: Each variant update is a single MongoDB $set operation
Conversation-preserving: Updating an agent in-place keeps all existing conversations linked
No LibreChat source changes: External script accessing the database directly

Prerequisites

Before implementation begins:

MONGO_URI environment variable set on Railway (contains the full MongoDB connection string for the LibreChat database)
pymongo available on the Railway volume (installed via uv pip install pymongo)
Master agent Uvilo Agent GLM 5 Turbo exists and is fully configured with all tools
All existing variant agents exist in MongoDB (will be found by name and updated in-place)