Documentation / @agentick/mcp / SampleAPI
Interface: SampleAPI
Defined in: protocol/types.ts:710
Sugar surface exposed at MCPHandlerContext.sample (undefined when the client did not advertise sampling). Wraps MCPServer.requestSampling() with typed shortcuts and capability gating.
Methods
audio()
audio(
opts):Promise<{data:string;mimeType:string; }>
Defined in: protocol/types.ts:734
Audio generation hint. Throws if response has no audio content block.
Parameters
opts
prompt
string
voice?
string
Returns
Promise<{ data: string; mimeType: string; }>
canIncludeContext()
canIncludeContext():
boolean
Defined in: protocol/types.ts:765
Returns
boolean
canSampleAudio()
canSampleAudio():
boolean
Defined in: protocol/types.ts:764
Returns
boolean
canUseTools()
canUseTools():
boolean
Defined in: protocol/types.ts:763
Capability probes.
Returns
boolean
image()
image(
opts):Promise<{data:string;mimeType:string; }>
Defined in: protocol/types.ts:727
Image generation hint. Throws if response has no image content block.
Parameters
opts
prompt
string
size?
"256x256" | "512x512" | "1024x1024"
style?
string
Returns
Promise<{ data: string; mimeType: string; }>
message()
message(
params):Promise<SamplingResult>
Defined in: protocol/types.ts:715
Multi-turn with full control. Returns the raw SamplingResult.
Parameters
params
Returns
Promise<SamplingResult>
structured()
structured<
T>(prompt,opts):Promise<T>
Defined in: protocol/types.ts:721
Structured output via Zod schema. Re-prompts on JSON parse / Zod validation failure up to maxRetries (default 2).
Type Parameters
T
T
Parameters
prompt
string
opts
object & SamplingTextOpts
Returns
Promise<T>
text()
text(
prompt,opts?):Promise<string>
Defined in: protocol/types.ts:712
Simplest: prompt in, text out. Single-turn.
Parameters
prompt
string
opts?
Returns
Promise<string>
withTools()
withTools<
T>(opts):Promise<{finalText:string;toolCalls:object[]; }>
Defined in: protocol/types.ts:744
Tool-use sampling — runs the spec-defined loop: model emits tool_use blocks → server invokes registered handlers → packages tool_result blocks (tool-results-only message constraint per spec) → feeds back. Bounded by maxIterations (default 8).
Throws when client did not advertise sampling.tools.
Type Parameters
T
T = unknown
Parameters
opts
maxIterations?
number
maxTokens?
number
modelPreferences?
prompt
string
systemPrompt?
string
toolChoice?
"auto" | "none" | "required"
tools
object[]
Returns
Promise<{ finalText: string; toolCalls: object[]; }>