runTask

Runs an autonomous tool-use loop until the model's output matches `outputSchema`.

mindstudio.runTask({ prompt, input, tools, outputSchema, model, maxTurns?, maxToolOutputChars?, onEvent? }) → Promise<RunTaskResult>

Runs a multi-step, tool-use loop: the platform calls the model, executes the tool calls it requests, and feeds the results back until the output matches outputSchema, validated and repaired on every turn. A run that cannot converge on a valid shape rejects rather than returning malformed output. It runs slowly, so most callers invoke it without awaiting and write the result back when it resolves; cron and email triggers await it instead, since no session is left to catch a later failure. Give it a capable model and a tight schema, since both shape how well it stays on task. Each tool result is capped at maxToolOutputChars (50,000 characters of JSON by default); past the cap, the model gets a truncation record instead. Results are resent every turn, so a tool that pages or summarizes works better than a higher cap.

Parameters

prompt

string

RequiredSystem prompt defining the agent's behavior and approach.

input

object

RequiredStructured input for this run, passed as the user message.

tools

TaskToolConfig[]

RequiredThe tools the model may call: SDK action names, the app's own methods, and inline functions. See TaskToolConfig.

outputSchema

JsonObjectSchema

Plain JSON Schema for the output (type/properties/required/enum/items; nullable via type arrays, never nullable: true). Validated every turn with automatic repair; result.output is typed from it. Use this over structuredOutputExample.

structuredOutputExample

object | string

Legacy alternative to outputSchema: an example shape, unvalidated. Check parsedSuccessfully before using the output.

model

string

RequiredModel id for the loop (must support tool use). Ask askMindStudioSdk; MindStudio ids do not match vendor ids.

maxTurns

number

Max loop iterations before a final forced output. Default 20, max 100.

maxToolOutputChars

number

How much of each tool result reaches the model, in characters of its JSON. Default 50,000. A larger result is cut, and the model gets { truncated, totalChars, shownChars, content } instead.

onEvent

(e: TaskEvent) => void

Streaming callback. When set, the run streams events instead of polling.

threadId

string

Continue a prior thread's persisted state.

Research and enrich (schema mode, all three tool kinds)

const result = await mindstudio.runTask({
  prompt: 'Research this restaurant and save it. Write in a warm, plain voice.',
  input: { name },
  tools: [
    'searchGoogle',                                   // SDK action
    { method: 'generateImage', defaults: { imageModelOverride: { model: 'seedream-4.5' } } },
    { appMethod: 'saveRestaurant', description: 'Persist the researched restaurant, once, at the end.' },
    { name: 'checkExisting', description: 'Look up whether we already track this name.',
      inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
      execute: async (i) => Restaurants.findByName(String(i.name)) },
  ],
  outputSchema: {
    type: 'object',
    properties: { name: { type: 'string' }, url: { type: ['string', 'null'] }, photoUrl: { type: 'string' } },
    required: ['name', 'url', 'photoUrl'],
  },
  model: 'claude-5-sonnet',
});
result.output.name; // typed from the schema