feat(xai): Add comprehensive tests and docs for agentic tool calling API

[KushagraaWadhwa]

Description

Adds comprehensive test coverage and documentation for X.AI's agentic tool calling API support in langchain-xai.

X.AI is deprecating the Live Search API by December 15, 2025 in favor of the new agentic tool calling API (docs). While the server_tools parameter already provides support for this feature, it lacked test coverage and documentation visibility, leading to user confusion.

Issue: Closes #33961

Changes

🧪 Test Coverage Added

Unit Tests (tests/unit_tests/test_chat_models.py):

• test_server_tools_param(): Validates server_tools parameter handling
• test_server_tools_and_search_parameters_conflict(): Ensures both APIs can't be used together
• test_search_parameters_deprecation_warning(): Verifies deprecation warnings

Integration Tests (tests/integration_tests/test_chat_models.py):

• test_server_tools_web_search(): Tests autonomous web search
• test_server_tools_x_search(): Tests X (Twitter) search
• test_server_tools_code_execution(): Tests code execution capability
• test_server_tools_multiple(): Tests using multiple tools simultaneously

📚 Documentation Enhancements

• Enhanced ChatXAI docstring with comprehensive agentic tool calling examples
• Added deprecation notices for search_parameters API
• Added validation to prevent using both old and new APIs simultaneously
• Added deprecation warnings with clear migration path
• Updated README with migration notice and quick examples

🔧 Code Quality

• Fixed import linting errors (PLC0415, I001)
• Properly sorted imports into standard groups

Migration Example

# Old (deprecated - remove by Dec 15, 2025)
model = ChatXAI(
    model="grok-4",
    search_parameters={"mode": "auto"},
)

# New (recommended)
model = ChatXAI(
    model="grok-4",
    server_tools=[{"type": "web_search"}],
)

# Multiple tools
model = ChatXAI(
    model="grok-4",
    server_tools=[
        {"type": "web_search"},
        {"type": "x_search"},
        {"type": "code_execution"},
    ],
)

Available Server Tools

• web_search: Autonomous web search for current information
• x_search: Search posts on X (formerly Twitter)
• code_execution: Execute code to solve complex problems

Dependencies

None - no new dependencies added.

Testing

cd libs/partners/xai
make format  # ✅ Passed
make lint    # ✅ Passed
make test    # ✅ Passed

All tests pass locally and are backwards compatible.

Breaking Changes

None - this PR is fully backward compatible. The old search_parameters API continues to work with deprecation warnings.

[codspeed-hq]

CodSpeed Performance Report

Merging #33967 will not alter performance

_{Comparing KushagraaWadhwa:feat/xai-agentic-tools-clean (06a288a) with master (8a3bb73)}

Summary

✅ 1 untouched
⏩ 33 skipped¹

Footnotes

1. 33 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[hyacinthus]

Thanks for this PR. I noticed that XAI should proactively unify API with OpenAI. However, in the LangChain integration, server_tools differs from OpenAI. The OpenAI package directly shares the bind_tools method. Is the OpenAI package also preparing for migration? If not, I think it's best to unify the behavior of both.