AI Agent Assembly — Enterprise Documentation

Welcome to the AI Agent Assembly enterprise documentation site.

AI Agent Assembly is a governance-native runtime for AI agents. It enforces policy, tracks costs, and intercepts unsafe actions across your entire AI agent fleet — without changing your existing agent code.

Who this documentation is for

This site is for enterprise evaluators, security teams, and operators assessing AI Agent Assembly for production adoption.

If you are a developer looking to contribute or integrate at the code level, see the open-source documentation.

What you will find here

The three-layer interception model

AI Agent Assembly enforces governance through three independently deployable layers:

1. SDK layer (in-process) — language SDKs wrap your agent calls and enforce pre-execution allow/deny before any network egress occurs.
2. Sidecar proxy (aa-proxy) — intercepts outbound HTTPS via MitM with a per-host CA, catching anything the SDK misses without code changes.
3. eBPF sensor (aa-ebpf) — kernel-level hooks watching SSL libraries and process syscalls; catches bypass attempts at the OS level (Linux only).

All three layers report to the gateway, which evaluates policy and tracks per-team budgets.

Last reviewed: 2026-05-10 — AI Agent Assembly Team

Security Model

This page documents the security posture of AI Agent Assembly for enterprise security and compliance teams.

IronClaw Five-Layer Defense

AI Agent Assembly organizes its security controls into five named layers. Each layer is independently deployable and adds defense-in-depth:

STRIDE Threat Model

The table below maps each STRIDE category to the five primary components of AI Agent Assembly and the mitigating controls in place.

Traceability: Each STRIDE row maps to a specific IronClaw layer control. For configuration paths and runbook references, consult the security runbook in the agent-assembly repository.

Cryptographic Primitives

All keys are generated using a CSPRNG. No MD5, SHA-1, or DES primitives are used anywhere in the stack.

Authentication Flow

SDK → Gateway (gRPC)

sequenceDiagram
  autonumber
  participant SDK as Language SDK
  participant GW as aa-gateway

  SDK->>GW: RegisterAgent(agent_id, public_key, metadata)
  GW-->>SDK: AgentToken (Ed25519-signed JWT, TTL=1h)
  Note over SDK,GW: All subsequent calls carry the AgentToken in gRPC metadata

  SDK->>GW: CheckPolicy(event) [+ AgentToken]
  GW->>GW: Verify Ed25519 signature, check TTL
  GW-->>SDK: PolicyDecision

Operator → Dashboard / CLI (SAML/OIDC)

sequenceDiagram
  autonumber
  participant Ops as Operator
  participant CLI as aasm CLI / Dashboard
  participant API as aa-api
  participant IdP as Enterprise IdP (SAML/OIDC)

  Ops->>CLI: aasm login --sso
  CLI->>IdP: Redirect to IdP with SAML AuthnRequest
  IdP-->>Ops: Login prompt (MFA enforced by IdP)
  Ops->>IdP: Credentials + MFA
  IdP-->>CLI: SAML Assertion / OIDC id_token
  CLI->>API: Exchange assertion for session token
  API-->>CLI: Signed session token (TTL=8h)
  CLI-->>Ops: Login successful

Secrets Management

• Secrets (LLM API keys, webhook tokens) are stored encrypted with AES-256-GCM.
• The encryption key is derived from a master secret held in the SaaS control plane's hardware security module (HSM).
• Secrets are never written to disk in plaintext.
• Secrets are never logged, even at DEBUG level.
• Secret rotation is supported via the aasm secret rotate command, which re-encrypts in place without service restart.

Audit Log

• Every agent action (policy check, event record, budget debit) produces an immutable log entry.
• Log entries are signed with HMAC-SHA256 using a log-signing key.
• Logs are append-only; no delete or update API exists.
• Log retention: configurable per tenant (default: 90 days).
• Logs are exportable in JSON or CEF format for SIEM integration.

Compliance Posture

Related Documentation

• Why AI Agent Assembly? — competitive positioning and governance differentiation
• Cloud Deployment — SSO configuration, SCIM provisioning
• Open Core Boundary — which security features are OSS vs enterprise

Last reviewed: 2026-05-10 — AI Agent Assembly Team

Why AI Agent Assembly?

