fix(agent): make parallel_tool_calls configurable; fixes Bedrock query/chat (#175)

query/chat agents hardcoded ModelSettings(parallel_tool_calls=False). On
Amazon Bedrock Claude models this is fatal: LiteLLM's Bedrock Converse
transform turns any parallel_tool_calls value into a tool_choice object
carrying only `{"disable_parallel_tool_use": ...}` with no `type` field
(converse_transformation.py: the _parallel_tool_use_config merge), which
Bedrock rejects with "tool_choice.type: Field required" — so every query and
chat fails. Confirmed unfixed through the latest litellm 1.91.1
(BerriAI/litellm#27184 still open); bumping doesn't help.

Expose it as a config knob instead of hardcoding:

- New `parallel_tool_calls` config key, default None = omit the setting (let
  the provider decide). Omitting is the only value that works on Bedrock, and
  is benign elsewhere (query tools are read-only; chat writes are
  path-restricted).
- config.resolve_parallel_tool_calls() validates bool/null (warns on junk);
  set/get_parallel_tool_calls() process-wide stash, set by cli._setup_llm_key,
  read in build_query_agent — same mechanism as extra_headers/timeout.
- Users can still force sequential tool calls with `parallel_tool_calls: false`
  on providers that support it.
- Docs: config.yaml.example + configuration README (key table + a Bedrock
  setup section, which the repo previously lacked entirely).

Closes #175

Author: KylinMountain

config.yaml.example

@@ -2,6 +2,12 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
+# Optional: whether query/chat agents may call tools in parallel. Omit (the
+# default) to let the provider decide. Leave it unset for Amazon Bedrock Claude
+# models — sending it makes LiteLLM emit a malformed tool_choice and every
+# query/chat fails. Set false to force sequential tool calls on other providers.
+# parallel_tool_calls: false
+
 # Optional: override the entity-type vocabulary used for entity pages.
 # Omit this key to use the default 7 types
 # (person, organization, place, product, work, event, other).

examples/configuration/README.md

@@ -70,6 +70,12 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
+# Optional: whether query/chat agents may call tools in parallel. Omit (the
+# default) to let the provider decide. Leave it unset for Amazon Bedrock Claude
+# models — sending it makes LiteLLM emit a malformed tool_choice and every
+# query/chat fails. Set false to force sequential tool calls on other providers.
+# parallel_tool_calls: false
+
 # Optional: override the entity-type vocabulary used for entity pages.
 # Omit this key to use the default 7 types
 # (person, organization, place, product, work, event, other).
@@ -95,6 +101,7 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 | `model` | `gpt-5.4` | LLM used for all compile/query/chat work. |
 | `language` | `en` | Language the wiki is written in. |
 | `pageindex_threshold` | `20` | PDFs with this many pages **or more** take the long-doc (PageIndex) path; shorter ones go through the short-doc path. See [`pageindex-cloud/`](../pageindex-cloud/). |
+| `parallel_tool_calls` | *(unset)* | Whether query/chat agents may call tools in parallel. Unset = provider default. **Leave unset for Amazon Bedrock** (see below). Set `false` to force sequential tool calls elsewhere. |
 | `entity_types` | 7 defaults | Custom vocabulary for entity pages. `other` is always kept. |
 | `litellm:` | – | A pass-through block for LiteLLM. See below. |
 
@@ -177,6 +184,24 @@ LLM_API_KEY=your-key-here
   won't warn about a missing one.
 - **PageIndex Cloud** uses a separate `PAGEINDEX_API_KEY` (see
   [`pageindex-cloud/`](../pageindex-cloud/)).
+- **Amazon Bedrock** (`model: bedrock/...`) authenticates with AWS credentials,
+  not `LLM_API_KEY`. Put them in `<kb>/.env` (LiteLLM/boto3 read them from the
+  environment); `LLM_API_KEY` isn't needed:
+
+  ```bash
+  # <kb>/.env
+  AWS_ACCESS_KEY_ID=...
+  AWS_SECRET_ACCESS_KEY=...
+  AWS_REGION_NAME=eu-central-1
+  ```
+
+  ```yaml
+  # <kb>/.openkb/config.yaml
+  model: bedrock/eu.anthropic.claude-sonnet-4-6
+  # Do NOT set parallel_tool_calls for Bedrock Claude — leaving it unset (the
+  # default) is what keeps query/chat working; setting it makes LiteLLM send a
+  # malformed tool_choice that Bedrock rejects (issue #175).
+  ```
 
 **Where keys are read from** (first match wins, existing env always respected):
 

openkb/agent/query.py

@@ -12,7 +12,7 @@
     read_wiki_image,
     write_kb_file,
 )
-from openkb.config import get_extra_headers, get_timeout_extra_args
+from openkb.config import get_extra_headers, get_parallel_tool_calls, get_timeout_extra_args
 from openkb.schema import get_agents_md
 
 MAX_TURNS = 50
@@ -96,7 +96,7 @@ def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
         tools=[read_file, get_page_content, get_image],
         model=f"litellm/{model}",
         model_settings=ModelSettings(
-            parallel_tool_calls=False,
+            parallel_tool_calls=get_parallel_tool_calls(),
             extra_headers=get_extra_headers() or None,
             extra_args=get_timeout_extra_args(),
         ),

openkb/cli.py

@@ -56,6 +56,8 @@ def filter(self, record: logging.LogRecord) -> bool:
     register_kb,
     resolve_extra_headers,
     set_extra_headers,
+    resolve_parallel_tool_calls,
+    set_parallel_tool_calls,
     resolve_timeout,
     set_timeout,
     resolve_litellm_settings,
@@ -174,6 +176,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
     provider: str | None = None
     extra_headers: dict[str, str] = {}
     timeout: float | None = None
+    parallel_tool_calls: bool | None = None
     litellm_settings: dict = {}
     if kb_dir is not None:
         config_path = kb_dir / ".openkb" / "config.yaml"
@@ -183,6 +186,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
             provider = _extract_provider(str(model))
             extra_headers = resolve_extra_headers(config)
             timeout = resolve_timeout(config)
+            parallel_tool_calls = resolve_parallel_tool_calls(config)
             litellm_settings = resolve_litellm_settings(config)
             # `timeout` / `extra_headers` in the block route to the per-call
             # stashes (replacing the legacy top-level keys); the rest are globals.
@@ -194,6 +198,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
                 timeout = resolve_timeout({"timeout": litellm_settings.pop("timeout")})
     set_extra_headers(extra_headers)
     set_timeout(timeout)
+    set_parallel_tool_calls(parallel_tool_calls)
     _apply_litellm_settings(litellm_settings)
 
     if not api_key:

openkb/config.py

@@ -17,6 +17,12 @@
     "model": "gpt-5.4",
     "language": "en",
     "pageindex_threshold": 20,
+    # Whether query/chat agents may call tools in parallel. None (default) omits
+    # the setting so the provider decides — required for Amazon Bedrock's Claude
+    # models, where sending parallel_tool_calls makes LiteLLM emit a malformed
+    # tool_choice (missing `type`) and every query/chat fails (issue #175). Set
+    # false to force sequential tool calls (fine on OpenAI/Anthropic-direct).
+    "parallel_tool_calls": None,
 }
 
 # Default entity-type vocabulary. Overridable per-KB via the optional
