Skip to content

Grok API

Grok Minions preserve xAI chat and response objects while completing client-side function calls.

grok

Assembly: minions Filename: grok.py Author: Terry D. Eppler Created: 09-05-2026

Last Modified By: Terry D. Eppler Last Modified On: 09-06-2026

 grok.py
 Copyright © 2026 Terry D. Eppler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You can contact me at: terryeppler@gmail.com or eppler.terry@epa.gov

xAI Grok Minion implementations.

Minion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Grok workflow agent backed by xAI client-side tool calling.

Initialize a Grok Minion.

Parameters:

Name Type Description Default
model str

Grok model identifier.

 required
instructions str

System instructions for the agent.

 required
tools Sequence[Tool] | None

Optional xAI tool schemas.

 None
functions Sequence[ToolFunction] | None

Optional matching tool callables.

 None
max_turns int

Maximum model turns per execution.

 10
api_key str | None

Optional xAI API key override.

 None
name str | None

Optional name overriding the implementation default.

 None

Returns:

Name Type Description
None None

Configuration and native clients are stored.
Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

validate_tools() -> None

Validate local schema-to-callable pairing.

Returns:

Name Type Description
None None

Local function pairs are validated and hosted tools are retained.
Source code in grok.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def validate_tools( self ) -> None:
    """Validate local schema-to-callable pairing.

    Returns:
        None: Local function pairs are validated and hosted tools are retained.
    """
    names = [ tool.function.name for tool in self.tools
        if tool.HasField( 'function' ) ]
    if len( names ) != len( set( names ) ):
        raise ValueError( 'Argument "tools" must contain unique function names!' )
    missing = sorted( set( names ).difference( self.functions ) )
    extra = sorted( set( self.functions ).difference( names ) )
    if missing or extra:
        raise ValueError(
            f'Grok tools and functions must match exactly; missing={missing}, extra={extra}!'
        )

create_chat(client: Client | AsyncClient) -> SyncChat | AsyncChat 

create_chat(client: Client) -> SyncChat

create_chat(client: AsyncClient) -> AsyncChat

Create an isolated provider-native chat.

Parameters:

Name Type Description Default
client Client | AsyncClient

xAI client used to create the chat.

 required

Returns:

Type Description
Chat | Chat

SyncChat | AsyncChat: Provider-native chat instance.
Source code in grok.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def create_chat( self, client: Client | AsyncClient ) -> SyncChat | AsyncChat:
    """Create an isolated provider-native chat.

    Args:
        client (Client | AsyncClient): xAI client used to create the chat.

    Returns:
        SyncChat | AsyncChat: Provider-native chat instance.
    """
    return client.chat.create(
        model=self.model,
        messages=[ system( self.instructions ) ],
        tools=self.tools or None,
    )

run(prompt: str) -> Response

Execute the complete Grok workflow synchronously.

Parameters:

Name Type Description Default
prompt str

User input for the workflow.

 required

Returns:

Name Type Description
Response Response

Final provider-native response.
Source code in grok.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def run( self, prompt: str ) -> Response:
    """Execute the complete Grok workflow synchronously.

    Args:
        prompt (str): User input for the workflow.

    Returns:
        Response: Final provider-native response.
    """
    throw_if( 'prompt', prompt )
    chat = self.create_chat( self.client )
    chat.append( user( prompt ) )
    for _ in range( self.max_turns ):
        response = chat.sample( )
        chat.append( response )
        self.result = response
        if not response.tool_calls:
            return response
        self.execute_tools( chat, response.tool_calls )
    raise RuntimeError( f'Grok workflow exceeded {self.max_turns} model turns!' )

run_async(prompt: str) -> Response async

Execute the complete Grok workflow asynchronously.

Parameters:

Name Type Description Default
prompt str

User input for the workflow.

 required

Returns:

Name Type Description
Response Response

Final provider-native response.
Source code in grok.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
async def run_async( self, prompt: str ) -> Response:
    """Execute the complete Grok workflow asynchronously.

    Args:
        prompt (str): User input for the workflow.

    Returns:
        Response: Final provider-native response.
    """
    throw_if( 'prompt', prompt )
    chat = self.create_chat( self.async_client )
    chat.append( user( prompt ) )
    for _ in range( self.max_turns ):
        response = await chat.sample( )
        chat.append( response )
        self.result = response
        if not response.tool_calls:
            return response
        await self.execute_tools_async( chat, response.tool_calls )
    raise RuntimeError( f'Grok workflow exceeded {self.max_turns} model turns!' )

stream(prompt: str) -> AsyncIterator[tuple[Response, Chunk]] async

Stream the complete Grok workflow across tool turns.

Parameters:

Name Type Description Default
prompt str

User input for the workflow.

 required

Yields:

Type Description
AsyncIterator[tuple[Response, Chunk]]

tuple[Response, Chunk]: Provider-native response and incremental chunk.
Source code in grok.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
async def stream( self, prompt: str ) -> AsyncIterator[ tuple[ Response, Chunk ] ]:
    """Stream the complete Grok workflow across tool turns.

    Args:
        prompt (str): User input for the workflow.

    Yields:
        tuple[Response, Chunk]: Provider-native response and incremental chunk.
    """
    throw_if( 'prompt', prompt )
    chat = self.create_chat( self.async_client )
    chat.append( user( prompt ) )
    for _ in range( self.max_turns ):
        response: Response | None = None
        async for response, chunk in chat.stream( ):
            self.result = response
            yield response, chunk
        if response is None:
            raise RuntimeError( 'Grok streaming returned no response!' )
        chat.append( response )
        if not response.tool_calls:
            return
        await self.execute_tools_async( chat, response.tool_calls )
    raise RuntimeError( f'Grok workflow exceeded {self.max_turns} model turns!' )

execute_tools(chat: SyncChat, tool_calls: Sequence[chat_pb2.ToolCall]) -> None

Execute and append synchronous tool results.

Parameters:

Name Type Description Default
chat Chat

Native chat receiving tool results.

 required
tool_calls Sequence[ToolCall]

Requested xAI tool calls.

 required

Returns:

Name Type Description
None None

Correlated results are appended to the chat.
Source code in grok.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
def execute_tools( self, chat: SyncChat,
        tool_calls: Sequence[ chat_pb2.ToolCall ] ) -> None:
    """Execute and append synchronous tool results.

    Args:
        chat (SyncChat): Native chat receiving tool results.
        tool_calls (Sequence[chat_pb2.ToolCall]): Requested xAI tool calls.

    Returns:
        None: Correlated results are appended to the chat.
    """
    for tool_call in tool_calls:
        function = self.functions.get( tool_call.function.name )
        if function is None:
            raise ValueError(
                f'Grok requested an unregistered tool: "{tool_call.function.name}"!'
            )
        arguments = self.parse_arguments( tool_call.function.arguments )
        output = function( **arguments )
        if isawaitable( output ):
            raise TypeError( f'Tool "{tool_call.function.name}" requires async execution!' )
        chat.append( tool_result(
            self.serialize_result( output ), tool_call_id=tool_call.id
        ) )

execute_tools_async(chat: AsyncChat, tool_calls: Sequence[chat_pb2.ToolCall]) -> None async

Execute and append asynchronous tool results.

Parameters:

Name Type Description Default
chat Chat

Native async chat receiving tool results.

 required
tool_calls Sequence[ToolCall]

Requested xAI tool calls.

 required

Returns:

Name Type Description
None None

Correlated results are appended to the chat.
Source code in grok.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
async def execute_tools_async( self, chat: AsyncChat,
        tool_calls: Sequence[ chat_pb2.ToolCall ] ) -> None:
    """Execute and append asynchronous tool results.

    Args:
        chat (AsyncChat): Native async chat receiving tool results.
        tool_calls (Sequence[chat_pb2.ToolCall]): Requested xAI tool calls.

    Returns:
        None: Correlated results are appended to the chat.
    """
    for tool_call in tool_calls:
        function = self.functions.get( tool_call.function.name )
        if function is None:
            raise ValueError(
                f'Grok requested an unregistered tool: "{tool_call.function.name}"!'
            )
        arguments = self.parse_arguments( tool_call.function.arguments )
        if iscoroutinefunction( function ):
            output = await function( **arguments )
        else:
            output = await asyncio.to_thread( function, **arguments )
            if isawaitable( output ):
                output = await output
        chat.append( tool_result(
            self.serialize_result( output ), tool_call_id=tool_call.id
        ) )

