fix(api-server): unblock /v1/chat/completions with narrow kwargs-collision fix

[Koraji95-coder]

What changed and why

gateway/platforms/api_server.py's _create_agent() builds runtime_kwargs via _resolve_runtime_agent_kwargs() (which sources model from config.yaml among other settings), then a few lines later constructs AIAgent(model=model, **runtime_kwargs). The explicit model=model collides with the model key already populated in runtime_kwargs, raising:

TypeError: AIAgent() got multiple values for keyword argument 'model'

…before any request is ever served. The API server platform is therefore unusable for any OpenAI-compatible client — every POST /v1/chat/completions returns HTTP 500 with that exact error.

This PR adds one line — runtime_kwargs.pop('model', None) — right after _resolve_runtime_agent_kwargs() returns, so the explicit model=model kwarg below wins unambiguously. The request-level model field is ignored in favor of the server-side config.yaml value, which matches the current (broken-by-the-crash) implicit behavior.

Strictly less scope than #25552 / #16403 / #18549 / #5862. No per-request routing, no new config surface, no behavior change for anyone whose payload already matched the server-side model. Just unblocks the 500 while the broader per-request-model design at #10773 gets settled. When #10773's full design lands, this pop gets replaced by whatever per-request routing it specifies.

How to test

Reproduction (any OS, hermes-agent v0.14.0):

# 1. Enable the API server
cat >> ~/.hermes/.env <<'ENV'
API_SERVER_ENABLED=true
API_SERVER_KEY=test-key
ENV

# 2. Start the gateway
hermes gateway

# 3. POST a chat completion request
curl -H 'Authorization: Bearer test-key' \
     -H 'Content-Type: application/json' \
     http://localhost:8642/v1/chat/completions \
     -d '{"model":"hermes-agent","messages":[{"role":"user","content":"ping"}]}'

Before this PR: HTTP 500 within ~50ms regardless of payload:

{
  "error": {
    "message": "Internal server error: run_agent.AIAgent() got multiple values for keyword argument 'model'",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

After this PR: HTTP 200 with a real OpenAI-shaped Chat Completion:

{
  "id": "chatcmpl-f67cabfe3f6146b1a870ab6b5ac54",
  "object": "chat.completion",
  "created": 1779567828,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "pong"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 14816, "completion_tokens": 29, "total_tokens": 14845}
}

What platforms

Tested on:

• Windows 11 Pro (build 26200), hermes-agent v0.14.0, Python 3.11.15 via the bundled venv. Foundry broker hitting /v1/chat/completions through a Tailscale-mesh reverse proxy (Basic Auth at edge, Bearer auto-injected for /v1/* paths). Real agent invocation, real tool-calls, finish_reason: stop, 33-second end-to-end response.
• Windows 11 Pro (build 26200), second independent machine, same hermes-agent version. Same Foundry-broker → API server path. Independent smoke confirmed 200 + matching response shape.

No Linux smoke from me personally — the kwargs collision is purely a Python-level constructor argument issue, not platform-specific, but flagging the gap for completeness.

Related issues

• feat(api-server): honor request-level model field for per-request model selection #10773 — root issue: feat(api-server): honor request-level model field for per-request model selection. This PR is strictly less than what feat(api-server): honor request-level model field for per-request model selection #10773 asks for; it just unblocks the crash so the broader design can land cleanly later.
• fix(api-server): honor chat completions request model #25552 — competing implementation (still OPEN, no merge). Larger surface area; this PR is the band-aid only.
• feat(api-server): honor X-Router-Model for per-request model override #16403, feat(api_server): honor inbound 'model' and 'provider' fields for per-request routing #18549, feat(gateway): add per-request model routing to API server #5862 — other competing implementations of feat(api-server): honor request-level model field for per-request model selection #10773.
• api_server: honor the model field in /v1/chat/completions #24008 — closed as duplicate of feat(api-server): honor request-level model field for per-request model selection #10773.
• My comment on feat(api-server): honor request-level model field for per-request model selection #10773 with this proposal: feat(api-server): honor request-level model field for per-request model selection #10773 (comment)

AI usage disclosure

• Provider: Anthropic
• Model: Claude 4.7 (Sonnet, 1M context)
• Mode: Used to draft the patch (single-line code change + 8-line explanatory comment), this PR body, and to verify the anchor-based edit produced no collateral changes. Production smoke tests above were run by humans on real production machines (two separate Windows boxes), not by the model.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR prevents a runtime keyword-argument collision when constructing AIAgent, avoiding a TypeError that currently causes 500s on POST /v1/chat/completions.

Changes:

• Remove (pop) any pre-existing model entry from runtime_kwargs to prevent passing model twice to AIAgent.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Koraji95-coder]

Considered both of your suggestions (a) 4xx-on-mismatch and (b) drop-only-when-matching, and explicitly picked the unconditional pop for this PR. Two reasons:

1. Precedence semantics is the design conversation at feat(api-server): honor request-level model field for per-request model selection #10773. The competing PRs (fix(api-server): honor chat completions request model #25552, feat(api-server): honor X-Router-Model for per-request model override #16403, feat(api_server): honor inbound 'model' and 'provider' fields for per-request routing #18549, feat(gateway): add per-request model routing to API server #5862) are wrestling with exactly what the request-level model field should mean — error, override, fallback, mismatch-warn. This PR is the band-aid that unblocks /v1/chat/completions for everyone while that design lands. Implementing either suggestion (a) or (b) here would mean picking a winner in the design debate, which is exactly what I don't want this PR to do.

2. Failing-loud on caller-provided model would surprise existing API consumers. Before the kwargs collision was ever triggered, callers could already send model in their request — the server-side config.yaml value won by virtue of the explicit model=model kwarg in the constructor, and the caller's value was silently ignored. That's the current implicit behavior of every working deployment that happens to not hit the collision. The narrow pop preserves that behavior exactly.

Added a regression test in tests/gateway/test_api_server.py::TestCreateAgent::test_create_agent_pops_colliding_model_from_runtime_kwargs (commit 86d349a) that locks in the no-TypeError behavior, mirroring the existing test_create_agent_forwards_config_reasoning_effort pattern in the same class.

When #10773's full design lands, the pop gets replaced by whatever precedence semantics it specifies, and the test gets updated alongside. If the maintainer's strong preference is option (b) precedence-aware behavior here rather than at #10773, happy to rework.

[alt-glitch]

Duplicate of #27678 — same runtime_kwargs.pop('model', None) fix in api_server.py to prevent the model kwargs collision. #27678 is the canonical PR for this fix (addresses #27540).

[Koraji95-coder]

Closing as duplicate of #27678 — thanks @alt-glitch for the catch. @briandevans's PR (filed 2026-05-18) implements the exact same runtime_kwargs.pop('model', None) fix in _create_agent(), with the additional context that it specifically addresses the fallback-provider trigger path from #27540, and even cites the canonical pattern from GatewayRunner._resolve_model_runt.... That PR is the right place for this fix to land.

Transferring our two-Windows-box production evidence to #27678 as a comment so it can help push that PR through.

The regression test I added in this PR (test_create_agent_pops_colliding_model_from_runtime_kwargs in tests/gateway/test_api_server.py::TestCreateAgent) was incidental to closing the kwargs collision — if it's useful to #27678, happy to file it as a follow-up test: PR against #27678's branch once that merges.