fix: prevent KeyError 'tool_call_id' in LangChain message handling

[xinquiry]

Summary

• Fix KeyError: 'tool_call_id' error when LangChain processes tool messages
• Get messages directly from state before model_dump() to preserve BaseMessage types (was serializing ToolMessage to dict and losing tool_call_id field)
• Add validation in history.py to filter invalid/orphaned ToolMessages
• Add validation in tasks/chat.py to skip storing tool responses with invalid toolCallId

Test plan

• All 275 tests pass
• Tested tool calling in frontend - works correctly now

🤖 Generated with Claude Code

Summary by Sourcery

确保 LangChain 聊天历史和工具消息处理在遇到无效的 tool_call_id 时依然健壮，并在 LLM 调用中保留消息的元数据。

Bug 修复：

• 在处理工具调用响应事件和加载会话历史时，防止因 tool_call_id 无效或缺失导致的崩溃。
• 通过在 LLM 节点构建器中在模型序列化之前从状态中读取消息，保留 LangChain BaseMessage 元数据（包括 tool_call_id）。

增强功能：

• 校验并过滤已存储的 ToolMessage，丢弃无效或孤立的条目，并记录关于被过滤历史的诊断日志。
• 改进与历史加载和工具消息校验相关的日志记录，以暴露被跳过或格式错误的消息。

Original summary in English

Summary by Sourcery

Ensure LangChain chat history and tool message handling are robust against invalid tool_call_id values and preserve message metadata for LLM calls.

Bug Fixes:

• Prevent crashes from invalid or missing tool_call_id values when processing tool call response events and loading conversation history.
• Preserve LangChain BaseMessage metadata (including tool_call_id) by reading messages from state before model serialization in the LLM node builder.

Enhancements:

• Validate and filter stored ToolMessages to drop invalid or orphaned entries and log diagnostics about filtered history.
• Improve logging around history loading and tool message validation to surface skipped or malformed messages.

[sourcery-ai]

Reviewer's Guide

通过在构建 LLM 输入时保留 BaseMessage 实例、在工具响应中校验 tool_call_id / toolCallId，以及在会话历史和持久化路径中过滤无效或孤立的 ToolMessage，修复 LangChain 工具消息处理问题，从而避免出现 KeyError 'tool_call_id'。

工具响应持久化与历史记录校验的时序图

sequenceDiagram
    actor User
    participant Frontend
    participant ToolService
    participant ChatWorker
    participant Database
    participant LangChain

    User->>Frontend: Send chat message
    Frontend->>ChatWorker: stream_event(data from ToolService)
    ChatWorker->>ChatWorker: Extract resp from stream_event
    ChatWorker->>ChatWorker: Validate toolCallId
    alt toolCallId invalid
        ChatWorker->>ChatWorker: Log warning
        ChatWorker->>Frontend: Publish stream_event (no persistence)
        ChatWorker-->>ToolService: Continue with next event
    else toolCallId valid
        ChatWorker->>Database: Persist MessageCreate with
        Note right of Database: event=TOOL_CALL_RESPONSE
        ChatWorker->>Frontend: Publish stream_event
    end

    loop Later conversation load
        ChatWorker->>Database: load_conversation_history
        Database-->>ChatWorker: Raw messages list
        ChatWorker->>ChatWorker: _validate_and_filter_messages
        ChatWorker->>ChatWorker: Collect valid tool_call_ids from AIMessage.tool_calls
        ChatWorker->>ChatWorker: Filter ToolMessages
        ChatWorker-->>LangChain: Validated messages list
    end

Loading

保留 BaseMessage 的 LLM 节点消息构建时序图

sequenceDiagram
    participant GraphBuilder
    participant llm_node
    participant State
    participant LLM

    GraphBuilder->>llm_node: Invoke with state
    alt state is BaseModel
        llm_node->>State: Access messages attribute
        State-->>llm_node: list[BaseMessage]
    else state is dict
        llm_node->>State: Get messages key
        State-->>llm_node: list[BaseMessage]
    end

    llm_node->>llm_node: Preserve BaseMessage instances
    llm_node->>llm_node: state_dict = _state_to_dict(state)
    llm_node->>llm_node: prompt = _render_template(prompt_template, state_dict)
    llm_node->>llm_node: llm_messages = messages + HumanMessage(prompt)
    llm_node->>LLM: ainvoke(llm_messages)
    LLM-->>llm_node: AIMessage (with tool_calls and tool_call_id)

Loading

更新后的 LangChain 消息处理与校验类图

