ContextQMD
Back to Fastmcp

run

docs/python-sdk/fastmcp-server-sampling-run.mdx

3.2.47.2 KB
Original Source

fastmcp.server.sampling.run

Sampling types and helper functions for FastMCP servers.

Functions

determine_handler_mode <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L139" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L198" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L251" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L361" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

python
prepare_tools(tools: Sequence[SamplingTool | FunctionTool | TransformedTool | Callable[..., Any]] | None) -> list[SamplingTool] | None

Convert tools to SamplingTool objects.

Accepts SamplingTool instances, FunctionTool instances, TransformedTool instances, or plain callable functions. FunctionTool and TransformedTool are converted using from_callable_tool(), while plain functions use from_function().

Args:

  • tools: Sequence of tools to prepare. Can be SamplingTool, FunctionTool, TransformedTool, or plain callable functions.

Returns:

  • List of SamplingTool instances, or None if tools is None.

extract_tool_calls <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L416" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L428" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L464" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L581" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L61" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L76" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L86" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L93" 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/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L106" 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.