STstreamkap
Agents

Test Run Agent

Changed on

Run an agent against a single sample record without deploying to Flink.

Synchronous, hard-capped at 15s wall-clock. Calls the LLM provider directly and runs MCP and HTTP tools live; transform tools and memory are not exercised (they exist only in the deployed Flink runtime). Per-tenant rate limit: shares the validate-llm budget (30 req/min/tenant) -> 429.

Provider failures (timeouts, schema errors, unsupported provider) are returned as a structured error object on the response (HTTP still 200), alongside the partial timeline. Only exceeding the input-token cap returns 422, because the run cannot start.

post/agents/test-run

Request

Request body

sampleRecordobject required

One Kafka-shaped record to feed the agent

agentIdstring nullable

Id of a saved agent. When set, an empty or masked apiKey in config is replaced server-side with that agent's stored key. Needed for agents saved with an inline key rather than an llmConnectionId.

savedConnectionIdstring nullable

Mirror of the ValidateLlmRequest.savedConnectionId path.

skipToolsboolean

When true, every MCP / HTTP tool dispatch returns a canned {skipped: true} payload to the LLM. Use to iterate on prompt shape without burning real tool calls.

Response

Successful Response

finalOutputunknown
stoppedReason'completed' | 'max_iterations' | 'error' | 'timeout' required
iterationsUsedinteger required
tokensIninteger required
tokensOutinteger required
durationMsinteger required
approximationsstring[]

Free-form list of caveats, e.g. 'memory_excluded', 'transforms_skipped'.

systemPromptstring nullable

Composed system prompt the LLM actually received - base template + auto-injected schema fields + tool descriptions + customInstructions. Identical to the prompt the deployed agent uses. Null when the run errored before reaching the LLM (e.g. llm_resolution_error).

userMessagestring nullable

First user message dispatched to the LLM, after the prompts.user template wraps the (input-fields-filtered) sample record. Lets the test pane show the exact pair of strings the LLM saw on iteration 1. Null when the run errored before message construction.

Changes