@agentspec/sdk 0.1.0 → 0.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,1382 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$ref": "#/definitions/AgentSpecManifest",
|
|
3
|
-
"definitions": {
|
|
4
|
-
"AgentSpecManifest": {
|
|
5
|
-
"type": "object",
|
|
6
|
-
"properties": {
|
|
7
|
-
"apiVersion": {
|
|
8
|
-
"type": "string",
|
|
9
|
-
"const": "agentspec.io/v1"
|
|
10
|
-
},
|
|
11
|
-
"kind": {
|
|
12
|
-
"type": "string",
|
|
13
|
-
"const": "AgentSpec"
|
|
14
|
-
},
|
|
15
|
-
"metadata": {
|
|
16
|
-
"type": "object",
|
|
17
|
-
"properties": {
|
|
18
|
-
"name": {
|
|
19
|
-
"type": "string",
|
|
20
|
-
"minLength": 1,
|
|
21
|
-
"pattern": "^[a-z0-9-]+$"
|
|
22
|
-
},
|
|
23
|
-
"version": {
|
|
24
|
-
"type": "string",
|
|
25
|
-
"pattern": "^\\d+\\.\\d+\\.\\d+$"
|
|
26
|
-
},
|
|
27
|
-
"description": {
|
|
28
|
-
"type": "string",
|
|
29
|
-
"minLength": 1
|
|
30
|
-
},
|
|
31
|
-
"tags": {
|
|
32
|
-
"type": "array",
|
|
33
|
-
"items": {
|
|
34
|
-
"type": "string"
|
|
35
|
-
},
|
|
36
|
-
"description": "Free-form tags for filtering and discovery (e.g. [\"finance\", \"rag\", \"internal\"])."
|
|
37
|
-
},
|
|
38
|
-
"author": {
|
|
39
|
-
"type": "string"
|
|
40
|
-
},
|
|
41
|
-
"license": {
|
|
42
|
-
"type": "string",
|
|
43
|
-
"description": "SPDX license identifier (e.g. \"MIT\", \"Apache-2.0\", \"proprietary\")."
|
|
44
|
-
}
|
|
45
|
-
},
|
|
46
|
-
"required": [
|
|
47
|
-
"name",
|
|
48
|
-
"version",
|
|
49
|
-
"description"
|
|
50
|
-
],
|
|
51
|
-
"additionalProperties": false
|
|
52
|
-
},
|
|
53
|
-
"spec": {
|
|
54
|
-
"type": "object",
|
|
55
|
-
"properties": {
|
|
56
|
-
"model": {
|
|
57
|
-
"type": "object",
|
|
58
|
-
"properties": {
|
|
59
|
-
"provider": {
|
|
60
|
-
"type": "string",
|
|
61
|
-
"description": "LLM provider. Common values: \"openai\", \"anthropic\", \"groq\", \"google\", \"mistral\", \"azure\", \"bedrock\". Determines the API client and base URL used."
|
|
62
|
-
},
|
|
63
|
-
"id": {
|
|
64
|
-
"type": "string",
|
|
65
|
-
"description": "Exact model ID as accepted by the provider API (e.g. \"gpt-4o\", \"claude-sonnet-4-6\", \"llama-3.1-70b-versatile\"). Check provider docs for valid IDs."
|
|
66
|
-
},
|
|
67
|
-
"apiKey": {
|
|
68
|
-
"type": "string",
|
|
69
|
-
"description": "Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
70
|
-
},
|
|
71
|
-
"parameters": {
|
|
72
|
-
"type": "object",
|
|
73
|
-
"properties": {
|
|
74
|
-
"temperature": {
|
|
75
|
-
"type": "number",
|
|
76
|
-
"minimum": 0,
|
|
77
|
-
"maximum": 2,
|
|
78
|
-
"description": "Sampling temperature. 0 = deterministic/focused, 1 = balanced, 2 = highly creative. Most providers recommend 0–1 for production agents."
|
|
79
|
-
},
|
|
80
|
-
"maxTokens": {
|
|
81
|
-
"type": "integer",
|
|
82
|
-
"minimum": 1,
|
|
83
|
-
"description": "Maximum tokens in the model response. Controls cost and latency. Check model context window limits."
|
|
84
|
-
},
|
|
85
|
-
"topP": {
|
|
86
|
-
"type": "number",
|
|
87
|
-
"minimum": 0,
|
|
88
|
-
"maximum": 1,
|
|
89
|
-
"description": "Nucleus sampling threshold. The model samples from the smallest set of tokens whose cumulative probability exceeds topP. Alternative to temperature — do not set both."
|
|
90
|
-
},
|
|
91
|
-
"frequencyPenalty": {
|
|
92
|
-
"type": "number",
|
|
93
|
-
"description": "Penalises tokens that have already appeared frequently in the output (-2.0–2.0). Positive values reduce repetition."
|
|
94
|
-
},
|
|
95
|
-
"presencePenalty": {
|
|
96
|
-
"type": "number",
|
|
97
|
-
"description": "Penalises tokens that appear at all in the output so far (-2.0–2.0). Positive values encourage the model to introduce new topics."
|
|
98
|
-
}
|
|
99
|
-
},
|
|
100
|
-
"additionalProperties": false
|
|
101
|
-
},
|
|
102
|
-
"fallback": {
|
|
103
|
-
"type": "object",
|
|
104
|
-
"properties": {
|
|
105
|
-
"provider": {
|
|
106
|
-
"type": "string",
|
|
107
|
-
"description": "LLM provider for the fallback model. Common values: \"openai\", \"anthropic\", \"groq\", \"google\", \"mistral\", \"azure\", \"bedrock\"."
|
|
108
|
-
},
|
|
109
|
-
"id": {
|
|
110
|
-
"type": "string",
|
|
111
|
-
"description": "Model ID for the fallback (e.g. \"gpt-4o-mini\", \"claude-haiku-4-5-20251001\"). Must be a valid ID for the declared provider."
|
|
112
|
-
},
|
|
113
|
-
"apiKey": {
|
|
114
|
-
"type": "string",
|
|
115
|
-
"description": "Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
116
|
-
},
|
|
117
|
-
"triggerOn": {
|
|
118
|
-
"type": "array",
|
|
119
|
-
"items": {
|
|
120
|
-
"type": "string",
|
|
121
|
-
"enum": [
|
|
122
|
-
"rate_limit",
|
|
123
|
-
"timeout",
|
|
124
|
-
"error_5xx",
|
|
125
|
-
"error_4xx"
|
|
126
|
-
]
|
|
127
|
-
},
|
|
128
|
-
"description": "Conditions that trigger failover to this model. Omit to use the fallback for all errors."
|
|
129
|
-
},
|
|
130
|
-
"maxRetries": {
|
|
131
|
-
"type": "integer",
|
|
132
|
-
"minimum": 0,
|
|
133
|
-
"maximum": 10,
|
|
134
|
-
"description": "Number of retry attempts before failing over. Defaults to 0 (immediate failover)."
|
|
135
|
-
}
|
|
136
|
-
},
|
|
137
|
-
"required": [
|
|
138
|
-
"provider",
|
|
139
|
-
"id",
|
|
140
|
-
"apiKey"
|
|
141
|
-
],
|
|
142
|
-
"additionalProperties": false
|
|
143
|
-
},
|
|
144
|
-
"costControls": {
|
|
145
|
-
"type": "object",
|
|
146
|
-
"properties": {
|
|
147
|
-
"maxMonthlyUSD": {
|
|
148
|
-
"type": "number",
|
|
149
|
-
"exclusiveMinimum": 0,
|
|
150
|
-
"description": "Hard monthly spend cap in USD. Requests are rejected once this limit is reached."
|
|
151
|
-
},
|
|
152
|
-
"alertAtUSD": {
|
|
153
|
-
"type": "number",
|
|
154
|
-
"exclusiveMinimum": 0,
|
|
155
|
-
"description": "Send an alert when cumulative monthly spend crosses this USD threshold. Must be less than maxMonthlyUSD."
|
|
156
|
-
}
|
|
157
|
-
},
|
|
158
|
-
"additionalProperties": false
|
|
159
|
-
}
|
|
160
|
-
},
|
|
161
|
-
"required": [
|
|
162
|
-
"provider",
|
|
163
|
-
"id",
|
|
164
|
-
"apiKey"
|
|
165
|
-
],
|
|
166
|
-
"additionalProperties": false
|
|
167
|
-
},
|
|
168
|
-
"prompts": {
|
|
169
|
-
"type": "object",
|
|
170
|
-
"properties": {
|
|
171
|
-
"system": {
|
|
172
|
-
"type": "string",
|
|
173
|
-
"description": "System prompt. Use \"$file:prompts/system.md\" to load from a file (recommended for long prompts), or provide an inline string. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
174
|
-
},
|
|
175
|
-
"fallback": {
|
|
176
|
-
"type": "string",
|
|
177
|
-
"description": "Inline fallback system prompt used if the primary system prompt file cannot be loaded. Only applies when \"system\" is a $file: reference."
|
|
178
|
-
},
|
|
179
|
-
"hotReload": {
|
|
180
|
-
"type": "boolean",
|
|
181
|
-
"default": false,
|
|
182
|
-
"description": "When true, the system prompt file is re-read on every request instead of being cached at startup. Useful for rapid iteration without restarts."
|
|
183
|
-
},
|
|
184
|
-
"variables": {
|
|
185
|
-
"type": "array",
|
|
186
|
-
"items": {
|
|
187
|
-
"type": "object",
|
|
188
|
-
"properties": {
|
|
189
|
-
"name": {
|
|
190
|
-
"type": "string",
|
|
191
|
-
"description": "Variable name used in the prompt template (e.g. \"user_name\" for {{user_name}})."
|
|
192
|
-
},
|
|
193
|
-
"value": {
|
|
194
|
-
"type": "string",
|
|
195
|
-
"description": "Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
196
|
-
}
|
|
197
|
-
},
|
|
198
|
-
"required": [
|
|
199
|
-
"name",
|
|
200
|
-
"value"
|
|
201
|
-
],
|
|
202
|
-
"additionalProperties": false
|
|
203
|
-
},
|
|
204
|
-
"description": "Template variables injected into the system prompt at runtime. Values support reference syntax for secrets and env vars."
|
|
205
|
-
}
|
|
206
|
-
},
|
|
207
|
-
"required": [
|
|
208
|
-
"system"
|
|
209
|
-
],
|
|
210
|
-
"additionalProperties": false
|
|
211
|
-
},
|
|
212
|
-
"tools": {
|
|
213
|
-
"type": "array",
|
|
214
|
-
"items": {
|
|
215
|
-
"type": "object",
|
|
216
|
-
"properties": {
|
|
217
|
-
"name": {
|
|
218
|
-
"type": "string",
|
|
219
|
-
"minLength": 1,
|
|
220
|
-
"pattern": "^[a-z0-9-]+$"
|
|
221
|
-
},
|
|
222
|
-
"type": {
|
|
223
|
-
"type": "string",
|
|
224
|
-
"enum": [
|
|
225
|
-
"function",
|
|
226
|
-
"mcp",
|
|
227
|
-
"builtin"
|
|
228
|
-
],
|
|
229
|
-
"description": "\"function\" = local code module, \"mcp\" = registered via an MCP server in spec.mcp, \"builtin\" = provided by the runtime (e.g. code-interpreter, web-search)."
|
|
230
|
-
},
|
|
231
|
-
"description": {
|
|
232
|
-
"type": "string",
|
|
233
|
-
"description": "Human-readable description of what the tool does and when the agent should use it. This text is included in the tool-call prompt."
|
|
234
|
-
},
|
|
235
|
-
"module": {
|
|
236
|
-
"type": "string",
|
|
237
|
-
"description": "Path to the module that implements this tool. Use \"$file:tools/my_tool.py\" syntax. Only required for type \"function\"."
|
|
238
|
-
},
|
|
239
|
-
"function": {
|
|
240
|
-
"type": "string",
|
|
241
|
-
"description": "Name of the callable function exported from the module (e.g. \"search\", \"run_query\"). Only required for type \"function\"."
|
|
242
|
-
},
|
|
243
|
-
"annotations": {
|
|
244
|
-
"type": "object",
|
|
245
|
-
"properties": {
|
|
246
|
-
"readOnlyHint": {
|
|
247
|
-
"type": "boolean",
|
|
248
|
-
"description": "MCP hint: tool does not modify state. Allows clients to show a read-only badge and skip confirmation prompts."
|
|
249
|
-
},
|
|
250
|
-
"destructiveHint": {
|
|
251
|
-
"type": "boolean",
|
|
252
|
-
"description": "MCP hint: tool may perform irreversible actions (delete, overwrite). Triggers human-in-the-loop approval when humanInTheLoop.approvalRequired includes \"before-destructive-tool\"."
|
|
253
|
-
},
|
|
254
|
-
"idempotentHint": {
|
|
255
|
-
"type": "boolean",
|
|
256
|
-
"description": "MCP hint: calling the tool multiple times with the same inputs produces the same result. Allows safe retries."
|
|
257
|
-
},
|
|
258
|
-
"openWorldHint": {
|
|
259
|
-
"type": "boolean",
|
|
260
|
-
"description": "MCP hint: tool interacts with systems outside the agent's controlled environment (e.g. the internet). Affects trust level in tool outputs."
|
|
261
|
-
}
|
|
262
|
-
},
|
|
263
|
-
"additionalProperties": false
|
|
264
|
-
}
|
|
265
|
-
},
|
|
266
|
-
"required": [
|
|
267
|
-
"name",
|
|
268
|
-
"type",
|
|
269
|
-
"description"
|
|
270
|
-
],
|
|
271
|
-
"additionalProperties": false
|
|
272
|
-
}
|
|
273
|
-
},
|
|
274
|
-
"mcp": {
|
|
275
|
-
"type": "object",
|
|
276
|
-
"properties": {
|
|
277
|
-
"servers": {
|
|
278
|
-
"type": "array",
|
|
279
|
-
"items": {
|
|
280
|
-
"type": "object",
|
|
281
|
-
"properties": {
|
|
282
|
-
"name": {
|
|
283
|
-
"type": "string"
|
|
284
|
-
},
|
|
285
|
-
"transport": {
|
|
286
|
-
"type": "string",
|
|
287
|
-
"enum": [
|
|
288
|
-
"stdio",
|
|
289
|
-
"sse",
|
|
290
|
-
"http"
|
|
291
|
-
],
|
|
292
|
-
"description": "\"stdio\" = spawn a local process (requires \"command\"), \"sse\" = Server-Sent Events over HTTP, \"http\" = streamable HTTP (requires \"url\")."
|
|
293
|
-
},
|
|
294
|
-
"command": {
|
|
295
|
-
"type": "string",
|
|
296
|
-
"description": "Shell command to spawn the MCP server process. Required for transport \"stdio\" (e.g. \"npx\", \"python\")."
|
|
297
|
-
},
|
|
298
|
-
"args": {
|
|
299
|
-
"type": "array",
|
|
300
|
-
"items": {
|
|
301
|
-
"type": "string"
|
|
302
|
-
},
|
|
303
|
-
"description": "Arguments passed to the command (e.g. [\"-m\", \"my_mcp_server\"]). Only used for transport \"stdio\"."
|
|
304
|
-
},
|
|
305
|
-
"url": {
|
|
306
|
-
"type": "string",
|
|
307
|
-
"format": "uri",
|
|
308
|
-
"description": "Base URL of the remote MCP server. Required for transport \"sse\" or \"http\". Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
309
|
-
},
|
|
310
|
-
"env": {
|
|
311
|
-
"type": "object",
|
|
312
|
-
"additionalProperties": {
|
|
313
|
-
"type": "string"
|
|
314
|
-
},
|
|
315
|
-
"description": "Environment variables injected into the MCP server process. Values support reference syntax. Use \"$env:API_KEY\" to forward secrets without hardcoding."
|
|
316
|
-
},
|
|
317
|
-
"healthCheck": {
|
|
318
|
-
"type": "object",
|
|
319
|
-
"properties": {
|
|
320
|
-
"timeoutSeconds": {
|
|
321
|
-
"type": "integer",
|
|
322
|
-
"minimum": 1,
|
|
323
|
-
"maximum": 60,
|
|
324
|
-
"default": 5,
|
|
325
|
-
"description": "Seconds to wait for the MCP server to respond during health checks. Increase for slow-starting processes."
|
|
326
|
-
}
|
|
327
|
-
},
|
|
328
|
-
"additionalProperties": false
|
|
329
|
-
}
|
|
330
|
-
},
|
|
331
|
-
"required": [
|
|
332
|
-
"name",
|
|
333
|
-
"transport"
|
|
334
|
-
],
|
|
335
|
-
"additionalProperties": false
|
|
336
|
-
}
|
|
337
|
-
}
|
|
338
|
-
},
|
|
339
|
-
"required": [
|
|
340
|
-
"servers"
|
|
341
|
-
],
|
|
342
|
-
"additionalProperties": false
|
|
343
|
-
},
|
|
344
|
-
"memory": {
|
|
345
|
-
"type": "object",
|
|
346
|
-
"properties": {
|
|
347
|
-
"shortTerm": {
|
|
348
|
-
"type": "object",
|
|
349
|
-
"properties": {
|
|
350
|
-
"backend": {
|
|
351
|
-
"type": "string",
|
|
352
|
-
"enum": [
|
|
353
|
-
"in-memory",
|
|
354
|
-
"redis",
|
|
355
|
-
"sqlite"
|
|
356
|
-
]
|
|
357
|
-
},
|
|
358
|
-
"maxTurns": {
|
|
359
|
-
"type": "integer",
|
|
360
|
-
"minimum": 1,
|
|
361
|
-
"description": "Maximum number of conversation turns (user + assistant message pairs) to retain in context. Older turns are evicted first. Use with maxTokens for dual-bounded windows."
|
|
362
|
-
},
|
|
363
|
-
"maxTokens": {
|
|
364
|
-
"type": "integer",
|
|
365
|
-
"minimum": 1,
|
|
366
|
-
"description": "Maximum total tokens across all retained messages. When exceeded, oldest turns are evicted. Required by MEM-05 compliance rule."
|
|
367
|
-
},
|
|
368
|
-
"ttlSeconds": {
|
|
369
|
-
"type": "integer",
|
|
370
|
-
"minimum": 0,
|
|
371
|
-
"description": "Time-to-live in seconds for memory entries. 0 = session-scoped (cleared when connection closes). Omitting means no expiry — increases PII exposure risk (MEM-02)."
|
|
372
|
-
},
|
|
373
|
-
"connection": {
|
|
374
|
-
"type": "string",
|
|
375
|
-
"description": "Connection string for redis or sqlite backends. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
376
|
-
}
|
|
377
|
-
},
|
|
378
|
-
"required": [
|
|
379
|
-
"backend"
|
|
380
|
-
],
|
|
381
|
-
"additionalProperties": false
|
|
382
|
-
},
|
|
383
|
-
"longTerm": {
|
|
384
|
-
"type": "object",
|
|
385
|
-
"properties": {
|
|
386
|
-
"backend": {
|
|
387
|
-
"type": "string",
|
|
388
|
-
"enum": [
|
|
389
|
-
"postgres",
|
|
390
|
-
"sqlite",
|
|
391
|
-
"mongodb"
|
|
392
|
-
]
|
|
393
|
-
},
|
|
394
|
-
"connectionString": {
|
|
395
|
-
"type": "string",
|
|
396
|
-
"description": "Database connection URI. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
397
|
-
},
|
|
398
|
-
"table": {
|
|
399
|
-
"type": "string",
|
|
400
|
-
"description": "Table or collection name where agent memories are stored. Defaults to \"agent_memories\" if omitted. Use a per-agent name to avoid cross-agent data leakage."
|
|
401
|
-
},
|
|
402
|
-
"ttlDays": {
|
|
403
|
-
"type": "integer",
|
|
404
|
-
"minimum": 1,
|
|
405
|
-
"description": "Time-to-live in days for long-term memory records. Omitting means no expiry — a compliance risk (MEM-02). Required by GDPR Article 5 data minimisation principle."
|
|
406
|
-
}
|
|
407
|
-
},
|
|
408
|
-
"required": [
|
|
409
|
-
"backend",
|
|
410
|
-
"connectionString"
|
|
411
|
-
],
|
|
412
|
-
"additionalProperties": false
|
|
413
|
-
},
|
|
414
|
-
"vector": {
|
|
415
|
-
"type": "object",
|
|
416
|
-
"properties": {
|
|
417
|
-
"backend": {
|
|
418
|
-
"type": "string",
|
|
419
|
-
"enum": [
|
|
420
|
-
"pgvector",
|
|
421
|
-
"pinecone",
|
|
422
|
-
"weaviate",
|
|
423
|
-
"qdrant",
|
|
424
|
-
"chroma"
|
|
425
|
-
]
|
|
426
|
-
},
|
|
427
|
-
"connectionString": {
|
|
428
|
-
"type": "string",
|
|
429
|
-
"description": "Connection URI for self-hosted backends (pgvector, weaviate, qdrant, chroma). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
430
|
-
},
|
|
431
|
-
"apiKey": {
|
|
432
|
-
"type": "string",
|
|
433
|
-
"description": "API key for managed backends (Pinecone, Weaviate Cloud). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
434
|
-
},
|
|
435
|
-
"dimension": {
|
|
436
|
-
"type": "integer",
|
|
437
|
-
"minimum": 1,
|
|
438
|
-
"description": "Embedding vector dimension. Must exactly match the output dimension of your embedding model (e.g. 1536 for text-embedding-3-small, 768 for nomic-embed-text). Mismatch causes insertion errors."
|
|
439
|
-
},
|
|
440
|
-
"topK": {
|
|
441
|
-
"type": "integer",
|
|
442
|
-
"minimum": 1,
|
|
443
|
-
"description": "Number of nearest-neighbour results to retrieve per similarity search. Higher values improve recall at the cost of latency and context token usage."
|
|
444
|
-
},
|
|
445
|
-
"namespace": {
|
|
446
|
-
"type": "string",
|
|
447
|
-
"description": "Logical partition within the vector store. Required by MEM-04 to prevent cross-agent data leakage. Recommended value: the agent name (spec.metadata.name)."
|
|
448
|
-
}
|
|
449
|
-
},
|
|
450
|
-
"required": [
|
|
451
|
-
"backend",
|
|
452
|
-
"dimension"
|
|
453
|
-
],
|
|
454
|
-
"additionalProperties": false
|
|
455
|
-
},
|
|
456
|
-
"hygiene": {
|
|
457
|
-
"type": "object",
|
|
458
|
-
"properties": {
|
|
459
|
-
"piiScrubFields": {
|
|
460
|
-
"type": "array",
|
|
461
|
-
"items": {
|
|
462
|
-
"type": "string"
|
|
463
|
-
},
|
|
464
|
-
"description": "PII field names to scrub before writing to long-term or vector memory. Required when longTerm is set (MEM-01). Use recogniser names compatible with your scrubbing library (e.g. Microsoft Presidio entity types): \"email\", \"phone_number\", \"credit_card\", \"iban\", \"ssn\", \"bank_account\", \"passport\", \"drivers_license\", \"person_name\", \"date_of_birth\", \"address\", \"ip_address\", \"api_key\", \"password\", \"medical_record\"."
|
|
465
|
-
},
|
|
466
|
-
"auditLog": {
|
|
467
|
-
"type": "boolean",
|
|
468
|
-
"default": false,
|
|
469
|
-
"description": "When true, all memory read and write operations are emitted as structured audit log events. Required for long-term memory (MEM-03) and HIPAA/SOC2 compliance."
|
|
470
|
-
},
|
|
471
|
-
"retentionPolicy": {
|
|
472
|
-
"type": "string",
|
|
473
|
-
"description": "Named governance or compliance retention policy applied to this agent's memory. Informational label — must be consistent with ttlSeconds/ttlDays on the backend configs. Common values: \"session\" (cleared on disconnect), \"ephemeral\" (never persisted), \"30d\", \"90d\", \"1y\", \"persistent\" (explicit no-expiry opt-in), \"gdpr-30d\" (GDPR Art.5 minimum), \"hipaa-6y\" (HIPAA 45 CFR §164.530), \"pci-dss-1y\" (PCI DSS Req.10.7)."
|
|
474
|
-
}
|
|
475
|
-
},
|
|
476
|
-
"additionalProperties": false
|
|
477
|
-
}
|
|
478
|
-
},
|
|
479
|
-
"additionalProperties": false
|
|
480
|
-
},
|
|
481
|
-
"subagents": {
|
|
482
|
-
"type": "array",
|
|
483
|
-
"items": {
|
|
484
|
-
"type": "object",
|
|
485
|
-
"properties": {
|
|
486
|
-
"name": {
|
|
487
|
-
"type": "string"
|
|
488
|
-
},
|
|
489
|
-
"ref": {
|
|
490
|
-
"anyOf": [
|
|
491
|
-
{
|
|
492
|
-
"type": "object",
|
|
493
|
-
"properties": {
|
|
494
|
-
"agentspec": {
|
|
495
|
-
"type": "string"
|
|
496
|
-
}
|
|
497
|
-
},
|
|
498
|
-
"required": [
|
|
499
|
-
"agentspec"
|
|
500
|
-
],
|
|
501
|
-
"additionalProperties": false
|
|
502
|
-
},
|
|
503
|
-
{
|
|
504
|
-
"type": "object",
|
|
505
|
-
"properties": {
|
|
506
|
-
"a2a": {
|
|
507
|
-
"type": "object",
|
|
508
|
-
"properties": {
|
|
509
|
-
"url": {
|
|
510
|
-
"type": "string"
|
|
511
|
-
},
|
|
512
|
-
"auth": {
|
|
513
|
-
"type": "object",
|
|
514
|
-
"properties": {
|
|
515
|
-
"type": {
|
|
516
|
-
"type": "string",
|
|
517
|
-
"enum": [
|
|
518
|
-
"bearer",
|
|
519
|
-
"apikey",
|
|
520
|
-
"none"
|
|
521
|
-
]
|
|
522
|
-
},
|
|
523
|
-
"token": {
|
|
524
|
-
"type": "string"
|
|
525
|
-
},
|
|
526
|
-
"header": {
|
|
527
|
-
"type": "string",
|
|
528
|
-
"description": "HTTP header name for the API key (e.g. \"X-API-Key\"). Only used when auth type is \"apikey\"."
|
|
529
|
-
}
|
|
530
|
-
},
|
|
531
|
-
"required": [
|
|
532
|
-
"type"
|
|
533
|
-
],
|
|
534
|
-
"additionalProperties": false
|
|
535
|
-
}
|
|
536
|
-
},
|
|
537
|
-
"required": [
|
|
538
|
-
"url"
|
|
539
|
-
],
|
|
540
|
-
"additionalProperties": false
|
|
541
|
-
}
|
|
542
|
-
},
|
|
543
|
-
"required": [
|
|
544
|
-
"a2a"
|
|
545
|
-
],
|
|
546
|
-
"additionalProperties": false
|
|
547
|
-
}
|
|
548
|
-
]
|
|
549
|
-
},
|
|
550
|
-
"invocation": {
|
|
551
|
-
"type": "string",
|
|
552
|
-
"enum": [
|
|
553
|
-
"parallel",
|
|
554
|
-
"sequential",
|
|
555
|
-
"on-demand"
|
|
556
|
-
],
|
|
557
|
-
"description": "\"parallel\" = invoked concurrently with other subagents, \"sequential\" = invoked in order after previous subagents complete, \"on-demand\" = only invoked when the agent decides it is needed (triggered by LLM or triggerKeywords)."
|
|
558
|
-
},
|
|
559
|
-
"passContext": {
|
|
560
|
-
"type": "boolean",
|
|
561
|
-
"default": false,
|
|
562
|
-
"description": "When true, the current conversation thread (messages so far) is forwarded to the subagent as context. Use with care — increases token usage and may leak sensitive conversation history."
|
|
563
|
-
},
|
|
564
|
-
"triggerKeywords": {
|
|
565
|
-
"type": "array",
|
|
566
|
-
"items": {
|
|
567
|
-
"type": "string"
|
|
568
|
-
},
|
|
569
|
-
"description": "Keywords in user messages that automatically trigger this subagent (only applies when invocation is \"on-demand\"). Case-insensitive substring match."
|
|
570
|
-
}
|
|
571
|
-
},
|
|
572
|
-
"required": [
|
|
573
|
-
"name",
|
|
574
|
-
"ref",
|
|
575
|
-
"invocation"
|
|
576
|
-
],
|
|
577
|
-
"additionalProperties": false
|
|
578
|
-
}
|
|
579
|
-
},
|
|
580
|
-
"api": {
|
|
581
|
-
"type": "object",
|
|
582
|
-
"properties": {
|
|
583
|
-
"type": {
|
|
584
|
-
"type": "string",
|
|
585
|
-
"enum": [
|
|
586
|
-
"rest",
|
|
587
|
-
"mcp",
|
|
588
|
-
"grpc",
|
|
589
|
-
"websocket"
|
|
590
|
-
]
|
|
591
|
-
},
|
|
592
|
-
"port": {
|
|
593
|
-
"type": "integer",
|
|
594
|
-
"minimum": 1,
|
|
595
|
-
"maximum": 65535
|
|
596
|
-
},
|
|
597
|
-
"pathPrefix": {
|
|
598
|
-
"type": "string",
|
|
599
|
-
"description": "URL path prefix applied to all API routes (e.g. \"/api/v1\"). Useful when the agent runs behind a reverse proxy."
|
|
600
|
-
},
|
|
601
|
-
"auth": {
|
|
602
|
-
"type": "object",
|
|
603
|
-
"properties": {
|
|
604
|
-
"type": {
|
|
605
|
-
"type": "string",
|
|
606
|
-
"enum": [
|
|
607
|
-
"jwt",
|
|
608
|
-
"apikey",
|
|
609
|
-
"oauth2",
|
|
610
|
-
"none"
|
|
611
|
-
]
|
|
612
|
-
},
|
|
613
|
-
"jwksUri": {
|
|
614
|
-
"type": "string",
|
|
615
|
-
"description": "JWKS endpoint URL used to fetch public keys for JWT signature verification (e.g. \"https://your-auth.example.com/.well-known/jwks.json\"). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
616
|
-
},
|
|
617
|
-
"header": {
|
|
618
|
-
"type": "string",
|
|
619
|
-
"description": "HTTP header name carrying the credential (e.g. \"Authorization\" for JWT bearer, \"X-API-Key\" for apikey auth). Defaults to \"Authorization\"."
|
|
620
|
-
}
|
|
621
|
-
},
|
|
622
|
-
"required": [
|
|
623
|
-
"type"
|
|
624
|
-
],
|
|
625
|
-
"additionalProperties": false
|
|
626
|
-
},
|
|
627
|
-
"rateLimit": {
|
|
628
|
-
"type": "object",
|
|
629
|
-
"properties": {
|
|
630
|
-
"requestsPerMinute": {
|
|
631
|
-
"type": "integer",
|
|
632
|
-
"minimum": 1,
|
|
633
|
-
"description": "Maximum requests allowed per client per minute. Excess requests receive HTTP 429."
|
|
634
|
-
},
|
|
635
|
-
"requestsPerHour": {
|
|
636
|
-
"type": "integer",
|
|
637
|
-
"minimum": 1,
|
|
638
|
-
"description": "Maximum requests allowed per client per hour. Excess requests receive HTTP 429."
|
|
639
|
-
}
|
|
640
|
-
},
|
|
641
|
-
"additionalProperties": false
|
|
642
|
-
},
|
|
643
|
-
"streaming": {
|
|
644
|
-
"type": "boolean",
|
|
645
|
-
"default": false,
|
|
646
|
-
"description": "When true, the API supports streaming responses (SSE). Set true for conversational agents to reduce perceived latency."
|
|
647
|
-
},
|
|
648
|
-
"healthEndpoint": {
|
|
649
|
-
"type": "string",
|
|
650
|
-
"description": "URL path for the health check endpoint (e.g. \"/health\", \"/ready\"). Exposes agentspec health report. Defaults to \"/agentspec/health\" when using the SDK."
|
|
651
|
-
},
|
|
652
|
-
"metricsEndpoint": {
|
|
653
|
-
"type": "string",
|
|
654
|
-
"description": "URL path where Prometheus-format metrics are exposed (e.g. \"/metrics\"). Required for observability.metrics to be scraped."
|
|
655
|
-
},
|
|
656
|
-
"corsOrigins": {
|
|
657
|
-
"type": "array",
|
|
658
|
-
"items": {
|
|
659
|
-
"type": "string"
|
|
660
|
-
},
|
|
661
|
-
"description": "Allowed CORS origins for browser clients (e.g. [\"https://app.example.com\", \"http://localhost:3000\"]). Use [\"*\"] only for fully public APIs."
|
|
662
|
-
},
|
|
663
|
-
"chatEndpoint": {
|
|
664
|
-
"type": "object",
|
|
665
|
-
"properties": {
|
|
666
|
-
"path": {
|
|
667
|
-
"type": "string",
|
|
668
|
-
"default": "/v1/chat",
|
|
669
|
-
"description": "URL path for the chat endpoint (e.g. \"/v1/chat\", \"/api/chat\"). Must start with \"/\"."
|
|
670
|
-
},
|
|
671
|
-
"protocol": {
|
|
672
|
-
"type": "string",
|
|
673
|
-
"enum": [
|
|
674
|
-
"openai-compatible",
|
|
675
|
-
"custom"
|
|
676
|
-
],
|
|
677
|
-
"default": "openai-compatible",
|
|
678
|
-
"description": "\"openai-compatible\" = request/response shape matches the OpenAI Chat Completions API (enables drop-in compatibility with OpenAI SDKs). \"custom\" = proprietary shape defined by the agent."
|
|
679
|
-
},
|
|
680
|
-
"streaming": {
|
|
681
|
-
"type": "boolean",
|
|
682
|
-
"default": true,
|
|
683
|
-
"description": "When true, the endpoint supports Server-Sent Events streaming responses. Clients receive tokens as they are generated."
|
|
684
|
-
},
|
|
685
|
-
"sessionMode": {
|
|
686
|
-
"type": "string",
|
|
687
|
-
"enum": [
|
|
688
|
-
"stateful",
|
|
689
|
-
"stateless"
|
|
690
|
-
],
|
|
691
|
-
"default": "stateful",
|
|
692
|
-
"description": "\"stateful\" = conversation history is persisted per thread (requires threadIdHeader). \"stateless\" = each request is independent; no memory across calls."
|
|
693
|
-
},
|
|
694
|
-
"threadIdHeader": {
|
|
695
|
-
"type": "string",
|
|
696
|
-
"default": "X-Thread-Id",
|
|
697
|
-
"description": "HTTP request header used to identify the conversation thread for stateful session routing (e.g. \"X-Thread-Id\", \"X-Session-Id\")."
|
|
698
|
-
}
|
|
699
|
-
},
|
|
700
|
-
"additionalProperties": false
|
|
701
|
-
}
|
|
702
|
-
},
|
|
703
|
-
"required": [
|
|
704
|
-
"type"
|
|
705
|
-
],
|
|
706
|
-
"additionalProperties": false
|
|
707
|
-
},
|
|
708
|
-
"skills": {
|
|
709
|
-
"type": "array",
|
|
710
|
-
"items": {
|
|
711
|
-
"type": "object",
|
|
712
|
-
"properties": {
|
|
713
|
-
"id": {
|
|
714
|
-
"type": "string",
|
|
715
|
-
"description": "Skill identifier as registered in the runtime skill registry (e.g. \"code-interpreter\", \"image-gen\")."
|
|
716
|
-
},
|
|
717
|
-
"version": {
|
|
718
|
-
"type": "string",
|
|
719
|
-
"description": "Pinned skill version. Omit to use the latest available version. Semver range or exact version string."
|
|
720
|
-
}
|
|
721
|
-
},
|
|
722
|
-
"required": [
|
|
723
|
-
"id"
|
|
724
|
-
],
|
|
725
|
-
"additionalProperties": false
|
|
726
|
-
}
|
|
727
|
-
},
|
|
728
|
-
"guardrails": {
|
|
729
|
-
"type": "object",
|
|
730
|
-
"properties": {
|
|
731
|
-
"input": {
|
|
732
|
-
"type": "array",
|
|
733
|
-
"items": {
|
|
734
|
-
"anyOf": [
|
|
735
|
-
{
|
|
736
|
-
"type": "object",
|
|
737
|
-
"properties": {
|
|
738
|
-
"type": {
|
|
739
|
-
"type": "string",
|
|
740
|
-
"const": "topic-filter"
|
|
741
|
-
},
|
|
742
|
-
"blockedTopics": {
|
|
743
|
-
"type": "array",
|
|
744
|
-
"items": {
|
|
745
|
-
"type": "string"
|
|
746
|
-
},
|
|
747
|
-
"description": "Topics or keywords that should be blocked in user input (e.g. [\"competitor-names\", \"legal-advice\"]). Case-insensitive substring match against the full message."
|
|
748
|
-
},
|
|
749
|
-
"action": {
|
|
750
|
-
"type": "string",
|
|
751
|
-
"enum": [
|
|
752
|
-
"reject",
|
|
753
|
-
"warn",
|
|
754
|
-
"log"
|
|
755
|
-
],
|
|
756
|
-
"description": "\"reject\" = refuse the request and return an error, \"warn\" = continue but emit a warning event, \"log\" = silently log the violation."
|
|
757
|
-
},
|
|
758
|
-
"message": {
|
|
759
|
-
"type": "string",
|
|
760
|
-
"description": "Custom error message returned to the user when a topic is blocked. Defaults to a generic refusal message."
|
|
761
|
-
}
|
|
762
|
-
},
|
|
763
|
-
"required": [
|
|
764
|
-
"type",
|
|
765
|
-
"blockedTopics",
|
|
766
|
-
"action"
|
|
767
|
-
],
|
|
768
|
-
"additionalProperties": false
|
|
769
|
-
},
|
|
770
|
-
{
|
|
771
|
-
"type": "object",
|
|
772
|
-
"properties": {
|
|
773
|
-
"type": {
|
|
774
|
-
"type": "string",
|
|
775
|
-
"const": "pii-detector"
|
|
776
|
-
},
|
|
777
|
-
"action": {
|
|
778
|
-
"type": "string",
|
|
779
|
-
"enum": [
|
|
780
|
-
"scrub",
|
|
781
|
-
"reject",
|
|
782
|
-
"warn"
|
|
783
|
-
],
|
|
784
|
-
"description": "\"scrub\" = replace detected PII with placeholders before passing to the model, \"reject\" = refuse the request, \"warn\" = pass through but emit a warning event."
|
|
785
|
-
},
|
|
786
|
-
"fields": {
|
|
787
|
-
"type": "array",
|
|
788
|
-
"items": {
|
|
789
|
-
"type": "string"
|
|
790
|
-
},
|
|
791
|
-
"description": "Specific PII entity types to detect. When omitted, all PII types supported by the detection library are scanned. Use the same entity names as in spec.memory.hygiene.piiScrubFields."
|
|
792
|
-
}
|
|
793
|
-
},
|
|
794
|
-
"required": [
|
|
795
|
-
"type",
|
|
796
|
-
"action"
|
|
797
|
-
],
|
|
798
|
-
"additionalProperties": false
|
|
799
|
-
},
|
|
800
|
-
{
|
|
801
|
-
"type": "object",
|
|
802
|
-
"properties": {
|
|
803
|
-
"type": {
|
|
804
|
-
"type": "string",
|
|
805
|
-
"const": "prompt-injection"
|
|
806
|
-
},
|
|
807
|
-
"action": {
|
|
808
|
-
"type": "string",
|
|
809
|
-
"enum": [
|
|
810
|
-
"reject",
|
|
811
|
-
"warn"
|
|
812
|
-
]
|
|
813
|
-
},
|
|
814
|
-
"sensitivity": {
|
|
815
|
-
"type": "string",
|
|
816
|
-
"enum": [
|
|
817
|
-
"low",
|
|
818
|
-
"medium",
|
|
819
|
-
"high"
|
|
820
|
-
],
|
|
821
|
-
"description": "Detection sensitivity. \"low\" = only block obvious injection patterns, \"medium\" = balanced (default), \"high\" = aggressive — may produce false positives on legitimate complex instructions."
|
|
822
|
-
}
|
|
823
|
-
},
|
|
824
|
-
"required": [
|
|
825
|
-
"type",
|
|
826
|
-
"action"
|
|
827
|
-
],
|
|
828
|
-
"additionalProperties": false
|
|
829
|
-
},
|
|
830
|
-
{
|
|
831
|
-
"type": "object",
|
|
832
|
-
"properties": {
|
|
833
|
-
"type": {
|
|
834
|
-
"type": "string",
|
|
835
|
-
"const": "custom"
|
|
836
|
-
},
|
|
837
|
-
"module": {
|
|
838
|
-
"type": "string",
|
|
839
|
-
"description": "Path to the module implementing the guardrail function. Use \"$file:guardrails/my_check.py\" syntax."
|
|
840
|
-
},
|
|
841
|
-
"function": {
|
|
842
|
-
"type": "string",
|
|
843
|
-
"description": "Name of the guardrail function exported from the module. Signature: (input: str) -> None (raise to block) or (input: str) -> str (return scrubbed value)."
|
|
844
|
-
},
|
|
845
|
-
"action": {
|
|
846
|
-
"type": "string",
|
|
847
|
-
"enum": [
|
|
848
|
-
"reject",
|
|
849
|
-
"warn",
|
|
850
|
-
"log"
|
|
851
|
-
]
|
|
852
|
-
}
|
|
853
|
-
},
|
|
854
|
-
"required": [
|
|
855
|
-
"type",
|
|
856
|
-
"module",
|
|
857
|
-
"function",
|
|
858
|
-
"action"
|
|
859
|
-
],
|
|
860
|
-
"additionalProperties": false
|
|
861
|
-
}
|
|
862
|
-
]
|
|
863
|
-
},
|
|
864
|
-
"description": "Guardrails applied to user input before it is sent to the model. Evaluated in order — first blocking rule wins."
|
|
865
|
-
},
|
|
866
|
-
"output": {
|
|
867
|
-
"type": "array",
|
|
868
|
-
"items": {
|
|
869
|
-
"anyOf": [
|
|
870
|
-
{
|
|
871
|
-
"type": "object",
|
|
872
|
-
"properties": {
|
|
873
|
-
"type": {
|
|
874
|
-
"type": "string",
|
|
875
|
-
"const": "hallucination-detector"
|
|
876
|
-
},
|
|
877
|
-
"threshold": {
|
|
878
|
-
"type": "number",
|
|
879
|
-
"minimum": 0,
|
|
880
|
-
"maximum": 1,
|
|
881
|
-
"description": "Confidence score below which a response is considered hallucinated (0.0–1.0). 0.0 = block everything, 1.0 = block nothing. Typical value: 0.5–0.7."
|
|
882
|
-
},
|
|
883
|
-
"action": {
|
|
884
|
-
"type": "string",
|
|
885
|
-
"enum": [
|
|
886
|
-
"reject",
|
|
887
|
-
"retry",
|
|
888
|
-
"warn"
|
|
889
|
-
],
|
|
890
|
-
"description": "\"reject\" = return error to user, \"retry\" = re-invoke the model (up to maxRetries), \"warn\" = return response with a warning annotation."
|
|
891
|
-
},
|
|
892
|
-
"maxRetries": {
|
|
893
|
-
"type": "integer",
|
|
894
|
-
"minimum": 1,
|
|
895
|
-
"maximum": 5,
|
|
896
|
-
"description": "Maximum re-generation attempts before giving up. Only used when action is \"retry\". Defaults to 1."
|
|
897
|
-
}
|
|
898
|
-
},
|
|
899
|
-
"required": [
|
|
900
|
-
"type",
|
|
901
|
-
"threshold",
|
|
902
|
-
"action"
|
|
903
|
-
],
|
|
904
|
-
"additionalProperties": false
|
|
905
|
-
},
|
|
906
|
-
{
|
|
907
|
-
"type": "object",
|
|
908
|
-
"properties": {
|
|
909
|
-
"type": {
|
|
910
|
-
"type": "string",
|
|
911
|
-
"const": "toxicity-filter"
|
|
912
|
-
},
|
|
913
|
-
"threshold": {
|
|
914
|
-
"type": "number",
|
|
915
|
-
"minimum": 0,
|
|
916
|
-
"maximum": 1,
|
|
917
|
-
"description": "Toxicity score above which a response is blocked (0.0–1.0). 0.0 = block all output, 1.0 = block nothing. Typical production value: 0.7–0.85."
|
|
918
|
-
},
|
|
919
|
-
"action": {
|
|
920
|
-
"type": "string",
|
|
921
|
-
"enum": [
|
|
922
|
-
"reject",
|
|
923
|
-
"warn"
|
|
924
|
-
]
|
|
925
|
-
}
|
|
926
|
-
},
|
|
927
|
-
"required": [
|
|
928
|
-
"type",
|
|
929
|
-
"threshold",
|
|
930
|
-
"action"
|
|
931
|
-
],
|
|
932
|
-
"additionalProperties": false
|
|
933
|
-
},
|
|
934
|
-
{
|
|
935
|
-
"type": "object",
|
|
936
|
-
"properties": {
|
|
937
|
-
"type": {
|
|
938
|
-
"type": "string",
|
|
939
|
-
"const": "pii-detector"
|
|
940
|
-
},
|
|
941
|
-
"action": {
|
|
942
|
-
"type": "string",
|
|
943
|
-
"enum": [
|
|
944
|
-
"scrub",
|
|
945
|
-
"reject",
|
|
946
|
-
"warn"
|
|
947
|
-
],
|
|
948
|
-
"description": "\"scrub\" = replace PII in the model output before returning to the user, \"reject\" = discard the response and return an error, \"warn\" = return with a warning annotation."
|
|
949
|
-
},
|
|
950
|
-
"fields": {
|
|
951
|
-
"type": "array",
|
|
952
|
-
"items": {
|
|
953
|
-
"type": "string"
|
|
954
|
-
},
|
|
955
|
-
"description": "Specific PII entity types to detect in model output. Omit to scan all types. Use the same entity names as in spec.memory.hygiene.piiScrubFields."
|
|
956
|
-
}
|
|
957
|
-
},
|
|
958
|
-
"required": [
|
|
959
|
-
"type",
|
|
960
|
-
"action"
|
|
961
|
-
],
|
|
962
|
-
"additionalProperties": false
|
|
963
|
-
},
|
|
964
|
-
{
|
|
965
|
-
"type": "object",
|
|
966
|
-
"properties": {
|
|
967
|
-
"type": {
|
|
968
|
-
"type": "string",
|
|
969
|
-
"const": "custom"
|
|
970
|
-
},
|
|
971
|
-
"module": {
|
|
972
|
-
"type": "string",
|
|
973
|
-
"description": "Path to the module implementing the output guardrail. Use \"$file:guardrails/output_check.py\" syntax."
|
|
974
|
-
},
|
|
975
|
-
"function": {
|
|
976
|
-
"type": "string",
|
|
977
|
-
"description": "Name of the guardrail function. Signature: (output: str) -> None (raise to block) or (output: str) -> str (return transformed value)."
|
|
978
|
-
},
|
|
979
|
-
"action": {
|
|
980
|
-
"type": "string",
|
|
981
|
-
"enum": [
|
|
982
|
-
"reject",
|
|
983
|
-
"warn",
|
|
984
|
-
"log"
|
|
985
|
-
]
|
|
986
|
-
}
|
|
987
|
-
},
|
|
988
|
-
"required": [
|
|
989
|
-
"type",
|
|
990
|
-
"module",
|
|
991
|
-
"function",
|
|
992
|
-
"action"
|
|
993
|
-
],
|
|
994
|
-
"additionalProperties": false
|
|
995
|
-
}
|
|
996
|
-
]
|
|
997
|
-
},
|
|
998
|
-
"description": "Guardrails applied to model output before it is returned to the user. Evaluated in order — first blocking rule wins."
|
|
999
|
-
}
|
|
1000
|
-
},
|
|
1001
|
-
"additionalProperties": false
|
|
1002
|
-
},
|
|
1003
|
-
"humanInTheLoop": {
|
|
1004
|
-
"type": "object",
|
|
1005
|
-
"properties": {
|
|
1006
|
-
"enabled": {
|
|
1007
|
-
"type": "boolean",
|
|
1008
|
-
"default": false
|
|
1009
|
-
},
|
|
1010
|
-
"approvalRequired": {
|
|
1011
|
-
"type": "array",
|
|
1012
|
-
"items": {
|
|
1013
|
-
"type": "string",
|
|
1014
|
-
"enum": [
|
|
1015
|
-
"before-destructive-tool",
|
|
1016
|
-
"before-external-call",
|
|
1017
|
-
"on-low-confidence",
|
|
1018
|
-
"on-high-cost",
|
|
1019
|
-
"always"
|
|
1020
|
-
]
|
|
1021
|
-
},
|
|
1022
|
-
"description": "Conditions that pause execution and request human approval. \"before-destructive-tool\" = any tool with destructiveHint=true, \"on-low-confidence\" = model confidence below a threshold, \"on-high-cost\" = single call exceeds cost controls."
|
|
1023
|
-
},
|
|
1024
|
-
"timeoutSeconds": {
|
|
1025
|
-
"type": "integer",
|
|
1026
|
-
"minimum": 1,
|
|
1027
|
-
"maximum": 3600,
|
|
1028
|
-
"default": 300,
|
|
1029
|
-
"description": "Seconds to wait for human approval before executing the timeoutAction. Default 300s (5 minutes). Max 3600s (1 hour)."
|
|
1030
|
-
},
|
|
1031
|
-
"timeoutAction": {
|
|
1032
|
-
"type": "string",
|
|
1033
|
-
"enum": [
|
|
1034
|
-
"reject",
|
|
1035
|
-
"proceed",
|
|
1036
|
-
"escalate"
|
|
1037
|
-
],
|
|
1038
|
-
"default": "reject",
|
|
1039
|
-
"description": "\"reject\" = abort the action and return an error (default, safest), \"proceed\" = continue without approval (use only for low-risk actions), \"escalate\" = forward to a higher-level approver or on-call channel."
|
|
1040
|
-
},
|
|
1041
|
-
"notifyVia": {
|
|
1042
|
-
"type": "array",
|
|
1043
|
-
"items": {
|
|
1044
|
-
"type": "string",
|
|
1045
|
-
"enum": [
|
|
1046
|
-
"slack",
|
|
1047
|
-
"email",
|
|
1048
|
-
"webhook",
|
|
1049
|
-
"console"
|
|
1050
|
-
]
|
|
1051
|
-
},
|
|
1052
|
-
"description": "Channels used to notify humans when approval is required. Multiple channels can be specified; all are notified simultaneously."
|
|
1053
|
-
},
|
|
1054
|
-
"webhookUrl": {
|
|
1055
|
-
"type": "string",
|
|
1056
|
-
"description": "URL to POST approval requests to when notifyVia includes \"webhook\". The payload contains the pending action and a callback token. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
1057
|
-
}
|
|
1058
|
-
},
|
|
1059
|
-
"additionalProperties": false
|
|
1060
|
-
},
|
|
1061
|
-
"evaluation": {
|
|
1062
|
-
"type": "object",
|
|
1063
|
-
"properties": {
|
|
1064
|
-
"framework": {
|
|
1065
|
-
"type": "string",
|
|
1066
|
-
"enum": [
|
|
1067
|
-
"deepeval",
|
|
1068
|
-
"braintrust",
|
|
1069
|
-
"langsmith",
|
|
1070
|
-
"ragas",
|
|
1071
|
-
"custom"
|
|
1072
|
-
]
|
|
1073
|
-
},
|
|
1074
|
-
"datasets": {
|
|
1075
|
-
"type": "array",
|
|
1076
|
-
"items": {
|
|
1077
|
-
"type": "object",
|
|
1078
|
-
"properties": {
|
|
1079
|
-
"name": {
|
|
1080
|
-
"type": "string",
|
|
1081
|
-
"description": "Unique dataset identifier, referenced by \"agentspec evaluate --dataset <name>\"."
|
|
1082
|
-
},
|
|
1083
|
-
"path": {
|
|
1084
|
-
"type": "string",
|
|
1085
|
-
"description": "Path to the evaluation dataset file (JSONL format). Use \"$file:evals/my_dataset.jsonl\" syntax. Each line is a JSON object with the following fields:\n input (required) – user query sent to the agent.\n expected (required) – expected output; used for string_match and answer_similarity scoring.\n context (optional) – string[] of retrieved chunks the agent actually used. Required for faithfulness, context_precision, hallucination metrics.\n reference_contexts (optional) – string[] of ground-truth relevant chunks. Required for context_recall metric.\n tags (optional) – string[] labels for filtering with --tag.\n metadata (optional) – arbitrary key/value pairs for reporting (e.g. {\"difficulty\": \"hard\"}).\nExample: {\"input\":\"What is RAG?\",\"expected\":\"Retrieval Augmented Generation\",\"context\":[\"RAG combines retrieval...\"],\"tags\":[\"rag\"]}"
|
|
1086
|
-
},
|
|
1087
|
-
"metrics": {
|
|
1088
|
-
"type": "array",
|
|
1089
|
-
"items": {
|
|
1090
|
-
"type": "string",
|
|
1091
|
-
"enum": [
|
|
1092
|
-
"faithfulness",
|
|
1093
|
-
"answer_relevancy",
|
|
1094
|
-
"answer_similarity",
|
|
1095
|
-
"hallucination",
|
|
1096
|
-
"toxicity",
|
|
1097
|
-
"context_precision",
|
|
1098
|
-
"context_recall",
|
|
1099
|
-
"bias",
|
|
1100
|
-
"custom"
|
|
1101
|
-
]
|
|
1102
|
-
},
|
|
1103
|
-
"description": "Metrics to compute for this specific dataset. Overrides (narrows) spec.evaluation.metrics for this dataset only. When omitted, the global spec.evaluation.metrics list is used. Example: a RAG dataset sets [\"faithfulness\",\"context_recall\"] while a safety dataset sets [\"toxicity\",\"bias\"]."
|
|
1104
|
-
}
|
|
1105
|
-
},
|
|
1106
|
-
"required": [
|
|
1107
|
-
"name",
|
|
1108
|
-
"path"
|
|
1109
|
-
],
|
|
1110
|
-
"additionalProperties": false
|
|
1111
|
-
},
|
|
1112
|
-
"description": "Evaluation datasets. Each entry maps a name to a JSONL file and optionally scopes which metrics to compute."
|
|
1113
|
-
},
|
|
1114
|
-
"metrics": {
|
|
1115
|
-
"type": "array",
|
|
1116
|
-
"items": {
|
|
1117
|
-
"type": "string",
|
|
1118
|
-
"enum": [
|
|
1119
|
-
"faithfulness",
|
|
1120
|
-
"answer_relevancy",
|
|
1121
|
-
"answer_similarity",
|
|
1122
|
-
"hallucination",
|
|
1123
|
-
"toxicity",
|
|
1124
|
-
"context_precision",
|
|
1125
|
-
"context_recall",
|
|
1126
|
-
"bias",
|
|
1127
|
-
"custom"
|
|
1128
|
-
]
|
|
1129
|
-
},
|
|
1130
|
-
"description": "Default metrics to compute across all datasets that do not declare their own metrics. \"faithfulness\", \"context_precision\", \"context_recall\" require the \"context\" field in dataset samples. \"context_recall\" additionally requires \"reference_contexts\". \"custom\" requires a scorer registered in the evaluation framework config."
|
|
1131
|
-
},
|
|
1132
|
-
"thresholds": {
|
|
1133
|
-
"type": "object",
|
|
1134
|
-
"additionalProperties": {
|
|
1135
|
-
"type": "number",
|
|
1136
|
-
"minimum": 0,
|
|
1137
|
-
"maximum": 1
|
|
1138
|
-
},
|
|
1139
|
-
"description": "Pass/fail thresholds per metric (0.0–1.0). Key = metric name, value = minimum required score. Example: {\"faithfulness\": 0.8, \"answer_relevancy\": 0.75}. Used by ciGate and \"agentspec evaluate\"."
|
|
1140
|
-
},
|
|
1141
|
-
"ciGate": {
|
|
1142
|
-
"type": "boolean",
|
|
1143
|
-
"default": false,
|
|
1144
|
-
"description": "When true, \"agentspec evaluate\" exits with code 1 if any metric falls below its threshold. Blocks CI pipelines on evaluation regression (EVAL-01)."
|
|
1145
|
-
}
|
|
1146
|
-
},
|
|
1147
|
-
"required": [
|
|
1148
|
-
"framework"
|
|
1149
|
-
],
|
|
1150
|
-
"additionalProperties": false
|
|
1151
|
-
},
|
|
1152
|
-
"observability": {
|
|
1153
|
-
"type": "object",
|
|
1154
|
-
"properties": {
|
|
1155
|
-
"tracing": {
|
|
1156
|
-
"type": "object",
|
|
1157
|
-
"properties": {
|
|
1158
|
-
"backend": {
|
|
1159
|
-
"type": "string",
|
|
1160
|
-
"enum": [
|
|
1161
|
-
"langfuse",
|
|
1162
|
-
"langsmith",
|
|
1163
|
-
"agentops",
|
|
1164
|
-
"otel",
|
|
1165
|
-
"honeycomb",
|
|
1166
|
-
"datadog"
|
|
1167
|
-
]
|
|
1168
|
-
},
|
|
1169
|
-
"endpoint": {
|
|
1170
|
-
"type": "string",
|
|
1171
|
-
"description": "Tracing collector endpoint URL. Required for \"otel\", \"honeycomb\", and self-hosted backends. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
1172
|
-
},
|
|
1173
|
-
"publicKey": {
|
|
1174
|
-
"type": "string",
|
|
1175
|
-
"description": "Public/project API key for the tracing backend (e.g. Langfuse public key). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
1176
|
-
},
|
|
1177
|
-
"secretKey": {
|
|
1178
|
-
"type": "string",
|
|
1179
|
-
"description": "Secret API key for the tracing backend (e.g. Langfuse secret key). Always use \"$secret:\" or \"$env:\" — never hardcode. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
1180
|
-
},
|
|
1181
|
-
"sampleRate": {
|
|
1182
|
-
"type": "number",
|
|
1183
|
-
"minimum": 0,
|
|
1184
|
-
"maximum": 1,
|
|
1185
|
-
"default": 1,
|
|
1186
|
-
"description": "Fraction of requests to trace (0.0–1.0). 1.0 = trace every request (default), 0.1 = trace 10% for high-traffic cost savings. Set to 1.0 during development."
|
|
1187
|
-
}
|
|
1188
|
-
},
|
|
1189
|
-
"required": [
|
|
1190
|
-
"backend"
|
|
1191
|
-
],
|
|
1192
|
-
"additionalProperties": false
|
|
1193
|
-
},
|
|
1194
|
-
"metrics": {
|
|
1195
|
-
"type": "object",
|
|
1196
|
-
"properties": {
|
|
1197
|
-
"backend": {
|
|
1198
|
-
"type": "string",
|
|
1199
|
-
"enum": [
|
|
1200
|
-
"opentelemetry",
|
|
1201
|
-
"prometheus",
|
|
1202
|
-
"datadog"
|
|
1203
|
-
]
|
|
1204
|
-
},
|
|
1205
|
-
"endpoint": {
|
|
1206
|
-
"type": "string",
|
|
1207
|
-
"description": "Metrics export endpoint (e.g. OTLP endpoint for OpenTelemetry, Datadog agent URL). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
1208
|
-
},
|
|
1209
|
-
"serviceName": {
|
|
1210
|
-
"type": "string",
|
|
1211
|
-
"description": "Service name used to label all emitted metrics and traces. Defaults to metadata.name. Use a consistent name across deployments for accurate dashboards."
|
|
1212
|
-
}
|
|
1213
|
-
},
|
|
1214
|
-
"required": [
|
|
1215
|
-
"backend"
|
|
1216
|
-
],
|
|
1217
|
-
"additionalProperties": false
|
|
1218
|
-
},
|
|
1219
|
-
"logging": {
|
|
1220
|
-
"type": "object",
|
|
1221
|
-
"properties": {
|
|
1222
|
-
"level": {
|
|
1223
|
-
"type": "string",
|
|
1224
|
-
"enum": [
|
|
1225
|
-
"debug",
|
|
1226
|
-
"info",
|
|
1227
|
-
"warn",
|
|
1228
|
-
"error"
|
|
1229
|
-
],
|
|
1230
|
-
"default": "info"
|
|
1231
|
-
},
|
|
1232
|
-
"structured": {
|
|
1233
|
-
"type": "boolean",
|
|
1234
|
-
"default": true,
|
|
1235
|
-
"description": "When true, logs are emitted as JSON objects (structured logging). Required for log aggregation platforms (Datadog, Splunk, CloudWatch). Set false only for local development readability."
|
|
1236
|
-
},
|
|
1237
|
-
"redactFields": {
|
|
1238
|
-
"type": "array",
|
|
1239
|
-
"items": {
|
|
1240
|
-
"type": "string"
|
|
1241
|
-
},
|
|
1242
|
-
"description": "Field names to redact from structured log output before writing to log sinks. Use the same values as spec.memory.hygiene.piiScrubFields plus any application-specific sensitive keys (e.g. [\"password\", \"credit_card\", \"session_token\"])."
|
|
1243
|
-
}
|
|
1244
|
-
},
|
|
1245
|
-
"additionalProperties": false
|
|
1246
|
-
}
|
|
1247
|
-
},
|
|
1248
|
-
"additionalProperties": false
|
|
1249
|
-
},
|
|
1250
|
-
"compliance": {
|
|
1251
|
-
"type": "object",
|
|
1252
|
-
"properties": {
|
|
1253
|
-
"packs": {
|
|
1254
|
-
"type": "array",
|
|
1255
|
-
"items": {
|
|
1256
|
-
"type": "string",
|
|
1257
|
-
"enum": [
|
|
1258
|
-
"owasp-llm-top10",
|
|
1259
|
-
"memory-hygiene",
|
|
1260
|
-
"model-resilience",
|
|
1261
|
-
"evaluation-coverage",
|
|
1262
|
-
"observability"
|
|
1263
|
-
]
|
|
1264
|
-
},
|
|
1265
|
-
"description": "Compliance rule packs to evaluate during \"agentspec audit\". Each pack groups related rules. Omit to run all packs."
|
|
1266
|
-
},
|
|
1267
|
-
"suppressions": {
|
|
1268
|
-
"type": "array",
|
|
1269
|
-
"items": {
|
|
1270
|
-
"type": "object",
|
|
1271
|
-
"properties": {
|
|
1272
|
-
"rule": {
|
|
1273
|
-
"type": "string",
|
|
1274
|
-
"description": "Rule ID to suppress (e.g. \"SEC-LLM-03\", \"MEM-02\"). Must match an existing compliance rule ID."
|
|
1275
|
-
},
|
|
1276
|
-
"reason": {
|
|
1277
|
-
"type": "string",
|
|
1278
|
-
"description": "Human-readable justification for suppressing this rule. Required for audit trails. Example: \"Hallucination detection handled by external Lakera Guard proxy.\""
|
|
1279
|
-
},
|
|
1280
|
-
"approvedBy": {
|
|
1281
|
-
"type": "string",
|
|
1282
|
-
"description": "Name or identifier of the person who approved this suppression (e.g. \"security-team\", \"alice@example.com\"). Used for compliance sign-off tracking."
|
|
1283
|
-
},
|
|
1284
|
-
"expires": {
|
|
1285
|
-
"type": "string",
|
|
1286
|
-
"description": "ISO 8601 date (YYYY-MM-DD) when this suppression expires and should be re-evaluated (e.g. \"2025-12-31\"). Suppressions without an expiry are flagged in audits."
|
|
1287
|
-
}
|
|
1288
|
-
},
|
|
1289
|
-
"required": [
|
|
1290
|
-
"rule",
|
|
1291
|
-
"reason"
|
|
1292
|
-
],
|
|
1293
|
-
"additionalProperties": false
|
|
1294
|
-
},
|
|
1295
|
-
"description": "Rules to suppress in audit output. Each suppression requires a reason and optional expiry date. Over-suppression is itself flagged."
|
|
1296
|
-
},
|
|
1297
|
-
"auditSchedule": {
|
|
1298
|
-
"type": "string",
|
|
1299
|
-
"enum": [
|
|
1300
|
-
"daily",
|
|
1301
|
-
"weekly",
|
|
1302
|
-
"monthly",
|
|
1303
|
-
"on-change"
|
|
1304
|
-
],
|
|
1305
|
-
"description": "How often the compliance audit should be re-run in CI. \"on-change\" = re-audit on every manifest change (recommended). Informational — enforcement depends on your CI configuration."
|
|
1306
|
-
}
|
|
1307
|
-
},
|
|
1308
|
-
"additionalProperties": false
|
|
1309
|
-
},
|
|
1310
|
-
"requires": {
|
|
1311
|
-
"type": "object",
|
|
1312
|
-
"properties": {
|
|
1313
|
-
"envVars": {
|
|
1314
|
-
"type": "array",
|
|
1315
|
-
"items": {
|
|
1316
|
-
"type": "string"
|
|
1317
|
-
},
|
|
1318
|
-
"description": "Environment variable names that must be set at agent startup. The SDK validates these at load time and throws a descriptive error if any are missing (e.g. [\"OPENAI_API_KEY\", \"DATABASE_URL\"])."
|
|
1319
|
-
},
|
|
1320
|
-
"services": {
|
|
1321
|
-
"type": "array",
|
|
1322
|
-
"items": {
|
|
1323
|
-
"type": "object",
|
|
1324
|
-
"properties": {
|
|
1325
|
-
"type": {
|
|
1326
|
-
"type": "string",
|
|
1327
|
-
"enum": [
|
|
1328
|
-
"postgres",
|
|
1329
|
-
"redis",
|
|
1330
|
-
"mysql",
|
|
1331
|
-
"mongodb",
|
|
1332
|
-
"elasticsearch"
|
|
1333
|
-
]
|
|
1334
|
-
},
|
|
1335
|
-
"connection": {
|
|
1336
|
-
"type": "string",
|
|
1337
|
-
"description": "Connection URI for this service. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
|
|
1338
|
-
}
|
|
1339
|
-
},
|
|
1340
|
-
"required": [
|
|
1341
|
-
"type",
|
|
1342
|
-
"connection"
|
|
1343
|
-
],
|
|
1344
|
-
"additionalProperties": false
|
|
1345
|
-
},
|
|
1346
|
-
"description": "External services that must be reachable at startup. The SDK health check verifies TCP connectivity to each service."
|
|
1347
|
-
},
|
|
1348
|
-
"minimumMemoryMB": {
|
|
1349
|
-
"type": "integer",
|
|
1350
|
-
"minimum": 128,
|
|
1351
|
-
"description": "Minimum RAM required to run the agent in megabytes (e.g. 512, 2048). Used by orchestrators for resource scheduling. Does not enforce a limit — purely declarative."
|
|
1352
|
-
},
|
|
1353
|
-
"nodeVersion": {
|
|
1354
|
-
"type": "string",
|
|
1355
|
-
"description": "Minimum Node.js version required, as a semver range or exact version (e.g. \">=20.0.0\", \"20.x\"). Used by CI and orchestrators for compatibility checks."
|
|
1356
|
-
},
|
|
1357
|
-
"pythonVersion": {
|
|
1358
|
-
"type": "string",
|
|
1359
|
-
"description": "Minimum Python version required, as a semver range or exact version (e.g. \">=3.11\", \"3.12\"). Used by CI and orchestrators for compatibility checks."
|
|
1360
|
-
}
|
|
1361
|
-
},
|
|
1362
|
-
"additionalProperties": false
|
|
1363
|
-
}
|
|
1364
|
-
},
|
|
1365
|
-
"required": [
|
|
1366
|
-
"model",
|
|
1367
|
-
"prompts"
|
|
1368
|
-
],
|
|
1369
|
-
"additionalProperties": false
|
|
1370
|
-
}
|
|
1371
|
-
},
|
|
1372
|
-
"required": [
|
|
1373
|
-
"apiVersion",
|
|
1374
|
-
"kind",
|
|
1375
|
-
"metadata",
|
|
1376
|
-
"spec"
|
|
1377
|
-
],
|
|
1378
|
-
"additionalProperties": false
|
|
1379
|
-
}
|
|
1380
|
-
},
|
|
1381
|
-
"$schema": "http://json-schema.org/draft-07/schema#"
|
|
1382
|
-
}
|