yao/agent/autonomous/DESIGN.md

Autonomous Agent

1. What is it?

An Autonomous Agent is an AI team member. It works on its own, makes decisions, and runs tasks without waiting for user input.

Key points:

• Belongs to a Team, managed like human members
• Has clear job duties (e.g., "Sales Manager: track KPIs, make reports")
• Created and deleted via Team API
• Runs on schedule, or when triggered by humans or events
• Learns from each run, stores knowledge in private KB

---

2. Architecture

2.1 System Flow

flowchart TB
    subgraph Triggers["Triggers"]
        WC[/"⏰ Clock"/]
        HI[/"👤 Human"/]
        EV[/"📡 Event"/]
    end

    subgraph Manager["Manager"]
        TC{"Enabled?"}
        Cache[("Cache")]
        Dedup{"Dedup?"}
        Queue["Queue"]
    end

    subgraph Pool["Workers"]
        W1["Worker"]
        W2["Worker"]
        W3["Worker"]
    end

    subgraph Executor["Executor"]
        TT{"Trigger?"}
        P0["P0: Inspiration"]
        P1["P1: Goals"]
        P2["P2: Tasks"]
        P3["P3: Run"]
        P4["P4: Deliver"]
        P5["P5: Learn"]
    end

    subgraph Storage["Storage"]
        KB[("KB")]
        DB[("DB")]
        Job[("Job")]
    end

    WC --> TC
    HI & EV --> TC
    TC -->|Yes| Cache
    TC -->|No| X[/Skip/]
    Cache --> Dedup
    Dedup -->|OK| Queue
    Dedup -->|Dup| Cache
    Queue --> W1 & W2 & W3
    W1 & W2 & W3 --> TT
    TT -->|Clock| P0
    TT -->|Human/Event| P1
    P0 --> P1 --> P2 --> P3 --> P4 --> P5
    P5 --> KB & DB & Job
    KB -.->|History| P0

2.2 Team Structure

AI members live in team_members table with member_type = "ai":

┌─────────────────────────────────────────────────────────────────┐
│                            Team                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    AI Members                            │    │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐        │    │
│  │  │Sales Manager│ │Data Analyst │ │CS Specialist│        │    │
│  │  │ • Track KPIs│ │ • Analyze   │ │ • Tickets   │        │    │
│  │  │ • Reports   │ │ • Reports   │ │ • Inquiries │        │    │
│  │  └─────────────┘ └─────────────┘ └─────────────┘        │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Human Members                          │    │
│  │  ┌─────────────┐ ┌─────────────┐                        │    │
│  │  │ John (Owner)│ │ Jane (Admin)│                        │    │
│  │  └─────────────┘ └─────────────┘                        │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

CREATE TABLE team_members (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    team_id VARCHAR(64) NOT NULL,
    user_id VARCHAR(64),              -- for humans
    member_type VARCHAR(32) NOT NULL, -- "user" | "ai"
    agent_id VARCHAR(64),             -- for AI only
    agent_config JSON,                -- AI config
    status VARCHAR(32) DEFAULT 'active',
    INDEX idx_team_id (team_id),
    INDEX idx_agent_id (agent_id)
);

---

3. How It Works

3.1 Flow: Trigger → Schedule → Run

sequenceDiagram
    autonumber
    participant T as Trigger
    participant M as Manager
    participant S as Scheduler
    participant W as Worker
    participant E as Executor
    participant A as Phase Agents
    participant KB as KB

    T->>M: Event
    M->>M: Check enabled
    M->>M: Get from cache
    M->>M: Check dedup
    M->>S: Submit

    S->>S: Check quota
    S->>S: Sort by priority
    S->>W: Dispatch

    W->>E: Run

    alt Clock trigger
        E->>A: P0: Inspiration (with clock context)
        A-->>E: Report
    end

    loop P1 to P5
        E->>A: Call agent
        A-->>E: Result
    end

    E->>KB: Save learning
    E-->>W: Done

3.2 Triggers

Type	What	Config
Clock	Timer (times/interval/daemon)	triggers.clock
Human	Manual action	triggers.intervene
Event	Webhook, DB change	triggers.event

All on by default. Turn off per agent:

triggers:
  clock: { enabled: true }
  intervene: { enabled: true, actions: ["add_task", "pause"] }
  event: { enabled: false }

3.3 Concurrency

