Skip to content

Core Concepts

This document explains the core concepts and terminology used throughout the Safeguards.

Overview

The Safeguards is built around several key concepts:

  1. Agents - The entities that perform tasks
  2. Budgets - Resource constraints for agent operations
  3. Pools - Shared resource containers
  4. Coordination - Management of resources across agents
  5. Monitoring - Observation of system metrics
  6. Guardrails - Safety mechanisms that prevent harmful actions
  7. Notifications - Alerts and messages about system status

Agents

An agent in this framework represents an autonomous entity that performs tasks and consumes resources. The Agent class is the base abstraction for all agent implementations.

Key characteristics of agents:

  • Identity: Each agent has a unique identifier
  • Budget: Agents consume budget when performing actions
  • Priority: Agents can have different priority levels (1-10)
  • State: Agents maintain state between operations

Agents are registered with the system and their resource usage is tracked throughout their lifecycle.

Budgets

Budgets represent the resources available to agents. These are typically numerical values (e.g., tokens, API calls, compute time) that are consumed when agents perform actions.

Key characteristics of budgets:

  • Initial Allocation: Starting amount of resources
  • Usage Tracking: System tracks consumption over time
  • Limits: Configurable thresholds (hourly, daily, total)
  • Warnings: Alerts when approaching limits

Budget Pools

Budget pools are containers that hold shared resources that can be distributed among multiple agents. Pools allow for more efficient resource allocation and sharing.

Key characteristics of pools:

  • Total Budget: Overall resources available in the pool
  • Allocated Budget: Resources currently assigned to agents
  • Priority: Pools have priority levels for resource contention
  • Minimum Balance: Required minimum resources to maintain

Budget Coordination

Budget coordination is the process of managing resource allocation, transfers, and rebalancing across agents and pools.

Key capabilities:

  • Registration: Adding agents and pools to the system
  • Transfer: Moving resources between agents or pools
  • Allocation: Distributing resources based on priorities
  • Rebalancing: Dynamically adjusting allocations based on usage patterns
  • Emergency Handling: Special procedures for critical operations

Monitoring

Monitoring involves tracking system metrics, agent behavior, and resource usage to ensure safe operation.

Key monitoring aspects:

  • Resource Metrics: CPU, memory, disk usage
  • Agent Metrics: Budget usage, action counts, latency
  • System Metrics: Overall usage, error rates, health status
  • Historical Analysis: Trend detection and pattern recognition

Safety Guardrails

Guardrails are protective mechanisms that prevent unsafe operations. They typically implement validation logic that runs before agent actions.

Types of guardrails:

  • Budget Guardrails: Prevent budget overruns
  • Resource Guardrails: Prevent excessive resource consumption
  • Permission Guardrails: Enforce access controls
  • Content Guardrails: Validate inputs and outputs for safety
  • Rate Guardrails: Prevent too many operations in a time window

Notifications & Alerts

The notification system provides visibility into system events, warnings, and errors.

Key elements:

  • Alert Levels: Different severity levels (INFO, WARNING, ERROR, CRITICAL)
  • Channels: Different notification methods (console, email, webhook)
  • Targeting: Specific notifications for specific components or agents
  • Thresholds: Configurable thresholds for generating alerts

APIs & Contracts

The framework uses API contracts to define consistent interfaces across different versions.

Key API categories:

  • Agent API: For agent management
  • Budget API: For budget operations
  • Metrics API: For monitoring and metrics
  • Config API: For system configuration
  • Notification API: For alerts and notifications

Transactions

The framework uses a transaction system to ensure operations that span multiple resources remain consistent.

Key aspects:

  • Atomicity: Operations succeed completely or fail completely
  • Consistency: System remains in a valid state
  • Isolation: Concurrent operations don't interfere
  • Durability: Completed operations persist

Priority Levels

Priority determines the importance of agents, pools, and operations, influencing resource allocation.

Priority levels range from 1-10:

  • 1-2: Low priority (background tasks)
  • 3-5: Normal priority (standard operations)
  • 6-8: High priority (important services)
  • 9-10: Critical priority (essential services)

Violation Types

When safety rules are broken, the system generates violation reports with specific types:

  • Overspend: Budget exceeded allocated amount
  • Rate Limit: Too many operations in a time window
  • Resource Breach: Exceeded resource allocation
  • Unauthorized: Attempted operation without permission
  • Pool Breach: Pool resources depleted below minimum

Next Steps

Now that you understand the core concepts, you can explore: - Quick Start Guide to begin implementing the framework - Architecture Overview for a deeper technical understanding - API Reference for detailed interface documentation