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.
This commit is contained in:
Max
parent
1d5881fe5f
commit
46d815affc
1 changed files with 245 additions and 253 deletions
|
|
@ -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
|
- Belongs to a Team, managed like human members
|
||||||
- **Job Responsibilities**: Has defined duties (e.g., "Sales Manager tracks KPIs")
|
- Has clear job duties (e.g., "Sales Manager: track KPIs, make reports")
|
||||||
- **Dynamic Lifecycle**: Created/destroyed via Team API
|
- Created and deleted via Team API
|
||||||
- **Multi-Trigger**: Activated by schedule, human intervention, or events
|
- Runs on schedule, or when triggered by humans or events
|
||||||
- **Self-Learning**: Maintains private knowledge base, learns from execution
|
- Learns from each run, stores knowledge in private KB
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Architecture
|
## 2. Architecture
|
||||||
|
|
||||||
### 2.1 System Overview
|
### 2.1 System Flow
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
flowchart TB
|
flowchart TB
|
||||||
subgraph Triggers["Trigger Sources"]
|
subgraph Triggers["Triggers"]
|
||||||
WC[/"⏰ World Clock<br/>(Schedule)"/]
|
WC[/"⏰ Schedule"/]
|
||||||
HI[/"👤 Human<br/>(Intervene)"/]
|
HI[/"👤 Human"/]
|
||||||
EV[/"📡 Events<br/>(Webhook/DB)"/]
|
EV[/"📡 Event"/]
|
||||||
end
|
end
|
||||||
|
|
||||||
subgraph Manager["Agent Manager"]
|
subgraph Manager["Manager"]
|
||||||
TC{"Trigger<br/>Enabled?"}
|
TC{"Enabled?"}
|
||||||
Cache[("Agent Cache")]
|
Cache[("Cache")]
|
||||||
Dedup{"Dedup<br/>Check"}
|
Dedup{"Dedup?"}
|
||||||
Queue["Priority Queue"]
|
Queue["Queue"]
|
||||||
end
|
end
|
||||||
|
|
||||||
subgraph Pool["Worker Pool"]
|
subgraph Pool["Workers"]
|
||||||
W1["Worker"]
|
W1["Worker"]
|
||||||
W2["Worker"]
|
W2["Worker"]
|
||||||
W3["Worker"]
|
W3["Worker"]
|
||||||
|
|
@ -43,33 +43,33 @@ flowchart TB
|
||||||
P0["P0: Inspiration"]
|
P0["P0: Inspiration"]
|
||||||
P1["P1: Goals"]
|
P1["P1: Goals"]
|
||||||
P2["P2: Tasks"]
|
P2["P2: Tasks"]
|
||||||
P3["P3: Execute"]
|
P3["P3: Run"]
|
||||||
P4["P4: Deliver"]
|
P4["P4: Deliver"]
|
||||||
P5["P5: Learn"]
|
P5["P5: Learn"]
|
||||||
end
|
end
|
||||||
|
|
||||||
subgraph Storage["Storage"]
|
subgraph Storage["Storage"]
|
||||||
KB[("Private KB")]
|
KB[("KB")]
|
||||||
DB[("Executions")]
|
DB[("DB")]
|
||||||
Job[("Job System")]
|
Job[("Job")]
|
||||||
end
|
end
|
||||||
|
|
||||||
WC & HI & EV --> TC
|
WC & HI & EV --> TC
|
||||||
TC -->|Yes| Cache
|
TC -->|Yes| Cache
|
||||||
TC -->|No| X[/Ignored/]
|
TC -->|No| X[/Skip/]
|
||||||
Cache --> Dedup
|
Cache --> Dedup
|
||||||
Dedup -->|Pass| Queue
|
Dedup -->|OK| Queue
|
||||||
Dedup -->|Skip| Cache
|
Dedup -->|Dup| Cache
|
||||||
Queue --> W1 & W2 & W3
|
Queue --> W1 & W2 & W3
|
||||||
W1 & W2 & W3 --> P0
|
W1 & W2 & W3 --> P0
|
||||||
P0 --> P1 --> P2 --> P3 --> P4 --> P5
|
P0 --> P1 --> P2 --> P3 --> P4 --> P5
|
||||||
P5 --> KB & DB & Job
|
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 │ │
|
│ │ AI Members │ │
|
||||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||||
│ │ │Sales Manager│ │Data Analyst │ │CS Specialist│ │ │
|
│ │ │Sales Manager│ │Data Analyst │ │CS Specialist│ │ │
|
||||||
│ │ │ Duties: │ │ Duties: │ │ Duties: │ │ │
|
|
||||||
│ │ │ • Track KPIs│ │ • Analyze │ │ • Tickets │ │ │
|
│ │ │ • Track KPIs│ │ • Analyze │ │ • Tickets │ │ │
|
||||||
│ │ │ • Reports │ │ • Reports │ │ • Inquiries │ │ │
|
│ │ │ • Reports │ │ • Reports │ │ • Inquiries │ │ │
|
||||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||||
|
|
@ -96,9 +95,9 @@ AI members are stored in `team_members` table with `member_type = "ai"`:
|
||||||
CREATE TABLE team_members (
|
CREATE TABLE team_members (
|
||||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||||
team_id VARCHAR(64) NOT NULL,
|
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"
|
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
|
agent_config JSON, -- AI config
|
||||||
status VARCHAR(32) DEFAULT 'active',
|
status VARCHAR(32) DEFAULT 'active',
|
||||||
INDEX idx_team_id (team_id),
|
INDEX idx_team_id (team_id),
|
||||||
|
|
@ -110,7 +109,7 @@ CREATE TABLE team_members (
|
||||||
|
|
||||||
## 3. How It Works
|
## 3. How It Works
|
||||||
|
|
||||||
### 3.1 Trigger → Schedule → Execute
|
### 3.1 Flow: Trigger → Schedule → Run
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
sequenceDiagram
|
sequenceDiagram
|
||||||
|
|
@ -120,39 +119,39 @@ sequenceDiagram
|
||||||
participant S as Scheduler
|
participant S as Scheduler
|
||||||
participant W as Worker
|
participant W as Worker
|
||||||
participant E as Executor
|
participant E as Executor
|
||||||
participant A as Agents (P0-P5)
|
participant A as Phase Agents
|
||||||
participant KB as Private KB
|
participant KB as KB
|
||||||
|
|
||||||
T->>M: Trigger Event
|
T->>M: Event
|
||||||
M->>M: Check trigger enabled
|
M->>M: Check enabled
|
||||||
M->>M: Get agent from cache
|
M->>M: Get from cache
|
||||||
M->>M: Dedup check
|
M->>M: Check dedup
|
||||||
M->>S: Submit request
|
M->>S: Submit
|
||||||
|
|
||||||
S->>S: Check quota
|
S->>S: Check quota
|
||||||
S->>S: Priority sort
|
S->>S: Sort by priority
|
||||||
S->>W: Dispatch
|
S->>W: Dispatch
|
||||||
|
|
||||||
W->>E: Execute
|
W->>E: Run
|
||||||
|
|
||||||
loop Phase 0-5
|
loop P0 to P5
|
||||||
E->>A: Call phase agent
|
E->>A: Call agent
|
||||||
A-->>E: Result
|
A-->>E: Result
|
||||||
end
|
end
|
||||||
|
|
||||||
E->>KB: Store learning
|
E->>KB: Save learning
|
||||||
E-->>W: Complete
|
E-->>W: Done
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3.2 Trigger Sources
|
### 3.2 Triggers
|
||||||
|
|
||||||
| Trigger | Description | Config |
|
| Type | What | Config |
|
||||||
| ------------- | --------------------------- | -------------------- |
|
| ------------ | ------------------------ | -------------------- |
|
||||||
| **Schedule** | World Clock (cron/interval) | `triggers.schedule` |
|
| **Schedule** | Timer (cron or interval) | `triggers.schedule` |
|
||||||
| **Intervene** | Human intervention | `triggers.intervene` |
|
| **Human** | Manual action | `triggers.intervene` |
|
||||||
| **Event** | Webhook, DB changes | `triggers.event` |
|
| **Event** | Webhook, DB change | `triggers.event` |
|
||||||
|
|
||||||
All triggers enabled by default. Configure per-agent:
|
All on by default. Turn off per agent:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
triggers:
|
triggers:
|
||||||
|
|
@ -161,114 +160,113 @@ triggers:
|
||||||
event: { enabled: false }
|
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 │
|
│ Sales Manager │ │ Data Analyst │ │ CS Specialist │
|
||||||
│ Quota: 3 │ │ Quota: 2 │ │ Quota: 3 │
|
│ Limit: 3 │ │ Limit: 2 │ │ Limit: 3 │
|
||||||
│ Current: 2 ✓ │ │ Current: 2 (full)│ │ Current: 1 ✓ │
|
│ Now: 2 ✓ │ │ Now: 2 (full) │ │ Now: 1 ✓ │
|
||||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3.4 Deduplication
|
### 3.4 Dedup
|
||||||
|
|
||||||
**Execution-level** (fast, memory):
|
**Fast check** (in memory):
|
||||||
|
|
||||||
```go
|
```go
|
||||||
key := fmt.Sprintf("%s:%s:%s", agentID, triggerType, window)
|
key := agentID + ":" + triggerType + ":" + window
|
||||||
if cache.Has(key) { skip }
|
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`
|
- 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
|
```go
|
||||||
type AgentCache struct {
|
type AgentCache struct {
|
||||||
agents map[string]*Agent // agent_id -> agent
|
agents map[string]*Agent // agent_id -> agent
|
||||||
byTeam map[string][]string // team_id -> []agent_id
|
byTeam map[string][]string // team_id -> agent_ids
|
||||||
}
|
}
|
||||||
|
// Refresh: on start, on change, every hour
|
||||||
// Refresh: startup, on change, periodic (hourly)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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 |
|
| Phase | Agent | In | Out |
|
||||||
| ----- | -------------- | -------------------------------------- | ----------------- |
|
| ----- | ----------- | ---------------- | --------------- |
|
||||||
| P0 | Inspiration | Data changes, world news, time context | InspirationReport |
|
| P0 | Inspiration | Data, news, time | Report |
|
||||||
| P1 | Goal Generator | Inspiration + KB experience | Goals[] |
|
| P1 | Goal Gen | Report + history | Goals |
|
||||||
| P2 | Task Planner | Goals + available resources | Tasks[] |
|
| P2 | Task Plan | Goals + tools | Tasks |
|
||||||
| P3 | Validator | Task results | Validated results |
|
| P3 | Validator | Results | Checked results |
|
||||||
| P4 | Delivery | All results | Email/Report/File |
|
| P4 | Delivery | All results | Email/File |
|
||||||
| P5 | Learning | Execution summary | KB entries |
|
| 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
|
```go
|
||||||
type InspirationReport struct {
|
type InspirationReport struct {
|
||||||
Summary string // Overall situation
|
Summary string // What's happening
|
||||||
Highlights []Highlight // Key findings (data_change|event|deadline|world_news)
|
Highlights []Highlight // Key changes
|
||||||
Opportunities []Opportunity // Discovered opportunities
|
Opportunities []Opportunity // Chances to act
|
||||||
Risks []Risk // Potential risks
|
Risks []Risk // Things to watch
|
||||||
WorldInsights []WorldInsight // External world insights
|
WorldInsights []WorldInsight // News from outside
|
||||||
Suggestions []string // Focus areas
|
Suggestions []string // What to focus on
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Data sources:**
|
**Sources:**
|
||||||
|
|
||||||
- Internal: Data changes, events, feedback, pending items
|
- Internal: Data changes, events, feedback, pending work
|
||||||
- External: Web search (industry news, competitors)
|
- External: Web search (news, competitors)
|
||||||
- Time: Day of week, month end, deadlines
|
- 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:
|
Prompt:
|
||||||
You are [Sales Manager], responsible for [tracking KPIs, generating reports].
|
You are [Sales Manager]. Your job: [track KPIs, make reports].
|
||||||
|
|
||||||
## Inspiration Report
|
## Report
|
||||||
### Key Findings
|
### Key Items
|
||||||
- [High] Data: 15 new sales records (+50%)
|
- [High] Data: 15 new sales (+50%)
|
||||||
- [High] Deadline: Friday, prepare weekly report
|
- [High] Deadline: Friday report due
|
||||||
- [High] External: Competitor launched new product
|
- [High] News: Competitor launched product
|
||||||
|
|
||||||
### Opportunities
|
### Chances
|
||||||
- Sales exceeded last week by 20%
|
- Sales up 20% vs last week
|
||||||
- Industry report shows market growth
|
- 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
|
```go
|
||||||
type Task struct {
|
type Task struct {
|
||||||
|
|
@ -276,22 +274,22 @@ type Task struct {
|
||||||
GoalID string
|
GoalID string
|
||||||
Description string
|
Description string
|
||||||
ExecutorType string // "assistant" | "mcp"
|
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:
|
For each task:
|
||||||
|
|
||||||
1. Call specified Assistant or MCP Tool
|
1. Call Assistant or MCP Tool
|
||||||
2. Collect result
|
2. Get result
|
||||||
3. Call Validator to verify
|
3. Validate
|
||||||
4. Update status
|
4. Update status
|
||||||
|
|
||||||
### 4.6 Phase 4: Delivery
|
### 4.6 P4: Deliver
|
||||||
|
|
||||||
Generates deliverables based on config:
|
Send output:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
delivery:
|
delivery:
|
||||||
|
|
@ -300,42 +298,42 @@ delivery:
|
||||||
to: ["manager@company.com"]
|
to: ["manager@company.com"]
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4.7 Phase 5: Learning
|
### 4.7 P5: Learn
|
||||||
|
|
||||||
Analyzes execution, writes to private KB:
|
Save to KB:
|
||||||
|
|
||||||
| Category | Examples |
|
| Type | Examples |
|
||||||
| ----------- | ----------------------------------- |
|
| ----------- | ------------------------ |
|
||||||
| `execution` | Task process, success/failure cases |
|
| `execution` | What worked, what failed |
|
||||||
| `feedback` | Validation results, error analysis |
|
| `feedback` | Errors, fixes |
|
||||||
| `insight` | Patterns, optimization suggestions |
|
| `insight` | Patterns, tips |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5. Configuration
|
## 5. Config
|
||||||
|
|
||||||
### 5.1 Config Structure
|
### 5.1 Structure
|
||||||
|
|
||||||
```go
|
```go
|
||||||
type Config struct {
|
type Config struct {
|
||||||
Triggers *Triggers `json:"triggers,omitempty"` // Trigger sources
|
Triggers *Triggers `json:"triggers,omitempty"`
|
||||||
Schedule *Schedule `json:"schedule,omitempty"` // Timing
|
Schedule *Schedule `json:"schedule,omitempty"`
|
||||||
Identity *Identity `json:"identity"` // Role & duties
|
Identity *Identity `json:"identity"`
|
||||||
Quota *Quota `json:"quota"` // Concurrency
|
Quota *Quota `json:"quota"`
|
||||||
PrivateKB *KB `json:"private_kb"` // Private KB
|
PrivateKB *KB `json:"private_kb"`
|
||||||
SharedKB *KB `json:"shared_kb,omitempty"` // Shared KB refs
|
SharedKB *KB `json:"shared_kb,omitempty"`
|
||||||
Resources *Resources `json:"resources"` // Agents & tools
|
Resources *Resources `json:"resources"`
|
||||||
Delivery *Delivery `json:"delivery"` // Output
|
Delivery *Delivery `json:"delivery"`
|
||||||
Input *Input `json:"input,omitempty"` // Input isolation
|
Input *Input `json:"input,omitempty"`
|
||||||
Events []Event `json:"events,omitempty"` // Event sources
|
Events []Event `json:"events,omitempty"`
|
||||||
Monitor *Monitor `json:"monitor,omitempty"` // Monitoring
|
Monitor *Monitor `json:"monitor,omitempty"`
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 5.2 Type Definitions
|
### 5.2 Types
|
||||||
|
|
||||||
```go
|
```go
|
||||||
// Triggers (all enabled by default)
|
// Triggers - all on by default
|
||||||
type Triggers struct {
|
type Triggers struct {
|
||||||
Schedule *Trigger `json:"schedule,omitempty"`
|
Schedule *Trigger `json:"schedule,omitempty"`
|
||||||
Intervene *Trigger `json:"intervene,omitempty"`
|
Intervene *Trigger `json:"intervene,omitempty"`
|
||||||
|
|
@ -344,54 +342,54 @@ type Triggers struct {
|
||||||
|
|
||||||
type Trigger struct {
|
type Trigger struct {
|
||||||
Enabled bool `json:"enabled"`
|
Enabled bool `json:"enabled"`
|
||||||
Actions []string `json:"actions,omitempty"` // For intervene only
|
Actions []string `json:"actions,omitempty"` // for intervene
|
||||||
}
|
}
|
||||||
|
|
||||||
// Schedule
|
// Schedule
|
||||||
type Schedule struct {
|
type Schedule struct {
|
||||||
Type string `json:"type"` // cron | interval
|
Type string `json:"type"` // cron | interval
|
||||||
Expr string `json:"expr"` // "0 9 * * 1-5" or "1h"
|
Expr string `json:"expr"` // "0 9 * * 1-5" or "1h"
|
||||||
TZ string `json:"tz"` // Timezone
|
TZ string `json:"tz"`
|
||||||
Timeout string `json:"timeout"` // Max execution time
|
Timeout string `json:"timeout"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// Identity
|
// Identity
|
||||||
type Identity struct {
|
type Identity struct {
|
||||||
Role string `json:"role"` // Role name
|
Role string `json:"role"`
|
||||||
Duties []string `json:"duties"` // Responsibilities
|
Duties []string `json:"duties"`
|
||||||
Rules []string `json:"rules"` // Constraints
|
Rules []string `json:"rules"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// Quota
|
// Quota
|
||||||
type Quota struct {
|
type Quota struct {
|
||||||
Max int `json:"max"` // Max concurrent (default: 2)
|
Max int `json:"max"` // max running (default: 2)
|
||||||
Queue int `json:"queue"` // Queue size (default: 10)
|
Queue int `json:"queue"` // queue size (default: 10)
|
||||||
Priority int `json:"priority"` // 1-10 (default: 5)
|
Priority int `json:"priority"` // 1-10 (default: 5)
|
||||||
}
|
}
|
||||||
|
|
||||||
// KB
|
// KB
|
||||||
type KB struct {
|
type KB struct {
|
||||||
ID string `json:"id,omitempty"` // Collection ID
|
ID string `json:"id,omitempty"`
|
||||||
Refs []string `json:"refs,omitempty"` // Shared refs
|
Refs []string `json:"refs,omitempty"`
|
||||||
Learn *Learn `json:"learn,omitempty"` // Learning config
|
Learn *Learn `json:"learn,omitempty"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type Learn struct {
|
type Learn struct {
|
||||||
On bool `json:"on"` // Enable
|
On bool `json:"on"`
|
||||||
Types []string `json:"types"` // ["execution", "feedback", "insight"]
|
Types []string `json:"types"` // execution, feedback, insight
|
||||||
Keep int `json:"keep"` // Retention days, 0 = forever
|
Keep int `json:"keep"` // days, 0 = forever
|
||||||
}
|
}
|
||||||
|
|
||||||
// Resources
|
// Resources
|
||||||
type Resources struct {
|
type Resources struct {
|
||||||
P0 string `json:"p0"` // Inspiration
|
P0 string `json:"p0"` // Inspiration
|
||||||
P1 string `json:"p1"` // Goal Generator
|
P1 string `json:"p1"` // Goal Gen
|
||||||
P2 string `json:"p2"` // Task Planner
|
P2 string `json:"p2"` // Task Plan
|
||||||
P3 string `json:"p3"` // Validator
|
P3 string `json:"p3"` // Validator
|
||||||
P4 string `json:"p4"` // Delivery
|
P4 string `json:"p4"` // Delivery
|
||||||
P5 string `json:"p5"` // Learning
|
P5 string `json:"p5"` // Learning
|
||||||
Agents []string `json:"agents"` // Callable assistants
|
Agents []string `json:"agents"`
|
||||||
MCP []MCP `json:"mcp"` // MCP services
|
MCP []MCP `json:"mcp"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type MCP struct {
|
type MCP struct {
|
||||||
|
|
@ -413,9 +411,9 @@ type Monitor struct {
|
||||||
|
|
||||||
type Alert struct {
|
type Alert struct {
|
||||||
Name string `json:"name"`
|
Name string `json:"name"`
|
||||||
When string `json:"when"` // failed | timeout | error_rate
|
When string `json:"when"` // failed | timeout | error_rate
|
||||||
Value float64 `json:"value"` // Threshold
|
Value float64 `json:"value"`
|
||||||
Window string `json:"window"` // 1h | 24h
|
Window string `json:"window"` // 1h | 24h
|
||||||
Do []Action `json:"do"`
|
Do []Action `json:"do"`
|
||||||
Cooldown string `json:"cooldown"`
|
Cooldown string `json:"cooldown"`
|
||||||
}
|
}
|
||||||
|
|
@ -426,7 +424,7 @@ type Action struct {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 5.3 Full Example
|
### 5.3 Example
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -446,8 +444,8 @@ type Action struct {
|
||||||
},
|
},
|
||||||
"identity": {
|
"identity": {
|
||||||
"role": "Sales Analyst",
|
"role": "Sales Analyst",
|
||||||
"duties": ["Analyze sales data", "Generate weekly reports"],
|
"duties": ["Analyze sales", "Make weekly reports"],
|
||||||
"rules": ["Only access sales-related data"]
|
"rules": ["Only access sales data"]
|
||||||
},
|
},
|
||||||
"quota": { "max": 2, "queue": 10, "priority": 5 },
|
"quota": { "max": 2, "queue": 10, "priority": 5 },
|
||||||
"private_kb": {
|
"private_kb": {
|
||||||
|
|
@ -457,7 +455,7 @@ type Action struct {
|
||||||
"keep": 90
|
"keep": 90
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"shared_kb": { "refs": ["sales-policies", "product-catalog"] },
|
"shared_kb": { "refs": ["sales-policies", "products"] },
|
||||||
"resources": {
|
"resources": {
|
||||||
"p0": "__yao.inspiration",
|
"p0": "__yao.inspiration",
|
||||||
"p1": "__yao.goal-gen",
|
"p1": "__yao.goal-gen",
|
||||||
|
|
@ -480,13 +478,11 @@ type Action struct {
|
||||||
|
|
||||||
## 6. Lifecycle
|
## 6. Lifecycle
|
||||||
|
|
||||||
### 6.1 State Diagram
|
### 6.1 States
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────┐ POST create ┌─────────┐
|
┌─────────┐ POST create ┌─────────┐
|
||||||
│ │ ─────────────▶ │ │
|
│ None │ ─────────────▶ │ Active │◀─────┐
|
||||||
│ None │ │ Active │◀─────┐
|
|
||||||
│ │ │ │ │
|
|
||||||
└─────────┘ └────┬────┘ │
|
└─────────┘ └────┬────┘ │
|
||||||
│ │
|
│ │
|
||||||
PATCH pause │ PATCH resume
|
PATCH pause │ PATCH resume
|
||||||
|
|
@ -502,27 +498,25 @@ type Action struct {
|
||||||
└─────────┘
|
└─────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
### 6.2 State Transitions
|
### 6.2 Transitions
|
||||||
|
|
||||||
| From | To | Trigger |
|
| From | To | How |
|
||||||
| ------------- | ------- | --------------------- |
|
| ------ | ------- | --------------------- |
|
||||||
| - | active | POST create member |
|
| - | active | POST create |
|
||||||
| active | paused | PATCH status="paused" |
|
| active | paused | PATCH status="paused" |
|
||||||
| paused | active | PATCH status="active" |
|
| paused | active | PATCH status="active" |
|
||||||
| active/paused | deleted | DELETE member |
|
| 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
|
### 6.4 Running
|
||||||
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
|
|
||||||
|
|
||||||
```
|
```
|
||||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||||
|
|
@ -533,31 +527,29 @@ On create:
|
||||||
└──────────────────────────────────────────────────┘
|
└──────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
### 6.5 Termination
|
### 6.5 On Delete
|
||||||
|
|
||||||
On delete:
|
1. Stop running jobs
|
||||||
|
|
||||||
1. Cancel running executions
|
|
||||||
2. Remove from cache
|
2. Remove from cache
|
||||||
3. Delete Job entry
|
3. Delete Job
|
||||||
4. Handle KB (delete or archive)
|
4. Delete or archive KB
|
||||||
5. Soft delete record
|
5. Soft delete record
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7. Integrations
|
## 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) │
|
│ Activity Monitor (UI) │
|
||||||
│ • Task list and status │
|
│ • List jobs │
|
||||||
│ • Real-time progress │
|
│ • See progress │
|
||||||
│ • Execution logs │
|
│ • View logs │
|
||||||
│ • Cancel/pause/retry │
|
│ • Cancel/retry │
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
|
|
@ -569,59 +561,59 @@ Each Agent maps to a Job, each execution to an Execution:
|
||||||
|
|
||||||
**APIs:**
|
**APIs:**
|
||||||
|
|
||||||
| Feature | API |
|
| Action | API |
|
||||||
| ----------- | -------------------------------------------- |
|
| -------- | -------------------------------------------- |
|
||||||
| List agents | `GET /api/jobs?category_id=autonomous_agent` |
|
| List | `GET /api/jobs?category_id=autonomous_agent` |
|
||||||
| History | `GET /api/jobs/:job_id/executions` |
|
| History | `GET /api/jobs/:job_id/executions` |
|
||||||
| Progress | `GET /api/jobs/:job_id/executions/:id` |
|
| Progress | `GET /api/jobs/:job_id/executions/:id` |
|
||||||
| Logs | `GET /api/jobs/:job_id/executions/:id/logs` |
|
| Logs | `GET /api/jobs/:job_id/executions/:id/logs` |
|
||||||
| Cancel | `POST /api/jobs/:job_id/stop` |
|
| Cancel | `POST /api/jobs/:job_id/stop` |
|
||||||
| Trigger | `POST /api/jobs/:job_id/trigger` |
|
| 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
|
- `execution`: What worked, what failed
|
||||||
- `feedback`: Validation, errors
|
- `feedback`: Errors, fixes
|
||||||
- `insight`: Patterns, best practices
|
- `insight`: Patterns, tips
|
||||||
|
|
||||||
**Lifecycle:**
|
**When:**
|
||||||
|
|
||||||
- Create: On agent creation
|
- Create: On agent create
|
||||||
- Update: After each execution (P5)
|
- Update: After P5
|
||||||
- Cleanup: Based on `keep` config
|
- Clean: Based on `keep` days
|
||||||
- Delete: On agent deletion (or archive)
|
- Delete: On agent delete
|
||||||
|
|
||||||
### 7.3 External Input
|
### 7.3 External Input
|
||||||
|
|
||||||
**Input types:**
|
**Types:**
|
||||||
|
|
||||||
- `schedule`: World Clock
|
- `schedule`: Timer
|
||||||
- `intervene`: Human intervention
|
- `intervene`: Human action
|
||||||
- `event`: Webhooks, DB triggers
|
- `event`: Webhook, DB change
|
||||||
- `callback`: Async task callbacks
|
- `callback`: Async result
|
||||||
|
|
||||||
**Intervention actions:**
|
**Human actions:**
|
||||||
|
|
||||||
- `adjust_goal`: Modify current goal
|
- `adjust_goal`: Change goal
|
||||||
- `add_task`: Add new task
|
- `add_task`: Add task
|
||||||
- `cancel_task`: Cancel task
|
- `cancel_task`: Stop task
|
||||||
- `pause` / `resume` / `abort`
|
- `pause` / `resume` / `abort`
|
||||||
- `plan`: Queue for later
|
- `plan`: Do later
|
||||||
|
|
||||||
**Plan Queue:**
|
**Plan Queue:**
|
||||||
|
|
||||||
- Stores deferred goals/tasks
|
- Holds tasks for later
|
||||||
- Processed at start of next execution
|
- Runs at next cycle start
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 8. API Reference
|
## 8. API
|
||||||
|
|
||||||
### 8.1 Core Interfaces
|
### 8.1 Manager
|
||||||
|
|
||||||
```go
|
```go
|
||||||
type Manager interface {
|
type Manager interface {
|
||||||
|
|
@ -635,7 +627,7 @@ type Manager interface {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 8.2 Execution State
|
### 8.2 State
|
||||||
|
|
||||||
```go
|
```go
|
||||||
type State struct {
|
type State struct {
|
||||||
|
|
@ -644,8 +636,8 @@ type State struct {
|
||||||
AgentID string
|
AgentID string
|
||||||
StartTime time.Time
|
StartTime time.Time
|
||||||
EndTime *time.Time
|
EndTime *time.Time
|
||||||
Status Status // pending | running | completed | failed
|
Status Status // pending | running | completed | failed
|
||||||
Phase Phase // inspiration | goal_generation | task_decomposition | task_execution | delivery | learning
|
Phase Phase // inspiration | goal_gen | task_plan | run | deliver | learn
|
||||||
Goals []Goal
|
Goals []Goal
|
||||||
Tasks []Task
|
Tasks []Task
|
||||||
Error string
|
Error string
|
||||||
|
|
@ -653,7 +645,7 @@ type State struct {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 8.3 Database Schema
|
### 8.3 Database
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
CREATE TABLE autonomous_executions (
|
CREATE TABLE autonomous_executions (
|
||||||
|
|
@ -678,17 +670,17 @@ CREATE TABLE autonomous_executions (
|
||||||
|
|
||||||
## 9. Security
|
## 9. Security
|
||||||
|
|
||||||
1. **Team Isolation**: Agents only access their team's resources
|
1. **Team only**: Agent sees only its team's data
|
||||||
2. **Permission Inheritance**: Permissions from role_id
|
2. **Role rules**: Uses role_id permissions
|
||||||
3. **Resource Restrictions**: Limited by `resources` config
|
3. **Limited tools**: Only what's in `resources`
|
||||||
4. **Execution Timeout**: Enforced by `timeout` config
|
4. **Timeout**: Stops if runs too long
|
||||||
5. **Audit Logs**: All executions persisted
|
5. **Logs**: All runs saved
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 10. Quick Reference
|
## 10. Quick Ref
|
||||||
|
|
||||||
### Trigger Config
|
### Triggers
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
triggers:
|
triggers:
|
||||||
|
|
@ -701,20 +693,20 @@ triggers:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
resources:
|
resources:
|
||||||
p0: "__yao.inspiration" # Inspiration
|
p0: "__yao.inspiration"
|
||||||
p1: "__yao.goal-gen" # Goal Generator
|
p1: "__yao.goal-gen"
|
||||||
p2: "__yao.task-plan" # Task Planner
|
p2: "__yao.task-plan"
|
||||||
p3: "__yao.validator" # Validator
|
p3: "__yao.validator"
|
||||||
p4: "__yao.delivery" # Delivery
|
p4: "__yao.delivery"
|
||||||
p5: "__yao.learning" # Learning
|
p5: "__yao.learning"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Quota
|
### Quota
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
quota:
|
quota:
|
||||||
max: 2 # Max concurrent
|
max: 2 # max running
|
||||||
queue: 10 # Queue size
|
queue: 10 # queue size
|
||||||
priority: 5 # 1-10
|
priority: 5 # 1-10
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -722,8 +714,8 @@ quota:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
schedule:
|
schedule:
|
||||||
type: cron # cron | interval
|
type: cron
|
||||||
expr: "0 9 * * 1-5" # Cron or duration
|
expr: "0 9 * * 1-5"
|
||||||
tz: Asia/Shanghai
|
tz: Asia/Shanghai
|
||||||
timeout: 30m
|
timeout: 30m
|
||||||
```
|
```
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue