From 9a2cc348d945a931bc8a5be2feb2294bdf267a94 Mon Sep 17 00:00:00 2001 From: Francesco Cerizzi Date: Wed, 28 Jan 2026 17:58:11 +0100 Subject: [PATCH 1/3] feat: add xAI model provider documentation - Add comprehensive xAI/Grok model provider documentation - Include server-side tools (X search, web search, code execution) - Document reasoning models and hybrid tool usage - Add xAI to community model providers navigation Closes: strands-agents/sdk-python#1542 --- docs/community/model-providers/xai.md | 173 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 174 insertions(+) create mode 100644 docs/community/model-providers/xai.md diff --git a/docs/community/model-providers/xai.md b/docs/community/model-providers/xai.md new file mode 100644 index 00000000..be7d303b --- /dev/null +++ b/docs/community/model-providers/xai.md @@ -0,0 +1,173 @@ +--- +project: + pypi: https://pypi.org/project/strands-xai/ + github: https://github.com/Cerrix/strands-xai + maintainer: Cerrix +service: + name: xAI + link: https://x.ai/ +--- + +# xAI + +!!! info "Community Contribution" + This is a community-maintained package that is not owned or supported by the Strands team. Validate and review + the package before using it in your project. + + Have your own integration? [We'd love to add it here too!](https://github.com/strands-agents/docs/issues/new?assignees=&labels=enhancement&projects=&template=content_addition.yml&title=%5BContent+Addition%5D%3A+) + +!!! note "Language Support" + This provider is only supported in Python. + +[xAI](https://x.ai/) is an AI company that develops the Grok family of large language models designed to deliver truthful, insightful answers with advanced reasoning capabilities. The [`strands-xai`](https://pypi.org/project/strands-xai/) package ([GitHub](https://github.com/Cerrix/strands-xai)) provides a community-maintained integration for the Strands Agents SDK, enabling seamless use of xAI's Grok models with powerful server-side tools including real-time X platform access, web search, and code execution. + +## Installation + +xAI integration is available as a separate community package: + +```bash +pip install strands-agents strands-xai +``` + +## Usage + +After installing `strands-xai`, you can import and initialize the xAI provider: + +```python +from strands import Agent +from strands_xai import xAIModel + +model = xAIModel( + client_args={"api_key": "xai-key"}, # or set XAI_API_KEY env var + model_id="grok-4-1-fast-non-reasoning-latest", +) + +agent = Agent(model=model) +response = agent("What's trending on X right now?") +print(response.message) +``` + +## Configuration + +### Environment Variables + +```bash +export XAI_API_KEY="your-api-key" +``` + +### Model Configuration + +The supported configurations are: + +| Parameter | Description | Example | Default | +|-----------|-------------|---------|---------| +| `model_id` | Grok model identifier | `grok-4-1-fast-reasoning-latest` | `grok-4-1-fast-non-reasoning-latest` | +| `client_args` | xAI client arguments | `{"api_key": "xai-key"}` | `{}` | +| `params` | Model parameters dict | `{"temperature": 0.7}` | `{}` | +| `xai_tools` | Server-side tools list | `[web_search(), x_search()]` | `[]` | +| `reasoning_effort` | Reasoning level (grok-3-mini only) | `"high"` | `None` | +| `use_encrypted_content` | Enable encrypted reasoning | `True` | `False` | +| `include` | Optional features | `["inline_citations"]` | `[]` | + +**Model Parameters (in `params` dict):** +- `temperature` - Sampling temperature (0.0-2.0), default: varies by model +- `max_tokens` - Maximum tokens in response, default: 2048 +- `top_p` - Nucleus sampling parameter (0.0-1.0), default: varies by model +- `frequency_penalty` - Frequency penalty (-2.0 to 2.0), default: 0 +- `presence_penalty` - Presence penalty (-2.0 to 2.0), default: 0 + +**Available Models:** +- `grok-4-1-fast-reasoning` - Fast reasoning with encrypted thinking +- `grok-4-1-fast-non-reasoning` - Fast model without reasoning +- `grok-3-mini` - Compact model with visible reasoning +- `grok-3-mini-non-reasoning` - Compact model without reasoning +- `grok-4-1-reasoning` - Full reasoning capabilities +- `grok-4-1-non-reasoning` - Full model without reasoning +- `grok-code-fast-1` - Code-optimized model + +## Advanced Features + +### Server-Side Tools + +xAI models come with built-in server-side tools executed by xAI's infrastructure, providing unique capabilities: + +```python +from strands_xai import xAIModel +from strands import Agent +from xai_sdk.tools import web_search, x_search, code_execution + +# Server-side tools are automatically available +model = xAIModel( + client_args={"api_key": "xai-key"}, + model_id="grok-4-1-fast-reasoning-latest", + xai_tools=[web_search(), x_search(), code_execution()], +) + +agent = Agent(model=model) +# Model can autonomously use web_search, x_search, and code_execution tools +response = agent("Search X for recent AI developments and analyze the sentiment") +``` + +**Built-in Server-Side Tools:** +- **X Search**: Real-time access to X platform posts, trends, and conversations +- **Web Search**: Live web search capabilities across diverse data sources +- **Code Execution**: Python code execution for data analysis and computation + +### Real-Time X Platform Access + +Grok has exclusive real-time access to X platform data: + +```python +# Access real-time X data and trends +response = agent("What are people saying about the latest tech announcements on X?") + +# Analyze trending topics +response = agent("Find trending hashtags related to AI and summarize the discussions") +``` + +### Hybrid Tool Usage + +Combine xAI's server-side tools with your own Strands tools: + +```python +from strands import Agent, tool +from strands_xai import xAIModel +from xai_sdk.tools import x_search + +@tool +def calculate_engagement_rate(likes: int, retweets: int, followers: int) -> float: + """Calculate social media engagement rate.""" + return ((likes + retweets) / followers) * 100 + +model = xAIModel( + client_args={"api_key": "xai-key"}, + model_id="grok-4-1-fast-reasoning-latest", + xai_tools=[x_search()], +) + +agent = Agent(model=model, tools=[calculate_engagement_rate]) +response = agent("Search X for posts about AI and calculate engagement rates for top posts") +``` + +### Reasoning Models + +Access models with visible reasoning capabilities: + +```python +# Use reasoning model to see the thinking process +model = xAIModel( + client_args={"api_key": "xai-key"}, + model_id="grok-3-mini", # Shows reasoning steps + reasoning_effort="high", + params={"temperature": 0.3} +) + +agent = Agent(model=model) +response = agent("Analyze the current AI market trends based on X discussions") +``` + +## References + +- [strands-xai GitHub Repository](https://github.com/Cerrix/strands-xai) +- [xAI API Documentation](https://docs.x.ai/) +- [xAI Models and Pricing](https://docs.x.ai/docs/models) diff --git a/mkdocs.yml b/mkdocs.yml index a6955abe..0eea98be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -229,6 +229,7 @@ nav: - SGLang: community/model-providers/sglang.md - vLLM: community/model-providers/vllm.md - MLX: community/model-providers/mlx.md + - xAI: community/model-providers/xai.md - Session Managers: - Amazon AgentCore Memory: community/session-managers/agentcore-memory.md - Valkey/Redis: community/session-managers/strands-valkey-session-manager.md From 1255ba262fb4aadc89736907b7540b3914ca6a8a Mon Sep 17 00:00:00 2001 From: Francesco Cerizzi Date: Wed, 28 Jan 2026 18:05:01 +0100 Subject: [PATCH 2/3] docs: improve xAI documentation with better Strands tools examples - Add dedicated section showing normal Strands tools usage - Improve hybrid tool usage example with more practical tools - Highlight that xAI works with regular @tool decorators - Show combination of server-side and client-side capabilities --- docs/community/model-providers/xai.md | 61 ++++++++++++++++++++++++--- 1 file changed, 54 insertions(+), 7 deletions(-) diff --git a/docs/community/model-providers/xai.md b/docs/community/model-providers/xai.md index be7d303b..daf943f4 100644 --- a/docs/community/model-providers/xai.md +++ b/docs/community/model-providers/xai.md @@ -47,6 +47,37 @@ response = agent("What's trending on X right now?") print(response.message) ``` +### With Strands Tools + +You can use regular Strands tools just like with any other model provider: + +```python +from strands import Agent, tool +from strands_xai import xAIModel + +@tool +def calculate(expression: str) -> str: + """Evaluate a mathematical expression.""" + try: + result = eval(expression) + return f"Result: {result}" + except Exception as e: + return f"Error: {e}" + +@tool +def get_weather(city: str) -> str: + """Get the current weather for a city.""" + return f"Weather in {city}: Sunny, 22°C" + +model = xAIModel( + client_args={"api_key": "xai-key"}, + model_id="grok-4-1-fast-non-reasoning-latest", +) + +agent = Agent(model=model, tools=[calculate, get_weather]) +response = agent("What's 15 * 7 and what's the weather in Paris?") +``` + ## Configuration ### Environment Variables @@ -127,7 +158,7 @@ response = agent("Find trending hashtags related to AI and summarize the discuss ### Hybrid Tool Usage -Combine xAI's server-side tools with your own Strands tools: +Combine xAI's server-side tools with your own Strands tools for maximum flexibility: ```python from strands import Agent, tool @@ -135,20 +166,36 @@ from strands_xai import xAIModel from xai_sdk.tools import x_search @tool -def calculate_engagement_rate(likes: int, retweets: int, followers: int) -> float: - """Calculate social media engagement rate.""" - return ((likes + retweets) / followers) * 100 +def calculate(expression: str) -> str: + """Evaluate a mathematical expression.""" + try: + result = eval(expression) + return f"Result: {result}" + except Exception as e: + return f"Error: {e}" + +@tool +def get_weather(city: str) -> str: + """Get the current weather for a city.""" + return f"Weather in {city}: Sunny, 22°C" model = xAIModel( client_args={"api_key": "xai-key"}, model_id="grok-4-1-fast-reasoning-latest", - xai_tools=[x_search()], + xai_tools=[x_search()], # Server-side X search ) -agent = Agent(model=model, tools=[calculate_engagement_rate]) -response = agent("Search X for posts about AI and calculate engagement rates for top posts") +# Combine server-side and client-side tools +agent = Agent(model=model, tools=[calculate, get_weather]) +response = agent("Search X for AI news, calculate 15*7, and tell me the weather in Tokyo") ``` +This powerful combination allows the agent to: +- Search X platform in real-time (server-side) +- Perform calculations (client-side) +- Get weather information (client-side) +- All in a single conversation! + ### Reasoning Models Access models with visible reasoning capabilities: From 80c7096be7b8f8eb9de23bcac8e1db38b1432ad6 Mon Sep 17 00:00:00 2001 From: Cerrix Date: Fri, 30 Jan 2026 12:06:38 +0100 Subject: [PATCH 3/3] fix: doc improvements --- docs/community/model-providers/xai.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/community/model-providers/xai.md b/docs/community/model-providers/xai.md index daf943f4..7d81a541 100644 --- a/docs/community/model-providers/xai.md +++ b/docs/community/model-providers/xai.md @@ -19,7 +19,7 @@ service: !!! note "Language Support" This provider is only supported in Python. -[xAI](https://x.ai/) is an AI company that develops the Grok family of large language models designed to deliver truthful, insightful answers with advanced reasoning capabilities. The [`strands-xai`](https://pypi.org/project/strands-xai/) package ([GitHub](https://github.com/Cerrix/strands-xai)) provides a community-maintained integration for the Strands Agents SDK, enabling seamless use of xAI's Grok models with powerful server-side tools including real-time X platform access, web search, and code execution. +[xAI](https://x.ai/) is an AI company that develops the Grok family of large language models with advanced reasoning capabilities. The [`strands-xai`](https://pypi.org/project/strands-xai/) package ([GitHub](https://github.com/Cerrix/strands-xai)) provides a community-maintained integration for the Strands Agents SDK, enabling seamless use of xAI's Grok models with powerful server-side tools including real-time X platform access, web search, and code execution. ## Installation @@ -31,7 +31,10 @@ pip install strands-agents strands-xai ## Usage -After installing `strands-xai`, you can import and initialize the xAI provider: +After installing `strands-xai`, you can import and initialize the xAI provider. + +!!! note "API Key Required" + Ensure `XAI_API_KEY` is set in your environment, or pass it via `client_args={"api_key": "your-key"}`. ```python from strands import Agent