@@ -144,6 +150,26 @@ def resolve_extra_headers(config: dict) -> dict[str, str]:
     return headers
 
 
+def resolve_parallel_tool_calls(config: dict) -> bool | None:
+    """Resolve the optional ``parallel_tool_calls:`` key.
+
+    Returns ``None`` (omit the setting — provider default) when absent or
+    explicitly null; ``True``/``False`` when set to a bool. A non-bool value is
+    invalid and treated as unset, with a warning. ``None`` is the normal
+    "unset" case and warns silently, matching ``resolve_timeout``.
+    """
+    value = config.get("parallel_tool_calls")
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        logger.warning(
+            "config: 'parallel_tool_calls' must be true or false, got %r — ignoring it.",
+            value,
+        )
+        return None
+    return value
+
+
 def resolve_timeout(config: dict) -> float | None:
     """Resolve the optional ``timeout:`` key to a finite positive number of seconds.
 
@@ -243,6 +269,24 @@ def get_timeout_extra_args() -> dict[str, float] | None:
     return {"timeout": _runtime_timeout} if _runtime_timeout is not None else None
 
 
+# Process-wide agent ``parallel_tool_calls`` setting, resolved from config by
+# the CLI (cli._setup_llm_key) and read when building query/chat agents. None =
+# omit the setting (provider default) — see the DEFAULT_CONFIG note on why
+# Bedrock needs this.
+_runtime_parallel_tool_calls: bool | None = None
+
+
+def set_parallel_tool_calls(value: bool | None) -> None:
+    """Set the process-wide agent ``parallel_tool_calls`` setting."""
+    global _runtime_parallel_tool_calls
+    _runtime_parallel_tool_calls = value
+
+
+def get_parallel_tool_calls() -> bool | None:
+    """Return the process-wide agent ``parallel_tool_calls`` setting (or None)."""
+    return _runtime_parallel_tool_calls
+
+
 def load_config(config_path: Path) -> dict[str, Any]:
     """Load YAML config from config_path, merged with DEFAULT_CONFIG.
 