classDiagram
    class BaseMessage

    class HumanMessage {
        +content str
    }

    class AIMessage {
        +content str
        +tool_calls list
    }

    class ToolMessage {
        +content str
        +tool_call_id str
    }

    BaseMessage <|-- HumanMessage
    BaseMessage <|-- AIMessage
    BaseMessage <|-- ToolMessage

    class HistoryModule {
        +load_conversation_history(db, topic) list~BaseMessage~
        +_build_tool_messages(formatted_content, num_tool_calls) ToolMessage
        +_validate_and_filter_messages(messages) list~BaseMessage~
    }

    class ChatTasksModule {
        +_process_chat_message_async(...)
    }

    class GraphBuilderModule {
        +_build_llm_node(config) NodeFunction
        +_state_to_dict(state) dict
        +_render_template(prompt_template, state_dict) str
    }

    HistoryModule ..> AIMessage : uses
    HistoryModule ..> ToolMessage : builds and filters
    HistoryModule ..> BaseMessage : returns list

    ChatTasksModule ..> ToolMessage : persists as tool role
    ChatTasksModule ..> HistoryModule : history consumed later

    GraphBuilderModule ..> BaseMessage : reads messages
    GraphBuilderModule ..> HumanMessage : appends prompt
    GraphBuilderModule ..> AIMessage : receives from LLM

Loading

文件级变更

Change	Details	Files
在构建 LLM 节点消息时保留 LangChain 的 BaseMessage 对象，以防丢失 tool_call_id 和其他消息特定字段。	不再依赖 model_dump() / state-to-dict 转换来获取用于 LLM 调用的 messages。 在转换之前，直接从 StateDict/BaseModel 中读取 messages，保留 BaseMessage 实例。 使用保留的 messages 加上一个带渲染后 prompt 的新 HumanMessage 来构建 llm_messages。	service/app/agents/graph_builder.py
在加载的会话历史中校验并过滤 ToolMessage，确保其包含有效的 tool_call_id 值并且有对应的 AIMessage tool_calls。	新增 _validate_and_filter_messages 对加载的历史记录做后处理。 在过滤前，先从 AIMessage.tool_calls 中收集所有有效的 tool_call_id。 丢弃缺失/无效 tool_call_id 或没有匹配 AIMessage.tool_call 的 ToolMessage，并记录警告日志及过滤结果汇总。 返回校验后的历史记录而非原始列表，并调整日志输出以显示校验前/后的数量。	service/app/core/chat/history.py
在将工具调用响应持久化到数据库时校验 toolCallId，对于无效条目不入库但仍继续向前端推流。	从工具响应中提取 toolCallId，并确保其为非空字符串后再进行持久化。 若 toolCallId 无效，则记录警告日志，将事件发布到前端，但跳过数据库持久化。 在持久化时，使用已校验的 tool_call_id，并在存储的内容载荷中对缺失的 result 字段使用空字符串作为默认值。	service/app/tasks/chat.py

---

Tips and commands

与 Sourcery 交互

• 触发新的代码审查： 在 pull request 中评论 @sourcery-ai review。
• 继续讨论： 直接回复 Sourcery 的审查评论。
• 从审查评论生成 GitHub issue： 在某条审查评论下回复，请 Sourcery 从该评论创建 issue。你也可以回复该评论 @sourcery-ai issue 来从中创建 issue。
• 生成 pull request 标题： 在 pull request 标题的任意位置写上 @sourcery-ai 来随时生成标题。你也可以在 pull request 中评论 @sourcery-ai title 来（重新）生成标题。
• 生成 pull request 摘要： 在 pull request 正文的任意位置写上 @sourcery-ai summary，即可在该位置生成 PR 摘要。你也可以在 pull request 中评论 @sourcery-ai summary 来（重新）生成摘要。
• 生成审查者指南： 在 pull request 中评论 @sourcery-ai guide 来随时（重新）生成审查者指南。
• 解决所有 Sourcery 评论： 在 pull request 中评论 @sourcery-ai resolve 来将所有 Sourcery 评论标记为已解决。如果你已经处理完所有评论且不希望再看到它们，这会很有用。
• 忽略所有 Sourcery 审查： 在 pull request 中评论 @sourcery-ai dismiss 来忽略所有现有的 Sourcery 审查。特别适用于你想从头开始新的审查时——别忘了再评论 @sourcery-ai review 来触发新的审查！

自定义你的使用体验

访问你的 dashboard 以：

• 启用或禁用诸如 Sourcery 生成的 pull request 摘要、审查者指南等审查功能。
• 更改审查语言。
• 添加、删除或编辑自定义审查说明。
• 调整其他审查设置。

