Skip to content

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.md
index 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 Docs
1. Edit MDX under `docs/edge/en/*` and reference it from `docs/docs.json` if
diff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.py
index 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 messages
if msg.get("content")
)
diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.py
index 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 = 0
for 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.py
new file mode 100644
index 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 saved
diff --git a/lib/crewai/tests/utilities/test_agent_utils.py b/lib/crewai/tests/utilities/test_agent_utils.py
index 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) > 1
for 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) > 1
for 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 text
class TestSplitTextByTokenLimit:
@@ -830,7 +865,7 @@ class TestExpandOversizedMessage:
expanded = _expand_oversized_message(msg, max_tokens=max_tokens)
assert len(expanded) > 1
assert all(
- _estimate_token_count(_message_content_text(part)) <= max_tokens
+ _estimate_token_count(message_content_text(part)) <= max_tokens
for part in expanded
)
@@ -859,7 +894,7 @@ class TestNormalizeMessagesForChunking:
assert normalized[-1]["content"] == "Done"
assert len(normalized) > 3
assert all(
- _estimate_token_count(_message_content_text(msg)) <= max_tokens
+ _estimate_token_count(message_content_text(msg)) <= max_tokens
for msg in normalized
)