Two levels to prevent one agent from using all resources:

┌─────────────────────────────────────────────────────────────────┐
│                    Global Pool (10 workers)                      │
└─────────────────────────────────────────────────────────────────┘
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Sales Manager   │ │ Data Analyst    │ │ CS Specialist   │
│ Limit: 3        │ │ Limit: 2        │ │ Limit: 3        │
│ Now: 2 ✓        │ │ Now: 2 (full)   │ │ Now: 1 ✓        │
└─────────────────┘ └─────────────────┘ └─────────────────┘

3.4 Dedup

Fast check (in memory):

key := agentID + ":" + triggerType + ":" + window
if has(key) { skip }

Smart check (for goals/tasks):

• Dedup Agent looks at history
• Returns: skip | merge | proceed

3.5 Cache

Keeps agents in memory. No DB query on each tick:

type AgentCache struct {
    agents map[string]*Agent   // agent_id -> agent
    byTeam map[string][]string // team_id -> agent_ids
}
// Refresh: on start, on change, every hour

---

4. Phases

4.1 Overview

Clock:        P0 → P1 → P2 → P3 → P4 → P5
Human/Event:       P1 → P2 → P3 → P4 → P5

Phase	Agent	In	Out	When
P0	Inspiration	Clock + Data + News	Report	Clock only
P1	Goal Gen	Report + history	Goals	Always
P2	Task Plan	Goals + tools	Tasks	Always
P3	Validator	Results	Checked results	Always
P4	Delivery	All results	Email/File	Always
P5	Learning	Summary	KB entries	Always

4.2 P0: Inspiration (Clock only)

Skipped for Human/Event triggers. They already have clear intent.

Gathers info to help make good goals. Clock context is key input - Agent knows what time it is and can decide what to do (e.g., 5pm Friday → write weekly report).

type InspirationReport struct {
    Clock         ClockContext   // Current time context
    Summary       string         // What's happening
    Highlights    []Highlight    // Key changes
    Opportunities []Opportunity  // Chances to act
    Risks         []Risk         // Things to watch
    WorldInsights []WorldInsight // News from outside
    Suggestions   []string       // What to focus on
}

type ClockContext struct {
    Now          time.Time // Current time
    Hour         int       // 0-23
    DayOfWeek    string    // Monday, Tuesday...
    DayOfMonth   int       // 1-31
    IsWeekend    bool
    IsMonthStart bool      // 1st-3rd
    IsMonthEnd   bool      // last 3 days
    IsQuarterEnd bool
    // Agent uses this to decide: "It's 5pm Friday, time for weekly report"
}

Sources:

• Clock: Current time, day of week, month end, etc.
• Internal: Data changes, events, feedback, pending work
• External: Web search (news, competitors)

4.3 P1: Goals

For Clock: Uses inspiration report (with clock context) to make goals. Agent decides based on time what's important now.

For Human/Event: Uses the input directly as goals (or to generate goals).

Prompt:
You are [Sales Manager]. Your job: [track KPIs, make reports].

## Report
### Key Items
- [High] Data: 15 new sales (+50%)
- [High] Deadline: Friday report due
- [High] News: Competitor launched product

### Chances
- Sales up 20% vs last week
- Market growing

Make today's goals.

4.4 P2: Tasks

Breaks goals into steps:

type Task struct {
    ID           string
    GoalID       string
    Description  string
    ExecutorType string // "assistant" | "mcp"
    ExecutorID   string
}

4.5 P3: Run

For each task:

1. Call Assistant or MCP Tool
2. Get result
3. Validate
4. Update status

4.6 P4: Deliver

Send output:

delivery:
  type: email # email | file | webhook | notify
  opts:
    to: ["manager@company.com"]

4.7 P5: Learn

Save to KB:

Type	Examples
execution	What worked, what failed
feedback	Errors, fixes
insight	Patterns, tips

---

5. Config

5.1 Structure

type Config struct {
    Triggers  *Triggers  `json:"triggers,omitempty"`
    Clock     *Clock     `json:"clock,omitempty"`
    Identity  *Identity  `json:"identity"`
    Quota     *Quota     `json:"quota"`
    PrivateKB *KB        `json:"private_kb"`
    SharedKB  *KB        `json:"shared_kb,omitempty"`
    Resources *Resources `json:"resources"`
    Delivery  *Delivery  `json:"delivery"`
    Input     *Input     `json:"input,omitempty"`
    Events    []Event    `json:"events,omitempty"`
    Monitor   *Monitor   `json:"monitor,omitempty"`
}