This page helps enterprise evaluators understand where AI Agent Assembly fits relative to other tools in the AI governance and observability space. All competitor data cited from vendor public documentation as of 2026-05-05.

Feature Matrix

Rows are capability axes. Columns: AI Agent Assembly (AAASM), Langfuse, Helicone, Opik, Pillar Security.

Legend: ✓ = full support · partial = limited / gated behind tier · ✗ = not available · n/a = not applicable to product category

Where We Currently Lag

These are capabilities competitors offer that AI Agent Assembly does not yet fully deliver. Linked roadmap tickets where one exists.

1. Vault-backed secrets management — Pillar Security provides first-class secrets vault integration with automatic secret rotation and injection. AAASM currently supports secret-pattern detection via regex policies but does not integrate with HashiCorp Vault or AWS Secrets Manager.
2. Automated human-in-the-loop approval workflows — Pillar Security provides structured approval routing with escalation chains. AAASM can deny and alert but does not yet route decisions to a named approver queue.
3. Self-hosted deployment — Langfuse, Opik, and Pillar Security all support self-hosted deployment. AAASM is SaaS-only in this release; self-hosted is out of scope for the current roadmap (see Open Core Boundary).
4. Evaluation frameworks and LLM-as-judge scoring — Langfuse and Opik provide built-in evaluation pipelines, dataset management, and automated LLM-as-judge scoring for output quality. AAASM's policy engine operates on patterns and metadata, not semantic quality.
5. Prompt management and versioning — Langfuse provides a managed prompt registry with version history and A/B comparison. AAASM does not include a prompt registry.

Where We Lead

These are capabilities where AI Agent Assembly provides uniquely strong or differentiated support.

1. Pre-execution runtime enforcement — AAASM is the only product in this comparison that makes binding allow/deny decisions before an agent action executes. All others are observability tools that record what happened after the fact.
2. Kernel-level bypass detection via eBPF — aa-ebpf intercepts TLS calls at the SSL library level using Linux uprobes, catching bypass attempts that SDK-only solutions cannot see. No competitor in this matrix offers kernel-level enforcement.
3. Network-layer interception without code changes — aa-proxy performs MitM HTTPS interception via a per-host CA. Governance can be applied to agents that do not use the SDK. No competitor supports sidecar-proxy-level enforcement.
4. Policy-as-code with GitOps workflow — AAASM policies are YAML/JSON documents that can be versioned, reviewed, and deployed via standard Git workflows. No competitor in this matrix offers a structured policy language; guardrails in other tools are typically configured through UI forms or proprietary DSLs.
5. Immutable tamper-evident audit log — AAASM's audit log entries are signed with HMAC-SHA256, making post-hoc alteration detectable. This is a compliance requirement in regulated industries (PCI-DSS, SOC 2 Type II) that no competitor in this matrix fully addresses.

Competitor Documentation References

Last validated: 2026-05-05 against vendor documentation as of that date.

Related Documentation

• Security Model — STRIDE threat model, IronClaw defense
• Open Core Boundary — what is OSS vs enterprise
• Quick Start (SaaS) — get started in minutes

Last reviewed: 2026-05-10 — AI Agent Assembly Team

Open Core Boundary

AI Agent Assembly follows an open-core model. The interception infrastructure, policy engine, SDK shims, and CLI are Apache-2.0 open source. Enterprise features — SSO, SCIM, advanced audit, multi-region data residency — are covered by the AAA-Commercial license and available on paid SaaS tiers.

Self-hosted deployment is not available. Regardless of license, AI Agent Assembly is a SaaS-only product. The Apache-2.0 crates are open source for inspection, contribution, and SDK integration — not for self-hosted deployment. There is no bring-your-own-infrastructure path. See Cloud Deployment and Quick Start (SaaS) for the available onboarding paths.

Why Open Core?

The interception and enforcement infrastructure that sits between AI agents and the outside world must be trustworthy, inspectable, and independently auditable. Keeping the core open source is not a marketing decision — it is a direct consequence of the product's security posture. An enterprise deploying AI agents cannot take our word for how the policy engine evaluates rules, how eBPF probes intercept system calls, or how the sidecar proxy terminates TLS. Open source means the enforcement path can be read, reviewed, and verified by a third party without involving us.

