# Reference Architecture

> Complete system design and control flow for ACS implementation

- **Category**: guardrails-acs

- **Canonical URL**: https://designpattern.fyi/guardrails-acs/reference-architecture/

---

## Description
Complete system design and control flow for ACS implementation








## Additional Notes

# Reference Architecture at a Glance

## Sequence Diagram

{{< mermaid >}}
sequenceDiagram
    participant U as User
    participant A as Observed Agent
    participant G as Guardian Agent
    participant T as Tool / MCP Server
    participant O as OTel/OCSF Sink

    U->>A: message (hook: User Message)
    A->>G: evaluate(context)
    G-->>A: verdict: allow / deny / modify
    A->>T: toolCallRequest (hook)
    A->>G: evaluate(tool, params)
    G-->>A: verdict
    T-->>A: toolCallResult (hook)
    A->>G: evaluate(result)
    G-->>A: verdict
    A->>O: trace event (every hook)
    A->>U: agent response (hook: Agent Response)
    A->>G: evaluate(response)
    G-->>A: verdict
{{< /mermaid >}}

Every hook in this sequence is a place where the Guardian Agent can intervene — and every hook also emits a trace event, so the sequence above is simultaneously your control-flow diagram and your audit-trail diagram.

---

## Architecture Components

### 1. Observed Agent (Tier 1)
The agent framework or platform that:
- Exposes standardized hooks at decision points
- Fires hook events with required context
- Handles verdicts from the Guardian Agent
- Emits trace events to observability backend

### 2. Guardian Agent (Tier 2)
The policy enforcement engine that:
- Receives hook events from Observed Agents
- Evaluates events against declarative policy
- Returns verdicts (allow/deny/modify) with reasoning
- Integrates enterprise classifiers from Tier 3

### 3. Enterprise Classifiers (Tier 3)
Organization-specific detection logic that:
- Provides custom classification for policies
- Implements industry-specific rules
- Integrates existing security tooling
- Maintains organizational compliance requirements

### 4. Observability Backend
The tracing and monitoring infrastructure that:
- Receives OpenTelemetry spans from agents
- Maps security events to OCSF format
- Forwards events to SIEM systems
- Supports incident response and compliance audits

### 5. AgBOM System
The dynamic inventory management that:
- Tracks all agent components (tools, models, knowledge sources)
- Updates automatically on capability discovery
- Maintains approved component lists
- Supports supply chain security monitoring

---

## Data Flow

### Request Flow
1. **User initiates interaction** → User Message hook fires
2. **Agent evaluates context** → Guardian Agent checks policy
3. **Verdict returned** → Agent proceeds, modifies, or blocks
4. **Tool call requested** → Tool Call Request hook fires
5. **Guardian Agent evaluates** → Tool authorization check
6. **Tool executes** → Returns result to agent
7. **Tool result processed** → Tool Call Result hook fires
8. **Guardian Agent evaluates** → Result filtering/redaction
9. **Agent generates response** → Agent Response hook fires
10. **Final policy check** → Guardian Agent evaluates outbound content

### Trace Flow
Every hook simultaneously emits a trace event:
1. **Hook fires** → OpenTelemetry span created
2. **Context captured** → Session ID, agent name, reasoning
3. **Span emitted** → Sent to observability backend
4. **Security events mapped** → Converted to OCSF format
5. **Forwarded to SIEM** → Integrated with security monitoring

### Inventory Flow
Component discovery triggers AgBOM updates:
1. **New component discovered** → Capability discovery event
2. **AgBOM updated** → New component added to inventory
3. **Policy check** → Component evaluated against approval list
4. **Alert if needed** → Security team notified of unapproved component

---

## Deployment Patterns

### Centralized Guardian Agent
```
Multiple Observed Agents → Single Guardian Agent Service
```

**Advantages:**
- Centralized policy management
- Consistent enforcement across agents
- Easier monitoring and maintenance

**Considerations:**
- Single point of failure (need HA)
- Network latency for hook evaluation
- Scalability for high-volume agent fleets

### Distributed Guardian Agent
```
Each Observed Agent → Embedded Guardian Agent SDK
```

**Advantages:**
- Lower latency (local evaluation)
- No single point of failure
- Better performance for high-volume agents

**Considerations:**
- Policy synchronization complexity
- More difficult to monitor and maintain
- Potential for policy drift across agents

### Hybrid Approach
```
Critical Agents → Dedicated Guardian Agent
Standard Agents → Shared Guardian Agent Service
```

**Advantages:**
- Optimizes performance where needed
- Centralized management for standard cases
- Flexibility for different agent profiles

