Skip to content

guardrail

Bases: BaseGuardrail

Source code in airia/client/guardrail/sync_guardrail.py 
10
11
def __init__(self, request_handler: RequestHandler):
    super().__init__(request_handler)

get_applicable_guardrails(project_id, agent_id=None, correlation_id=None)

Get guardrails applicable to a specific project and optional agent.

This method retrieves guardrail definitions that apply to the specified context using the same matching logic as pipeline execution. It supports hierarchical matching (tenant -> project -> agent) and exclusion mode (IsException flag) when the feature flag is enabled.

Parameters:

Name Type Description Default
project_id str

The unique identifier of the project. This is required and must be a valid GUID.

 required
agent_id str

The unique identifier of the agent/pipeline. When provided, returns guardrails applicable to this specific agent. When omitted, returns guardrails applicable at the project level only.

 None
correlation_id str

A unique identifier for request tracing and logging. If not provided, one will be automatically generated.

 None

Returns:

Type Description
List[Guardrail]

List[Guardrail]: A list of guardrail definitions that apply to the specified context. Each guardrail includes its filters, assignments, and target configurations.

Raises:

Type Description
AiriaAPIError

If the API request fails, including cases where: - The project_id is invalid or doesn't exist (400) - Authentication fails (401) - Access is forbidden (403) - Server errors (5xx)
Example 
from airia import AiriaClient

client = AiriaClient(api_key="your_api_key")

# Get project-level guardrails
guardrails = client.guardrail.get_applicable_guardrails(
    project_id="00000000-0000-0000-0000-000000000000"
)
for guardrail in guardrails:
    print(f"Guardrail: {guardrail.name}")
    print(f"  Enabled: {guardrail.enabled}")
    print(f"  Filters: {len(guardrail.filters)}")

# Get agent-specific guardrails
guardrails = client.guardrail.get_applicable_guardrails(
    project_id="00000000-0000-0000-0000-000000000000",
    agent_id="11111111-1111-1111-1111-111111111111"
)
print(f"Found {len(guardrails)} guardrails for the agent")
Note

Guardrails are matched using hierarchical logic: - Tenant-level guardrails apply to all projects and agents - Project-level guardrails apply to all agents in that project - Agent-level guardrails apply only to that specific agent

When isException is True on a guardrail target, the guardrail applies to all entities EXCEPT those in the assignment list.

Source code in airia/client/guardrail/sync_guardrail.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def get_applicable_guardrails(
    self,
    project_id: str,
    agent_id: Optional[str] = None,
    correlation_id: Optional[str] = None,
) -> List[Guardrail]:
    """
    Get guardrails applicable to a specific project and optional agent.

    This method retrieves guardrail definitions that apply to the specified
    context using the same matching logic as pipeline execution. It supports
    hierarchical matching (tenant -> project -> agent) and exclusion mode
    (IsException flag) when the feature flag is enabled.

    Args:
        project_id (str): The unique identifier of the project. This is required
            and must be a valid GUID.
        agent_id (str, optional): The unique identifier of the agent/pipeline.
            When provided, returns guardrails applicable to this specific agent.
            When omitted, returns guardrails applicable at the project level only.
        correlation_id (str, optional): A unique identifier for request tracing
            and logging. If not provided, one will be automatically generated.

    Returns:
        List[Guardrail]: A list of guardrail definitions that apply to the
            specified context. Each guardrail includes its filters, assignments,
            and target configurations.

    Raises:
        AiriaAPIError: If the API request fails, including cases where:
            - The project_id is invalid or doesn't exist (400)
            - Authentication fails (401)
            - Access is forbidden (403)
            - Server errors (5xx)

    Example:
        ```python
        from airia import AiriaClient

        client = AiriaClient(api_key="your_api_key")

        # Get project-level guardrails
        guardrails = client.guardrail.get_applicable_guardrails(
            project_id="00000000-0000-0000-0000-000000000000"
        )
        for guardrail in guardrails:
            print(f"Guardrail: {guardrail.name}")
            print(f"  Enabled: {guardrail.enabled}")
            print(f"  Filters: {len(guardrail.filters)}")

        # Get agent-specific guardrails
        guardrails = client.guardrail.get_applicable_guardrails(
            project_id="00000000-0000-0000-0000-000000000000",
            agent_id="11111111-1111-1111-1111-111111111111"
        )
        print(f"Found {len(guardrails)} guardrails for the agent")
        ```

    Note:
        Guardrails are matched using hierarchical logic:
        - Tenant-level guardrails apply to all projects and agents
        - Project-level guardrails apply to all agents in that project
        - Agent-level guardrails apply only to that specific agent

        When `isException` is True on a guardrail target, the guardrail applies
        to all entities EXCEPT those in the assignment list.
    """
    request_data = self._pre_get_applicable_guardrails(
        project_id=project_id,
        agent_id=agent_id,
        correlation_id=correlation_id,
        api_version=ApiVersion.V1.value,
    )
    resp = self._request_handler.make_request("POST", request_data)

    return [Guardrail(**item) for item in resp]