The boundary between what is open and what is commercial follows a single principle: enforcement is always open; operational convenience and enterprise compliance infrastructure are commercial. If a feature controls what agents can do, it belongs in the Apache-2.0 core. If a feature controls how operators manage, scale, or audit the system at enterprise grade — SSO federation, automated user lifecycle via SCIM, long-retention tamper-evident audit logs, multi-region data residency — it belongs in the commercial tier. This principle means that a motivated team can always fork, read, or contribute to every security control in the stack, regardless of their subscription status.

Open-sourcing the core also creates a community feedback loop that makes the enforcement logic stronger over time. Security researchers who find a gap in the policy engine, proxy TLS handling, or eBPF program can open an issue or send a pull request. The Apache-2.0 license was chosen specifically because it permits commercial integration without a copyleft obligation — SDK users can embed the shims in proprietary products without the license propagating to their codebase.

Finally, open core without self-hosting is a deliberate choice. We ship the crates as open source so teams can read, audit, and contribute — not so they can run their own private deployment. Operating a multi-tenant SaaS with the security and reliability commitments described in the Security Model requires infrastructure, on-call, and operational expertise that goes far beyond what a compiled binary provides. Keeping deployment SaaS-only lets us uphold the SLA and compliance posture without fragmenting the product across self-managed installs.

Feature Matrix

Crate Licensing

All Cargo crates in the agent-assembly workspace are Apache-2.0:

Apache 2.0 key terms

The Apache License 2.0 grants users the right to use, reproduce, prepare derivative works, distribute, and sublicense the software with or without modification. It does not grant trademark rights, and it requires preservation of copyright notices and attribution in distributed works. See the full license text at https://www.apache.org/licenses/LICENSE-2.0.

Enterprise features (SSO, SCIM, tamper-evident audit, dedicated regions) are delivered via SaaS-side configuration — not via separate closed-source crates. The OSS codebase contains all interception and enforcement logic.

Contributing to the OSS Core

The Apache-2.0 crates welcome community contributions. See CONTRIBUTING.md in the agent-assembly repository for:

• Branching and commit conventions
• How to run the test suite (cargo nextest run --workspace)
• The CLA requirement for non-trivial contributions
• How to file issues and feature requests

Enterprise feature requests (SSO, SCIM, audit extensions) are tracked as AAASM JIRA tickets in the Enterprise component and delivered by the AI Agent Assembly team.

Related Documentation

• Security Model — cryptographic primitives and audit log details
• Cloud Deployment — SSO, SCIM, SLA tier comparison
• Why AI Agent Assembly? — open-source posture vs competitors

Last reviewed: 2026-05-10 · Legal approver: @legal-team

Quick Start (SaaS)

AI Agent Assembly is a SaaS-only product. Choose the tier that matches your team size and compliance requirements, then follow the path below to connect your first AI agent.

Self-hosted deployment is not available. There is no self-hosted, on-premises, or bring-your-own-infrastructure option. All governance, policy evaluation, and audit logging run in the AI Agent Assembly cloud. See Open Core Boundary for the licensing model.

LangChain: Zero-to-Governance in Under 5 Minutes

This end-to-end example takes a LangChain agent from zero to fully governed in under 5 minutes using any SaaS tier.

Prerequisites: Python 3.12+, an OpenAI API key, and a Pro (or higher) workspace.

Step 1 — Install packages

pip install agent-assembly langchain langchain-openai langchain-core

Step 2 — Set credentials

export AAA_WORKSPACE_ID="<your-workspace-id>"   # from Settings → Workspace
export AAA_API_KEY="<your-api-key>"             # from Settings → API Keys
export OPENAI_API_KEY="<your-openai-key>"

Step 3 — Instrument your LangChain agent

import os
from agent_assembly import AgentAssembly
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.tools import tool

aaa = AgentAssembly()

@tool
def summarise_text(text: str) -> str:
    """Return a one-sentence summary of the provided text."""
    return text[:200] + "..." if len(text) > 200 else text

@aaa.agent(name="langchain-research-agent")
def run_agent(question: str) -> str:
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    tools = [summarise_text]

    prompt = ChatPromptTemplate.from_messages([
        ("system", "You are a helpful research assistant."),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])

    agent = create_openai_tools_agent(llm, tools, prompt)
    executor = AgentExecutor(agent=agent, tools=tools, verbose=False)
    result = executor.invoke({"input": question})
    return result["output"]

