Agent Safe Defaults

Making Your Agent Safe by Default

This guide walks you through the checklist and patterns for deploying AI agents safely with OnceOnly.

🛡️ The Safety Pyramid

        ┌─────────────────────────┐
        │   Audit & Monitoring    │ (Logging)
        ├─────────────────────────┤
        │   Policy Enforcement    │ (Rate limits, Budget)
        ├─────────────────────────┤
        │   Tool Registration     │ (HMAC auth, Timeouts)
        ├─────────────────────────┤
        │   Idempotency           │ (No duplicates)
        ├─────────────────────────┤
        │   API Authentication    │ (Valid key)
        └─────────────────────────┘

Step 1: Authenticate API Key

# Always verify API key first
def call_onceonly(endpoint: str, payload: dict):
    response = requests.post(
        f"https://api.onceonly.tech{endpoint}",
        headers={
            "Authorization": f"Bearer {os.getenv('ONCEONLY_API_KEY')}",
            "Content-Type": "application/json"
        },
        json=payload
    )

    if response.status_code == 401:
        raise Exception("Invalid API key - check ONCEONLY_API_KEY")

    return response.json()

Step 2: Check Idempotency

# Always check lock before executing action
def safe_execute(action_id: str, action_fn, *args, **kwargs):
    """
    Execute action safely with idempotency protection.
    """
    # Check OnceOnly
    lock = call_onceonly("/v1/check-lock", {
        "key": f"action_{action_id}",
        "ttl": 3600,
        "metadata": {
            "action_id": action_id,
            "timestamp": datetime.now().isoformat()
        }
    })

    if lock["status"] == "duplicate":
        logger.warning(f"Duplicate action detected: {action_id}")
        # Return cached result
        return get_cached_result(action_id)

    # New action - execute
    try:
        result = action_fn(*args, **kwargs)
        cache_result(action_id, result)
        return result
    except Exception as e:
        logger.error(f"Action failed: {action_id}", exc_info=True)
        raise

Step 3: Register All Tools

# Before agent can use a tool, register it
def register_tool(tool_name: str, url: str, price_usd: float = 0.0):
    """Register tool with OnceOnly"""

    response = requests.post(
        "https://api.onceonly.tech/v1/tools",
        headers={"Authorization": f"Bearer {os.getenv('ONCEONLY_API_KEY')}"},
        json={
            "name": tool_name,
            "scope_id": "global",
            "url": url,
            "auth": {
                "type": "hmac_sha256",
                "secret": os.getenv(f"{tool_name.upper()}_SECRET")
            },
            "timeout_ms": 15000,
            "max_retries": 2,
            "enabled": True,
            "description": f"Tool: {tool_name}"
        }
    )

    if response.status_code != 201:
        raise Exception(f"Failed to register tool: {response.text}")

    logger.info(f"Tool registered: {tool_name}")
    return response.json()

Step 4: Set Up Policies

# Define strict policies for each agent
def setup_agent_policy(agent_id: str, allowed_tools: list, budget_usd: float):
    """Setup safety policy for agent"""

    policy = {
        "agent_id": agent_id,
        "allowed_tools": allowed_tools,
        "blocked_tools": [
            "delete_user",
            "delete_data",
            "change_password"
        ],
        "max_actions_per_hour": 100,
        "max_spend_usd_per_day": budget_usd,
        "pricing_rules": [
            {"tool": tool, "price_usd": 0.01}
            for tool in allowed_tools
        ]
    }

    response = requests.post(
        f"https://api.onceonly.tech/v1/policies/{agent_id}",
        headers={"Authorization": f"Bearer {os.getenv('ONCEONLY_API_KEY')}"},
        json=policy
    )

    if response.status_code != 201:
        raise Exception(f"Failed to set policy: {response.text}")

    logger.info(f"Policy set for agent: {agent_id}")
    return response.json()

Step 5: Monitor Execution

# Check agent logs regularly
def monitor_agent(agent_id: str):
    """Monitor agent for suspicious activity"""

    logs = requests.get(
        f"https://api.onceonly.tech/v1/agents/{agent_id}/logs",
        headers={"Authorization": f"Bearer {os.getenv('ONCEONLY_API_KEY')}"},
        params={"limit": 100}
    ).json()

    # Count blocked actions
    blocked = [log for log in logs if log.get("allowed") == False]

    if len(blocked) > 10:
        logger.warning(f"Agent {agent_id} has {len(blocked)} blocked actions")
        # Disable agent if too many blocks
        disable_agent(agent_id, reason="suspicious_activity")

    return logs

Complete Safe Agent Setup

class SafeAgent:
    """Wrapper that makes any agent safe by default"""

    def __init__(self, agent_id: str, tools: list, budget_usd: float = 100.0):
        self.agent_id = agent_id
        self.tools = tools
        self.budget = budget_usd

        # Setup
        self._register_tools()
        self._setup_policy()
        self._start_monitoring()

    def _register_tools(self):
        """Register all tools"""
        for tool in self.tools:
            try:
                register_tool(
                    tool_name=tool["name"],
                    url=tool["url"],
                    price_usd=tool.get("price", 0.01)
                )
            except Exception as e:
                logger.error(f"Failed to register tool: {e}")

    def _setup_policy(self):
        """Setup safety policy"""
        setup_agent_policy(
            agent_id=self.agent_id,
            allowed_tools=[t["name"] for t in self.tools],
            budget_usd=self.budget
        )

    def _start_monitoring(self):
        """Start background monitoring"""
        import schedule
        schedule.every(1).hour.do(monitor_agent, self.agent_id)

    def execute_action(self, action_id: str, action_fn, *args, **kwargs):
        """Execute action safely"""
        return safe_execute(action_id, action_fn, *args, **kwargs)

# Usage
agent = SafeAgent(
    agent_id="my_support_bot",
    tools=[
        {"name": "send_email", "url": "https://..."},
        {"name": "create_ticket", "url": "https://..."}
    ],
    budget_usd=100.0
)

# Agent is now safe!
agent.execute_action("email_1", send_email, user_email)

Safety Checklist

Before deploying agent to production:

• API key configured and tested
• All tools registered with OnceOnly
• Policy set with appropriate limits
• Idempotency checks in place
• Error handling implemented
• Monitoring/alerts set up
• Audit logging enabled
• Rate limits validated
• Budget limits reviewed
• Blocklisted tools excluded

Common Mistakes to Avoid

❌ Don’t:

• Skip idempotency checks (duplicates!)
• Use unlimited budget (runaway costs)
• Allow all tools (security risk)
• Ignore policy blocks (indicates misconfiguration)
• Deploy without monitoring (blind to problems)

✅ Do:

• Always call check-lock first
• Set realistic rate/budget limits
• Whitelist only needed tools
• Monitor logs daily
• Test policies before production

---

Next: Writing Retriable Tool Calls