Forge Agent Architecture

How the Forge agent system works: Bot configuration, prompt composition, memory, and deployment.

Bot Prompt Architecture

Forge agents are defined as Bots — configurable entities with a modular prompt tree, model selection, tool access, and runtime context.

BOT CONFIGURATION
  Bot identity (name, handle, group)
  + System prompt (composed from Prompt + ChildPrompts)
  + Model selection (integration:modelName)
  + Tool attachments (eager, deferred, discovery)
  + Access control (department, project scoping)
  ─────────────────────────────────────────
  Defines the agent's capabilities and behavior

───────────── RUNTIME BOUNDARY ──────────────

RUNTIME CONTEXT (injected per-session)
  Department / project context
  + Conversation history
  + User identity and permissions
  ≈ varies by session

───────────── ON-DEMAND BOUNDARY ──────────────

ON-DEMAND (loaded mid-session as needed)
  Skills, project docs, grep results
  ≈ 0–5,000 words (varies by task)

Prompt Composition

Each Bot has a system prompt built from a prompt tree:

• Bot → has one or more Prompts attached
• Prompt → contains prompt text and may have ChildPrompts (up to 3 levels deep)
• ChildPrompts allow modular, reusable instruction blocks (e.g., a shared “rules” block used across multiple Bots)

Prompt versions are tracked; updates to a Prompt or ChildPrompt propagate to all Bots that reference them.

Model Selection

Each Bot specifies its model in integration:modelName format (e.g., openai:gpt-5-mini, anthropic:claude-sonnet-4-20250514). Model availability is determined by the configured integrations; no YAML configuration file is needed.

Tool Access

Tools are attached to Bots in three modes:

Mode	Behavior
Eager	Always loaded in the Bot’s active tool set
Deferred	Discovered via toolSearch, loaded on demand with loadTool
Discovery	Built-in tools (toolSearch, loadTool, unloadTool) always available

Least-privilege principle: a Bot receives only the tools it needs for its responsibility.

Bot Prompt and Version Management

• Source of truth: Bot and Prompt records in the Forge platform database
• Configuration: Bots are configured through the Forge admin UI or API — system prompt text, ChildPrompt composition, model, tools, and access control are all managed centrally
• Version tracking: Prompt versions are saved automatically; diffs can be reviewed via application/vnd.prompt-version artifacts
• Deployment: Changes to Bot configuration take effect on the next session; no manual sync script or redeploy step is required
• Rationale: Centralized Bot configuration replaces the former pattern of copying prompt text into agent instruction fields, ensuring a single source of truth and eliminating sync drift

Memory Architecture

File-Based Memory (Shared / Team-Scoped)

