Skip to content

extra_fields=ignore for request/response classes #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChengZhang-98 merged 2 commits into from
Feb 19, 2026
Merged

extra_fields=ignore for request/response classes #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dd9c69d
update docs
ChengZhang-98 Feb 19, 2026
80833e8
ignore extra fields for request/response classes
ChengZhang-98 Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 94 additions & 78 deletions docs/control/reference/rest_api/headers/security_config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,15 @@ This header is **optional** and can be used in Headers-Only Mode to fine-tune se
"min_num_tools_for_filtering": 10,
"clear_session_meta": "never",
"max_n_turns": null,
"allow_history_mismatch": null,
"clear_history_every_n_attempts": null,
"disable_rllm": true,
"enable_multistep_planning": null,
"enabled_internal_tools": null,
"prune_failed_steps": false,
"force_to_cache": [],
"max_pllm_steps": null,
"max_pllm_failed_steps": null,
"max_tool_calls_per_step": null,
"reduced_grammar_for_rllm_review": true,
"retry_on_policy_violation": false,
Expand All @@ -30,6 +32,8 @@ This header is **optional** and can be used in Headers-Only Mode to fine-tune se
},
"prompt": {
"pllm": {
"flavor": null,
"version": null,
"debug_info_level": "normal",
"clarify_ambiguous_queries": null,
"context_var_visibility": null,
Expand All @@ -40,7 +44,15 @@ This header is **optional** and can be used in Headers-Only Mode to fine-tune se
"query_include_tool_results": null
},
"rllm": {
"flavor": null,
"version": null,
"debug_info_level": null
},
"tllm": {
"flavor": null,
"version": null,
"add_tool_description": null,
"add_tool_input_schema": null
}
},
"response_format": {
Expand All @@ -58,7 +70,7 @@ The configuration is organized into three sections:

- **`fsm`**: FSM (Finite State Machine) overrides for execution behavior
- **`prompt`**: Per-LLM prompt configuration overrides
- **`response_format`**: Response format and content settings
- **`response_format`**: Response format configuration for dual-LLM sessions

All fields are optional and have sensible defaults.

Expand All @@ -74,15 +86,15 @@ All fields are optional and have sensible defaults.
|------|----------|---------|-------------|
| `integer` or `null` | No | `10` | >= 2 |

Minimum number of available tools to trigger tool filtering. If fewer tools are available, no filtering is performed.
Minimum number of registered tools to enable tool-filtering LLM step. Set to `null` to disable.

#### `fsm.clear_session_meta`

| Type | Required | Default |
|------|----------|---------|
| `string` | No | `"never"` |

When to clear session metadata:
When to clear session meta information:

- `"never"`: Never clear
- `"every_attempt"`: Clear at the beginning of each PLLM attempt
Expand All @@ -94,145 +106,149 @@ When to clear session metadata:
|------|----------|---------|-------------|
| `integer` or `null` | No | endpoint-dependent | >= 1 |

Maximum number of conversation turns allowed in the session. When not set, the server applies a default based on the endpoint type.
Maximum number of turns allowed in the session. If `null`, unlimited turns are allowed. When not set, the server applies a default based on the endpoint type.

### Dual-LLM Only Fields

#### `fsm.max_pllm_steps`

| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |

Maximum number of PLLM steps before giving up and returning an error.

#### `fsm.max_tool_calls_per_step`

| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |

Maximum number of tool calls allowed per PLLM step.

#### `fsm.allow_history_mismatch`

| Type | Required | Default |
|------|----------|---------|
| `boolean` or `null` | No | `null` |

Allow mismatches between the stored session history and the incoming messages.
Controls behaviour when incoming messages diverge from stored history in stateless mode. When `true`, the server silently truncates its stored history to the last consistent point and accepts the caller's version. When `false`, the server rejects the request with an error if a mismatch is detected.

#### `fsm.clear_history_every_n_attempts`

| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |

If set, clears the tool call history every n PLLM attempts to save token usage.
Single-step mode only. Clear all failed step history every N attempts to save tokens.

#### `fsm.max_pllm_failed_steps`
#### `fsm.disable_rllm`

| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |
| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `true` |

Maximum number of failed PLLM steps allowed before giving up and returning an error.
Whether to skip the response LLM (RLLM) review step.

#### `fsm.retry_on_policy_violation`
#### `fsm.enable_multistep_planning`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |

Retry PLLM attempts when a policy violation is detected.
When `false` (single-step), each attempt solves independently. When `true` (multi-step), each step builds on previous.

#### `fsm.disable_rllm`
#### `fsm.enabled_internal_tools`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `true` |
| `array[string]` | No | endpoint-dependent |

Disable the Response LLM (RLLM) for reviewing final responses.
List of internal tool IDs available to planning LLM. Valid values: `"parse_with_ai"`, `"verify_hypothesis"`, `"set_policy"`, `"complete_turn"`. When not set, the server applies a default based on the endpoint type.

#### `fsm.reduced_grammar_for_rllm_review`
#### `fsm.prune_failed_steps`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `true` |
| `boolean` | No | `false` |

Use reduced grammar for the RLLM review process.
Multi-step mode only. Remove failed steps from history after turn completes.

#### `fsm.enable_multistep_planning`
#### `fsm.force_to_cache`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |
| `array[string]` | No | `[]` |

Enable multi-step planning for complex user queries.
List of tool ID regex patterns to always cache their results regardless of the cache_tool_result setting.

#### `fsm.prune_failed_steps`
#### `fsm.max_pllm_steps`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |
| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |

Prune failed PLLM steps from session history to save tokens.
Maximum number of steps allowed per turn.

#### `fsm.enabled_internal_tools`
#### `fsm.max_pllm_failed_steps`

| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |

Maximum number of failed steps allowed per turn.

#### `fsm.max_tool_calls_per_step`

| Type | Required | Default | Constraints |
|------|----------|---------|-------------|
| `integer` or `null` | No | `null` | >= 1 |

Maximum number of tool calls allowed per PLLM attempt. If `null`, no limit is enforced.

#### `fsm.reduced_grammar_for_rllm_review`

| Type | Required | Default |
|------|----------|---------|
| `array[string]` | No | endpoint-dependent |
| `boolean` | No | `true` |

Internal tools to enable. Valid values: `"parse_with_ai"`, `"verify_hypothesis"`. When not set, the server applies a default based on the endpoint type.
Whether to paraphrase RLLM output via reduced grammar before feeding back to planning LLM.

#### `fsm.force_to_cache`
#### `fsm.retry_on_policy_violation`

| Type | Required | Default |
|------|----------|---------|
| `array[string]` | No | `[]` |
| `boolean` | No | `false` |

List of tool ID regex patterns to always cache.
When `true`, allow planning LLM to retry after policy violation.

#### `fsm.wrap_tool_result`

| Type | Required | Default |
|------|----------|---------|
| `boolean` or `null` | No | `null` |

Whether to wrap tool results before passing to PLLM.
Whether to wrap tool results in Ok/Err types.

#### `fsm.detect_tool_errors`

| Type | Required | Default |
|------|----------|---------|
| `string` or `null` | No | `null` |

Tool error detection strategy: `"none"`, `"regex"`, or `"llm"`.
Whether and how to detect errors in tool results:

- `"none"`: Do not detect tool result errors
- `"regex"`: Use regex patterns to detect common error messages in tool results
- `"llm"`: Use an LLM to analyze tool results and detect potential errors

#### `fsm.detect_tool_error_regex_pattern`

| Type | Required | Default |
|------|----------|---------|
| `string` or `null` | No | `null` |

Regex pattern to use when `detect_tool_errors` is set to `"regex"`.
The regex pattern to use for detecting error messages in tool results when `detect_tool_errors` is set to `"regex"`.

#### `fsm.detect_tool_error_max_result_length`

| Type | Required | Default |
|------|----------|---------|
| `integer` or `null` | No | `null` |

Maximum tool result length to consider for error detection.
The maximum length of tool result to consider for error detection. Longer results will be truncated. If `null`, no limit is enforced.

#### `fsm.strict_tool_result_parsing`

| Type | Required | Default |
|------|----------|---------|
| `boolean` or `null` | No | `null` |

Enable strict parsing of tool results.
If `true`, only parse external tool results as JSON when the tool declares an output_schema. When `false`, always attempt `json.loads` on tool results.

---

Expand All @@ -246,46 +262,46 @@ Planning LLM prompt overrides:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `flavor` | `string` | `null` | Prompt flavor |
| `version` | `string` | `null` | Prompt version |
| `debug_info_level` | `string` | `"normal"` | Debug info level: `"minimal"`, `"normal"`, `"extra"` |
| `clarify_ambiguous_queries` | `boolean` | `null` | Allow PLLM to ask clarifying questions |
| `context_var_visibility` | `string` | `null` | Context variable visibility: `"none"`, `"basic-notext"`, `"basic-executable"`, `"all-executable"`, `"all"` |
| `query_inline_roles` | `array[string]` | `null` | Message roles to inline in query: `"assistant"`, `"tool"`, `"developer"`, `"system"` |
| `query_role_name_overrides` | `object` | `null` | Map of message role name overrides |
| `query_include_tool_calls` | `boolean` | `null` | Include tool calls in query |
| `query_include_tool_args` | `boolean` | `null` | Include tool arguments in query |
| `query_include_tool_results` | `boolean` | `null` | Include tool results in query |
| `flavor` | `string` | `null` | Prompt template variant to use (e.g., `"universal"`). |
| `version` | `string` | `null` | Prompt template version. Combined with flavor to load template. |
| `debug_info_level` | `string` | `"normal"` | Level of detail for debug/execution information in planning LLM prompt: `"minimal"`, `"normal"`, `"extra"`. |
| `clarify_ambiguous_queries` | `boolean` | `null` | Whether planning LLM is allowed to ask for clarification on ambiguous queries. |
| `context_var_visibility` | `string` | `null` | The visibility level of context variables in the PLLM prompts: `"none"`, `"basic-notext"`, `"basic-executable"`, `"all-executable"`, `"all"`. |
| `query_inline_roles` | `array[string]` | `null` | List of roles whose messages will be inlined into the user query: `"assistant"`, `"tool"`, `"developer"`, `"system"`. |
| `query_role_name_overrides` | `object` | `null` | Overrides for message role names in the inlined user query. For example, `{"assistant": "developer"}` will change the role of assistant messages to developer. |
| `query_include_tool_calls` | `boolean` | `null` | Whether to include upstream tool calls in inlined query. |
| `query_include_tool_args` | `boolean` | `null` | Whether to include arguments of upstream tool calls. |
| `query_include_tool_results` | `boolean` | `null` | Whether to include results of upstream tool calls. |

### `prompt.rllm`

Response LLM prompt overrides:
Review LLM prompt overrides:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `flavor` | `string` | `null` | Prompt flavor |
| `version` | `string` | `null` | Prompt version |
| `debug_info_level` | `string` | `null` | Debug info level |
| `flavor` | `string` | `null` | Prompt template variant to use (e.g., `"universal"`). |
| `version` | `string` | `null` | Prompt template version. Combined with flavor to load template. |
| `debug_info_level` | `string` | `null` | Level of detail for debug/execution information in RLLM prompt: `"minimal"`, `"normal"`, `"extra"`. |

### `prompt.tllm`

Tool-formulating LLM prompt overrides:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `flavor` | `string` | `null` | Prompt flavor |
| `version` | `string` | `null` | Prompt version |
| `add_tool_description` | `boolean` | `null` | Add tool description to prompt |
| `add_tool_input_schema` | `boolean` | `null` | Add tool input schema to prompt |
| `flavor` | `string` | `null` | Prompt template variant to use (e.g., `"universal"`). |
| `version` | `string` | `null` | Prompt template version. Combined with flavor to load template. |
| `add_tool_description` | `boolean` | `null` | Whether to include tool descriptions in tool-filtering prompt. |
| `add_tool_input_schema` | `boolean` | `null` | Whether to include tool input JSON schemas in tool-filtering prompt. |

### Other LLM Prompts

`prompt.grllm`, `prompt.qllm`, `prompt.tagllm`, `prompt.policy_llm`, `prompt.error_detector_llm` all support:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `flavor` | `string` | `null` | Prompt flavor |
| `version` | `string` | `null` | Prompt version |
| `flavor` | `string` | `null` | Prompt template variant to use (e.g., `"universal"`). |
| `version` | `string` | `null` | Prompt template version. Combined with flavor to load template. |

---

Expand All @@ -297,28 +313,28 @@ Tool-formulating LLM prompt overrides:
|------|----------|---------|
| `boolean` | No | `false` |

Strip the response content. This overrides other inclusion settings.
When `true`, returns only essential result value as plain text, stripping all metadata.

#### `response_format.include_program`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |

Include the final program in the response.
Whether to include the generated program in the response.

#### `response_format.include_policy_check_history`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |

Include the policy check history in the response.
Whether to include policy check results even when there are no violations.

#### `response_format.include_namespace_snapshot`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |

Include the namespace snapshot in the response.
Whether to include snapshot of all variables after program execution.
10 changes: 5 additions & 5 deletions docs/control/reference/rest_api/headers/security_features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,13 @@ The agent architecture to use. Valid values:
|------|----------|---------|
| `array[object]` | No | `null` |

An array of content classifier configurations. Each classifier has the following fields:
LLM-based content classifiers that analyze tool call arguments (pre-execution) and results (post-execution) to detect sensitive content (e.g., PII, toxicity). Each classifier has the following fields:

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | `string` | Yes | - | Classifier identifier (see below) |
| `threshold` | `float` | No | `0.5` | Detection sensitivity threshold (0.0 - 1.0) |
| `mode` | `string` | No | `null` | Preset mode that overrides threshold: `"normal"` or `"strict"` |
| `threshold` | `float` | No | `0.5` | Threshold for the tagger (0.0 - 1.0) |
| `mode` | `string` | No | `null` | Optional mode that overrides threshold (e.g., `"high sensitivity"`, `"strict"`, `"low sensitivity"`, `"normal"`) |

Available classifiers:

Expand All @@ -62,11 +62,11 @@ Available classifiers:
|------|----------|---------|
| `array[object]` | No | `null` |

An array of content blocker configurations. Each blocker has the following fields:
Content blockers that redact or mask sensitive content in tool call arguments (pre-execution) and results (post-execution). Each blocker has the following fields:

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | `string` | Yes | - | Blocker identifier (see below) |
| `name` | `string` | Yes | - | Blocker identifier: `"url_blocker"` or `"file_blocker"` (see below) |

Available blockers:

Expand Down
Loading