if __name__ == "__main__":
    answer = run_agent("What is AI Agent Assembly and why does it matter for enterprise governance?")
    print(answer)

The @aaa.agent decorator registers langchain-research-agent with the gateway, wraps every invocation with pre-execution policy evaluation, and emits an audit event for every LangChain call — without modifying LangChain internals.

Step 4 — Activate a starter policy

In the console, open Policies → New Policy and apply the starter template (allow all, audit all). This takes under 30 seconds. Every subsequent call from langchain-research-agent is now governed, audited, and visible in the Audit Log panel.

What governance looks like at runtime

[AAASM] Agent registered: langchain-research-agent (workspace: ws-a1b2...)
[AAASM] Policy check: ALLOW  event=llm_call  agent=langchain-research-agent
[AAASM] Audit event written: id=evt_01j...  latency=2ms

Pro Tier

Signup: self-serve at https://app.agent-assembly.io/signup

Included features: up to 10 agents, basic policy engine (allow/deny/audit), 30-day audit log retention, community forum support.

Expected onboarding time: ~10 minutes from signup to first governed agent call.

Primary contact channel: self-serve; community forum at https://community.agent-assembly.io.

Pro signup steps

1. Navigate to https://app.agent-assembly.io/signup and create an account with your work email.
2. Verify your email address.
3. On the Workspace Setup page, enter a workspace name (e.g., acme-ai-ops) and select your primary region.
4. Copy your Workspace ID and generate an API Key under Settings → API Keys.
5. Install the SDK:

pip install agent-assembly          # Python
pnpm add @agent-assembly/sdk        # TypeScript
go get github.com/agent-assembly/go-sdk  # Go

6. Set credentials:

export AAA_WORKSPACE_ID="<your-workspace-id>"
export AAA_API_KEY="<your-api-key>"

7. Instrument your agent entry point:

from agent_assembly import AgentAssembly

aaa = AgentAssembly()

@aaa.agent(name="my-first-agent")
def run_agent(prompt: str) -> str:
    import openai
    client = openai.OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

8. Open Policies → New Policy in the console and activate a starter policy. Your agent is now governed.

Business Tier

Signup: self-serve at https://app.agent-assembly.io/signup — select Business during workspace setup.

Included features: up to 50 agents, full policy engine, SSO (SAML 2.0 / OIDC), 90-day audit log retention, SIEM export, business-hours support (24h response).

Expected onboarding time: ~30 minutes, including SSO connect.

Primary contact channel: support ticket via https://app.agent-assembly.io/support.

Business signup steps

1. Sign up at https://app.agent-assembly.io/signup, select the Business tier.
2. On the Billing page, enter your credit card details (processed via Stripe).
3. Complete workspace setup (name, region) as in the Pro flow above.
4. Connect SSO: navigate to Settings → Authentication → SSO and follow the SAML 2.0 or OIDC setup steps. SSO is optional at the Business tier but recommended for teams.
5. Invite your team under Settings → Users — assign roles (Admin, Developer, Viewer).
6. Instrument agents and create policies as in the Pro flow.

Enterprise Tier

Signup: form-driven via https://app.agent-assembly.io/contact-sales.

Included features: unlimited agents, dedicated region (data residency), SCIM provisioning, tamper-evident audit log, audit log retention up to 1 year, 99.9% SLA, 24/7 support (4h response), dedicated SRE contact.

Expected onboarding time: 1–3 weeks, driven by procurement and security review.

Primary contact channel: your assigned Sales Engineer (SE).

Enterprise procurement timeline

Enterprise-specific steps

1. Submit the contact form at https://app.agent-assembly.io/contact-sales. Include estimated agent count, primary region preference, and compliance requirements (SOC 2, HIPAA, GDPR).
2. During the SE call, confirm your IdP (Okta, Azure AD, PingFederate, etc.) and data residency requirement.
3. After contract signature, the SE provisions your workspace in the selected dedicated region and sends your Workspace ID and initial API key.
4. Configure SSO (SAML or OIDC) per Cloud Deployment → SSO Configuration.
5. Configure SCIM provisioning per Cloud Deployment → SCIM User Provisioning for automated user lifecycle management.
6. Configure budgets per Cloud Deployment → Budget Configuration for per-team LLM spend caps.
7. Instrument agents and create policies as in the Pro flow.

