mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-14 01:29:10 +02:00
a1cf2aff6eCo-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>
192 lines
6.7 KiB
Text
192 lines
6.7 KiB
Text
---
|
|
title: run
|
|
sidebarTitle: run
|
|
---
|
|
|
|
# `fastmcp.server.sampling.run`
|
|
|
|
|
|
Sampling types and helper functions for FastMCP servers.
|
|
|
|
## Functions
|
|
|
|
### `determine_handler_mode` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
determine_handler_mode(context: Context, needs_tools: bool) -> bool
|
|
```
|
|
|
|
|
|
Determine whether to use fallback handler or client for sampling.
|
|
|
|
**Args:**
|
|
- `context`: The MCP context.
|
|
- `needs_tools`: Whether the sampling request requires tool support.
|
|
|
|
**Returns:**
|
|
- True if fallback handler should be used, False to use client.
|
|
|
|
**Raises:**
|
|
- `ValueError`: If client lacks required capability and no fallback configured.
|
|
|
|
|
|
### `call_sampling_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
call_sampling_handler(context: Context, messages: list[SamplingMessage]) -> CreateMessageResult | CreateMessageResultWithTools
|
|
```
|
|
|
|
|
|
Make LLM call using the fallback handler.
|
|
|
|
Note: This function expects the caller (sample_step) to have validated that
|
|
sampling_handler is set via determine_handler_mode(). The checks below are
|
|
safeguards against internal misuse.
|
|
|
|
|
|
### `execute_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L240" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
execute_tools(tool_calls: list[ToolUseContent], tool_map: dict[str, SamplingTool], mask_error_details: bool = False, tool_concurrency: int | None = None) -> list[ToolResultContent]
|
|
```
|
|
|
|
|
|
Execute tool calls and return results.
|
|
|
|
**Args:**
|
|
- `tool_calls`: List of tool use requests from the LLM.
|
|
- `tool_map`: Mapping from tool name to SamplingTool.
|
|
- `mask_error_details`: If True, mask detailed error messages from tool execution.
|
|
When masked, only generic error messages are returned to the LLM.
|
|
Tools can explicitly raise ToolError to bypass masking when they want
|
|
to provide specific error messages to the LLM.
|
|
- `tool_concurrency`: Controls parallel execution of tools\:
|
|
- None (default)\: Sequential execution (one at a time)
|
|
- 0\: Unlimited parallel execution
|
|
- N > 0\: Execute at most N tools concurrently
|
|
If any tool has sequential=True, all tools execute sequentially
|
|
regardless of this setting.
|
|
|
|
**Returns:**
|
|
- List of tool result content blocks in the same order as tool_calls.
|
|
|
|
|
|
### `prepare_messages` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L350" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
prepare_messages(messages: str | Sequence[str | SamplingMessage]) -> list[SamplingMessage]
|
|
```
|
|
|
|
|
|
Convert various message formats to a list of SamplingMessage objects.
|
|
|
|
|
|
### `prepare_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
prepare_tools(tools: Sequence[SamplingTool | Callable[..., Any]] | None) -> list[SamplingTool] | None
|
|
```
|
|
|
|
|
|
Convert tools to SamplingTool objects.
|
|
|
|
|
|
### `extract_tool_calls` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L388" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
extract_tool_calls(response: CreateMessageResult | CreateMessageResultWithTools) -> list[ToolUseContent]
|
|
```
|
|
|
|
|
|
Extract tool calls from a response.
|
|
|
|
|
|
### `create_final_response_tool` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
create_final_response_tool(result_type: type) -> SamplingTool
|
|
```
|
|
|
|
|
|
Create a synthetic 'final_response' tool for structured output.
|
|
|
|
This tool is used to capture structured responses from the LLM.
|
|
The tool's schema is derived from the result_type.
|
|
|
|
|
|
### `sample_step_impl` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L436" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
sample_step_impl(context: Context, messages: str | Sequence[str | SamplingMessage]) -> SampleStep
|
|
```
|
|
|
|
|
|
Implementation of Context.sample_step().
|
|
|
|
Make a single LLM sampling call. This is a stateless function that makes
|
|
exactly one LLM call and optionally executes any requested tools.
|
|
|
|
|
|
### `sample_impl` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
sample_impl(context: Context, messages: str | Sequence[str | SamplingMessage]) -> SamplingResult[ResultT]
|
|
```
|
|
|
|
|
|
Implementation of Context.sample().
|
|
|
|
Send a sampling request to the client and await the response. This method
|
|
runs to completion automatically, executing a tool loop until the LLM
|
|
provides a final text response.
|
|
|
|
|
|
## Classes
|
|
|
|
### `SamplingResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L52" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
|
|
Result of a sampling operation.
|
|
|
|
**Attributes:**
|
|
- `text`: The text representation of the result (raw text or JSON for structured).
|
|
- `result`: The typed result (str for text, parsed object for structured output).
|
|
- `history`: All messages exchanged during sampling.
|
|
|
|
|
|
### `SampleStep` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
|
|
Result of a single sampling call.
|
|
|
|
Represents what the LLM returned in this step plus the message history.
|
|
|
|
|
|
**Methods:**
|
|
|
|
#### `is_tool_use` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
is_tool_use(self) -> bool
|
|
```
|
|
|
|
True if the LLM is requesting tool execution.
|
|
|
|
|
|
#### `text` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
text(self) -> str | None
|
|
```
|
|
|
|
Extract text from the response, if available.
|
|
|
|
|
|
#### `tool_calls` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L97" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
tool_calls(self) -> list[ToolUseContent]
|
|
```
|
|
|
|
Get the list of tool calls from the response.
|
|
|