获取帮助

• 通过 联系支持团队 获取问题解答或反馈渠道。
• 访问我们的 文档 以查阅详细指南和信息。
• 关注我们的 X/Twitter、LinkedIn 或 GitHub 与 Sourcery 团队保持联系。

Original review guide in English

Reviewer's Guide

Fixes LangChain tool message handling by preserving BaseMessage instances when building LLM inputs, validating tool_call_id / toolCallId for tool responses, and filtering invalid or orphaned ToolMessages from conversation history and persistence paths to prevent KeyError 'tool_call_id'.

Sequence diagram for tool response persistence and history validation

sequenceDiagram
    actor User
    participant Frontend
    participant ToolService
    participant ChatWorker
    participant Database
    participant LangChain

    User->>Frontend: Send chat message
    Frontend->>ChatWorker: stream_event(data from ToolService)
    ChatWorker->>ChatWorker: Extract resp from stream_event
    ChatWorker->>ChatWorker: Validate toolCallId
    alt toolCallId invalid
        ChatWorker->>ChatWorker: Log warning
        ChatWorker->>Frontend: Publish stream_event (no persistence)
        ChatWorker-->>ToolService: Continue with next event
    else toolCallId valid
        ChatWorker->>Database: Persist MessageCreate with
        Note right of Database: event=TOOL_CALL_RESPONSE
        ChatWorker->>Frontend: Publish stream_event
    end

    loop Later conversation load
        ChatWorker->>Database: load_conversation_history
        Database-->>ChatWorker: Raw messages list
        ChatWorker->>ChatWorker: _validate_and_filter_messages
        ChatWorker->>ChatWorker: Collect valid tool_call_ids from AIMessage.tool_calls
        ChatWorker->>ChatWorker: Filter ToolMessages
        ChatWorker-->>LangChain: Validated messages list
    end

Loading

Sequence diagram for LLM node message building with preserved BaseMessage

sequenceDiagram
    participant GraphBuilder
    participant llm_node
    participant State
    participant LLM

    GraphBuilder->>llm_node: Invoke with state
    alt state is BaseModel
        llm_node->>State: Access messages attribute
        State-->>llm_node: list[BaseMessage]
    else state is dict
        llm_node->>State: Get messages key
        State-->>llm_node: list[BaseMessage]
    end

    llm_node->>llm_node: Preserve BaseMessage instances
    llm_node->>llm_node: state_dict = _state_to_dict(state)
    llm_node->>llm_node: prompt = _render_template(prompt_template, state_dict)
    llm_node->>llm_node: llm_messages = messages + HumanMessage(prompt)
    llm_node->>LLM: ainvoke(llm_messages)
    LLM-->>llm_node: AIMessage (with tool_calls and tool_call_id)

Loading

Updated class diagram for LangChain message handling and validation

classDiagram
    class BaseMessage

    class HumanMessage {
        +content str
    }

    class AIMessage {
        +content str
        +tool_calls list
    }

    class ToolMessage {
        +content str
        +tool_call_id str
    }

    BaseMessage <|-- HumanMessage
    BaseMessage <|-- AIMessage
    BaseMessage <|-- ToolMessage

    class HistoryModule {
        +load_conversation_history(db, topic) list~BaseMessage~
        +_build_tool_messages(formatted_content, num_tool_calls) ToolMessage
        +_validate_and_filter_messages(messages) list~BaseMessage~
    }

    class ChatTasksModule {
        +_process_chat_message_async(...)
    }

    class GraphBuilderModule {
        +_build_llm_node(config) NodeFunction
        +_state_to_dict(state) dict
        +_render_template(prompt_template, state_dict) str
    }

    HistoryModule ..> AIMessage : uses
    HistoryModule ..> ToolMessage : builds and filters
    HistoryModule ..> BaseMessage : returns list

    ChatTasksModule ..> ToolMessage : persists as tool role
    ChatTasksModule ..> HistoryModule : history consumed later

    GraphBuilderModule ..> BaseMessage : reads messages
    GraphBuilderModule ..> HumanMessage : appends prompt
    GraphBuilderModule ..> AIMessage : receives from LLM

Loading

File-Level Changes