5.2 Types

// Phase - execution phase enum
type Phase string

const (
    PhaseInspiration Phase = "inspiration" // P0: Clock only
    PhaseGoals       Phase = "goals"       // P1
    PhaseTasks       Phase = "tasks"       // P2
    PhaseValidation  Phase = "validation"  // P3
    PhaseDelivery    Phase = "delivery"    // P4
    PhaseLearning    Phase = "learning"    // P5
)

// AllPhases for iteration
var AllPhases = []Phase{
    PhaseInspiration, PhaseGoals, PhaseTasks,
    PhaseValidation, PhaseDelivery, PhaseLearning,
}

// ClockMode - clock trigger mode enum
type ClockMode string

const (
    ClockModeTimes    ClockMode = "times"    // run at specific times
    ClockModeInterval ClockMode = "interval" // run every X duration
    ClockModeDaemon   ClockMode = "daemon"   // run continuously
)

// DeliveryType - output delivery type enum
type DeliveryType string

const (
    DeliveryEmail   DeliveryType = "email"
    DeliveryFile    DeliveryType = "file"
    DeliveryWebhook DeliveryType = "webhook"
    DeliveryNotify  DeliveryType = "notify"
)

// Status - execution status enum
type Status string

const (
    StatusPending   Status = "pending"
    StatusRunning   Status = "running"
    StatusCompleted Status = "completed"
    StatusFailed    Status = "failed"
)

// Triggers - all on by default
type Triggers struct {
    Clock     *Trigger `json:"clock,omitempty"`
    Intervene *Trigger `json:"intervene,omitempty"`
    Event     *Trigger `json:"event,omitempty"`
}

type Trigger struct {
    Enabled bool     `json:"enabled"`
    Actions []string `json:"actions,omitempty"` // for intervene
}

// Clock - when to wake up
type Clock struct {
    Mode    ClockMode `json:"mode"`
    Times   []string  `json:"times"`   // for times: ["09:00", "14:00"]
    Days    []string  `json:"days"`    // ["Mon", "Tue"...] or ["*"]
    Every   string    `json:"every"`   // for interval: "30m", "1h"
    TZ      string    `json:"tz"`      // Asia/Shanghai
    Timeout string    `json:"timeout"` // max run time
}

// Identity
type Identity struct {
    Role   string   `json:"role"`
    Duties []string `json:"duties"`
    Rules  []string `json:"rules"`
}

// Quota
type Quota struct {
    Max      int `json:"max"`      // max running (default: 2)
    Queue    int `json:"queue"`    // queue size (default: 10)
    Priority int `json:"priority"` // 1-10 (default: 5)
}

// KB
type KB struct {
    ID    string   `json:"id,omitempty"`
    Refs  []string `json:"refs,omitempty"`
    Learn *Learn   `json:"learn,omitempty"`
}

type Learn struct {
    On    bool     `json:"on"`
    Types []string `json:"types"` // execution, feedback, insight
    Keep  int      `json:"keep"`  // days, 0 = forever
}

// Resources
type Resources struct {
    Phases map[Phase]string `json:"phases,omitempty"` // optional, defaults to __yao.{phase}
    Agents []string         `json:"agents"`
    MCP    []MCP            `json:"mcp"`
}

type MCP struct {
    ID    string   `json:"id"`
    Tools []string `json:"tools,omitempty"` // empty = all
}

// Delivery
type Delivery struct {
    Type DeliveryType           `json:"type"`
    Opts map[string]interface{} `json:"opts"`
}

// Monitor
type Monitor struct {
    On     bool    `json:"on"`
    Alerts []Alert `json:"alerts,omitempty"`
}

type Alert struct {
    Name     string   `json:"name"`
    When     string   `json:"when"`  // failed | timeout | error_rate
    Value    float64  `json:"value"`
    Window   string   `json:"window"` // 1h | 24h
    Do       []Action `json:"do"`
    Cooldown string   `json:"cooldown"`
}

type Action struct {
    Type string                 `json:"type"` // email | webhook | notify
    Opts map[string]interface{} `json:"opts"`
}

5.3 Example