**Considerations:**
- More complex deployment
- Need clear criteria for agent classification
- Multiple deployment patterns to maintain

---

## Integration Points

### Framework Integration
Agent frameworks need to implement AOS hooks:
- **LangChain** — callback-based hook integration
- **CrewAI** — middleware-based hook system
- **Custom frameworks** — direct hook implementation
- **Model providers** — native hook support in platforms

### Policy Management
Policies need to be:
- **Declarative** — defined in policy language, not code
- **Versioned** — track changes over time
- **Testable** — validate policies before deployment
- **Deployable** — automated policy rollout

### Observability Integration
Trace data needs to flow to:
- **OpenTelemetry collector** — span aggregation and processing
- **OCSF mapper** — security event conversion
- **SIEM systems** — existing security monitoring infrastructure
- ** dashboards** — real-time monitoring and alerting

### Security Tooling Integration
Enterprise classifiers integrate with:
- **DLP systems** — data loss prevention
- **IAM systems** — identity and access management
- **Threat intelligence** — security threat feeds
- **Compliance tools** — regulatory monitoring and reporting

---

## Security Considerations

### Guardian Agent Security
The Guardian Agent itself is a security-critical component:
- **Secure communication** — encrypted channels between agents and Guardian Agent
- **Authentication** — verify agent identities before processing hooks
- **Authorization** — ensure agents can only access appropriate policies
- **Tamper resistance** — protect Guardian Agent from compromise

### Policy Security
Policies are security-sensitive configurations:
- **Access control** — restrict who can modify policies
- **Version control** — track all policy changes
- **Approval workflows** — require review for policy changes
- **Backup and recovery** — protect against accidental or malicious policy deletion

### Trace Data Security
Trace data contains sensitive information:
- **Data minimization** — only collect necessary trace data
- **Encryption** — protect trace data in transit and at rest
- **Retention policies** — define appropriate data retention periods
- **Access controls** — restrict who can access trace data

### AgBOM Security
Component inventories are supply chain critical:
- **Immutable records** — prevent tampering with historical AgBOM data
- **Cryptographic verification** — verify component integrity
- **Approval workflows** — formal process for component approval
- **Continuous monitoring** — detect unauthorized component changes

---

## Scalability Considerations

### Performance Requirements
Guardian Agent evaluation must be fast:
- **Latency budget** — typically < 100ms for hook evaluation
- **Throughput** — handle peak agent interaction volumes
- **Resource utilization** — efficient CPU and memory usage
- **Caching** — cache policy evaluations where appropriate

### High Availability
Guardian Agent is a control plane component:
- **Redundancy** — deploy multiple instances for failover
- **Load balancing** — distribute load across instances
- **Health checks** — monitor Guardian Agent availability
- **Graceful degradation** — fail-safe behavior if Guardian Agent unavailable

### Elastic Scaling
Agent fleets may have variable load:
- **Auto-scaling** — scale Guardian Agent capacity with demand
- **Resource limits** — prevent resource exhaustion
- **Priority queuing** — prioritize critical agent interactions
- **Backpressure handling** — manage overload situations gracefully

---

## Monitoring and Alerting

### Key Metrics
Monitor Guardian Agent health and performance:
- **Hook evaluation latency** — time to process hook events
- **Policy evaluation rates** — hooks processed per second
- **Verdict distribution** — allow/deny/modify ratios
- **Error rates** — failed evaluations or system errors

### Security Alerts
Alert on potential security issues:
- **Unusual deny patterns** — spikes in denied actions
- **Policy violations** — repeated attempts to bypass controls
- **Component changes** — unauthorized AgBOM modifications
- **Authentication failures** — failed agent authentication attempts

### Compliance Monitoring
Track compliance-relevant events:
- **Human oversight events** — interventions requiring human review
- **Regulatory triggers** — events mapped to compliance requirements
- **Audit trail completeness** — verify trace data integrity
- **Policy coverage** — ensure all required controls are active

---

## Key Takeaways

1. **Every hook is a control point** — Guardian Agent can intervene at any decision point
2. **Every hook emits a trace** — complete audit trail for compliance and incident response
3. **Three-tier architecture** — clear separation between platform, enforcement, and enterprise
4. **Multiple deployment patterns** — choose centralized, distributed, or hybrid based on needs
5. **Security is critical** — Guardian Agent itself must be protected and secured
6. **Scalability matters** — Guardian Agent must handle peak loads with low latency
7. **Monitoring is essential** — track performance, security, and compliance metrics

---

## Next Steps

- **Governance Checklist** — assess your implementation maturity
- **Ecosystem & Roadmap** — understand current ACS status and future plans