Next Steps

• Cloud Deployment — SSO/SCIM deep-dive, region selection, billing, SLA tiers
• Policy Reference — full policy rule schema
• Open Core Boundary — what's in the OSS core vs enterprise tier

Last reviewed: 2026-05-10 · AI Agent Assembly Team

Cloud Deployment

This page covers enterprise deployment configuration for the AI Agent Assembly SaaS platform: identity federation, user provisioning, regional data residency, and SLA commitments.

Self-hosted deployment is not available. AI Agent Assembly is a SaaS-only product. There is no self-hosted, on-premises, or bring-your-own-infrastructure option. All compute, storage, and governance logic runs in the AI Agent Assembly cloud.

SaaS Regions

AI Agent Assembly is available in the following regions. Data at rest and in transit stays within the selected region.

Select your primary region when creating a workspace (see Quick Start (SaaS)). Region selection is permanent — contact support to migrate.

Tenant Provisioning

A workspace is the top-level isolation boundary. All agents, policies, budgets, and users belong to a single workspace (tenant).

Tenant creation

Tenant ID format

Tenant IDs (workspace IDs) follow the format ws-<uuid4> — for example, ws-a1b2c3d4-e5f6-7890-abcd-ef1234567890. The workspace ID is shown in Settings → Workspace and is required in all SDK configuration.

Default quotas per tier

Contact support to request a quota increase.

SSO Configuration

The following diagram shows the SSO authentication flow for a user's first login after SSO is configured.

sequenceDiagram
  autonumber
  participant User as User (Browser)
  participant AAA as AI Agent Assembly
  participant IdP as Identity Provider

  User->>AAA: Navigate to app.agent-assembly.io
  AAA-->>User: Redirect to IdP SSO URL
  User->>IdP: Authenticate (password / MFA)
  IdP-->>User: SAML assertion or OIDC id_token
  User->>AAA: POST assertion / code to ACS / callback URL
  AAA->>IdP: Verify assertion signature (SAML) or exchange code (OIDC)
  IdP-->>AAA: Validated identity claims (email, groups)
  AAA->>AAA: Map groups to AAASM roles (SCIM group-role mapping)
  AAA-->>User: Session cookie issued — workspace access granted

SAML 2.0

1. In the AI Agent Assembly console, navigate to Settings → Authentication → SSO.
2. Select SAML 2.0.
3. Copy the Assertion Consumer Service (ACS) URL and Entity ID shown in the console.
4. In your IdP (Okta, Azure AD, PingFederate, etc.), create a new SAML application:
   • Set the Single Sign-On URL to the ACS URL.
   • Set the Audience URI / SP Entity ID to the Entity ID.
   • Map the following attributes:

5. Download the IdP metadata XML from your IdP and upload it to the AI Agent Assembly console.
6. Click Test SSO to verify the configuration before enabling.
7. Enable Enforce SSO to prevent password-based login for your domain.

OIDC

1. In the AI Agent Assembly console, navigate to Settings → Authentication → SSO.
2. Select OpenID Connect (OIDC).
3. Register AI Agent Assembly as an OIDC client in your IdP:
   • Set the Redirect URI to the value shown in the console.
   • Request scopes: openid email profile groups.
