@solidxai/core 0.1.13-beta.0 → 0.1.13-beta.11

package/docs/agent-hub-grooming.md

@@ -0,0 +1,301 @@
+# SolidX AI Agent Builder / Agent Registry Vision
+
+## Concept
+
+The **AI Agent Builder** is a SolidX module that allows teams to define, configure, test, and deploy AI agents as first-class metadata-driven entities.
+
+The goal is to make agents configurable through SolidX rather than hardcoded in application code.
+
+Each agent is powered by a **Mini-SWE style runtime loop**, but the behaviour of the agent is controlled by SolidX metadata:
+
+```text
+Agent Definition
++ Skills
++ Tools
++ Knowledge Base
++ Policies
++ Output Schema
+= Runnable Enterprise Agent
+```
+
+---
+
+## Module Installation
+
+The AI Agent Builder can be installed as a standard SolidX module.
+
+Once installed, it brings its own domain model, such as:
+
+```text
+Agent
+Agent Skill
+Agent Tool
+Agent Knowledge Base
+Agent Policy
+Agent Run
+Agent Interaction
+Tool Call Log
+```
+
+However, the actual agent configuration can be saved directly into SolidX metadata JSON, instead of requiring every configuration detail to be stored as transactional database rows.
+
+The database can mainly store runtime records such as:
+
+```text
+Agent Run
+Conversation History
+Tool Calls
+Execution Logs
+Errors
+Audit Trail
+```
+
+---
+
+## Agent Configuration UI
+
+SolidX can provide either:
+
+1. A native SolidX CRUD-style UI, or  
+2. A custom Agent Builder UI
+
+to manage agent artefacts.
+
+The user can configure:
+
+```text
+Agent name
+Agent description
+System instructions
+Allowed skills
+Allowed tools
+Linked knowledge bases
+Runtime limits
+Approval rules
+Output schema
+```
+
+Example:
+
+```text
+Customer Support Agent
+- Skill: Complaint Handling
+- Skill: Refund Policy Interpretation
+- Tool: Gmail
+- Tool: CRM
+- Knowledge Base: Support SOPs
+- Runtime: Mini-SWE
+```
+
+---
+
+## Skills
+
+A skill represents reusable know-how.
+
+Examples:
+
+```text
+Contract Review
+Invoice Validation
+Customer Escalation Handling
+Code Review
+Document Classification
+```
+
+A skill may contain:
+
+```text
+Instructions
+Prompt templates
+Examples
+Decision criteria
+Expected output format
+```
+
+Skill = **how to think / how to perform a task**
+
+---
+
+## Tools
+
+Tools are executable capabilities available to agents.
+
+Examples:
+
+```text
+Send Email
+Search Gmail
+Query Database
+Create Ticket
+Read File
+Call API
+Search Knowledge Base
+```
+
+Tool = **what action the agent can perform**
+
+SolidX can provide a screen where all registered/discovered tools are visible.
+
+The tool registry can include:
+
+```text
+Native SolidX tools
+Internal APIs
+MCP tools
+Composio tools
+Custom enterprise tools
+```
+
+Each tool can have metadata:
+
+```text
+Name
+Description
+Input schema
+Output schema
+Auth mode
+Approval requirement
+Allowed roles
+Provider
+```
+
+---
+
+## Knowledge Base
+
+Agents can be linked to one or more knowledge bases.
+
+Examples:
+
+```text
+Company policies
+Product documentation
+Support articles
+Technical specifications
+SOPs
+Contract templates
+```
+
+This allows each agent to operate with controlled enterprise context.
+
+---
+
+## Agent Runtime
+
+Each configured agent is executed as a Mini-SWE loop.
+
+When invoked, SolidX spawns an agent run and gives it:
+
+```text
+Goal
+User input
+Agent metadata
+Relevant skills
+Available tools
+Knowledge context
+Policies
+Output schema
+```
+
+The agent then runs autonomously:
+
+```text
+Plan
+Act
+Use tool
+Observe
+Re-plan
+Complete
+```
+
+The workflow engine or UI does not need to understand the internal reasoning loop.
+
+It only receives the final structured result.
+
+---
+
+## Test Interface
+
+Once an agent is configured, users can test it inside SolidX.
+
+Default interface:
+
+```text
+Chat-based test console
+```
+
+Future interfaces:
+
+```text
+Voice
+WhatsApp
+Slack
+Email
+Embedded app widget
+```
+
+This allows business users and developers to validate the agent before attaching it to workflows.
+
+---
+
+## Workflow Integration
+
+Any SolidX workflow can include an Agent Handoff step.
+
+Example:
+
+```text
+Workflow Step:
+Delegate document review to Document Review Agent
+```
+
+The workflow creates an Agent Run.
+
+The agent works asynchronously.
+
+When completed, it sends back a result.
+
+The workflow then continues.
+
+```text
+Workflow
+  ↓
+Agent Handoff
+  ↓
+Mini-SWE Agent Run
+  ↓
+Agent Result
+  ↓
+Workflow Continues
+```
+
+---
+
+## Strategic Value
+
+This makes SolidX an enterprise agent platform, not just a workflow or low-code platform.
+
+The key advantage is that agents become:
+
+```text
+Configurable
+Reusable
+Governed
+Auditable
+Workflow-aware
+Tool-aware
+Knowledge-aware
+```
+
+SolidX remains the control plane.
+
+Mini-SWE becomes the execution loop.
+
+Tools provide actions.
+
+Skills provide task expertise.
+
+Knowledge bases provide enterprise context.
+
+Together, this creates a metadata-driven framework for building and deploying enterprise-grade AI agents.