agent-lab/docs/plans/todo-7-provider-compatibility.md

Todo 7 Provider Compatibility Plan

Status: done

Result

Implemented by subagent, then documentation was adjusted in README.md so the smoke example uses backend model fallback by default and documents AGENT_LAB_OPENAI_INCLUDE_USAGE.

Commands:

uv run pytest tests/test_websocket_api.py tests/test_ws_smoke.py
uv run pytest
uv run python -c "from agent_lab.main import app; print(app.title)"
uv run python scripts/ws_smoke.py --help

Results:

• focused provider/API tests: 10 passed, 1 warning in 0.23s
• full suite: 14 passed, 1 warning in 0.24s
• import smoke: Agent Lab
• smoke helper help: command prints expected options.

Goal

Fix code-review findings that can break real OpenAI Chat Completions compatible providers.

Scope

This todo covers:

• Letting backend settings provide the default model when UI/smoke requests do not specify one.
• Role-aware provider message serialization so tool messages do not send unsupported name fields.
• Configurable stream_options.include_usage for providers that reject stream options.
• Tests that lock provider payload shape after tool calls.

This todo does not cover:

• Live network LLM smoke.
• New UI controls beyond model fallback behavior.
• Changing the EventAgent tool set.

Files

• Modify: src/agent_lab/application/contracts.py
• Modify: src/agent_lab/infrastructure/chat_client.py
• Modify: src/agent_lab/settings.py
• Modify: src/agent_lab/presentation/static/index.html
• Modify: src/agent_lab/presentation/static/app.js
• Modify: scripts/ws_smoke.py
• Modify: .env.example
• Modify tests as needed.
• Do not modify: docs/plans/todos.md.

Design

AgentParams.model should be optional. If omitted or blank, OpenAICompatibleChatClient uses Settings.openai_default_model.

Provider message serialization should be role-aware:

• system, user, assistant: include role, content, and assistant tool_calls when present.
• tool: include only role, content, and tool_call_id.

Add Settings.openai_include_usage: bool = True. When true, send stream_options: {"include_usage": True}; when false, omit stream_options.

The static UI and smoke helper should send an empty model by default, allowing backend fallback. Users may still provide a model explicitly.

Steps

1. Add failing tests for:
   • blank request model uses client default model.
   • tool message serialization excludes name while preserving tool_call_id.
   • stream_options is omitted when configured off.
2. Implement optional/blank model support in contracts and client payload.
3. Add role-aware message serialization in the client.
4. Add AGENT_LAB_OPENAI_INCLUDE_USAGE setting and .env.example entry.
5. Remove hardcoded default model from the static UI and smoke helper request payload defaults.

6. Run:

   uv run pytest tests/test_websocket_api.py tests/test_ws_smoke.py
   uv run pytest
   uv run python scripts/ws_smoke.py --help
   

Verification

Expected result:

• Provider payload tests pass.
• Full suite passes.
• Smoke helper help still works.