Change	Details	Files
Preserve LangChain BaseMessage objects when building LLM node messages so tool_call_id and other message-specific fields are not lost.	Stop relying on model_dump() / state-to-dict conversion to retrieve messages for LLM calls. Read messages directly from the StateDict/BaseModel prior to conversion, preserving BaseMessage instances. Construct llm_messages from the preserved messages plus a new HumanMessage with the rendered prompt.	service/app/agents/graph_builder.py
Validate and filter ToolMessages in loaded conversation history to ensure they have valid tool_call_id values and corresponding AIMessage tool_calls.	Introduce _validate_and_filter_messages to post-process loaded history. Collect all valid tool_call_ids from AIMessage.tool_calls before filtering. Drop ToolMessages with missing/invalid tool_call_id or without a matching AIMessage.tool_call, logging warnings and a final summary of filtered messages. Return the validated history instead of the raw list and adjust logging to show pre/post-validation counts.	service/app/core/chat/history.py
Validate toolCallId when persisting tool call responses to the database and avoid storing invalid entries while still streaming them to the frontend.	Extract toolCallId from the tool response and ensure it is a non-empty string before persistence. If toolCallId is invalid, log a warning, publish the event to the frontend, and skip DB persistence. When persisting, use the validated tool_call_id and default missing result fields to an empty string in the stored content payload.	service/app/tasks/chat.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - 我发现了 1 个问题，并给出了一些整体反馈：

• _validate_and_filter_messages 中对 AIMessage.tool_calls 的校验逻辑假定每个 tool_call 都是带有 id 的字典；如果 LangChain 将来在这里返回的是类型化对象，这里可能会静默失败——可以考虑对非字典类型的 tool_call 做更健壮的处理（例如通过 getattr 或 isinstance 检查）。
• _build_tool_messages 和 _process_chat_message_async 中重复的 tool_call_id/toolCallId 校验逻辑非常相似；可以考虑抽取一个小的共享 helper 来减少重复，并把规则集中在一个地方保持一致性。
• 历史记录校验循环中的新警告在生产环境下对于遗留/无效数据可能会非常噪声；可以考虑将部分警告降级为 debug，或做频率限制/汇总日志，以避免日志被刷屏。

给 AI Agents 的提示词

Please address the comments from this code review:

## Overall Comments
- The validation logic for AIMessage.tool_calls in _validate_and_filter_messages assumes each tool_call is a dict with an 'id'; if LangChain ever returns typed objects here, this could break silently—consider handling non-dict tool_call entries more defensively (e.g., via getattr or an isinstance check).
- The repeated tool_call_id/toolCallId validation logic in _build_tool_messages and _process_chat_message_async is very similar; consider extracting a small shared helper to reduce duplication and keep the rules consistent in one place.
- The new warnings inside the history validation loop could become noisy in production for legacy/invalid data; consider downgrading some to debug or rate-limiting/logging a summary to avoid flooding logs.

## Individual Comments

### Comment 1
<location> `service/app/agents/graph_builder.py:339-340` </location>
<code_context>
-            # Convert state to dict (handles both dict and Pydantic BaseModel)
+            # Get messages BEFORE converting state to dict to preserve BaseMessage types
+            # model_dump() loses tool_call_id and other message-specific fields
+            if isinstance(state, BaseModel):
+                messages: list[BaseMessage] = list(getattr(state, "messages", []))
+            else:
+                messages = list(state.get("messages", []))
</code_context>

<issue_to_address>
**issue:** 在调用 list() 之前要防止 state.messages 为 None，以避免 TypeError。

如果 `state.messages` / `state.get("messages")` 可能为 `None`，`list(None)` 会抛出 `TypeError`。可以考虑先做归一化处理，例如：

```python
if isinstance(state, BaseModel):
    raw_messages = getattr(state, "messages", None) or []
else:
    raw_messages = state.get("messages") or []
messages: list[BaseMessage] = list(raw_messages)
```

这样既保持了当前行为（拷贝并保留 `BaseMessage` 实例），又能在 messages 缺失或为 `None` 时避免运行时错误。
</issue_to_address>

---

Sourcery 对开源项目免费——如果你觉得我们的 Review 有帮助，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据这些反馈来改进后续的 Review。}

Original comment in English

Hey - I've found 1 issue, and left some high level feedback:

• The validation logic for AIMessage.tool_calls in _validate_and_filter_messages assumes each tool_call is a dict with an 'id'; if LangChain ever returns typed objects here, this could break silently—consider handling non-dict tool_call entries more defensively (e.g., via getattr or an isinstance check).
• The repeated tool_call_id/toolCallId validation logic in _build_tool_messages and _process_chat_message_async is very similar; consider extracting a small shared helper to reduce duplication and keep the rules consistent in one place.
• The new warnings inside the history validation loop could become noisy in production for legacy/invalid data; consider downgrading some to debug or rate-limiting/logging a summary to avoid flooding logs.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The validation logic for AIMessage.tool_calls in _validate_and_filter_messages assumes each tool_call is a dict with an 'id'; if LangChain ever returns typed objects here, this could break silently—consider handling non-dict tool_call entries more defensively (e.g., via getattr or an isinstance check).
- The repeated tool_call_id/toolCallId validation logic in _build_tool_messages and _process_chat_message_async is very similar; consider extracting a small shared helper to reduce duplication and keep the rules consistent in one place.
- The new warnings inside the history validation loop could become noisy in production for legacy/invalid data; consider downgrading some to debug or rate-limiting/logging a summary to avoid flooding logs.

## Individual Comments

### Comment 1
<location> `service/app/agents/graph_builder.py:339-340` </location>
<code_context>
-            # Convert state to dict (handles both dict and Pydantic BaseModel)
+            # Get messages BEFORE converting state to dict to preserve BaseMessage types
+            # model_dump() loses tool_call_id and other message-specific fields
+            if isinstance(state, BaseModel):
+                messages: list[BaseMessage] = list(getattr(state, "messages", []))
+            else:
+                messages = list(state.get("messages", []))
</code_context>

<issue_to_address>
**issue:** Guard against state.messages being None before calling list() to avoid TypeError.

If `state.messages`/`state.get("messages")` can be `None`, `list(None)` will raise a `TypeError`. Consider normalizing first, e.g.:

```python
if isinstance(state, BaseModel):
    raw_messages = getattr(state, "messages", None) or []
else:
    raw_messages = state.get("messages") or []
messages: list[BaseMessage] = list(raw_messages)
```

This keeps the current behavior (copying and preserving `BaseMessage` instances) while avoiding runtime errors when messages is missing or `None`.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue: 在调用 list() 之前要防止 state.messages 为 None，以避免 TypeError。

如果 state.messages / state.get("messages") 可能为 None，list(None) 会抛出 TypeError。可以考虑先做归一化处理，例如：

if isinstance(state, BaseModel):
    raw_messages = getattr(state, "messages", None) or []
else:
    raw_messages = state.get("messages") or []
messages: list[BaseMessage] = list(raw_messages)

这样既保持了当前行为（拷贝并保留 BaseMessage 实例），又能在 messages 缺失或为 None 时避免运行时错误。

Original comment in English

issue: Guard against state.messages being None before calling list() to avoid TypeError.

If state.messages/state.get("messages") can be None, list(None) will raise a TypeError. Consider normalizing first, e.g.:

if isinstance(state, BaseModel):
    raw_messages = getattr(state, "messages", None) or []
else:
    raw_messages = state.get("messages") or []
messages: list[BaseMessage] = list(raw_messages)

This keeps the current behavior (copying and preserving BaseMessage instances) while avoiding runtime errors when messages is missing or None.

[codecov]

Codecov Report

❌ Patch coverage is 2.43902% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
service/app/core/chat/history.py	3.12%	31 Missing ⚠️
service/app/tasks/chat.py	0.00%	5 Missing ⚠️
service/app/agents/graph_builder.py	0.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR fixes a KeyError: 'tool_call_id' issue that occurred when LangChain processed tool messages. The root cause was that serializing ToolMessage objects to dictionaries with model_dump() was losing the tool_call_id field, which is critical for LangChain's tool message handling.

Changes:

• Added validation to skip persisting tool responses with invalid toolCallId values
• Extracted messages before state serialization to preserve BaseMessage types and their fields
• Implemented filtering logic to remove invalid or orphaned ToolMessages from conversation history

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
service/app/tasks/chat.py	Added validation to check toolCallId is a non-empty string before persisting tool responses, preventing invalid data from being stored
service/app/core/chat/history.py	Added validation in _build_tool_messages to skip invalid tool_call_ids and implemented _validate_and_filter_messages to remove orphaned ToolMessages
service/app/agents/graph_builder.py	Modified to extract messages before calling model_dump() on state, preserving BaseMessage types and their tool_call_id fields

---

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

[Copilot]

The code creates a list copy three times: first at line 340/342 with list(...), then again at line 351 when building llm_messages. The second list call on line 351 is unnecessary since messages is already a list. Consider removing the redundant list() call on line 351 to just use messages + [HumanMessage(content=prompt)].

Suggested change

	llm_messages = list(messages) + [HumanMessage(content=prompt)]
	llm_messages = messages + [HumanMessage(content=prompt)]