{
  "member_type": "ai",
  "agent_id": "sales-bot",
  "agent_config": {
    "triggers": {
      "clock": { "enabled": true },
      "intervene": { "enabled": true },
      "event": { "enabled": false }
    },
    "clock": {
      "mode": "times",
      "times": ["09:00", "14:00", "17:00"],
      "days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
      "tz": "Asia/Shanghai",
      "timeout": "30m"
    },
    "identity": {
      "role": "Sales Analyst",
      "duties": ["Analyze sales", "Make weekly reports"],
      "rules": ["Only access sales data"]
    },
    "quota": { "max": 2, "queue": 10, "priority": 5 },
    "private_kb": {
      "learn": {
        "on": true,
        "types": ["execution", "feedback", "insight"],
        "keep": 90
      }
    },
    "shared_kb": { "refs": ["sales-policies", "products"] },
    "resources": {
      "phases": {
        "inspiration": "__yao.inspiration",
        "goals": "__yao.goals",
        "tasks": "__yao.tasks",
        "validation": "__yao.validation",
        "delivery": "__yao.delivery",
        "learning": "__yao.learning"
      },
      "agents": ["data-analyst", "chart-gen"],
      "mcp": [{ "id": "database", "tools": ["query"] }]
    },
    "delivery": {
      "type": "email",
      "opts": { "to": ["manager@company.com"] }
    }
  }
}

---

6. Lifecycle

6.1 Agent States

stateDiagram-v2
    [*] --> Active: POST create
    Active --> Paused: PATCH pause
    Paused --> Active: PATCH resume
    Active --> [*]: DELETE
    Paused --> [*]: DELETE

From	To	How
-	active	POST create
active	paused	PATCH status="paused"
paused	active	PATCH status="active"
any	deleted	DELETE

6.2 On Create

1. Check config
2. Make agent_id if missing
3. Create KB: agent_{team_id}_{agent_id}_kb
4. Add to cache
5. Create Job
6. Set active

6.3 On Delete

1. Stop running jobs
2. Remove from cache
3. Delete Job
4. Delete or archive KB
5. Soft delete record

6.4 Execution Flow

Single execution flow, depends on trigger type:

flowchart LR
    subgraph Trigger
        T{Trigger}
    end

    subgraph Schedule Path
        P0[P0: Inspiration]
    end

    subgraph Common Path
        P1[P1: Goals]
        P2[P2: Tasks]
        P3[P3: Run]
        P4[P4: Deliver]
        P5[P5: Learn]
    end

    T -->|Clock| P0
    T -->|Human/Event| P1
    P0 --> P1
    P1 --> P2 --> P3 --> P4 --> P5

stateDiagram-v2
    [*] --> Triggered
    Triggered --> P0_Inspiration: Clock
    Triggered --> P1_Goals: Human/Event
    P0_Inspiration --> P1_Goals
    P1_Goals --> P2_Tasks
    P2_Tasks --> P3_Run
    P3_Run --> P4_Deliver
    P4_Deliver --> P5_Learn
    P5_Learn --> [*]

---

7. Integrations

7.1 Job System

Each agent = 1 Job. Each run = 1 Execution.

┌─────────────────────────────────────────────────────────────────┐
│                    Activity Monitor (UI)                         │
│  • List jobs                                                     │
│  • See progress                                                  │
│  • View logs                                                     │
│  • Cancel/retry                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Job Framework                               │
│  Job → Execution → Progress → Logs                               │
└─────────────────────────────────────────────────────────────────┘

APIs:

Action	API
List	GET /api/jobs?category_id=autonomous_agent
History	GET /api/jobs/:job_id/executions
Progress	GET /api/jobs/:job_id/executions/:id
Logs	GET /api/jobs/:job_id/executions/:id/logs
Cancel	POST /api/jobs/:job_id/stop
Trigger	POST /api/jobs/:job_id/trigger

7.2 Private KB

Made on agent create: agent_{team_id}_{agent_id}_kb

What it stores:

• execution: What worked, what failed
• feedback: Errors, fixes
• insight: Patterns, tips

When:

• Create: On agent create
• Update: After P5
• Clean: Based on keep days
• Delete: On agent delete

7.3 External Input

Types:

• clock: Timer (with time context)
• intervene: Human action
• event: Webhook, DB change
• callback: Async result

Human actions:

• adjust_goal: Change goal
• add_task: Add task
• cancel_task: Stop task
• pause / resume / abort
• plan: Do later

