Document model_providers headers in configuration reference

README.md

@@ -32,7 +32,7 @@ Plano solves this by moving core delivery concerns into a unified, out-of-proces
 Plano pulls rote plumbing out of your framework so you can stay focused on what matters most: the core product logic of your agentic applications. Plano is backed by [industry-leading LLM research](https://planoai.dev/research) and built on [Envoy](https://envoyproxy.io) by its core contributors, who built critical infrastructure at scale for modern worklaods.
 
 **High-Level Network Sequence Diagram**:
-![high-level network plano arcitecture for Plano](docs/source/_static/img/plano_network_diagram_high_level.png)
+![high-level network plano architecture for Plano](docs/source/_static/img/plano_network_diagram_high_level.png)
 
 **Jump to our [docs](https://docs.planoai.dev)** to learn how you can use Plano to improve the speed, safety and obervability of your agentic applications.
 
@@ -156,7 +156,7 @@ curl http://localhost:8001/v1/chat/completions \
 
 Every request is traced end-to-end with OpenTelemetry - no instrumentation code needed.
 
-![Atomatic Tracing](docs/source/_static/img/demo_tracing.png)
+![Automatic Tracing](docs/source/_static/img/demo_tracing.png)
 
 ### What You Didn't Have to Build
 

cli/planoai/config_generator.py

@@ -562,15 +562,15 @@ def validate_and_render_schema():
                     "Please provide model_providers either under listeners or at root level, not both. Currently we don't support multiple listeners with model_providers"
                 )
 
-    # Validate input_filters IDs on listeners reference valid agent/filter IDs
+    # Validate listener-level filter IDs reference valid agent/filter IDs.
     for listener in listeners:
-        listener_input_filters = listener.get("input_filters", [])
-        for fc_id in listener_input_filters:
-            if fc_id not in agent_id_keys:
-                raise Exception(
-                    f"Listener '{listener.get('name', 'unknown')}' references input_filters id '{fc_id}' "
-                    f"which is not defined in agents or filters. Available ids: {', '.join(sorted(agent_id_keys))}"
-                )
+        for filter_field in ("input_filters", "output_filters"):
+            for fc_id in listener.get(filter_field, []):
+                if fc_id not in agent_id_keys:
+                    raise Exception(
+                        f"Listener '{listener.get('name', 'unknown')}' references {filter_field} id '{fc_id}' "
+                        f"which is not defined in agents or filters. Available ids: {', '.join(sorted(agent_id_keys))}"
+                    )
 
     # Validate model aliases if present
     if "model_aliases" in config_yaml:

cli/test/test_config_generator.py

@@ -327,6 +327,63 @@ def test_validate_and_render_happy_path_agent_config(monkeypatch):
 tracing:
   random_sampling: 100
 
+""",
+    },
+    {
+        "id": "unknown_listener_output_filter",
+        "expected_error": "references output_filters id 'missing_output_guard'",
+        "plano_config": """
+version: v0.4.0
+
+filters:
+  - id: input_guard
+    url: http://localhost:10500
+    type: http
+
+listeners:
+  - name: llm
+    type: model
+    port: 12000
+    input_filters:
+      - input_guard
+    output_filters:
+      - missing_output_guard
+
+model_providers:
+  - model: openai/gpt-4o-mini
+    access_key: $OPENAI_API_KEY
+    default: true
+
+""",
+    },
+    {
+        "id": "valid_listener_output_filter",
+        "expected_error": None,
+        "plano_config": """
+version: v0.4.0
+
+filters:
+  - id: input_guard
+    url: http://localhost:10500
+    type: http
+  - id: output_guard
+    url: http://localhost:10501
+    type: http
+
+listeners:
+  - name: llm
+    type: model
+    port: 12000
+    input_filters:
+      - input_guard
+    output_filters:
+      - output_guard
+
+model_providers:
+  - model: openai/gpt-4o-mini
+    access_key: $OPENAI_API_KEY
+    default: true
+
 """,
     },
 ]

crates/brightstaff/src/main.rs

@@ -142,25 +142,19 @@ async fn init_app_state(
         .listeners
         .iter()
         .find(|l| l.listener_type == ListenerType::Model);
-    let resolve_chain = |filter_ids: Option<Vec<String>>| -> Option<ResolvedFilterChain> {
-        filter_ids.map(|ids| {
-            let agents = ids
-                .iter()
-                .filter_map(|id| {
-                    global_agent_map
-                        .get(id)
-                        .map(|a: &Agent| (id.clone(), a.clone()))
-                })
-                .collect();
-            ResolvedFilterChain {
-                filter_ids: ids,
-                agents,
-            }
-        })
-    };
     let filter_pipeline = Arc::new(FilterPipeline {
-        input: resolve_chain(model_listener.and_then(|l| l.input_filters.clone())),
-        output: resolve_chain(model_listener.and_then(|l| l.output_filters.clone())),
+        input: resolve_filter_chain(
+            "input_filters",
+            model_listener.and_then(|l| l.input_filters.clone()),
+            &global_agent_map,
+        )
+        .map_err(|e| format!("failed to resolve model listener input filters: {e}"))?,
+        output: resolve_filter_chain(
+            "output_filters",
+            model_listener.and_then(|l| l.output_filters.clone()),
+            &global_agent_map,
+        )
+        .map_err(|e| format!("failed to resolve model listener output filters: {e}"))?,
     });
 
     let overrides = config.overrides.clone().unwrap_or_default();
@@ -350,6 +344,29 @@ async fn init_app_state(
     })
 }
 
+fn resolve_filter_chain(
+    field_name: &str,
+    filter_ids: Option<Vec<String>>,
+    global_agent_map: &HashMap<String, Agent>,
+) -> Result<Option<ResolvedFilterChain>, String> {
+    let Some(ids) = filter_ids else {
+        return Ok(None);
+    };
+
+    let mut agents = HashMap::new();
+    for id in &ids {
+        let agent = global_agent_map
+            .get(id)
+            .ok_or_else(|| format!("{field_name} id '{id}' is not defined in agents or filters"))?;
+        agents.insert(id.clone(), agent.clone());
+    }
+
+    Ok(Some(ResolvedFilterChain {
+        filter_ids: ids,
+        agents,
+    }))
+}
+
 /// Initialize the conversation state storage backend (if configured).
 async fn init_state_storage(
     config: &Configuration,
@@ -588,3 +605,63 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let state = Arc::new(init_app_state(&config).await?);
     run_server(state).await
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_agent(id: &str) -> Agent {
+        Agent {
+            id: id.to_string(),
+            transport: None,
+            tool: None,
+            url: "http://localhost:10500".to_string(),
+            agent_type: Some("http".to_string()),
+        }
+    }
+
+    #[test]
+    fn resolve_filter_chain_keeps_valid_filter_references() {
+        let agent = test_agent("output_guard");
+        let global_agent_map = HashMap::from([(agent.id.clone(), agent)]);
+
+        let resolved = resolve_filter_chain(
+            "output_filters",
+            Some(vec!["output_guard".to_string()]),
+            &global_agent_map,
+        )
+        .expect("filter chain should resolve")
+        .expect("filter chain should be present");
+
+        assert_eq!(resolved.filter_ids, vec!["output_guard".to_string()]);
+        assert!(resolved.agents.contains_key("output_guard"));
+    }
+
+    #[test]
+    fn resolve_filter_chain_errors_on_missing_output_filter_reference() {
+        let global_agent_map = HashMap::new();
+
+        let err = resolve_filter_chain(
+            "output_filters",
+            Some(vec!["missing_output_guard".to_string()]),
+            &global_agent_map,
+        )
+        .expect_err("missing output filter should fail closed");
+
+        assert!(err.contains("output_filters id 'missing_output_guard'"));
+    }
+
+    #[test]
+    fn resolve_filter_chain_errors_on_missing_input_filter_reference() {
+        let global_agent_map = HashMap::new();
+
+        let err = resolve_filter_chain(
+            "input_filters",
+            Some(vec!["missing_input_guard".to_string()]),
+            &global_agent_map,
+        )
+        .expect_err("missing input filter should fail closed");
+
+        assert!(err.contains("input_filters id 'missing_input_guard'"));
+    }
+}

crates/common/src/api/open_ai.rs

@@ -53,7 +53,7 @@ impl Serialize for FunctionParameters {
     where
         S: serde::Serializer,
     {
-        // select all requried parameters
+        // select all required parameters
         let required: Vec<&String> = self
             .properties
             .iter()

docs/source/resources/configuration_reference.rst

@@ -7,6 +7,29 @@ The following is a complete reference of the ``plano_config.yml`` that controls
 the Plano gateway. This where you enable capabilities like routing to upstream LLm providers, defining prompt_targets
 where prompts get routed to, apply guardrails, and enable critical agent observability features.
 
+Model provider headers
+----------------------
+
+Each entry under ``model_providers`` (or the legacy ``llm_providers`` alias) may include a ``headers`` map of extra
+HTTP headers that Plano adds to upstream LLM requests. Plano applies these headers after it sets authentication from
+``access_key`` or ``passthrough_auth``, so you can supply provider-specific metadata without replacing the configured
+credentials.
+
+- **Type:** map of strings (header name → value)
+- **Optional:** yes
+- **Common uses:** required ``User-Agent`` values, organization or account identifiers, or other headers some APIs expect
+
+.. code-block:: yaml
+
+    model_providers:
+      - model: moonshotai/kimi-for-coding
+        access_key: $MOONSHOTAI_API_KEY
+        base_url: https://api.kimi.com/coding/v1
+        headers:
+          User-Agent: "KimiCLI/1.3"
+
+The example below includes this and other provider options in context.
+
 .. literalinclude:: includes/plano_config_full_reference.yaml
     :language: yaml
     :linenos:

docs/source/resources/includes/plano_config_full_reference.yaml

@@ -47,6 +47,14 @@ model_providers:
     http_host: api.custom-provider.com
     access_key: $CUSTOM_API_KEY
 
+  # headers: optional map of extra HTTP headers sent on upstream requests (after auth).
+  # Use for provider-specific requirements such as User-Agent, org IDs, or account headers.
+  - model: moonshotai/kimi-for-coding
+    access_key: $MOONSHOTAI_API_KEY
+    base_url: https://api.kimi.com/coding/v1
+    headers:
+      User-Agent: "KimiCLI/1.3"
+
 # Model aliases - use friendly names instead of full provider model names
 model_aliases:
   fast-llm:

docs/source/resources/includes/plano_config_full_reference_rendered.yaml

@@ -88,6 +88,18 @@ listeners:
     port: 443
     protocol: https
     provider_interface: openai
+  - access_key: $MOONSHOTAI_API_KEY
+    base_url: https://api.kimi.com/coding/v1
+    base_url_path_prefix: /coding/v1
+    cluster_name: moonshotai_api.kimi.com
+    endpoint: api.kimi.com
+    headers:
+      User-Agent: KimiCLI/1.3
+    model: kimi-for-coding
+    name: moonshotai/kimi-for-coding
+    port: 443
+    protocol: https
+    provider_interface: moonshotai
   name: model_1
   output_filters:
   - input_guards
@@ -144,6 +156,18 @@ model_providers:
   port: 443
   protocol: https
   provider_interface: openai
+- access_key: $MOONSHOTAI_API_KEY
+  base_url: https://api.kimi.com/coding/v1
+  base_url_path_prefix: /coding/v1
+  cluster_name: moonshotai_api.kimi.com
+  endpoint: api.kimi.com
+  headers:
+    User-Agent: KimiCLI/1.3
+  model: kimi-for-coding
+  name: moonshotai/kimi-for-coding
+  port: 443
+  protocol: https
+  provider_interface: moonshotai
 - internal: true
   model: Plano-Orchestrator
   name: plano-orchestrator