4. Enter the following values from your IdP registration:
   • Issuer URL (e.g., https://your-idp.example.com)
   • Client ID
   • Client Secret
5. Save the configuration and click Test OIDC Login.

SCIM User Provisioning

SCIM 2.0 enables automatic user and group provisioning from your IdP. When SCIM is configured, users are created, updated, and deprovisioned automatically as they are added to or removed from groups in your IdP.

Supported operations

Configuration steps

1. In the console, navigate to Settings → Authentication → SCIM.
2. Click Generate SCIM Token. Copy the token — it is shown only once.
3. In your IdP, configure the SCIM provisioning connector:
   • SCIM Endpoint URL: shown in the console (e.g., https://api.agentassembly.io/scim/v2)
   • Authentication Method: Bearer Token
   • Bearer Token: the token generated in step 2
4. Enable provisioning in your IdP and run a test synchronization.
5. Verify users appear under Settings → Users in the console.

Role-Based Access Control

Workspace members are assigned one of the following roles:

Roles are assigned in the console under Settings → Users, or automatically via SCIM group-to-role mapping.

SCIM Group → Role Mapping

Configure group-to-role mappings in Settings → Authentication → SCIM → Role Mapping:

Budget Configuration

Budgets cap per-team LLM spending. The gateway enforces the budget before allowing agent actions.

Configuring a budget

1. Navigate to Budgets → New Budget.
2. Set the following fields:

3. Click Save Budget.

Budget enforcement behaviour

• Budgets are evaluated after policy rules. A deny policy overrides a budget allow.
• When a budget is exceeded and action is deny, agents receive a BudgetExceededError.
• Budget state resets at the start of each window (midnight UTC for daily/weekly/monthly).
• Budget alerts are delivered to the configured notification channel (Slack, webhook).

SLA Tiers

SLA credits apply for downtime exceeding the SLA threshold. See the Terms of Service for the full credit schedule.

Billing Setup

Card-based billing (Pro and Business)

Pro and Business tiers are billed monthly via Stripe.

1. During workspace creation, enter your credit card on the Billing page.
2. Invoices are emailed to the workspace Owner's address on the first of each month.
3. Update your payment method any time under Settings → Billing → Payment Method.

Invoice-based billing (Enterprise)

Enterprise customers are billed via net-30 invoice.

1. The Sales Engineer adds your purchase order number to the workspace at contract signature.
2. Invoices are issued monthly to the billing contact specified in the Order Form.
3. Wire transfer and ACH are accepted; credit card is not required.

BAA and DPA (Enterprise)

HIPAA and GDPR compliance documents: Enterprise customers requiring a Business Associate Agreement (BAA) for HIPAA compliance or a Data Processing Agreement (DPA) for GDPR compliance should request these documents during the SE call. Both are countersigned by the AI Agent Assembly legal team before workspace provisioning.

Related Documentation

• Security Model — authentication flow diagrams, cryptographic primitives
• Quick Start (SaaS) — initial workspace setup
• Open Core Boundary — which features are on which tier

Last reviewed: 2026-05-10 · AI Agent Assembly Team

Policy Reference

Policies are YAML documents that control what AI agents are allowed, denied, or rate-limited to do. The gateway evaluates every policy before each agent action.

Document Formats

The gateway accepts two formats.

Envelope format (recommended)

Uses apiVersion / kind / metadata / spec wrapping — version-controlled and GitOps-friendly:

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: my-policy         # shown in console and audit log
  version: "1.0.0"        # your policy revision
  description: ...        # optional
spec:
  scope: team:platform
  network:
    allowlist:
      - api.openai.com
  budget:
    daily_limit_usd: 25.0

Flat format

Minimal format without the envelope wrapper — useful for quick testing:

version: "1.0"
scope: global
network:
  allowlist:
    - api.openai.com

Top-Level Fields

Scope

The scope field determines which agents a policy applies to. Policies cascade from broadest to narrowest — Global → Org → Team → Agent → Tool — with most-restrictive-wins merging.

tool:<name> sits at the most-restrictive end of the cascade. A tool-scoped policy can deny slack-mcp for every agent in team:platform even when team- and agent-level policies would otherwise allow it.

Validation: The agent: variant requires a valid hyphenated UUID. The identifier after : must not be empty. Unknown scope kinds (e.g., project:foo) are rejected with a validation error.

network

Controls outbound network connections the agent may initiate.

When network is present but allowlist is absent or empty, no outbound connections are permitted.

network:
  allowlist:
    - "api.openai.com"
    - "*.slack.com"
    - "internal-api.corp.example"

schedule

Restricts the time window during which the agent is permitted to run.

schedule.active_hours

All three sub-fields are required when active_hours is present. start must be earlier than end.

schedule:
  active_hours:
    start: "09:00"
    end: "18:00"
    timezone: "America/New_York"

budget

Caps per-agent LLM spend. The gateway enforces the budget before allowing the agent action.

budget:
  daily_limit_usd: 25.0
  monthly_limit_usd: 500.0
  timezone: "America/Los_Angeles"
  action_on_exceed: deny

data

Scans agent inputs and outputs for PII or credential patterns using regex.

data:
  sensitive_patterns:
    - "sk-[a-zA-Z0-9]{48}"               # OpenAI API key
    - "\\b\\d{3}-\\d{2}-\\d{4}\\b"       # US SSN
    - "(?i)password\\s*[:=]\\s*\\S+"     # password assignment

tools

Per-tool configuration keyed by tool name. Each key in the tools map is a tool name string; the value is a tool policy object.

tools:
  bash:
    allow: true
    limit_per_hour: 10
    requires_approval_if: "governance_level >= L2"
  execute_shell:
    allow: false
  file_write:
    allow: true
    limit_per_hour: 5

requires_approval_if CEL expressions: The expression is evaluated against the tool call context. The identifier governance_level exposes the current agent's governance tier (L0–L3). Referencing an unknown level (e.g., L4) is a validation error.

capabilities

Broad capability allow/deny lists that apply across all tools and actions.

Valid capability strings

Unknown capability strings are rejected with a validation error. The mcp_tool: and model: prefixes require a non-empty name after the colon.

capabilities:
  allow:
    - file_read
    - network_outbound
    - mcp_tool:git
    - mcp_tool:bash
  deny:
    - terminal_exec
    - file_write

approval

Per-policy escalation overrides. When absent, team-level routing defaults are used.

approval:
  timeout_seconds: 600
  escalation_role: org-admin

The top-level approval_timeout_secs sets the default for the whole policy document; approval.timeout_seconds overrides it at the per-policy escalation level.

Validation Rules

The gateway validates every policy on upload. All errors are collected and returned together; the upload is rejected if any error is present.

Unknown keys at any level produce a warning (not an error) — the policy is accepted and the unknown key is ignored. This allows forward-compatible policy files.

Examples

Minimal — budget cap only

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: budget-only
  version: "1.0.0"
spec:
  budget:
    daily_limit_usd: 10.0
    action_on_exceed: deny

Network egress allowlist

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: allowlist-openai-slack
  version: "1.0.0"
spec:
  scope: team:platform
  network:
    allowlist:
      - "api.openai.com"
      - "*.slack.com"

Capability control

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: capability-example
  version: "1.0.0"
spec:
  scope: global
  capabilities:
    allow:
      - file_read
      - network_outbound
      - mcp_tool:git
      - mcp_tool:bash
    deny:
      - terminal_exec
      - file_write

Tool rate-limiting with approval gate

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: guarded-tools
  version: "1.0.0"
spec:
  tools:
    bash:
      allow: true
      limit_per_hour: 10
      requires_approval_if: "governance_level >= L2"
    execute_shell:
      allow: false

Business-hours schedule

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: business-hours-only
  version: "1.0.0"
spec:
  scope: team:ops
  schedule:
    active_hours:
      start: "09:00"
      end: "18:00"
      timezone: "America/New_York"

PII detection

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: no-pii-in-output
  version: "1.0.0"
spec:
  data:
    sensitive_patterns:
      - "sk-[a-zA-Z0-9]{48}"
      - "\\b\\d{3}-\\d{2}-\\d{4}\\b"

Full policy — all sections

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: production-full
  version: "1.0.0"
  description: Full example combining all policy sections.
spec:
  scope: team:platform
  network:
    allowlist:
      - "api.openai.com"
      - "slack.com"
  schedule:
    active_hours:
      start: "09:00"
      end: "18:00"
      timezone: "Asia/Taipei"
  budget:
    daily_limit_usd: 25.0
    monthly_limit_usd: 500.0
    action_on_exceed: deny
  data:
    sensitive_patterns:
      - "sk-[a-zA-Z0-9]{48}"
  tools:
    bash:
      allow: true
      limit_per_hour: 10
    file_write:
      allow: false
  capabilities:
    allow:
      - file_read
      - network_outbound
    deny:
      - terminal_exec
  approval_timeout_secs: 300
  approval:
    escalation_role: org-admin

Related Documentation

• Security Model — IronClaw layers and policy engine position in the stack
• Cloud Deployment — uploading and activating policies in the console
• Quick Start (SaaS) — create and activate your first policy

Last reviewed: 2026-05-10 · AI Agent Assembly Team