Fix AddImageTool injection for multimodal Agent.kickoff (#3936)

[ProCO-RPHopkins]

Summary

This PR fixes how Agent.kickoff / kickoff_async behave when multimodal=True is set on the agent.

Right now, multimodal support (and AddImageTool) is wired up when an agent runs inside a Crew, but not when you call Agent.kickoff(...) directly. On top of that, tools were being appended to self.tools, so repeated calls could slowly grow the tool list.

With this change, multimodal tools like AddImageTool are also available when calling Agent.kickoff(...) and kickoff_async(...). The tools are built in a method-local list instead of modifying self.tools, and an existing AddImageTool on the agent is respected instead of being duplicated.

Fixes #3936.

Implementation details

The core of the change is a new private helper, Agent._get_tools_for_run().

That helper starts from a shallow copy of self.tools (if any), then adds platform tools from self.apps via get_platform_tools, and MCP tools from self.mcps via get_mcp_tools. When multimodal=True, it either calls get_multimodal_tools() on the agent (if that’s available) or falls back to injecting a single AddImageTool. A small set of tool types is used to avoid adding duplicate multimodal tools (including AddImageTool).

Both Agent.kickoff(...) and Agent.kickoff_async(...) now call _get_tools_for_run() and pass the resulting list into LiteAgent, so the sync and async paths stay aligned without duplicating logic. The goal is to keep the change small and easy to review while still cleaning up the behavior.

Tests

New tests live in lib/crewai/tests/agents/test_agent_kickoff_multimodal.py:

• test_agent_kickoff_multimodal_adds_add_image_tool_once
  Checks that a multimodal agent with no tools gets exactly one AddImageTool, even if kickoff is called multiple times.

• test_agent_kickoff_multimodal_does_not_duplicate_existing_add_image_tool
  Covers the case where the agent already has an AddImageTool and confirms kickoff doesn’t add another.

• test_agent_kickoff_async_multimodal_adds_add_image_tool_once
  Async version of the first test for kickoff_async.

• test_agent_kickoff_async_multimodal_does_not_duplicate_existing_add_image_tool
  Async version of the second test for kickoff_async.

• test_agent_kickoff_does_not_mutate_agent_tools
  Uses a _DummyTool plus multimodal=True to confirm that LiteAgent sees both the dummy tool and AddImageTool, while agent.tools still only contains the original dummy tool after kickoff.

All tests pass with:

uv run pytest lib/crewai/tests/agents/test_agent_kickoff_multimodal.py
uv run pytest lib/crewai/tests/test_crew.py -k multimodal

Pre-commit also passes on this branch with:

uv run pre-commit run ruff --all-files
uv run pre-commit run ruff-format --all-files
# mypy errors are known to be outside this change, no files touched in this PR

Notes

• This PR does not touch any of the crewai-tools code or external providers.
• The change is limited to crewai.agent.core.Agent and new tests under lib/crewai/tests/agents/.

---

Note

Make Agent.kickoff/kickoff_async build per-run tool lists (including multimodal) without mutating self.tools and without duplicates; add tests.

• Agent tool wiring
  • Build per-run tools_for_run from self.tools plus platform (get_platform_tools) and MCP (get_mcp_tools) tools.
  • When multimodal=True, add multimodal tools (e.g., AddImageTool) once, avoiding duplicate tool types across runs.
  • Do not mutate self.tools; pass tools_for_run to LiteAgent.
  • Ensure LiteAgent receives id=self.id in both sync and async paths.
• Tests (lib/crewai/tests/agents/test_agent_kickoff_multimodal.py)
  • Verify AddImageTool is injected exactly once for kickoff and kickoff_async.
  • Confirm no duplication when AddImageTool already present.
  • Ensure agent.tools is not mutated across runs.

^{Written by Cursor Bugbot for commit 9cd9f24. This will update automatically on new commits. Configure here.}

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[ProCO-RPHopkins]

No reported bugs - I’ve updated the async kickoff_async path to match the sync kickoff behavior more closely by passing id=self.id into LiteAgent and narrowing the AddImageTool import handling to except ImportError so it behaves the same way as the sync method. The multimodal tool wiring still uses a per-run tools_for_run list so self.tools isn’t mutated and AddImageTool isn’t duplicated across calls.

I re-ran the focused tests (pytest lib/crewai/tests/agents/test_agent_kickoff_multimodal.py and pytest lib/crewai/tests/test_crew.py -k multimodal) and they’re still green, and the ruff + ruff-format hooks pass on the updated file. Let me know if you’d like me to also follow up with a small refactor to de-duplicate the shared tool-building logic between sync and async in a separate PR.