# How Switchyard Routes `reasoning_effort` and `extra_body` Parameters to the Network

> Discover how Switchyard routes reasoning_effort and extra_body parameters to the network. Learn when these parameters are dropped due to capability validation or existing request keys.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: internals
- Published: 2026-09-13

---

**In NVIDIA-NeMo/Switchyard, target-level `reasoning_effort` and `extra_body` configurations reach the network only after capability validation and shallow-merge deduplication, with `reasoning_effort` dropping when the backend reports `supports_reasoning_effort == false` and `extra_body` dropping when request keys already exist.**

NVIDIA-NeMo/Switchyard is a high-performance inference router that manages LLM traffic through configurable targets. Understanding how `reasoning_effort` and `extra_body` parameters propagate from TOML configuration to the wire protocol—and the specific conditions that cause them to be silently removed—is essential for debugging request behavior and enforcing strict parameter hygiene.

## How Parameters Travel from Configuration to Network

### Configuration Parsing in the Runner

When a `Runner` initializes, it loads target definitions from TOML configuration into the `Target` struct. The [[`crates/switchyard-runner/src/config.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs) file validates that `reasoning_effort` values (such as `low`, `medium`, or `high`) are compatible with the target's backend capabilities. If a mismatch exists between `first.reasoning_effort` and `target.reasoning_effort`, the validation layer raises an error before the runner starts.

The `extra_body` field is parsed as a shallow map of JSON keys and values intended as default parameters. These values are stored in the target's configuration but are not immediately transmitted; they await the request construction phase.

### Request Body Assembly

The [[`crates/libsy-llm-client/src/client.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy-llm-client/src/client.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/sy-llm-client/src/client.rs) file handles the actual request construction. Before the HTTP backend transmits the request, the code calls `merge_extra_body(&mut body, backend.extra_body())` (around line 258). This function performs a **shallow merge**, injecting `extra_body` keys only if they are **absent** from the existing request body. If the caller explicitly provided a value for a key present in `extra_body`, the caller's value wins and the default is discarded.

```rust
// Conceptual flow in client.rs
let mut body = build_initial_request();
// Only adds keys not already present
merge_extra_body(&mut body, target.extra_body());

```

### Capability-Based Translation

The [[`crates/switchyard-translation/src/util.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-translation/src/util.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-translation/src/util.rs) layer checks the backend's advertised capabilities via `supports_reasoning_effort`. When this flag is `Some(true)`, the translation layer inserts the `reasoning_effort` field into the outbound JSON, overriding any client-side `reasoning.effort` or `reasoning_effort` values. If the flag is `Some(false)` or the client type does not support reasoning effort (e.g., Anthropic message endpoints), the parameter is stripped before reaching the wire.

## When Parameters Are Dropped

### `reasoning_effort` Drop Conditions

The `reasoning_effort` parameter is dropped in the following scenarios:

*   **Unsupported Backend**: If the backend's capability metadata indicates `supports_reasoning_effort == false`, the translation layer skips insertion entirely.
*   **Incompatible Client Type**: Certain client implementations (such as Anthropic) do not accept a `reasoning_effort` field. Attempting to configure it on these targets results in the parameter being ignored, as documented in the [TOML schema reference](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/reference/toml_schema.md).
*   **Validation Failure**: If the configuration defines conflicting `reasoning_effort` values across fallback targets, [[`crates/switchyard-runner/src/config.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs) raises a validation error and prevents the runner from starting, effectively dropping the configuration.

### `extra_body` Drop Conditions

The `extra_body` map is dropped or ignored under these constraints:

*   **Key Collision**: By design, `merge_extra_body` only fills missing keys. If the incoming request already contains a key defined in `extra_body`, the default value is discarded.
*   **Explicit Override Precedence**: If a target defines both `reasoning_effort` and an `extra_body` entry for the same reasoning key, the explicit `reasoning_effort` field takes precedence, and the `extra_body` value is ignored during the merge.

## Practical Configuration Example

The following TOML snippet demonstrates a target that uses both parameters:

```toml
[[targets]]
name = "openai-reasoning"
model = "o1-mini"
reasoning_effort = "high"

[targets.extra_body]
temperature = 0.2
top_p = 0.9

```

In this example, `reasoning_effort` reaches the OpenAI API only if the backend advertises support. The `temperature` and `top_p` values are injected only if the upstream request does not already specify them.

## Summary

- **Configuration Origin**: Both parameters originate in [[`crates/switchyard-runner/src/config.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs) as part of the `Target` struct validation.
- **Network Gateway**: [[`crates/libsy-llm-client/src/client.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy-llm-client/src/client.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/sy-llm-client/src/client.rs) acts as the final gatekeeper, merging `extra_body` via `merge_extra_body` and handling the raw HTTP transmission.
- **Capability Guard**: [[`crates/switchyard-translation/src/util.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-translation/src/util.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-translation/src/util.rs) filters `reasoning_effort` based on the `supports_reasoning_effort` capability flag.
- **Drop Rules**: `reasoning_effort` drops on unsupported backends; `extra_body` drops on key collisions, serving strictly as a defaults-only mechanism.

## Frequently Asked Questions

### What happens if I configure `reasoning_effort` on a backend that does not support it?

The parameter is silently dropped during the translation phase. The [[`crates/switchyard-translation/src/util.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-translation/src/util.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-translation/src/util.rs) layer checks the backend's `supports_reasoning_effort` capability, and if the value is `Some(false)` or undefined for that client type, the field is omitted from the outbound JSON.

### Can `extra_body` override parameters explicitly provided by the caller?

No. The `merge_extra_body` function in [[`crates/libsy-llm-client/src/client.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy-llm-client/src/client.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/sy-llm-client/src/client.rs) performs a shallow merge that only inserts keys missing from the request. Explicit caller values always take precedence, making `extra_body` a defaults-only mechanism.

### How does Switchyard handle conflicting `reasoning_effort` values across fallback targets?

The runner validates target configurations at startup in [[`crates/switchyard-runner/src/config.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs). If a fallback chain defines mismatched `reasoning_effort` values, the validation logic raises an error and prevents the runner from initializing, ensuring consistent reasoning configuration across the fallback path.

### Why is my `extra_body` parameter missing from the upstream request?

Check for key collisions. If the incoming request already contains the key you defined in `extra_body`, Switchyard drops the default to avoid overwriting explicit instructions. Additionally, verify that your TOML syntax defines `extra_body` as a map (table) and not a scalar value, as malformed configuration will fail validation in the runner's config parser.