feat: client-side support for SEP-1577 sampling with tools by jlowin · Pull Request #1722 · modelcontextprotocol/python-sdk
SEP-1577 added tool calling support to sampling (via #1594). This PR adds the necessary client-side support:
- Capability advertisement: The spec requires servers to error when
toolsortoolChoiceare provided butclientCapabilities.sampling.toolsis missing. The SDK's types already support this, butClientSessionhad no way to advertise it—servers would always see the capability as missing and error. This adds asampling_capabilitiesparameter. If not provided, the previous logic applies: the presence of asampling_callbackenables basic sampling support without tools.
session = ClientSession( read_stream, write_stream, sampling_callback=my_callback, sampling_capabilities=SamplingCapability( tools=SamplingToolsCapability() ), )
- Return type for tool responses: When tools are provided in a sampling request, the LLM may respond with tool calls, requiring
CreateMessageResultWithTools(which supports array content). TheSamplingFnTcallback andClientResultTypedidn't include this type, so the client's response validation would reject it before it could be sent back to the server. This addsCreateMessageResultWithToolsto both.
FWIW, with these changes we have full agentic sampling wired up in a branch of FastMCP, which is extremely exciting!