runTask

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

mindstudio.runTask({ prompt, input, tools, outputSchema, model, maxTurns?, 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.

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.

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