# DevOS v1 AI Agent Architecture

## 1. Principle
AI is an operating layer, not merely a chat feature.

```text
                    AI Gateway
                         |
              +----------+----------+
              |                     |
            Agent                 Memory
              |
       +------+------+------+
       |      |      |      |
     Tools   MCP  Workflow Approval
```

## 2. Agent Loop

```text
Observe
  ↓
Discover Resources
  ↓
Plan
  ↓
Risk Evaluation
  ↓
Approval if required
  ↓
Execute Tools
  ↓
Verify
  ↓
Report
```

## 3. Tool Examples
- server.list
- server.exec
- server.restart
- server.getStatus
- server.getDockerContainers
- website.list
- website.deploy
- website.logs
- git.repositories
- git.commits
- domain.records
- email.search
- note.create
- task.create

## 4. Context
Agent context should be built from:
- workspace
- user permissions
- relevant resources
- resource relations
- recent events
- task/run history
- tool schemas

Do not indiscriminately inject the entire database into the model.

## 5. Risk
Risk levels:
- LOW
- MEDIUM
- HIGH
- CRITICAL

HIGH and CRITICAL operations require user approval by default.

Examples:
- production deployment
- destructive filesystem operations
- database deletion
- credential changes

## 6. Verification
An Agent action is not successful merely because a command returned zero. The Agent should perform domain-specific verification where possible:
- deployment health
- HTTP health check
- container state
- DNS propagation/result
- SSL availability

## 7. Action Log
Agent runs should expose human-readable steps such as:
- found target server
- Docker available
- repository connected
- deployment created
- container started
- health check passed