Skip to main content

πŸ“‹ CRD Architecture

This document provides a detailed technical reference for Wegent's CRD (Custom Resource Definition) architecture, designed for developers who need to understand the internal structure and implementation details.

⚠️ Terminology Note: Team vs Bot​

Important: Please note the distinction between code-level terminology and user interface display names.

Code/CRD LevelUI DisplayDescription
TeamAgentThe user-facing AI agent that executes tasks
BotBotA building block component that makes up a Team

Simple Understanding:

  • Bot = A configured AI worker unit (includes prompt, runtime, model)
  • Team = A "working team" composed of one or more Bots - this is what users interact with to execute tasks

πŸ”— Features and CRD Mapping​

FeatureRelated CRDsDescription
ChatChat Shell + TeamDirect LLM conversation via Chat Shell
CodeClaudeCode Shell + Team + WorkspaceCloud coding execution with Git integration
FollowSubscription + TeamScheduled/event-triggered AI tasks
KnowledgeKnowledgeBase + RetrieverDocument storage and RAG retrieval
CustomizationGhost + Bot + TeamConfigure prompts, tools, and collaboration

πŸ“‹ CRD Architecture Overview​

Wegent is built on Kubernetes-style declarative API and CRD (Custom Resource Definition) design patterns, providing a standardized framework for creating and managing AI agent ecosystems.

Core Resource Types​

IconCode NameDescriptionAnalogy
πŸ‘»GhostThe "soul" of an agentDefines personality and capabilities
🧠ModelAI model configurationBrain configuration parameters
🐚ShellRuntime environmentExecutable program container
πŸ€–BotAgent building blockGhost + Shell + Model
πŸ‘₯TeamUser-facing agentCombination of multiple Bots
🀝CollaborationCollaboration modeInteraction pattern between Bots
πŸ’ΌWorkspaceWork environmentIsolated code workspace
🎯TaskTaskWork unit assigned to a Team

Resource Hierarchy​

Ghost (system prompt + MCP servers + skills)
   ↓
Bot (Ghost + Shell + optional Model)           ← UI: Bot
   ↓
Team (multiple Bots with roles)                ← UI: Agent
   ↓
Task (Team + Workspace) β†’ Subtasks

Database Table Mapping​

⚠️ Important: Task and Workspace resources are stored in a separate tasks table, not in the kinds table.

CRD KindDatabase TableModel Class
Ghost, Model, Shell, Bot, Team, SkillkindsKind
Task, WorkspacetasksTaskResource
Skill Binaryskill_binariesSkillBinary

Code Usage:

# For Task/Workspace - use TaskResource model
from app.models.task import TaskResource
task = db.query(TaskResource).filter(TaskResource.kind == "Task", ...).first()

# For other CRDs (Ghost, Model, Shell, Bot, Team) - use Kind model
from app.models.kind import Kind
team = db.query(Kind).filter(Kind.kind == "Team", ...).first()

πŸ‘» Ghost - Soul of the Agent​

Ghost represents the "soul" of an agent, defining its personality, capabilities, and behavior patterns.

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: "You are a professional software developer, skilled in using TypeScript and React to develop frontend applications."
  mcpServers:
    github:
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ghp_xxxxx
      command: docker
      args:
        - run
        - -i
        - --rm
        - -e
        - GITHUB_PERSONAL_ACCESS_TOKEN
        - ghcr.io/github/github-mcp-server
status:
  state: "Available"

🧠 Model - AI Model Configuration​

Model defines AI model configuration, including environment variables and model parameters.

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: claude-model
  namespace: default
spec:
  modelConfig:
    env:
      ANTHROPIC_MODEL: "openrouter,anthropic/claude-sonnet-4"
      ANTHROPIC_AUTH_TOKEN: "sk-xxxxxx"
      ANTHROPIC_BASE_URL: "http://xxxxx"
      ANTHROPIC_DEFAULT_HAIKU_MODEL: "openrouter,anthropic/claude-haiku-4.5"