tests/conftest.py

@@ -5,12 +5,14 @@
 
 @pytest.fixture(autouse=True)
 def _reset_extra_headers():
-    """Keep the process-wide LLM extra-headers / timeout stashes from leaking across tests."""
-    from openkb.config import set_extra_headers, set_timeout
+    """Keep the process-wide LLM extra-headers / timeout / parallel-tool-calls
+    stashes from leaking across tests."""
+    from openkb.config import set_extra_headers, set_parallel_tool_calls, set_timeout
 
     yield
     set_extra_headers({})
     set_timeout(None)
+    set_parallel_tool_calls(None)
 
 
 @pytest.fixture

tests/test_config.py

@@ -3,17 +3,55 @@
 from openkb.config import (
     DEFAULT_CONFIG,
     get_extra_headers,
+    get_parallel_tool_calls,
     get_timeout,
     load_config,
     resolve_extra_headers,
     resolve_litellm_settings,
+    resolve_parallel_tool_calls,
     resolve_timeout,
     save_config,
     set_extra_headers,
+    set_parallel_tool_calls,
     set_timeout,
 )
 
 
+def test_parallel_tool_calls_defaults_to_none():
+    assert DEFAULT_CONFIG["parallel_tool_calls"] is None
+
+
+def test_resolve_parallel_tool_calls_absent_is_none():
+    assert resolve_parallel_tool_calls({}) is None
+
+
+def test_resolve_parallel_tool_calls_explicit_bools():
+    assert resolve_parallel_tool_calls({"parallel_tool_calls": True}) is True
+    assert resolve_parallel_tool_calls({"parallel_tool_calls": False}) is False
+
+
+def test_resolve_parallel_tool_calls_none_is_silent(caplog):
+    with caplog.at_level(logging.WARNING, logger="openkb.config"):
+        assert resolve_parallel_tool_calls({"parallel_tool_calls": None}) is None
+    assert caplog.text == ""
+
+
+def test_resolve_parallel_tool_calls_rejects_non_bool(caplog):
+    # A non-bool (e.g. a string or int) is invalid → treat as unset, with a warning.
+    with caplog.at_level(logging.WARNING, logger="openkb.config"):
+        assert resolve_parallel_tool_calls({"parallel_tool_calls": "true"}) is None
+    assert "parallel_tool_calls" in caplog.text
+
+
+def test_parallel_tool_calls_stash_roundtrip():
+    set_parallel_tool_calls(False)
+    assert get_parallel_tool_calls() is False
+    set_parallel_tool_calls(True)
+    assert get_parallel_tool_calls() is True
+    set_parallel_tool_calls(None)
+    assert get_parallel_tool_calls() is None
+
+
 def test_default_config_keys():
     assert "model" in DEFAULT_CONFIG
     assert "language" in DEFAULT_CONFIG

tests/test_query.py

@@ -154,14 +154,34 @@ def test_extra_headers_applied_from_stash(self, tmp_path):
         set_extra_headers({"Editor-Version": "vscode/1.95.0"})
         agent = build_query_agent(str(tmp_path), "github_copilot/gpt-5-mini")
         assert agent.model_settings.extra_headers == {"Editor-Version": "vscode/1.95.0"}
-        # Existing settings are preserved.
-        assert agent.model_settings.parallel_tool_calls is False
 
     def test_no_extra_headers_by_default(self, tmp_path):
         agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
         assert agent.model_settings.extra_headers is None
 
 
+class TestQueryAgentParallelToolCalls:
+    """Config-driven parallel_tool_calls reaches the agents-SDK model settings.
+
+    Default is None (omit the param → provider default), which is what keeps
+    Bedrock's Claude models working: passing parallel_tool_calls at all makes
+    LiteLLM emit a tool_choice object missing the required `type` field (see
+    issue #175). Users can still force sequential tool calls with
+    `parallel_tool_calls: false`.
+    """
+
+    def test_omitted_by_default(self, tmp_path):
+        agent = build_query_agent(str(tmp_path), "bedrock/eu.anthropic.claude-sonnet-4-6")
+        assert agent.model_settings.parallel_tool_calls is None
+
+    def test_applied_from_stash(self, tmp_path):
+        from openkb.config import set_parallel_tool_calls
+
+        set_parallel_tool_calls(False)
+        agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
+        assert agent.model_settings.parallel_tool_calls is False
+
+
 class TestQueryAgentTimeout:
     """Config-driven timeout reaches the agents-SDK model settings via extra_args.