Plan Queue:

• Holds tasks for later
• Runs at next cycle start

---

8. API

8.1 Manager (Internal)

type Manager interface {
    // Lifecycle
    Start() error
    Stop() error

    // Cache
    LoadActiveAgents(ctx context.Context) error
    GetAgent(teamID, agentID string) *Agent

    // Clock trigger (internal, called by ticker)
    Tick(ctx context.Context, now time.Time) error
}

8.2 Trigger (Called by openapi layer)

// TriggerType enum
type TriggerType string

const (
    TriggerClock TriggerType = "clock"
    TriggerHuman TriggerType = "human"
    TriggerEvent TriggerType = "event"
)

// Trigger interface - called by openapi handlers
type Trigger interface {
    // Human intervention
    Intervene(ctx context.Context, req InterveneRequest) (*ExecutionResult, error)

    // Event trigger (webhook, db change)
    HandleEvent(ctx context.Context, req EventRequest) (*ExecutionResult, error)

    // Query & control
    GetStatus(ctx context.Context, teamID, agentID string) (*AgentStatus, error)
    Pause(ctx context.Context, teamID, agentID string) error
    Resume(ctx context.Context, teamID, agentID string) error
}

type InterveneRequest struct {
    TeamID      string
    AgentID     string
    Action      string // add_task | adjust_goal | cancel_task | pause | resume | abort | plan
    Description string
    Priority    string    // high | normal | low
    PlanTime    time.Time // for action=plan
}

type EventRequest struct {
    AgentID   string
    Source    string // webhook path or table name
    EventType string // lead.created, etc.
    Data      map[string]interface{}
}

type ExecutionResult struct {
    ExecutionID string // Job execution ID
    Status      Status
}

type AgentStatus struct {
    AgentID   string
    Status    string // active | paused | running
    LastRun   time.Time
    NextRun   time.Time
    RunningID string // current execution ID if running
}

8.4 Execution (Uses Job System)

No separate autonomous_executions table. Uses existing Job system:

// On agent create
job.Create(Job{
    ID:         "agent_" + agentID,
    CategoryID: "autonomous_agent",
    Name:       agent.Identity.Role,
    Handler:    "autonomous.Execute",
    Args:       map[string]interface{}{"agent_id": agentID},
})

// On trigger (clock/human/event)
job.Push(jobID, ExecutionArgs{
    TriggerType: TriggerClock, // or TriggerHuman, TriggerEvent
    TriggerData: data,
})

// Query history
executions := job.GetExecutions(jobID, limit)
logs := job.GetLogs(executionID)

Job APIs for monitoring:

Action	API
List	GET /api/jobs?category=autonomous_agent
Status	GET /api/jobs/:job_id
History	GET /api/jobs/:job_id/executions
Logs	GET /api/jobs/:job_id/executions/:id/logs
Cancel	POST /api/jobs/:job_id/cancel

---

9. Security

1. Team only: Agent sees only its team's data
2. Role rules: Uses role_id permissions
3. Limited tools: Only what's in resources
4. Timeout: Stops if runs too long
5. Logs: All runs saved

---

10. Quick Ref

Triggers

triggers:
  clock: { enabled: true }
  intervene: { enabled: true, actions: [...] }
  event: { enabled: false }

Clock

# Mode 1: Specific times
clock:
  mode: times
  times: ["09:00", "14:00", "17:00"]
  days: ["Mon", "Tue", "Wed", "Thu", "Fri"]
  tz: Asia/Shanghai
  timeout: 30m

# Mode 2: Interval
clock:
  mode: interval
  every: 30m  # run every 30 minutes
  timeout: 10m

# Mode 3: Daemon (continuous thinking/analysis)
clock:
  mode: daemon  # restart immediately after each run
  timeout: 10m  # max time per run
  # Use case: Research analyst, market monitor

Phase Agents

# Optional - defaults to __yao.{phase} if not specified
resources:
  phases:
    inspiration: "__yao.inspiration" # Clock only
    goals: "__yao.goals"
    tasks: "__yao.tasks"
    validation: "__yao.validation"
    delivery: "__yao.delivery"
    learning: "__yao.learning"

Quota

quota:
  max: 2 # max running
  queue: 10 # queue size
  priority: 5 # 1-10

---

11. Examples

