box: Add searchoptions for BoxRetriever, documentation for BoxRetriever as agent tool (#26181)

Thank you for contributing to LangChain!

- [x] **PR title**: "package: description"
- Where "package" is whichever of langchain, community, core,
experimental, etc. is being modified. Use "docs: ..." for purely docs
changes, "templates: ..." for template changes, "infra: ..." for CI
changes.
  - Example: "community: add foobar LLM"


Added search options for BoxRetriever and added documentation to
demonstrate how to use BoxRetriever as an agent tool - @BoxPlatform


- [x] **Add tests and docs**: If you're adding a new integration, please
include
1. a test for the integration, preferably unit tests that do not rely on
network access,
2. an example notebook showing its use. It lives in
`docs/docs/integrations` directory.


- [x] **Lint and test**: Run `make format`, `make lint` and `make test`
from the root of the package(s) you've modified. See contribution
guidelines for more: https://python.langchain.com/docs/contributing/

Additional guidelines:
- Make sure optional dependencies are imported within a function.
- Please do not add dependencies to pyproject.toml files (even optional
ones) unless they are required for unit tests.
- Most PRs should not touch more than one package.
- Changes should be backwards compatible.
- If you are adding something to community, do not re-import it in
langchain.

If no one reviews your PR within a few days, please @-mention one of
baskaryan, efriis, eyurtsev, ccurme, vbarda, hwchase17.

libs/partners/box/langchain_box/retrievers/box.py

@@ -6,7 +6,7 @@ from langchain_core.retrievers import BaseRetriever
 from pydantic import ConfigDict, model_validator
 from typing_extensions import Self
 
-from langchain_box.utilities import BoxAuth, _BoxAPIWrapper
+from langchain_box.utilities import BoxAuth, BoxSearchOptions, _BoxAPIWrapper
 
 
 class BoxRetriever(BaseRetriever):
@@ -128,7 +128,10 @@ class BoxRetriever(BaseRetriever):
     """character_limit is an int that caps the number of characters to
        return per document."""
 
-    _box: Optional[_BoxAPIWrapper] = None
+    box_search_options: Optional[BoxSearchOptions] = None
+    """Search options to configure BoxRetriever to narrow search results."""
+
+    _box: Optional[_BoxAPIWrapper]
 
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
@@ -150,6 +153,7 @@ class BoxRetriever(BaseRetriever):
             box_developer_token=self.box_developer_token,
             box_auth=self.box_auth,
             character_limit=self.character_limit,
+            box_search_options=self.box_search_options,
         )
 
         self._box = _box