AI Agent System Documentation

Overview

The AISTEAM agent system is built around a Supervisor pattern combined with a centralized agent panel. The Chief AI Officer, also called Hans, acts as the central coordinator. All user requests start in the assistant chat, which is visually tied to the agent panel. The system can:

• Receive user messages through a single assistant panel
• Assign an active agent for each conversation
• Load project context and client settings automatically
• Route tasks to the correct execution agents
• Execute structured tasks through the execution API
• Store conversations and tasks for later review

Core principle: all non supervisor agents are execution agents. They actually perform work such as creating pages, updating content, and running workflows. The supervisor coordinates these agents and validates results.

Central Agent Panel

AISTEAM uses a single centralized assistant panel instead of separate pages for each agent. The panel is available globally in the application and acts as the cockpit for all AI powered work.

Panel goals

• Expose all relevant agents for the current tenant or project
• Let the user choose which agent is currently active
• Display a persistent conversation for the selected context
• Show routing information such as which agent handled a reply
• Act as the primary entry point into the AI system

Panel structure

• Agent selector list containing supervisor, leads, and specialists
• Conversation area showing messages, status updates, and task confirmations
• Context header that indicates the project or tenant currently in focus
• Optional meta section that summarizes which agents participated in the thread

The same panel is used whether the user is on the main dashboard, in a project view, on tickets, or in other modules. Context and routing adapt to the location and projectId.

Agent Hierarchy and Types

Agents are organized into a clear hierarchy. This keeps the system understandable for users and predictable for developers.

Supervisor layer

• Chief AI Officer Hans, primary brain and conversation owner for complex flows

Lead layer

Leads handle domains of responsibility and coordinate specialized work.

• Delivery Lead
• Client Success Lead
• Creative Lead
• Growth Lead
• Technical Lead

Execution agents

These agents are the doers. They create content, perform web changes, and run actions through APIs.

• Web Engineer Nico
• SEO Specialist
• Content and Copy Specialist
• Social and E marketing Specialist
• Sports Media Specialist
• Branding and Design Specialist
• E commerce Specialist

Utility agents

Utility agents help with orchestration, scheduling, and research.

• Research Agent
• Scheduler and Calendar Agent
• File and Knowledge Agent
• Automation Agent
• Notification Agent

Agent Catalog

This section documents each core agent, the type of work they perform, and how developers should think about routing tasks to them. In practice, the exact list of active agents can be configured per tenant or project through Supabase configuration.

Chief AI Officer Hans, Supervisor

• Primary coordinator for all user conversations
• First recipient of every message in the assistant chat
• Decides whether to answer directly or call another agent
• Validates and refines outputs from execution agents before sending back to the user
• Responsible for multi step plans that involve several agents and panels

Delivery Lead Selena

• Project management and delivery coordination
• Helps translate messy user intent into structured tasks
• Assists with timelines, priorities, and scope
• Coordinates follow up actions and status updates

Client Success Lead

• Focus on client relationships and goals
• Helps define objectives and success metrics
• Surfaces opportunities based on project and ticket data

Creative Lead Mak

• Owns brand voice, visual identity, and creative direction
• Helps define layout ideas and content frameworks
• Works together with Web Engineer and Growth on experiences that convert

Growth Lead Dana

• Responsible for traffic, leads, and revenue growth
• SEO and E marketing strategy for each project
• Coordinates with analytics, campaigns, and reporting panels in the app

Technical Lead

• Architecture, integrations, and technical decisions
• Hosting, performance, and security guidance
• Works closely with Web Engineer and Automation Agent for deep technical work

Web Engineer Nico

• Execution agent for web and CMS tasks
• Creates and updates pages, posts, menus, and settings
• Works with WordPress, WooCommerce, Shopify, and other platforms
• Consumes project context instead of asking the user for basic site information

Other Execution and Utility Agents

Additional agents such as SEO Specialist, E commerce Specialist, and Notification Agent follow the same model. Each has a concise mandate, default tools, and expected task types. Their full definitions live in database configuration rather than being hard coded in the UI.

Assistant Chat and Agent Selection

