From 46d815affcf409907f6c2f031bb4dfac77769a51 Mon Sep 17 00:00:00 2001 From: Max Date: Tue, 13 Jan 2026 08:58:19 +0800 Subject: [PATCH] Refactor Autonomous Agent Design Document for Improved Clarity and Structure - Revised the document to enhance clarity by updating section titles and terminology, such as changing "Overview" to "What is it?" and "Key Characteristics" to "Key points." - Streamlined the architecture section, renaming components for consistency and clarity, including changes to trigger sources and agent management terminology. - Updated execution flow diagrams and descriptions to reflect the new structure, improving understanding of the agent's operational phases. - Enhanced the configuration section to provide a clearer overview of triggers, scheduling, and resource management, ensuring better organization throughout the document. --- agent/autonomous/DESIGN.md | 498 ++++++++++++++++++------------------- 1 file changed, 245 insertions(+), 253 deletions(-) diff --git a/agent/autonomous/DESIGN.md b/agent/autonomous/DESIGN.md index c41d61eb..50b97299 100644 --- a/agent/autonomous/DESIGN.md +++ b/agent/autonomous/DESIGN.md @@ -1,39 +1,39 @@ -# Autonomous Agent Design Document +# Autonomous Agent -## 1. Overview +## 1. What is it? -An **Autonomous Agent** is an AI team member that operates independently, makes decisions, and executes tasks proactively. Unlike Assistants that respond to user requests, Autonomous Agents run periodically based on job responsibilities. +An **Autonomous Agent** is an AI team member. It works on its own, makes decisions, and runs tasks without waiting for user input. -**Key Characteristics:** +**Key points:** -- **Team Member**: Managed like human members, belongs to a Team -- **Job Responsibilities**: Has defined duties (e.g., "Sales Manager tracks KPIs") -- **Dynamic Lifecycle**: Created/destroyed via Team API -- **Multi-Trigger**: Activated by schedule, human intervention, or events -- **Self-Learning**: Maintains private knowledge base, learns from execution +- 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 Overview +### 2.1 System Flow ```mermaid flowchart TB - subgraph Triggers["Trigger Sources"] - WC[/"⏰ World Clock
(Schedule)"/] - HI[/"πŸ‘€ Human
(Intervene)"/] - EV[/"πŸ“‘ Events
(Webhook/DB)"/] + subgraph Triggers["Triggers"] + WC[/"⏰ Schedule"/] + HI[/"πŸ‘€ Human"/] + EV[/"πŸ“‘ Event"/] end - subgraph Manager["Agent Manager"] - TC{"Trigger
Enabled?"} - Cache[("Agent Cache")] - Dedup{"Dedup
Check"} - Queue["Priority Queue"] + subgraph Manager["Manager"] + TC{"Enabled?"} + Cache[("Cache")] + Dedup{"Dedup?"} + Queue["Queue"] end - subgraph Pool["Worker Pool"] + subgraph Pool["Workers"] W1["Worker"] W2["Worker"] W3["Worker"] @@ -43,33 +43,33 @@ flowchart TB P0["P0: Inspiration"] P1["P1: Goals"] P2["P2: Tasks"] - P3["P3: Execute"] + P3["P3: Run"] P4["P4: Deliver"] P5["P5: Learn"] end subgraph Storage["Storage"] - KB[("Private KB")] - DB[("Executions")] - Job[("Job System")] + KB[("KB")] + DB[("DB")] + Job[("Job")] end WC & HI & EV --> TC TC -->|Yes| Cache - TC -->|No| X[/Ignored/] + TC -->|No| X[/Skip/] Cache --> Dedup - Dedup -->|Pass| Queue - Dedup -->|Skip| Cache + Dedup -->|OK| Queue + Dedup -->|Dup| Cache Queue --> W1 & W2 & W3 W1 & W2 & W3 --> P0 P0 --> P1 --> P2 --> P3 --> P4 --> P5 P5 --> KB & DB & Job - KB -.->|Experience| P0 + KB -.->|History| P0 ``` -### 2.2 Team Integration +### 2.2 Team Structure -AI members are stored in `team_members` table with `member_type = "ai"`: +AI members live in `team_members` table with `member_type = "ai"`: ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” @@ -78,7 +78,6 @@ AI members are stored in `team_members` table with `member_type = "ai"`: β”‚ β”‚ AI Members β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ β”‚ β”‚Sales Managerβ”‚ β”‚Data Analyst β”‚ β”‚CS Specialistβ”‚ β”‚ β”‚ -β”‚ β”‚ β”‚ Duties: β”‚ β”‚ Duties: β”‚ β”‚ Duties: β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β€’ Track KPIsβ”‚ β”‚ β€’ Analyze β”‚ β”‚ β€’ Tickets β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β€’ Reports β”‚ β”‚ β€’ Reports β”‚ β”‚ β€’ Inquiries β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ @@ -96,9 +95,9 @@ AI members are stored in `team_members` table with `member_type = "ai"`: CREATE TABLE team_members ( id BIGINT PRIMARY KEY AUTO_INCREMENT, team_id VARCHAR(64) NOT NULL, - user_id VARCHAR(64), -- Human members + user_id VARCHAR(64), -- for humans member_type VARCHAR(32) NOT NULL, -- "user" | "ai" - agent_id VARCHAR(64), -- AI members only + agent_id VARCHAR(64), -- for AI only agent_config JSON, -- AI config status VARCHAR(32) DEFAULT 'active', INDEX idx_team_id (team_id), @@ -110,7 +109,7 @@ CREATE TABLE team_members ( ## 3. How It Works -### 3.1 Trigger β†’ Schedule β†’ Execute +### 3.1 Flow: Trigger β†’ Schedule β†’ Run ```mermaid sequenceDiagram @@ -120,39 +119,39 @@ sequenceDiagram participant S as Scheduler participant W as Worker participant E as Executor - participant A as Agents (P0-P5) - participant KB as Private KB + participant A as Phase Agents + participant KB as KB - T->>M: Trigger Event - M->>M: Check trigger enabled - M->>M: Get agent from cache - M->>M: Dedup check - M->>S: Submit request + 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: Priority sort + S->>S: Sort by priority S->>W: Dispatch - W->>E: Execute + W->>E: Run - loop Phase 0-5 - E->>A: Call phase agent + loop P0 to P5 + E->>A: Call agent A-->>E: Result end - E->>KB: Store learning - E-->>W: Complete + E->>KB: Save learning + E-->>W: Done ``` -### 3.2 Trigger Sources +### 3.2 Triggers -| Trigger | Description | Config | -| ------------- | --------------------------- | -------------------- | -| **Schedule** | World Clock (cron/interval) | `triggers.schedule` | -| **Intervene** | Human intervention | `triggers.intervene` | -| **Event** | Webhook, DB changes | `triggers.event` | +| Type | What | Config | +| ------------ | ------------------------ | -------------------- | +| **Schedule** | Timer (cron or interval) | `triggers.schedule` | +| **Human** | Manual action | `triggers.intervene` | +| **Event** | Webhook, DB change | `triggers.event` | -All triggers enabled by default. Configure per-agent: +All on by default. Turn off per agent: ```yaml triggers: @@ -161,114 +160,113 @@ triggers: event: { enabled: false } ``` -### 3.3 Concurrency Control +### 3.3 Concurrency -Two-level control prevents resource monopolization: +Two levels to prevent one agent from using all resources: ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Global Worker Pool (10 workers) β”‚ +β”‚ Global Pool (10 workers) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β–Ό β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Sales Manager β”‚ β”‚ Data Analyst β”‚ β”‚ CS Specialist β”‚ -β”‚ Quota: 3 β”‚ β”‚ Quota: 2 β”‚ β”‚ Quota: 3 β”‚ -β”‚ Current: 2 βœ“ β”‚ β”‚ Current: 2 (full)β”‚ β”‚ Current: 1 βœ“ β”‚ +β”‚ Limit: 3 β”‚ β”‚ Limit: 2 β”‚ β”‚ Limit: 3 β”‚ +β”‚ Now: 2 βœ“ β”‚ β”‚ Now: 2 (full) β”‚ β”‚ Now: 1 βœ“ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -### 3.4 Deduplication +### 3.4 Dedup -**Execution-level** (fast, memory): +**Fast check** (in memory): ```go -key := fmt.Sprintf("%s:%s:%s", agentID, triggerType, window) -if cache.Has(key) { skip } +key := agentID + ":" + triggerType + ":" + window +if has(key) { skip } ``` -**Semantic-level** (Agent-based, for goals/tasks): +**Smart check** (for goals/tasks): -- Dedup Agent analyzes historical records +- Dedup Agent looks at history - Returns: `skip` | `merge` | `proceed` -### 3.5 Agent Cache +### 3.5 Cache -Avoids frequent DB queries: +Keeps agents in memory. No DB query on each tick: ```go type AgentCache struct { - agents map[string]*Agent // agent_id -> agent - byTeam map[string][]string // team_id -> []agent_id + agents map[string]*Agent // agent_id -> agent + byTeam map[string][]string // team_id -> agent_ids } - -// Refresh: startup, on change, periodic (hourly) +// Refresh: on start, on change, every hour ``` --- -## 4. Execution Phases +## 4. Phases -### 4.1 Phase Overview +### 4.1 Overview ``` -P0: Inspiration β†’ P1: Goals β†’ P2: Tasks β†’ P3: Execute β†’ P4: Deliver β†’ P5: Learn +P0: Inspiration β†’ P1: Goals β†’ P2: Tasks β†’ P3: Run β†’ P4: Deliver β†’ P5: Learn ``` -| Phase | Agent | Input | Output | -| ----- | -------------- | -------------------------------------- | ----------------- | -| P0 | Inspiration | Data changes, world news, time context | InspirationReport | -| P1 | Goal Generator | Inspiration + KB experience | Goals[] | -| P2 | Task Planner | Goals + available resources | Tasks[] | -| P3 | Validator | Task results | Validated results | -| P4 | Delivery | All results | Email/Report/File | -| P5 | Learning | Execution summary | KB entries | +| Phase | Agent | In | Out | +| ----- | ----------- | ---------------- | --------------- | +| P0 | Inspiration | Data, news, time | Report | +| P1 | Goal Gen | Report + history | Goals | +| P2 | Task Plan | Goals + tools | Tasks | +| P3 | Validator | Results | Checked results | +| P4 | Delivery | All results | Email/File | +| P5 | Learning | Summary | KB entries | -### 4.2 Phase 0: Inspiration +### 4.2 P0: Inspiration -Collects context to generate high-value goals: +Gathers info to help make good goals: ```go type InspirationReport struct { - Summary string // Overall situation - Highlights []Highlight // Key findings (data_change|event|deadline|world_news) - Opportunities []Opportunity // Discovered opportunities - Risks []Risk // Potential risks - WorldInsights []WorldInsight // External world insights - Suggestions []string // Focus areas + 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 } ``` -**Data sources:** +**Sources:** -- Internal: Data changes, events, feedback, pending items -- External: Web search (industry news, competitors) -- Time: Day of week, month end, deadlines +- Internal: Data changes, events, feedback, pending work +- External: Web search (news, competitors) +- Time: Day of week, deadlines -### 4.3 Phase 1: Goal Generation +### 4.3 P1: Goals -Uses inspiration report to generate goals: +Uses inspiration to make goals: ``` Prompt: -You are [Sales Manager], responsible for [tracking KPIs, generating reports]. +You are [Sales Manager]. Your job: [track KPIs, make reports]. -## Inspiration Report -### Key Findings -- [High] Data: 15 new sales records (+50%) -- [High] Deadline: Friday, prepare weekly report -- [High] External: Competitor launched new product +## Report +### Key Items +- [High] Data: 15 new sales (+50%) +- [High] Deadline: Friday report due +- [High] News: Competitor launched product -### Opportunities -- Sales exceeded last week by 20% -- Industry report shows market growth +### Chances +- Sales up 20% vs last week +- Market growing -Please generate today's most valuable work goals. +Make today's goals. ``` -### 4.4 Phase 2: Task Decomposition +### 4.4 P2: Tasks -Breaks goals into executable tasks: +Breaks goals into steps: ```go type Task struct { @@ -276,22 +274,22 @@ type Task struct { GoalID string Description string ExecutorType string // "assistant" | "mcp" - ExecutorID string // Assistant ID or MCP tool + ExecutorID string } ``` -### 4.5 Phase 3: Execution +### 4.5 P3: Run For each task: -1. Call specified Assistant or MCP Tool -2. Collect result -3. Call Validator to verify +1. Call Assistant or MCP Tool +2. Get result +3. Validate 4. Update status -### 4.6 Phase 4: Delivery +### 4.6 P4: Deliver -Generates deliverables based on config: +Send output: ```yaml delivery: @@ -300,42 +298,42 @@ delivery: to: ["manager@company.com"] ``` -### 4.7 Phase 5: Learning +### 4.7 P5: Learn -Analyzes execution, writes to private KB: +Save to KB: -| Category | Examples | -| ----------- | ----------------------------------- | -| `execution` | Task process, success/failure cases | -| `feedback` | Validation results, error analysis | -| `insight` | Patterns, optimization suggestions | +| Type | Examples | +| ----------- | ------------------------ | +| `execution` | What worked, what failed | +| `feedback` | Errors, fixes | +| `insight` | Patterns, tips | --- -## 5. Configuration +## 5. Config -### 5.1 Config Structure +### 5.1 Structure ```go type Config struct { - Triggers *Triggers `json:"triggers,omitempty"` // Trigger sources - Schedule *Schedule `json:"schedule,omitempty"` // Timing - Identity *Identity `json:"identity"` // Role & duties - Quota *Quota `json:"quota"` // Concurrency - PrivateKB *KB `json:"private_kb"` // Private KB - SharedKB *KB `json:"shared_kb,omitempty"` // Shared KB refs - Resources *Resources `json:"resources"` // Agents & tools - Delivery *Delivery `json:"delivery"` // Output - Input *Input `json:"input,omitempty"` // Input isolation - Events []Event `json:"events,omitempty"` // Event sources - Monitor *Monitor `json:"monitor,omitempty"` // Monitoring + Triggers *Triggers `json:"triggers,omitempty"` + Schedule *Schedule `json:"schedule,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 Type Definitions +### 5.2 Types ```go -// Triggers (all enabled by default) +// Triggers - all on by default type Triggers struct { Schedule *Trigger `json:"schedule,omitempty"` Intervene *Trigger `json:"intervene,omitempty"` @@ -344,54 +342,54 @@ type Triggers struct { type Trigger struct { Enabled bool `json:"enabled"` - Actions []string `json:"actions,omitempty"` // For intervene only + Actions []string `json:"actions,omitempty"` // for intervene } // Schedule type Schedule struct { Type string `json:"type"` // cron | interval Expr string `json:"expr"` // "0 9 * * 1-5" or "1h" - TZ string `json:"tz"` // Timezone - Timeout string `json:"timeout"` // Max execution time + TZ string `json:"tz"` + Timeout string `json:"timeout"` } // Identity type Identity struct { - Role string `json:"role"` // Role name - Duties []string `json:"duties"` // Responsibilities - Rules []string `json:"rules"` // Constraints + Role string `json:"role"` + Duties []string `json:"duties"` + Rules []string `json:"rules"` } // Quota type Quota struct { - Max int `json:"max"` // Max concurrent (default: 2) - Queue int `json:"queue"` // Queue size (default: 10) + 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"` // Collection ID - Refs []string `json:"refs,omitempty"` // Shared refs - Learn *Learn `json:"learn,omitempty"` // Learning config + ID string `json:"id,omitempty"` + Refs []string `json:"refs,omitempty"` + Learn *Learn `json:"learn,omitempty"` } type Learn struct { - On bool `json:"on"` // Enable - Types []string `json:"types"` // ["execution", "feedback", "insight"] - Keep int `json:"keep"` // Retention days, 0 = forever + On bool `json:"on"` + Types []string `json:"types"` // execution, feedback, insight + Keep int `json:"keep"` // days, 0 = forever } // Resources type Resources struct { - P0 string `json:"p0"` // Inspiration - P1 string `json:"p1"` // Goal Generator - P2 string `json:"p2"` // Task Planner - P3 string `json:"p3"` // Validator - P4 string `json:"p4"` // Delivery - P5 string `json:"p5"` // Learning - Agents []string `json:"agents"` // Callable assistants - MCP []MCP `json:"mcp"` // MCP services + P0 string `json:"p0"` // Inspiration + P1 string `json:"p1"` // Goal Gen + P2 string `json:"p2"` // Task Plan + P3 string `json:"p3"` // Validator + P4 string `json:"p4"` // Delivery + P5 string `json:"p5"` // Learning + Agents []string `json:"agents"` + MCP []MCP `json:"mcp"` } type MCP struct { @@ -413,9 +411,9 @@ type Monitor struct { type Alert struct { Name string `json:"name"` - When string `json:"when"` // failed | timeout | error_rate - Value float64 `json:"value"` // Threshold - Window string `json:"window"` // 1h | 24h + 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"` } @@ -426,7 +424,7 @@ type Action struct { } ``` -### 5.3 Full Example +### 5.3 Example ```json { @@ -446,8 +444,8 @@ type Action struct { }, "identity": { "role": "Sales Analyst", - "duties": ["Analyze sales data", "Generate weekly reports"], - "rules": ["Only access sales-related data"] + "duties": ["Analyze sales", "Make weekly reports"], + "rules": ["Only access sales data"] }, "quota": { "max": 2, "queue": 10, "priority": 5 }, "private_kb": { @@ -457,7 +455,7 @@ type Action struct { "keep": 90 } }, - "shared_kb": { "refs": ["sales-policies", "product-catalog"] }, + "shared_kb": { "refs": ["sales-policies", "products"] }, "resources": { "p0": "__yao.inspiration", "p1": "__yao.goal-gen", @@ -480,13 +478,11 @@ type Action struct { ## 6. Lifecycle -### 6.1 State Diagram +### 6.1 States ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” POST create β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ β”‚ ─────────────▢ β”‚ β”‚ -β”‚ None β”‚ β”‚ Active │◀─────┐ -β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ None β”‚ ─────────────▢ β”‚ Active │◀─────┐ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ PATCH pause β”‚ PATCH resume @@ -502,27 +498,25 @@ type Action struct { β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -### 6.2 State Transitions +### 6.2 Transitions -| From | To | Trigger | -| ------------- | ------- | --------------------- | -| - | active | POST create member | -| active | paused | PATCH status="paused" | -| paused | active | PATCH status="active" | -| active/paused | deleted | DELETE member | +| From | To | How | +| ------ | ------- | --------------------- | +| - | active | POST create | +| active | paused | PATCH status="paused" | +| paused | active | PATCH status="active" | +| any | deleted | DELETE | -### 6.3 Initialization +### 6.3 On Create -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 -1. Validate config -2. Generate agent_id (if not provided) -3. Create private KB: `agent_{team_id}_{agent_id}_kb` -4. Register with Manager (add to cache) -5. Create Job entry -6. Set status = "active" - -### 6.4 Active State +### 6.4 Running ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” @@ -533,31 +527,29 @@ On create: β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -### 6.5 Termination +### 6.5 On Delete -On delete: - -1. Cancel running executions +1. Stop running jobs 2. Remove from cache -3. Delete Job entry -4. Handle KB (delete or archive) +3. Delete Job +4. Delete or archive KB 5. Soft delete record --- ## 7. Integrations -### 7.1 Job System (Activity Monitor) +### 7.1 Job System -Each Agent maps to a Job, each execution to an Execution: +Each agent = 1 Job. Each run = 1 Execution. ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Activity Monitor (UI) β”‚ -β”‚ β€’ Task list and status β”‚ -β”‚ β€’ Real-time progress β”‚ -β”‚ β€’ Execution logs β”‚ -β”‚ β€’ Cancel/pause/retry β”‚ +β”‚ β€’ List jobs β”‚ +β”‚ β€’ See progress β”‚ +β”‚ β€’ View logs β”‚ +β”‚ β€’ Cancel/retry β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό @@ -569,59 +561,59 @@ Each Agent maps to a Job, each execution to an Execution: **APIs:** -| Feature | API | -| ----------- | -------------------------------------------- | -| List agents | `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` | +| 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 Knowledge Base +### 7.2 Private KB -Auto-created per agent: `agent_{team_id}_{agent_id}_kb` +Made on agent create: `agent_{team_id}_{agent_id}_kb` -**Learning categories:** +**What it stores:** -- `execution`: Task process, success/failure -- `feedback`: Validation, errors -- `insight`: Patterns, best practices +- `execution`: What worked, what failed +- `feedback`: Errors, fixes +- `insight`: Patterns, tips -**Lifecycle:** +**When:** -- Create: On agent creation -- Update: After each execution (P5) -- Cleanup: Based on `keep` config -- Delete: On agent deletion (or archive) +- Create: On agent create +- Update: After P5 +- Clean: Based on `keep` days +- Delete: On agent delete ### 7.3 External Input -**Input types:** +**Types:** -- `schedule`: World Clock -- `intervene`: Human intervention -- `event`: Webhooks, DB triggers -- `callback`: Async task callbacks +- `schedule`: Timer +- `intervene`: Human action +- `event`: Webhook, DB change +- `callback`: Async result -**Intervention actions:** +**Human actions:** -- `adjust_goal`: Modify current goal -- `add_task`: Add new task -- `cancel_task`: Cancel task +- `adjust_goal`: Change goal +- `add_task`: Add task +- `cancel_task`: Stop task - `pause` / `resume` / `abort` -- `plan`: Queue for later +- `plan`: Do later **Plan Queue:** -- Stores deferred goals/tasks -- Processed at start of next execution +- Holds tasks for later +- Runs at next cycle start --- -## 8. API Reference +## 8. API -### 8.1 Core Interfaces +### 8.1 Manager ```go type Manager interface { @@ -635,7 +627,7 @@ type Manager interface { } ``` -### 8.2 Execution State +### 8.2 State ```go type State struct { @@ -644,8 +636,8 @@ type State struct { AgentID string StartTime time.Time EndTime *time.Time - Status Status // pending | running | completed | failed - Phase Phase // inspiration | goal_generation | task_decomposition | task_execution | delivery | learning + Status Status // pending | running | completed | failed + Phase Phase // inspiration | goal_gen | task_plan | run | deliver | learn Goals []Goal Tasks []Task Error string @@ -653,7 +645,7 @@ type State struct { } ``` -### 8.3 Database Schema +### 8.3 Database ```sql CREATE TABLE autonomous_executions ( @@ -678,17 +670,17 @@ CREATE TABLE autonomous_executions ( ## 9. Security -1. **Team Isolation**: Agents only access their team's resources -2. **Permission Inheritance**: Permissions from role_id -3. **Resource Restrictions**: Limited by `resources` config -4. **Execution Timeout**: Enforced by `timeout` config -5. **Audit Logs**: All executions persisted +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 Reference +## 10. Quick Ref -### Trigger Config +### Triggers ```yaml triggers: @@ -701,20 +693,20 @@ triggers: ```yaml resources: - p0: "__yao.inspiration" # Inspiration - p1: "__yao.goal-gen" # Goal Generator - p2: "__yao.task-plan" # Task Planner - p3: "__yao.validator" # Validator - p4: "__yao.delivery" # Delivery - p5: "__yao.learning" # Learning + p0: "__yao.inspiration" + p1: "__yao.goal-gen" + p2: "__yao.task-plan" + p3: "__yao.validator" + p4: "__yao.delivery" + p5: "__yao.learning" ``` ### Quota ```yaml quota: - max: 2 # Max concurrent - queue: 10 # Queue size + max: 2 # max running + queue: 10 # queue size priority: 5 # 1-10 ``` @@ -722,8 +714,8 @@ quota: ```yaml schedule: - type: cron # cron | interval - expr: "0 9 * * 1-5" # Cron or duration + type: cron + expr: "0 9 * * 1-5" tz: Asia/Shanghai timeout: 30m ```