parse_arguments(arguments: str) -> dict[str, object] staticmethod

Parse and validate model-supplied JSON arguments.

Parameters:

Name Type Description Default
arguments str

JSON object supplied by Grok.

 required

Returns:

Type Description
dict[str, object]

dict[str, object]: Validated keyword arguments.
Source code in grok.py 
276
277
278
279
280
281
282
283
284
285
286
287
288
289
@staticmethod
def parse_arguments( arguments: str ) -> dict[ str, object ]:
    """Parse and validate model-supplied JSON arguments.

    Args:
        arguments (str): JSON object supplied by Grok.

    Returns:
        dict[str, object]: Validated keyword arguments.
    """
    values = json.loads( arguments )
    if not isinstance( values, dict ):
        raise TypeError( 'Tool arguments must be a JSON object!' )
    return values

serialize_result(result: object) -> str staticmethod

Serialize a local tool result.

Parameters:

Name Type Description Default
result object

Value returned by a tool.

 required

Returns:

Name Type Description
str str

Provider-compatible result content.
Source code in grok.py 
292
293
294
295
296
297
298
299
300
301
302
@staticmethod
def serialize_result( result: object ) -> str:
    """Serialize a local tool result.

    Args:
        result (object): Value returned by a tool.

    Returns:
        str: Provider-compatible result content.
    """
    return result if isinstance( result, str ) else json.dumps( result, default=str )

DataMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for data workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

GovernanceMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for governance workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

ResearchMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for research workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

CodingMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for software workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

WritingMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for writing workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

PlanningMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for planning workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

ComplianceMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for compliance, legal, and budget workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

BusinessMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for business, finance, and marketing workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

ImageGenerationMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for image-generation workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

ImageAnalysisMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for image-analysis workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

ImageEditingMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for image-editing workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

TranslationMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for translation workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

TranscriptionMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for transcription workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None

SpeechMinion(model: str, instructions: str, tools: Sequence[chat_pb2.Tool] | None = None, functions: Sequence[ToolFunction] | None = None, max_turns: int = 10, api_key: str | None = None, name: str | None = None)

Bases: Minion

Grok Minion specialized for speech workflows.

Source code in grok.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__( self, model: str, instructions: str,
        tools: Sequence[ chat_pb2.Tool ] | None=None,
        functions: Sequence[ ToolFunction ] | None=None, max_turns: int=10,
        api_key: str | None=None, name: str | None=None ) -> None:
    """Initialize a Grok Minion.

    Args:
        model (str): Grok model identifier.
        instructions (str): System instructions for the agent.
        tools (Sequence[chat_pb2.Tool] | None): Optional xAI tool schemas.
        functions (Sequence[ToolFunction] | None): Optional matching tool callables.
        max_turns (int): Maximum model turns per execution.
        api_key (str | None): Optional xAI API key override.
        name (str | None): Optional name overriding the implementation default.

    Returns:
        None: Configuration and native clients are stored.
    """
    throw_if( 'model', model )
    throw_if( 'instructions', instructions )
    if max_turns < 1:
        raise ValueError( 'Argument "max_turns" must be at least 1!' )
    self.name = name or self.minion_name
    throw_if( 'name', self.name )
    self.model = model
    self.instructions = instructions
    self.tools = list( tools or [ ] )
    function_list = list( functions or [ ] )
    self.functions = { function.__name__: function for function in function_list }
    if len( self.functions ) != len( function_list ):
        raise ValueError( 'Argument "functions" must contain unique names!' )
    self.validate_tools( )
    self.max_turns = max_turns
    self.api_key = api_key or os.getenv( 'XAI_API_KEY' )
    throw_if( 'api_key', self.api_key )
    self.client = Client( api_key=self.api_key )
    self.async_client = AsyncClient( api_key=self.api_key )
    self.result: Response | None = None