The right side assistant chat is always visible when the assistant panel is open. The user interacts through one text area, but the system can change which agent actually responds.

Conversation ownership

• Every conversation in the database tracks a current agent field, such as chief or webEngineer
• The user can explicitly select an agent in the panel to change this field
• The Supervisor can override the selection when routing is clearly better handled elsewhere

UI behavior

• Selecting an agent in the panel updates the agentId sent to the chat API
• The conversation history remains continuous, but message meta can record which agent authored each reply
• The panel can show the current active agent and any routing decisions taken by the Supervisor

Task Flow from User Request to Execution

Step 1, User submits request

The user types a message in the assistant panel. This message, along with conversation history and optional project context, is sent to the chat API at the route for assistant chat.

Step 2, Active agent and Supervisor receive the message

The chat API receives the current agentId from the panel. The system then:

• Normalizes the message and loads the conversation record
• Loads the current project context if projectId is available
• Invokes Supervisor logic to decide whether to keep the active agent, reroute the message, or answer directly

Step 3, Project context loading

When the user is on a project page, the system:

• Detects projectId from the URL using Next navigation
• Fetches project data from the projects table
• Collects key information such as name, domain, CMS platform, CMS URL, and custom settings
• Builds a system prompt segment that describes the project

Agents are instructed to use this information and only ask for missing details that are strictly required for the current task.

Step 4, Routing and delegation

The Supervisor decides which agent should be responsible for the current message. There are three basic outcomes:

• The supervisor answers directly and remains the active agent
• The request is delegated to a specific agent such as Web Engineer or Growth Lead
• The request is broken into multiple tasks that involve several agents, with the supervisor orchestrating the sequence

Step 5, Agent processing

The chosen agent receives:

• Conversation history, usually the last few messages
• Project context when available
• Additional agent specific instructions regarding tools and limits

The agent then decides whether the task requires actual execution or only advisory work. For execution, the agent calls the execute API through a structured function call.

Step 6, Task execution

For tasks that require action on a site or system, the agent calls an execute function in its tool set. Conceptually it looks similar to this:

{
  "name": "execute_task",
  "arguments": {
    "task_type": "create_page",
    "parameters": {
      "title": "About Us",
      "content": "...",
      "cms": "wordpress"
    },
    "message": "Creating new WordPress page in the project CMS"
  }
}

The back end route that handles execution then uses Supabase and CMS integrations to perform the requested change or to queue a task for later execution.

Step 7, Response generation

Once execution completes or is queued, the agent produces a human readable explanation. The Supervisor validates this response and sends the final message back to the user, optionally with a summary of actions taken and any next steps.

Supervisor Decision Process

For each user request, the Supervisor follows a repeatable process:

1. Receive the message and identify the conversation
2. Analyze intent based on message content and history
3. Load project data and any relevant tenant or client context
4. Decide whether the request is strategic, execution focused, or mixed
5. Route to the correct agent or handle directly
6. Optionally break the work into a plan with multiple steps
7. Validate any agent output before it reaches the user

Agent Routing Logic

Routing is currently based on a combination of explicit selection in the panel and keyword based logic in the back end. The assistant chat route contains a helper that can adjust the routed agent based on the content of the latest message.

function determineAgent(
  userMessage: string,
  currentAgent: string
): string {
  const message = userMessage.toLowerCase();

  // Explicit mentions of leads
  if (message.includes("delivery") || message.includes("selena")) {
    return "deliveryLead";
  }
  if (message.includes("client") || message.includes("account")) {
    return "clientSuccess";
  }
  if (message.includes("brand") || message.includes("creative") || message.includes("mak")) {
    return "creativeLead";
  }
  if (message.includes("seo") || message.includes("marketing") || message.includes("dana")) {
    return "growthLead";
  }
  if (message.includes("tech") || message.includes("system") || message.includes("hosting")) {
    return "technicalLead";
  }
  if (
    message.includes("web") ||
    message.includes("code") ||
    message.includes("build") ||
    message.includes("implement") ||
    message.includes("page") ||
    message.includes("post")
  ) {
    return "webEngineer";
  }

  // Default to current selection or supervisor
  return currentAgent || "chief";
}