Each example shows a different trigger mode:

Example	Trigger	Mode	Scenario
11.1	Clock	times	SEO/GEO Content - daily content optimization
11.2	Clock	interval	Competitor Monitor - check every 2 hours
11.3	Clock	daemon	Research Analyst - continuous insight mining
11.4	Human	intervene	Sales Assistant - manager assigns tasks
11.5	Event	webhook	Lead Processor - qualify and route new leads

---

11.1 SEO/GEO Content Agent (Clock: times)

Trigger: Clock - specific times daily

Role: AI Marketing - auto-generate and optimize SEO/GEO content.

{
  "agent_id": "seo-content",
  "agent_config": {
    "triggers": {
      "clock": { "enabled": true },
      "intervene": { "enabled": true }
    },
    "clock": {
      "mode": "times",
      "times": ["06:00", "18:00"],
      "days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
      "tz": "Asia/Shanghai"
    },
    "identity": {
      "role": "SEO/GEO Content Specialist",
      "duties": [
        "Research trending keywords in our industry",
        "Generate SEO-optimized articles (2-3 per day)",
        "Optimize existing content for GEO (AI search)",
        "Track keyword rankings and adjust strategy",
        "A/B test titles and meta descriptions"
      ]
    },
    "resources": {
      "agents": ["keyword-researcher", "content-writer", "seo-optimizer"],
      "mcp": [
        { "id": "google-search", "tools": ["trends", "rankings"] },
        { "id": "cms", "tools": ["create", "update", "publish"] }
      ]
    },
    "delivery": {
      "type": "notify",
      "opts": { "channel": "marketing-team" }
    }
  }
}

Example run at 06:00 Monday:

P0 Inspiration:
  Clock: Monday 06:00, start of week
  Data:
    - Keyword "AI app development" trending (+45% this week)
    - Our article ranks #8, competitor #2
    - 3 articles need GEO optimization
  World: New AI regulation announced last Friday

P1 Goals:
  1. Write new article targeting "AI app development"
  2. Optimize 3 old articles for GEO
  3. Update meta descriptions for top 5 pages

P2 Tasks:
  1. Research "AI app development" keywords → keyword-researcher
  2. Write article with SEO structure → content-writer
  3. Add FAQ schema for GEO → seo-optimizer
  4. Publish to CMS → cms.publish

P3 Execute:
  - Keywords: "AI app development", "build AI apps", "AI dev guide" (12 total)
  - Article: 2500 words, 8 sections, FAQ schema added
  - Published to CMS, indexed by Google

P4 Delivery:
  → Notify: "Published: 'Complete Guide to AI App Development' - targeting 12 keywords"

P5 Learn:
  - "AI app development" articles perform well on Monday morning
  - FAQ schema improves GEO visibility by 30%

---

11.2 Competitor Monitor (Clock: interval)

Trigger: Clock - every 2 hours

Role: Monitor competitors, track market changes, alert on important updates.

{
  "agent_id": "competitor-monitor",
  "agent_config": {
    "triggers": {
      "clock": { "enabled": true }
    },
    "clock": {
      "mode": "interval",
      "every": "2h"
    },
    "identity": {
      "role": "Competitor Intelligence Analyst",
      "duties": [
        "Monitor competitor websites for changes",
        "Track competitor pricing updates",
        "Watch for new product launches",
        "Analyze competitor content strategy",
        "Alert team on significant changes"
      ]
    },
    "resources": {
      "agents": ["web-scraper", "diff-analyzer", "report-writer"],
      "mcp": [{ "id": "web-search", "tools": ["search", "news"] }]
    },
    "delivery": {
      "type": "webhook",
      "opts": { "url": "https://slack.com/webhook/competitor-alerts" }
    }
  }
}

Example run detecting competitor change:

P0 Inspiration:
  Clock: Tuesday 14:00
  Data:
    - Competitor A: pricing page changed
    - Competitor B: new blog post about "AI agents"
    - Competitor C: no changes

P1 Goals:
  1. Analyze Competitor A pricing change
  2. Summarize Competitor B's new content
  3. Assess impact on our positioning

P2 Tasks:
  1. Scrape old vs new pricing → web-scraper
  2. Compare pricing tiers → diff-analyzer
  3. Generate competitive analysis → report-writer

P3 Execute:
  - Competitor A: dropped price 20% on enterprise tier
  - Competitor B: targeting same keywords as us