File	Scope	Loaded when
Forge/Skills/*_MCP/SKILL.md	All users, relevant sessions	On demand
SKILL.md + LESSONS.md	All users, when skill is active	On demand
Project_Plan_{N}.md, Project_Execute_State_{N}.md, Project_Learnings.md, persisted evaluation reports	All users on that project	Per-project session start or phase evaluation

Project recovery state is reconstructed from the Phase file, current durable work-products, Execute_State files where applicable, persisted evaluation or verification reports, saved conversation or AgentJob metadata, git status, and relevant todo items.

User and Conversation Context

User-specific context (preferences, learned facts) is managed within the conversation session and uvilo-mono platform. The platform provides per-user and per-conversation scoping for context that should not be shared across all team members.

Opt-in write policy. Persistent user context is ONLY written when the user explicitly requests it (“Remember that I…”, “Don’t forget…”, etc.). It does NOT proactively extract or infer facts from conversation.

Not a substitute for file-based memory. File-based memory is shared team state. Per-user context is for personalization only. Do NOT store project state, task progress, or operational knowledge in per-user context — those belong in project State files, LESSONS.md, Skills, Knowledge, and durable reports.

Skill-Level LESSONS.md

Every SKILL.md gets a co-located LESSONS.md in the same directory. Both are read when the skill is activated. Prune when >500 words: graduate stable learnings into the SKILL.md procedure.

Bot Configuration Architecture

Bot Identity

Each Bot is identified by:

Field	Purpose
botId	Unique internal identifier
botGroup	Grouping (e.g., forge)
botHandle	Handle within group (e.g., task-runner)

Bots are referenced by botId alone or by botGroup + botHandle pair.

Prompt Tree

A Bot’s system prompt is composed from its attached Prompts and ChildPrompts. This modular structure allows:

• Shared instruction blocks across multiple Bots
• Versioned updates that propagate automatically
• Override capabilities (system prompt override, append) when spawning sub-agents

Model Selection

Each Bot declares its default model. When spawning a sub-agent via spawnAgent, the caller can override the model with modelOverride in integration:modelName format.

Tool Attachments

Tools are assigned per-Bot. The three attachment modes (eager, deferred, discovery) enforce least-privilege access. SRP agents receive only the minimal tool set needed for their single responsibility.

Access Control

Bots are scoped to departments and projects. The spawnAgent tool accepts department and project parameters to propagate context to sub-agents. Access control ensures agents operate within their authorized scope.

Deployment and Update Flow

1. Create or update Bot configuration (identity, prompt tree, model, tools, access)
2. Changes take effect on the next session — no manual sync or redeploy required
3. Sub-agents spawned via spawnAgent always use the latest Bot configuration
4. Prompt version history is maintained for audit and rollback

SRP Agent Architecture

Single-Responsibility Principle agents have minimal system prompts and least-privilege tool access. They are invocable from orchestrator Bots (Task Runner, Project Worker) via the spawnAgent tool. Each SRP agent:

• Has a single, well-defined responsibility
• Gets its instructions from its Bot’s prompt tree
• Has only the tools it needs (no extra access)
• Can be spawned independently or as part of a workflow
• Is invoked via spawnAgent({ botGroup, botHandle, message }) or spawnAgent({ botId, message })

Adding a New Model

1. Ensure the model is available through a configured integration (e.g., OpenAI, Anthropic)
2. Update the Bot’s model field to integration:modelName (e.g., openai:gpt-5-mini)
3. Test by chatting with the Bot directly or spawning it as a sub-agent

Adding a New SRP Agent

1. Create a new Bot with a descriptive name, group, and handle
2. Write the system prompt text and attach it as a Prompt (with ChildPrompts if needed for modularity)
3. Assign the minimal tool set the agent needs
4. Set the model and access control scope
5. Test by chatting with the Bot directly, then test via spawnAgent from an orchestrator Bot

Safety Properties

• Idempotent Bot configuration (update N times = same result)
• Non-destructive (updates in-place, preserves Bot identity)
• Conversation-preserving (existing conversations continue with their session context)

Artifact Instructions

Artifacts are created and updated via the artifacts tool. The tool supports multiple content types and display modes:

Parameter	Purpose
identifier	Stable unique key for the artifact (reuse to update in place)
title	Human-readable label shown in the artifact card
type	Content type: text/markdown, text/html, image/svg+xml, application/vnd.mermaid, application/vnd.prompt-version, application/vnd.markdown-file, application/vnd.git-changes
content	Complete, self-contained content (no placeholders)
display	panel (default, opens in workspace panel) or inline (renders in transcript)

Artifact instructions are embedded in the Bot’s system prompt. Specialized artifact types support inspection workflows:

• application/vnd.prompt-version — Inspects Bot prompt versions. Created with a JSON/YAML payload containing promptId, version, and name. When opened, the UI loads version N and N−1 from the database and displays a unified text diff, allowing humans to inspect prompt content and track changes over time without direct database access.
• application/vnd.markdown-file — Inspects workspace files by path.
• application/vnd.git-changes — Inspects multi-file changes by loading a unified git diff vs upstream.