In the future this routing can be enhanced with intent detection using the AI model itself, but the above approach keeps behavior predictable and debuggable.

Project Context and Information

When a user opens the assistant while on a project page, the system automatically attaches project context to each request. This avoids repeated questions and keeps agent responses grounded in real data.

Included project data

• Project name
• Main domain and any secondary domains
• CMS platform and access URL
• Key configuration values in custom data fields
• Any important tags such as ecommerce, membership, or media site

Agents receive a clear instruction: use this project information first and do not ask the user for details that the system already knows.

Task Execution

Execution agents use structured tasks to interact with external systems. Tasks are stored in the database so that they can be audited or replayed.

Supported task types

• Create or update pages and posts in CMS platforms
• Create or update products in ecommerce systems
• Update content or media metadata
• Create structured tasks and tickets in AISTEAM panels

The execute API receives a taskType string, parameters object, projectId, and conversationId. This keeps the execution layer decoupled from the conversational logic while still traceable.

API Structure

Assistant chat route

Main endpoint that handles chat interactions and coordinates routing.

POST /api/assistant/chat

Request:

{
  "messages": [...],
  "agentId": "chief",
  "projectContext": {
    "projectId": "uuid",
    "projectName": "string",
    "projectDomain": "string"
  }
}

Response:

{
  "message": "AI response text",
  "routedAgent": "webEngineer",
  "executedTask": {...},
  "usage": {...}
}

Execution route

Endpoint used by agents to execute structured tasks.

POST /api/assistant/execute

Request:

{
  "taskType": "create_page",
  "parameters": {...},
  "projectId": "uuid",
  "conversationId": "uuid"
}

Database Schema

The assistant system uses dedicated tables to store conversations, messages, and tasks. Agent related configuration can live either in a specific agent definition table or inside JSON configuration for the tenant.

assistant_conversations

id             uuid primary key
tenant_id      uuid
user_id        uuid
started_at     timestamptz
closed_at      timestamptz
active_flag    boolean
metadata       jsonb
current_agent  text default 'chief'

assistant_messages

id               uuid primary key
conversation_id uuid references assistant_conversations
author           text            -- 'user' or 'agent'
agent_id         text            -- which agent produced the message
kind             text            -- 'text' or 'status' or 'form'
text             text
created_at       timestamptz

assistant_tasks

id               uuid primary key
conversation_id  uuid references assistant_conversations
status           text            -- 'open', 'in_progress', 'completed', 'cancelled'
action           text
target           text
intent           text
priority         text            -- 'low', 'medium', 'high', 'urgent'
notes            text
created_at       timestamptz
updated_at       timestamptz

Optional agent definitions

Agent definitions can be stored in a dedicated table such as assistant_agent_definitions or inside tenant configuration JSON. A typical record would include:

• Agent identifier such as chief or webEngineer
• Display name and avatar configuration
• Role description and capabilities
• Default tools and allowed task types
• Ordering and visibility flags in the panel

Workflow Logic

The workflow logic for the AISTEAM assistant system is documented in detail in a separate comprehensive reference document. This document, called the "Assistant System Bible", covers the complete architecture, message lifecycle, routing decisions, validation rules, execution model, and implementation patterns.

The workflow document is essential reading for developers working on the assistant system, as it provides the source of truth for how the system behaves at every level.

Key Topics Covered

• Message lifecycle and experience timeline
• Agent selection and routing logic
• Validation and escalation rules
• Project context and scoping
• Execution model and task contracts
• Logging and experience tracking
• UI behavior and error handling
• API contracts and database schema
• Implementation patterns and best practices

Related Files

• app/api/assistant/chat/route.ts, main chat API and routing
• app/api/assistant/execute/route.ts, task execution API
• app/assistant/AssistantPanel.tsx, centralized agent panel UI
• app/assistant/AssistantProvider.tsx, assistant state management
• app/assistant/supervisor/ChiefAIOfficer.tsx, supervisor logic
• supabase/migrations/assistant_schema.sql, database schema
• Optional, supabase/migrations/assistant_agent_definitions.sql for agent catalog