status:
  state: "Available"

🐚 Shell - Runtime Environment​

Shell is the container where agents run, specifying the runtime environment.

Shell Types​

TypeDescriptionUse Case
ChatDirect LLM API (no Docker)Lightweight conversations
ClaudeCodeClaude Code SDK in DockerCloud coding tasks
AgnoAgno framework in DockerMulti-agent collaboration
DifyExternal Dify API proxyDify workflow integration

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: claude-shell
  namespace: default
spec:
  runtime: "ClaudeCode"
  supportModel:
    - "openai"
    - "anthropic"
status:
  state: "Available"

πŸ€– Bot - Complete Agent Instance​

Bot is a complete agent instance combining Ghost (soul), Shell (container), and Model (configuration).

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: developer-bot
  namespace: default
spec:
  ghostRef:
    name: developer-ghost
    namespace: default
  shellRef:
    name: claude-shell
    namespace: default
  modelRef:
    name: claude-model
    namespace: default
status:
  state: "Available"

πŸ‘₯ Team - Collaborative Team​

Team defines a collection of Bots working together with specific roles and collaboration patterns.

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Team
metadata:
  name: dev-team
  namespace: default
spec:
  members:
    - name: "developer"
      botRef:
        name: developer-bot
        namespace: default
      prompt: "You are the developer in the team, responsible for implementing features..."
      role: "leader"
    - name: "reviewer"
      botRef:
        name: reviewer-bot
        namespace: default
      prompt: "You are the code reviewer in the team, responsible for reviewing code quality..."
      role: "member"
  collaborationModel: "pipeline"
status:
  state: "Available"

🀝 Collaboration Models​

Four collaboration patterns define how Bots interact within a Team:

1. Pipeline​

Sequential execution where each Bot's output feeds into the next.

Developer Bot β†’ Reviewer Bot β†’ Tester Bot β†’ Deployer Bot

2. Route​

Leader assigns tasks to appropriate Bots based on content.

User Query β†’ Leader Bot β†’ {Frontend Bot | Backend Bot | DB Bot}

3. Coordinate​

Leader coordinates parallel Bot execution and aggregates results.

Leader Bot β†’ [Analyst Bot, Data Bot, Report Bot] β†’ Leader Bot (aggregate)

4. Collaborate​

All Bots share context and freely discuss.

[Bot A ↔ Bot B ↔ Bot C] (shared context)

πŸ’Ό Workspace - Work Environment​

Workspace defines the team's work environment, including repository and branch information.

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Workspace
metadata:
  name: project-workspace
  namespace: default
spec:
  repository:
    gitUrl: "https://github.com/user/repo.git"
    gitRepo: "user/repo"
    gitRepoId: 12345
    branchName: "main"
    gitDomain: "github.com"
status:
  state: "Available"

🎯 Task - Executable Work Unit​

Task is an executable work unit assigned to a Team, associating Team and Workspace.

YAML Configuration Example​

apiVersion: agent.wecode.io/v1
kind: Task
metadata:
  name: implement-feature
  namespace: default
spec:
  title: "Implement new feature"
  prompt: "Please implement a user authentication feature with JWT tokens"
  teamRef:
    name: dev-team
    namespace: default
  workspaceRef:
    name: project-workspace
    namespace: default
status:
  state: "Available"
  status: "PENDING"
  progress: 0

πŸ”„ Concept Relationship Diagram​

πŸ’‘ Best Practices​

1. Ghost Design​

  • βœ… Clearly define the agent's expertise
  • βœ… Provide clear behavioral guidelines
  • βœ… Configure necessary MCP tools

2. Bot Composition​

  • βœ… Create specialized Bots for different tasks
  • βœ… Reuse Ghost and Model configurations
  • βœ… Choose appropriate Shell types

3. Team Building​

  • βœ… Select suitable collaboration models
  • βœ… Define clear member roles
  • βœ… Provide clear task prompts for each member

πŸ”— Related Resources​