P4 Delivery:
  → Slack: "🚨 Competitor A cut enterprise price 20% - review needed"

P5 Learn:
  - Competitor A tends to change pricing on Tuesdays
  - Price changes often precede feature launches

---

11.3 Industry Research Analyst (Clock: daemon)

Trigger: Clock - continuous daemon mode

Role: Continuously read industry news, papers, social media; extract insights; build knowledge.

{
  "agent_id": "research-analyst",
  "agent_config": {
    "triggers": {
      "clock": { "enabled": true }
    },
    "clock": {
      "mode": "daemon",
      "timeout": "10m"
    },
    "identity": {
      "role": "Industry Research Analyst",
      "duties": [
        "Continuously scan industry news and papers",
        "Analyze trends and extract key insights",
        "Identify emerging technologies and competitors",
        "Build and maintain industry knowledge base",
        "Alert team on significant developments"
      ]
    },
    "resources": {
      "agents": ["content-reader", "insight-extractor", "report-writer"],
      "mcp": [
        { "id": "web-search", "tools": ["search", "news"] },
        { "id": "arxiv", "tools": ["search", "fetch"] },
        { "id": "twitter", "tools": ["search", "trends"] }
      ]
    },
    "delivery": {
      "type": "notify",
      "opts": { "channel": "research-insights" }
    }
  }
}

Example continuous run:

Run #1 (09:00):
  P0: Scan sources
      - 15 new AI news articles
      - 3 new papers on arXiv
      - Twitter: "AI Agent" trending
  P1: Goals:
      1. Read and analyze new content
      2. Extract insights relevant to our business
      3. Update knowledge base
  P2: Tasks:
      1. Read articles → content-reader
      2. Analyze papers → content-reader
      3. Extract insights → insight-extractor
  P3: Execute:
      - Article: "OpenAI releases new agent framework"
        Insight: Validates our direction, watch for API changes
      - Paper: "Multi-agent collaboration patterns"
        Insight: Useful for our agent design, save to KB
      - Twitter: Sentiment positive on AI agents
  P4: Notify: "📚 3 new insights added to KB"
  P5: Learn: OpenAI news = high relevance, prioritize
  → Restart immediately

Run #2 (09:12):
  P0: Scan sources
      - 2 new articles (low relevance)
      - No new papers
      - Twitter: Normal activity
  P1: Low-value content, skip deep analysis
  P5: Learn: Mid-morning usually quiet
  → Restart immediately

Run #3 (09:25):
  P0: Scan sources
      - Breaking: "Competitor X raises $100M for AI platform"
  P1: Goals:
      1. Deep analyze competitor news
      2. Assess impact on our market
      3. Alert team immediately
  P2: Tasks:
      1. Gather all competitor X info → web-search
      2. Analyze their positioning → insight-extractor
      3. Write competitive brief → report-writer
  P3: Execute:
      - Competitor X: Focus on enterprise, similar target market
      - Funding: Will likely expand sales team
      - Threat level: Medium-High
  P4: Notify: "🚨 Competitor X raised $100M - brief attached"
  P5: Learn: Funding news = always high priority
  → Restart immediately

---

11.4 Sales Assistant (Human: intervene)

Trigger: Human intervention - sales manager assigns tasks

Role: Help sales team with research, proposals, follow-ups when manager assigns work.

{
  "agent_id": "sales-assistant",
  "agent_config": {
    "triggers": {
      "clock": { "enabled": false },
      "intervene": {
        "enabled": true,
        "actions": ["add_task", "adjust_goal", "pause"]
      }
    },
    "identity": {
      "role": "Sales Assistant",
      "duties": [
        "Research assigned prospects and companies",
        "Prepare customized proposals and presentations",
        "Draft follow-up emails",
        "Analyze deal history and suggest strategies",
        "Prepare meeting briefs"
      ]
    },
    "resources": {
      "agents": ["company-researcher", "proposal-writer", "email-drafter"],
      "mcp": [
        { "id": "crm", "tools": ["query", "update"] },
        { "id": "linkedin", "tools": ["search", "profile"] },
        { "id": "email", "tools": ["draft", "send"] }
      ]
    },
    "delivery": {
      "type": "email",
      "opts": { "to": ["sales-manager@company.com"] }
    }
  }
}

Example: Sales manager assigns task:

Sales Manager Input:
  Action: add_task
  Description: "Meeting with BigCorp CTO tomorrow. Prepare materials.
               They do smart manufacturing, $150M revenue, digital transformation."

Agent Execution (no P0 for human trigger):
  P1 Goals (from human input):
    1. Research BigCorp and their CTO
    2. Prepare meeting brief
    3. Draft customized proposal

  P2 Tasks:
    1. Research BigCorp → company-researcher
       - Company background, recent news
       - Digital transformation status
       - Potential pain points
    2. Research CTO profile → linkedin.profile
       - Background, interests
       - Recent posts/articles
    3. Prepare meeting brief → proposal-writer
    4. Draft proposal → proposal-writer

  P3 Execute:
    - BigCorp: Leading smart manufacturing, 3 factories, implementing MES
    - CTO John: Ex-Google, focused on AI+Manufacturing, recent post on "AI QC"
    - Pain point: High QC labor cost, 2% defect miss rate
    - Opportunity: Our AI QC solution can reduce miss rate to 0.1%

  P4 Delivery:
    → Email to sales manager:
      - Attachment 1: BigCorp Research Report (PDF)
      - Attachment 2: CTO Profile Brief
      - Attachment 3: Custom Proposal - AI QC Solution
      - Attachment 4: Meeting Agenda Suggestion

Sales Manager Follow-up:
  Action: add_task
  Description: "Also prepare some similar case studies, manufacturing preferred"

Agent Continues:
  P1: Find similar manufacturing case studies
  P2: Search CRM for manufacturing wins
  P3: Found 3 cases: Auto parts factory, Electronics plant, Food processing
  P4: Email: "3 manufacturing case studies attached"
  P5: Learn: Manufacturing prospects often need QC case studies

---

11.5 Lead Processor (Event: webhook)

Trigger: Event - new lead from website/CRM

Role: Instantly process and qualify new leads, route to sales.

{
  "agent_id": "lead-processor",
  "agent_config": {
    "triggers": {
      "clock": { "enabled": false },
      "event": { "enabled": true }
    },
    "events": [
      {
        "type": "webhook",
        "source": "/webhook/leads",
        "filter": { "event_types": ["lead.created"] }
      },
      {
        "type": "database",
        "source": "crm_leads",
        "filter": { "trigger": "insert" }
      }
    ],
    "identity": {
      "role": "Lead Qualification Specialist",
      "duties": [
        "Instantly process new leads",
        "Enrich lead data (company info, LinkedIn)",
        "Score lead quality (1-100)",
        "Route hot leads to sales immediately",
        "Add cold leads to nurture sequence"
      ]
    },
    "resources": {
      "agents": ["data-enricher", "lead-scorer"],
      "mcp": [
        { "id": "clearbit", "tools": ["enrich"] },
        { "id": "crm", "tools": ["update", "assign"] },
        { "id": "email", "tools": ["send"] }
      ]
    },
    "delivery": {
      "type": "webhook",
      "opts": { "url": "https://slack.com/webhook/sales-leads" }
    }
  }
}

Example: New lead event:

Event Received:
  Type: lead.created
  Data: {
    name: "John Smith",
    email: "john@bigcorp.com",
    company: "BigCorp",
    message: "Interested in Enterprise pricing, team of 50"
  }

Agent Execution (no P0 for events):
  P1 Goals:
    1. Enrich lead data
    2. Score lead quality
    3. Route appropriately

  P2 Tasks:
    1. Lookup company info → clearbit.enrich
    2. Calculate lead score → lead-scorer
    3. Update CRM → crm.update
    4. Notify sales → slack webhook

  P3 Execute:
    - Company: BigCorp, 500 employees, Series C
    - LinkedIn: VP of Engineering
    - Lead Score: 85/100 (HOT)
    - Reason: Enterprise inquiry, decision maker, funded company

  P4 Delivery:
    → Slack: "🔥 HOT LEAD (85/100): John Smith @ BigCorp
              - 500 employees, Series C
              - Interested in Enterprise (50 seats)
              - Assigned to: Sales Rep A"
    → CRM: Lead updated, assigned to Sales Rep A
    → Email to lead: "Thanks for your inquiry. Our sales rep will contact you within 1 hour."

  P5 Learn:
    - BigCorp profile saved for future reference
    - VP-level leads from funded companies = high conversion