Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
fix(agents): render message content parts as text, not a python repr (#7109)
João Moura6ad3bf939048
diff --git a/AGENTS.md b/AGENTS.mdindex d2f796c82..f744fdb3b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -14,6 +14,23 @@ Follow these guidelines when contributing:6. Follow software principles such as DRY and YAGNI.7. Keep diffs as minimal as possible.+## Message Content++`LLMMessage.content` is `str | list[dict[str, Any]] | None`; the list form is+multimodal content parts. Never `str()` it — that puts a Python repr+(`[{'type': 'text', 'text': 'hi'}]`) in front of the model and into memory.+Collapse a message to text with the helper instead:++```python+from crewai.utilities.agent_utils import message_content_text++text = message_content_text(msg) # "" for None; joined text for a parts list+```++Parts arrive from a model and are typed `dict[str, Any]`, so a `text` key that+is not a string is possible. `_content_parts_text` skips those blocks rather+than raising, and names a list with no usable text `[multimodal content]`.+## Changing Docs1. Edit MDX under `docs/edge/en/*` and reference it from `docs/docs.json` ifdiff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.pyindex f387d88be..0ac21743a 100644--- a/lib/crewai/src/crewai/agent/core.py+++ b/lib/crewai/src/crewai/agent/core.py@@ -97,6 +97,7 @@ from crewai.utilities.agent_utils import (get_tool_names,is_inside_event_loop,load_agent_from_repository,+ message_content_text,parse_tools,render_text_description_and_args,)@@ -1572,7 +1573,7 @@ class Agent(BaseAgent):# assistant's own replies were the user's.request_index = _request_index(carried)request = carried[request_index] if carried else None- formatted_messages = str(request.get("content") or "") if request else ""+ formatted_messages = message_content_text(request) if request else ""# Split, rather than one history list: the promoted request keeps# its position in the conversation. Sending everything before it# would hoist a trailing tool pair above the question it answers,@@ -1581,7 +1582,7 @@ class Agent(BaseAgent):history = carried[:request_index]trailing = carried[request_index + 1 :]recall_text = "\n".join(- str(msg.get("content", "")) for msg in carried if msg.get("content")+ message_content_text(msg) for msg in carried if msg.get("content"))# Only the request's attachments go on the current turn; a history# message keeps its own, so unioning them all would send prior@@ -1804,7 +1805,7 @@ class Agent(BaseAgent):else:input_str = ("\n".join(- str(msg.get("content", ""))+ message_content_text(msg)for msg in messagesif msg.get("content"))diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.pyindex 3d11ff290..6c0ea6bdc 100644--- a/lib/crewai/src/crewai/utilities/agent_utils.py+++ b/lib/crewai/src/crewai/utilities/agent_utils.py@@ -844,11 +844,40 @@ def _estimate_token_count(text: str) -> int:return len(text) // 4-def _message_content_text(msg: LLMMessage) -> str:- """Return the message content as text for token estimation."""+def _content_parts_text(content: list[dict[str, Any]]) -> str:+ """Text carried by a multimodal content-part list.++ Non-text blocks (images, audio) have no text to give, so a list with+ none of them is named rather than rendered -- ``str()`` on the list+ would put a Python repr in front of the model.++ Blocks are ``dict[str, Any]`` and arrive from a model, so a ``text``+ key that is not a string is possible; such a block carries no usable+ text and is skipped rather than joined, which would raise.+ """+ text_parts = [+ block["text"]+ for block in content+ if isinstance(block, dict)+ and block.get("type") == "text"+ and isinstance(block.get("text"), str)+ ]+ return " ".join(text_parts) if text_parts else "[multimodal content]"+++def message_content_text(msg: LLMMessage) -> str:+ """Return the message content as text.++ Used wherever a message has to collapse to a string -- token+ estimation, memory, and the one turn promoted into the executor+ prompt. Content is ``str | list[dict] | None``, and the list form is+ the multimodal one.+ """content = msg.get("content")if content is None:return ""+ if isinstance(content, list):+ return _content_parts_text(content)return str(content)@@ -866,7 +895,7 @@ def _split_text_by_token_limit(text: str, max_tokens: int) -> list[str]:def _expand_oversized_message(msg: LLMMessage, max_tokens: int) -> list[LLMMessage]:"""Split a message whose content alone exceeds max_tokens into sub-messages."""- msg_text = _message_content_text(msg)+ msg_text = message_content_text(msg)if _estimate_token_count(msg_text) <= max_tokens:return [msg]@@ -932,12 +961,7 @@ def _format_messages_for_summary(messages: list[LLMMessage]) -> str:else:content = ""elif isinstance(content, list):- text_parts = [- block.get("text", "")- for block in content- if isinstance(block, dict) and block.get("type") == "text"- ]- content = " ".join(text_parts) if text_parts else "[multimodal content]"+ content = _content_parts_text(content)if role == "assistant":label = "[ASSISTANT]:"@@ -976,7 +1000,7 @@ def _split_messages_into_chunks(current_tokens = 0for msg in normalized:- msg_tokens = _estimate_token_count(_message_content_text(msg))+ msg_tokens = _estimate_token_count(message_content_text(msg))if current_chunk and (current_tokens + msg_tokens) > max_tokens:chunks.append(current_chunk)diff --git a/lib/crewai/tests/agents/test_agent_kickoff_content_parts.py b/lib/crewai/tests/agents/test_agent_kickoff_content_parts.pynew file mode 100644index 000000000..096e0a030--- /dev/null+++ b/lib/crewai/tests/agents/test_agent_kickoff_content_parts.py@@ -0,0 +1,132 @@+"""A multimodal content-part list must reach the model as its text."""++from __future__ import annotations++import asyncio+from typing import Any+from unittest.mock import MagicMock++from crewai import Agent+from crewai.llms.base_llm import BaseLLM+++class _Recorder(BaseLLM):+ """Records the exact message list handed to the provider."""++ def __init__(self) -> None:+ super().__init__(model="recorder")+ object.__setattr__(self, "seen", [])++ def call(self, messages: Any, **kwargs: Any) -> str:+ self.seen.append(list(messages) if isinstance(messages, list) else messages)+ return "ok"++ async def acall(self, messages: Any, **kwargs: Any) -> str:+ return self.call(messages, **kwargs)++ def supports_function_calling(self) -> bool:+ return False++ def supports_stop_words(self) -> bool:+ return False++ def get_context_window_size(self) -> int:+ return 8192+++PARTS = [+ {"type": "text", "text": "what is in this photo"},+ {"type": "image_url", "image_url": {"url": "https://example/p.png"}},+]++IMAGE_ONLY = [{"type": "image_url", "image_url": {"url": "https://example/p.png"}}]+++def _agent(llm: _Recorder, **kwargs: Any) -> Agent:+ return Agent(role="Support", goal="help", backstory="b", llm=llm, **kwargs)+++def _request_text(seen: list[dict[str, Any]]) -> str:+ return str([m for m in seen if m.get("role") == "user"][-1]["content"])+++def test_the_promoted_request_carries_the_text_not_a_repr() -> None:+ """`str()` on the parts list put `[{'type': 'text', ...}]` in Current Task."""+ llm = _Recorder()+ _agent(llm).kickoff([{"role": "user", "content": PARTS}])++ text = _request_text(llm.seen[0])++ assert "what is in this photo" in text+ assert "'type'" not in text+ assert "image_url" not in text+++def test_the_async_path_agrees_with_the_sync_one() -> None:+ """`kickoff_async` shares `_prepare_kickoff`; assert it, don't assume it.++ Driven with ``asyncio.run`` rather than an async test: ``kickoff`` takes a+ different path when called from inside a running loop, so the sync half+ has to run outside one for the comparison to mean anything.+ """+ sync_llm = _Recorder()+ _agent(sync_llm).kickoff([{"role": "user", "content": PARTS}])++ async_llm = _Recorder()+ asyncio.run(_agent(async_llm).kickoff_async([{"role": "user", "content": PARTS}]))++ assert _request_text(async_llm.seen[0]) == _request_text(sync_llm.seen[0])+ assert "what is in this photo" in _request_text(async_llm.seen[0])+++def test_an_image_only_request_is_named_not_serialized() -> None:+ """No text block to promote, so the placeholder stands in for the repr."""+ llm = _Recorder()+ _agent(llm).kickoff([{"role": "user", "content": IMAGE_ONLY}])++ text = _request_text(llm.seen[0])++ assert "[multimodal content]" in text+ assert "example/p.png" not in text+++def test_history_keeps_its_parts_list_untouched() -> None:+ """Only the promoted turn collapses to text; the provider still gets parts."""+ llm = _Recorder()+ _agent(llm).kickoff(+ [+ {"role": "user", "content": PARTS},+ {"role": "assistant", "content": "a cat"},+ {"role": "user", "content": "and this one?"},+ ]+ )+ history = [m for m in llm.seen[0] if m.get("role") == "user"][0]++ assert history["content"] == PARTS+++def test_a_plain_string_request_is_unchanged() -> None:+ llm = _Recorder()+ _agent(llm).kickoff([{"role": "user", "content": "just text"}])++ assert "just text" in _request_text(llm.seen[0])+++def test_memory_recall_and_save_get_text_not_a_repr() -> None:+ """Both memory paths flattened the same way and stored the repr."""+ llm = _Recorder()+ memory = MagicMock()+ memory.recall.return_value = []+ memory.extract_memories.return_value = ["m"]++ agent = _agent(llm)+ object.__setattr__(agent, "memory", memory)+ agent.kickoff([{"role": "user", "content": PARTS}])++ recalled = memory.recall.call_args[0][0]+ assert "what is in this photo" in recalled+ assert "'type'" not in recalled++ saved = memory.extract_memories.call_args[0][0]+ assert "what is in this photo" in saved+ assert "'type'" not in saveddiff --git a/lib/crewai/tests/utilities/test_agent_utils.py b/lib/crewai/tests/utilities/test_agent_utils.pyindex ffca78c63..58dc28817 100644--- a/lib/crewai/tests/utilities/test_agent_utils.py+++ b/lib/crewai/tests/utilities/test_agent_utils.py@@ -24,7 +24,7 @@ from crewai.utilities.agent_utils import (_expand_oversized_message,_extract_summary_tags,_format_messages_for_summary,- _message_content_text,+ message_content_text,_normalize_messages_for_chunking,_split_messages_into_chunks,_split_text_by_token_limit,@@ -708,7 +708,7 @@ class TestSplitMessagesIntoChunks:assert len(chunks) > 1for chunk in chunks:chunk_tokens = sum(- _estimate_token_count(_message_content_text(msg)) for msg in chunk+ _estimate_token_count(message_content_text(msg)) for msg in chunk)assert chunk_tokens <= max_tokens@@ -723,7 +723,7 @@ class TestSplitMessagesIntoChunks:assert len(chunks) > 1for chunk in chunks:chunk_tokens = sum(- _estimate_token_count(_message_content_text(msg)) for msg in chunk+ _estimate_token_count(message_content_text(msg)) for msg in chunk)assert chunk_tokens <= max_tokens@@ -750,22 +750,57 @@ class TestSplitMessagesIntoChunks:class TestMessageContentText:- """Tests for _message_content_text helper."""+ """Tests for message_content_text helper."""def test_string_content(self) -> None:msg: dict[str, Any] = {"role": "user", "content": "hello"}- assert _message_content_text(msg) == "hello"+ assert message_content_text(msg) == "hello"def test_none_content(self) -> None:msg: dict[str, Any] = {"role": "assistant", "content": None}- assert _message_content_text(msg) == ""+ assert message_content_text(msg) == ""- def test_list_content_uses_str(self) -> None:+ def test_list_content_yields_its_text(self) -> None:+ """A parts list used to collapse to its Python repr."""msg: dict[str, Any] = {"role": "user",- "content": [{"type": "text", "text": "first"}],+ "content": [{"type": "text", "text": "first"}, {"type": "text", "text": "second"}],}- assert _message_content_text(msg) == str(msg["content"])+ assert message_content_text(msg) == "first second"++ @pytest.mark.parametrize(+ "bad_text", [123, None, {"nested": "x"}, ["a"]], ids=str+ )+ def test_a_non_string_text_block_does_not_raise(self, bad_text: Any) -> None:+ """Blocks are `dict[str, Any]` from a model, so `text` may be anything."""+ msg: dict[str, Any] = {+ "role": "user",+ "content": [{"type": "text", "text": bad_text}],+ }++ assert message_content_text(msg) == "[multimodal content]"++ def test_a_usable_text_block_survives_a_malformed_sibling(self) -> None:+ msg: dict[str, Any] = {+ "role": "user",+ "content": [+ {"type": "text", "text": {"nested": "x"}},+ {"type": "text", "text": "real text"},+ ],+ }++ assert message_content_text(msg) == "real text"++ def test_list_content_without_text_is_named_not_repr(self) -> None:+ msg: dict[str, Any] = {+ "role": "user",+ "content": [{"type": "image_url", "image_url": {"url": "https://x/y.png"}}],+ }++ text = message_content_text(msg)++ assert text == "[multimodal content]"+ assert "image_url" not in textclass TestSplitTextByTokenLimit:@@ -830,7 +865,7 @@ class TestExpandOversizedMessage:expanded = _expand_oversized_message(msg, max_tokens=max_tokens)assert len(expanded) > 1assert all(- _estimate_token_count(_message_content_text(part)) <= max_tokens+ _estimate_token_count(message_content_text(part)) <= max_tokensfor part in expanded)@@ -859,7 +894,7 @@ class TestNormalizeMessagesForChunking:assert normalized[-1]["content"] == "Done"assert len(normalized) > 3assert all(- _estimate_token_count(_message_content_text(msg)) <= max_tokens+ _estimate_token_count(message_content_text(msg)) <= max_tokensfor msg in normalized)