Skip to content

Commit 0d76ce3

Browse files
TristonianJonesTristonianJones
committed
Initial draft at AI attributes and policy function helper declarations
1 parent 8e848ac commit 0d76ce3

File tree

5 files changed

+1056
-1
lines changed

5 files changed

+1056
-1
lines changed

‎doc/langdef.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Language Definition
22

33
This page constitutes the reference for CEL. For a gentle introduction, see
4-
[Intro](intro.md).
4+
[Intro](intro.md). For specific guidance regarding CEL in policy
5+
see the `doc/policy` folder contains best practices, such as attribute
6+
specification and example environments for [AI Policy](doc/policy/ai/README.md)
57

68
## Overview
79

‎doc/policy/ai/README.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
# **AI Policy Attributes**
2+
3+
This document outlines a schema designed for governing AI agents, providing a standardized way to track identity, security context, and the flow of information between users, agents, tools, and models.
4+
5+
These message definitions should be accompanied by the function
6+
implementations declared in the [common_env.yaml](common_env.yaml),
7+
and provide attributes for either an [agent][agent_env.yaml] policy
8+
or [tool call](tool_call_env.yaml) policy or some combination thereof
9+
which most closely matches the needs of the use case.
10+
11+
## **Core Definitions**
12+
13+
### **Message: Agent**
14+
15+
The top-level container representing the AI System. It encapsulates both static configuration (Manifests, Identity) and dynamic runtime state (Context, Inputs, Outputs).
16+
17+
| Attribute | Type | Purpose |
18+
| :---- | :---- | :---- |
19+
| name | string | The unique resource name of the agent (e.g. agents/finance-helper). |
20+
| description | string | Human-readable description of the agent's purpose. |
21+
| version | string | The semantic version of the agent definition. |
22+
| model | Model | The underlying model family backing this agent. |
23+
| provider | AgentProvider | The provider or vendor responsible for hosting/managing this agent. |
24+
| auth | AgentAuth | Identity of the Agent itself (Service Account / Principal). |
25+
| context | AgentContext | The accumulated security context (Trust, Sensitivity, Data Sources). |
26+
| input | AgentMessage | The current turn's input (Prompt \+ Attachments). |
27+
| output | AgentMessage | The pending response (if evaluating egress/output policies). |
28+
29+
### **Message: AgentAuth**
30+
31+
Represents the identity of the Agent itself. This is independent of the end-user credentials.
32+
33+
| Attribute | Type | Purpose |
34+
| :---- | :---- | :---- |
35+
| principal | string | The principal of the agent, preferably in [SPIFFE format](https://spiffe.io/docs/latest/spiffe/concepts/#spiffe-identifiers). |
36+
| claims | google.protobuf.Struct | Map of structured claims about the agent (e.g. issuer, audience, expiration) typically found in [JWT tokens (RFC 7519\)](https://datatracker.ietf.org/doc/html/rfc7519). |
37+
| oauth\_scopes | repeated string | The OAuth scopes granted to the agent. |
38+
39+
## **Security & Trust Context**
40+
41+
### **Message: AgentContext**
42+
43+
Represents the aggregate security and data governance state of the agent's context window.
44+
45+
| Attribute | Type | Purpose |
46+
| :---- | :---- | :---- |
47+
| trust | TrustLevel | Aggregated trust level associated with relevant data in the window. |
48+
| sources | repeated DataSource | Origin and lineage tracking for data included in the context. |
49+
| prompt | string | The flattened text content of the current prompt. |
50+
51+
#### **Nested Message: DataSource**
52+
53+
| Attribute | Type | Purpose |
54+
| :---- | :---- | :---- |
55+
| id | string | Unique id describing the originating data source (e.g. bigquery:sales\_table). |
56+
| provenance | string | The category of origin for this data (e.g. UserPrompt, PublicWeb). |
57+
58+
### **Message: TrustLevel**
59+
60+
Describes the integrity or veracity of the data.
61+
62+
| Attribute | Type | Purpose |
63+
| :---- | :---- | :---- |
64+
| level | string | The trust level of the data (e.g. untrusted, trusted). |
65+
| findings | repeated Finding | Findings which support or are associated with this trust level. |
66+
67+
### **Message: ClassificationLabel**
68+
69+
Describes the classification of data within the context, such as sensitivity or safety hints.
70+
71+
| Attribute | Type | Purpose |
72+
| :---- | :---- | :---- |
73+
| name | string | Common labels (e.g. pii, internal, child\_safety). |
74+
| category | Category (Enum) | The category of the label (SENSITIVITY, SAFETY, THREAT). |
75+
| findings | repeated Finding | Findings associated with this specific label. |
76+
77+
### **Message: Finding**
78+
79+
Describes confidence measures and reasoning associated with a label or trust level.
80+
81+
| Attribute | Type | Purpose |
82+
| :---- | :---- | :---- |
83+
| value | string | The name of the confidence measure (e.g. picc\_score). |
84+
| confidence | double | The confidence score between 0 and 1\. |
85+
| explanation | string | An optional explanation for the confidence score. |
86+
87+
## **Messaging & Content**
88+
89+
### **Message: AgentMessage**
90+
91+
Represents a single turn in the conversation, acting as a container for multimodal content.
92+
93+
| Attribute | Type | Purpose |
94+
| :---- | :---- | :---- |
95+
| role | string | The actor who constructed the message (e.g. user, model, tool). |
96+
| parts | repeated Part | The ordered sequence of content parts. |
97+
| metadata | google.protobuf.Struct | Arbitrary metadata associated with the message turn. |
98+
| time | google.protobuf.Timestamp | Message creation time. |
99+
100+
#### **Nested Message: Part (oneof)**
101+
102+
| Field | Type | Purpose |
103+
| :---- | :---- | :---- |
104+
| prompt | ContentPart | User or System text input. |
105+
| tool\_call | ToolCall | A request to execute a specific tool. |
106+
| attachment | ContentPart | A file or multimodal object (Image, PDF). |
107+
| error | ErrorPart | An error that occurred during processing. |
108+
109+
### **Message: ContentPart**
110+
111+
A catch-all message type for encapsulating multimodal or structured content.
112+
113+
| Attribute | Type | Purpose |
114+
| :---- | :---- | :---- |
115+
| id | string | Unique identifier for this content part. |
116+
| type | string | The type of content (e.g. text, file, json). |
117+
| mime\_type | string | The MIME type of the content (e.g. image/png). |
118+
| content | string | String serialized representation of the content. |
119+
| data | bytes | Binary representation of the content. |
120+
| structured\_content | google.protobuf.Struct | JSON object representation of the content. |
121+
| time | google.protobuf.Timestamp | Timestamp associated with the content part. |
122+
123+
## **Tooling & Execution**
124+
125+
### **Message: Tool**
126+
127+
Describes a specific function or capability available to the agent.
128+
129+
| Attribute | Type | Purpose |
130+
| :---- | :---- | :---- |
131+
| name | string | The unique name of the tool (e.g. weather\_lookup). |
132+
| description | string | Human readable description of what the tool does. |
133+
| input\_schema | google.protobuf.Struct | JSON Schema defining the expected arguments. |
134+
| output\_schema | google.protobuf.Struct | JSON Schema defining the expected output. |
135+
| annotations | ToolAnnotations | Behavioral hints about the tool. |
136+
137+
### **Message: ToolAnnotations**
138+
139+
Hints describing a tool's behavior, informed by conventions like the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) spec.
140+
141+
| Attribute | Type | Purpose |
142+
| :---- | :---- | :---- |
143+
| read\_only | bool | If true, the tool does not modify its environment. |
144+
| destructive | bool | If true, the tool may perform destructive updates. |
145+
| idempotent | bool | If true, repeated calls with same args have no additional effect. |
146+
| open\_world | bool | If true, tool interacts with an "open world" of external entities. |
147+
| async | bool | If true, this tool is intended to be called asynchronously. |
148+
| output\_trust | TrustLevel | The trust level of the tool's output. |
149+
150+
### **Message: ToolCall**
151+
152+
Represents a specific invocation of a tool by the agent.
153+
154+
| Attribute | Type | Purpose |
155+
| :---- | :---- | :---- |
156+
| id | string | Unique identifier used to correlate call with results/errors. |
157+
| name | string | The name of the tool being called. |
158+
| params | google.protobuf.Struct | The arguments provided to the tool call. |
159+
| result | ContentPart | The successful output of the tool (if status is result). |
160+
| error | ErrorPart | The error encountered during execution (if status is error). |
161+
| user\_confirmed | bool | Indicates if the user explicitly confirmed this action (HITL). |
162+
163+
## **Policy Expressions & Use Cases**
164+
165+
Policy authors use Common Expression Language (CEL) to inspect the agent's state and enforce governance rules. Below are common use cases and examples based on the cel.expr.ai environment.
166+
167+
### **1\. Data Sensitivity & PII Governance**
168+
169+
Ensure that sensitive data (like PII) is handled correctly across different parts of the agent context.
170+
171+
* **Retrieving Sensitivity Labels:**
172+
173+
// Get optional list of sensitivity findings for the 'pii' label.
174+
agent.context.sensitivityFindings("pii")
175+
176+
* **Restricting High-Confidence PII in Tool Calls:**
177+
178+
// Fail if any PII finding has a confidence score greater than 0.5.
179+
tool.call.sensitivityFindings("pii").orValue(\[\])
180+
.all(finding, finding.confidence \<= 0.5)
181+
182+
* **Checking for Specific Data Types:**
183+
184+
// Returns true if the tool call contains both 'phone\_number' and 'ssn' findings.
185+
tool.call.sensitivityFindings("pii").hasAll(\["phone\_number", "ssn"\])
186+
187+
### **2\. Safety & Threat Mitigation**
188+
189+
Identify and block malicious inputs or unsafe model outputs.
190+
191+
* **Detecting Prompt Injections or Jailbreaks:**
192+
193+
// Returns true if any specified threats are detected with high confidence.
194+
agent.context.threatFindings().hasAll(\["injection", "jailbreak", "malicious\_uri"\])
195+
196+
* **Filtering Output for Responsible AI Safety:**
197+
198+
// Check if the model output contains hate speech or sexually explicit content.
199+
agent.output.safetyFindings("responsible\_ai")
200+
.hasAll(\["hate\_speech", "sexually\_explicit"\])
201+
202+
### **3\. Context & History Analysis**
203+
204+
Analyze previous turns in the conversation to enforce policies over time.
205+
206+
* **Filtering History by Role and Time:**
207+
208+
// Check for threats in user messages from the last 5 minutes.
209+
agent.history
210+
.role("user")
211+
.after(now \- duration('5m'))
212+
.threatFindings().hasAll(\["injection", "jailbreak"\])
213+
214+
* **Inspecting Tool History:**
215+
216+
// Find all JSON-based tool results in the agent's history.
217+
agent.history.role("agent").toolCalls("get\_weather").resultType("json")
218+
219+
### **4\. Advanced Tool Governance**
220+
221+
Control how tools interact with the world based on their definitions.
222+
223+
* **The "Lethal Trifecta" Check:**
224+
225+
// Block tool calls that are destructive, interact with the open world, and produce untrusted output.
226+
agent.input.parts.exists(part,
227+
has(part.tool\_call) &&
228+
\!part.tool\_call.spec().annotations.output\_trust.level in \['trusted', 'trusted\_1p'\]
229+
)
230+
231+
### **5\. Utility Functions**
232+
233+
* **Creating Manual Findings:** `ai.finding("picc_score", 0.5)`
234+
* **Casting Content:** `agent.input.parts[0].asType(bigquery.QueryRequest)`
235+
* **Union of Findings:** Combine findings from context and tool calls, keeping the highest confidence score:
236+
237+
agent.context.sensitivityFindings("pii")
238+
.union(tool.call.sensitivityFindings("pii"))

‎doc/policy/ai/agent_env.yaml‎

Whitespace-only changes.

0 commit comments

Comments
 (0)