feat(files): add files param to agent.kickoff() and async aliases

lib/crewai/tests/agents/test_lite_agent.py

@@ -829,3 +829,168 @@ def test_lite_agent_standalone_still_works():
     assert result is not None
     assert isinstance(result, LiteAgentOutput)
     assert result.raw is not None
+
+
+def test_agent_kickoff_with_files_parameter():
+    """Test that Agent.kickoff() accepts and passes files to the executor."""
+    from unittest.mock import MagicMock, Mock, patch
+
+    from crewai.types.usage_metrics import UsageMetrics
+
+    mock_llm = Mock(spec=LLM)
+    mock_llm.call.return_value = "Final Answer: I can see the file content."
+    mock_llm.stop = []
+    mock_llm.supports_stop_words.return_value = False
+    mock_llm.get_token_usage_summary.return_value = UsageMetrics(
+        total_tokens=100,
+        prompt_tokens=50,
+        completion_tokens=50,
+        cached_prompt_tokens=0,
+        successful_requests=1,
+    )
+
+    agent = Agent(
+        role="File Analyzer",
+        goal="Analyze files",
+        backstory="An agent that analyzes files",
+        llm=mock_llm,
+        verbose=False,
+    )
+
+    mock_file = MagicMock()
+    files = {"document.pdf": mock_file}
+
+    with patch.object(
+        agent, "_prepare_kickoff", wraps=agent._prepare_kickoff
+    ) as mock_prepare:
+        result = agent.kickoff(messages="Analyze the document", files=files)
+
+        mock_prepare.assert_called_once()
+        call_args = mock_prepare.call_args
+        assert call_args.args[0] == "Analyze the document"
+        assert call_args.kwargs.get("files") == files or call_args.args[2] == files
+
+    assert result is not None
+
+
+def test_prepare_kickoff_extracts_files_from_messages():
+    """Test that _prepare_kickoff extracts files from messages."""
+    from unittest.mock import MagicMock, Mock
+
+    from crewai.types.usage_metrics import UsageMetrics
+
+    mock_llm = Mock(spec=LLM)
+    mock_llm.call.return_value = "Final Answer: Done."
+    mock_llm.stop = []
+    mock_llm.supports_stop_words.return_value = False
+    mock_llm.get_token_usage_summary.return_value = UsageMetrics(
+        total_tokens=100,
+        prompt_tokens=50,
+        completion_tokens=50,
+        cached_prompt_tokens=0,
+        successful_requests=1,
+    )
+
+    agent = Agent(
+        role="Test Agent",
+        goal="Test files",
+        backstory="Test backstory",
+        llm=mock_llm,
+        verbose=False,
+    )
+
+    mock_file = MagicMock()
+    messages = [
+        {"role": "user", "content": "Analyze this", "files": {"img.png": mock_file}}
+    ]
+
+    executor, inputs, agent_info, parsed_tools = agent._prepare_kickoff(messages=messages)
+
+    assert "files" in inputs
+    assert "img.png" in inputs["files"]
+    assert inputs["files"]["img.png"] is mock_file
+
+
+def test_prepare_kickoff_merges_files_from_messages_and_parameter():
+    """Test that _prepare_kickoff merges files from messages and parameter."""
+    from unittest.mock import MagicMock, Mock
+
+    from crewai.types.usage_metrics import UsageMetrics
+
+    mock_llm = Mock(spec=LLM)
+    mock_llm.call.return_value = "Final Answer: Done."
+    mock_llm.stop = []
+    mock_llm.supports_stop_words.return_value = False
+    mock_llm.get_token_usage_summary.return_value = UsageMetrics(
+        total_tokens=100,
+        prompt_tokens=50,
+        completion_tokens=50,
+        cached_prompt_tokens=0,
+        successful_requests=1,
+    )
+
+    agent = Agent(
+        role="Test Agent",
+        goal="Test files",
+        backstory="Test backstory",
+        llm=mock_llm,
+        verbose=False,
+    )
+
+    msg_file = MagicMock()
+    param_file = MagicMock()
+    messages = [
+        {"role": "user", "content": "Analyze these", "files": {"from_msg.png": msg_file}}
+    ]
+    files = {"from_param.pdf": param_file}
+
+    executor, inputs, agent_info, parsed_tools = agent._prepare_kickoff(
+        messages=messages, files=files
+    )
+
+    assert "files" in inputs
+    assert "from_msg.png" in inputs["files"]
+    assert "from_param.pdf" in inputs["files"]
+    assert inputs["files"]["from_msg.png"] is msg_file
+    assert inputs["files"]["from_param.pdf"] is param_file
+
+
+def test_prepare_kickoff_param_files_override_message_files():
+    """Test that files parameter overrides files from messages with same name."""
+    from unittest.mock import MagicMock, Mock
+
+    from crewai.types.usage_metrics import UsageMetrics
+
+    mock_llm = Mock(spec=LLM)
+    mock_llm.call.return_value = "Final Answer: Done."
+    mock_llm.stop = []
+    mock_llm.supports_stop_words.return_value = False
+    mock_llm.get_token_usage_summary.return_value = UsageMetrics(
+        total_tokens=100,
+        prompt_tokens=50,
+        completion_tokens=50,
+        cached_prompt_tokens=0,
+        successful_requests=1,
+    )
+
+    agent = Agent(
+        role="Test Agent",
+        goal="Test files",
+        backstory="Test backstory",
+        llm=mock_llm,
+        verbose=False,
+    )
+
+    msg_file = MagicMock(name="msg_file")
+    param_file = MagicMock(name="param_file")
+    messages = [
+        {"role": "user", "content": "Analyze", "files": {"same.png": msg_file}}
+    ]
+    files = {"same.png": param_file}
+
+    executor, inputs, agent_info, parsed_tools = agent._prepare_kickoff(
+        messages=messages, files=files
+    )
+
+    assert "files" in inputs
+    assert inputs["files"]["same.png"] is param_file  # param takes precedence