Task Agent

Run a configured task through the SDK and get back text or JSON you can trust, adding AI to a product feature without writing prompts: call a curated, versioned, observable skill from code.

Reach for it when you need:

• Synchronous AI APIs: quick, reliable responses inside a product feature.
• Deterministic contracts: predictable outputs shaped by a schema.
• Non-chat tasks: summaries, classification, extraction, or generation.

Both complete and streaming modes use the same call: foldspace.agent('AGENT-API-NAME').runTask(). Passing streamOptions switches it to streaming.

Parameters

Parameter	Type	Required	Description
taskKey	string	Yes	The unique identifier for the task you want to run.
data	string | object	Yes	The input payload for the task.
streamOptions	object	No	Enables streaming mode if provided.
cacheOptions	object	No	Configures caching behavior, such as defining a Time-To-Live (TTL) or forcing a fresh execution.

Complete mode

Call runTask() without streamOptions to wait for the server and resolve a Promise with the full result once the task finishes.

foldspace.agent('AGENT-API-NAME').runTask({
  taskKey: 'TASK-KEY',
  data: 'ANY-STRING-OR-OBJECT'
})
  .then((result) => {
    console.log('Task result:', result);
  })
  .catch((error) => {
    console.error('Task failed:', error);
  });

The resolved value depends on the task’s configured response type:

• string for TEXT response types.
• object for JSON response types.

Cache options

The optional cacheOptions object controls when cached results are used, when to force a fresh execution, and how long new results are cached. Caching behaves identically in both complete and streaming modes.

Property	Type	Default	Description
bypass	boolean	false	When true, the task executes fresh, ignoring any existing cached result.
ttlSeconds	number	21600 (6 hours)	How long to cache the new result, in seconds. Set to 0 to disable caching for the new result.

Behavior matrix

bypass	ttlSeconds	Result
Omitted / false	Omitted	Check cache. If executed, cache new result for 6 hours.
Omitted / false	300 (custom)	Check cache. If executed, cache new result for 5 minutes.
Omitted / false	0	Check cache. If executed, do not cache new result.
true	Omitted	Skip cache. Execute fresh & cache new result for 6 hours.
true	0	Skip cache. Execute fresh & cache new result for 6 hours.

Force a refresh

Ignore any cached value and run the task. The new result is cached for the default 6 hours.

foldspace.agent('AGENT-API-NAME').runTask({
  taskKey: 'SUMMARIZE_TASK',
  data: 'some long text...',
  cacheOptions: {
    bypass: true
  }
});

Skip caching the new result

Still check for an existing cached result, but if a new result is generated (for example, because no cache was found), don’t store it for future use.

foldspace.agent('AGENT-API-NAME').runTask({
  taskKey: 'SUMMARIZE_TASK',
  data: 'some long text...',
  cacheOptions: {
    ttlSeconds: 0
  }
});

Full-fresh, no-cache

Skip reading from the cache and prevent the new result from being stored.

foldspace.agent('AGENT-API-NAME').runTask({
  taskKey: 'SUMMARIZE_TASK',
  data: 'some long text...',
  cacheOptions: {
    bypass: true,
    ttlSeconds: 0
  }
});

Custom TTL with streaming

cacheOptions works the same in streaming mode. This caches the streamed result for 10 minutes (600 seconds).

foldspace.agent('AGENT-API-NAME').runTask({
  taskKey: 'LONG_STREAM_TASK',
  data: { prompt: 'Generate a story...' },

  // Cache this specific stream's result for 10 minutes
  cacheOptions: {
    ttlSeconds: 600
  },

  streamOptions: {
    onMessage: ({ textDelta }) => {
      // Append text to UI
    },
    onComplete: () => {
      console.log('Stream done and result is cached.');
    }
  }
});

Streaming mode

Provide a streamOptions object to receive incremental chunks as they become available, ideal for AI text generation, incremental updates, or long-running processes. Each chunk triggers onMessage, letting you render output progressively.

Note

Streaming mode is only supported for tasks configured with a TEXT response type. It is not compatible with JSON response types.

foldspace.agent('AGENT-API-NAME').runTask({
  taskKey: 'TASK-KEY',
  data: { input: "Hello, world" },
  streamOptions: {
    onStart: ({ id, abortStreamTask }) => {
      console.log('Stream started with ID:', id);
      // You can call abortStreamTask() to stop the stream at any time
    },
    onMessage: ({ textDelta, fullText, chunk }) => {
      console.log('New message chunk:', textDelta);
      console.log('Full accumulated text:', fullText);
    },
    onComplete: ({ fullText }) => {
      console.log('Stream completed:', fullText);
    },
    onError: (error) => {
      console.error('Stream error:', error);
    }
  }
});

streamOptions callbacks

Callback	Description	Parameters
onStart	Called when the stream begins.	{ id: string, abortStreamTask: () => void }
onMessage	Called for every data chunk received from the stream.	{ textDelta: string, fullText: string, chunk: object, id: string }
onComplete	Called once the stream ends (naturally or via abort).	{ textDelta?: string, fullText: string, chunk?: object, id?: string }
onError	Called if an error occurs during the stream.	(error: Error)

Aborting a stream manually

The onStart callback provides an abortStreamTask function. Store it and call it at any time to stop the stream from the client side, useful for “Stop Generation” buttons, handling user navigation, or enforcing a client-side timeout. Calling abortStreamTask() gracefully terminates the stream, and onComplete still fires.

// Store the abort function in a higher scope
let abortTask = null;

function startStream() {
  foldspace.agent('AGENT-API-NAME').runTask({
    taskKey: 'LONG_STREAM_TASK',
    data: { prompt: 'Generate a very long story...' },
    streamOptions: {
      onStart: ({ id, abortStreamTask }) => {
        console.log('Stream started:', id);
        // Store the function so it can be called by other elements
        abortTask = abortStreamTask;
      },
      onMessage: ({ textDelta }) => {
        console.log(textDelta); // Append text to UI
      },
      onComplete: ({ fullText }) => {
        console.log('Stream completed.');
        abortTask = null; // Clean up
      },
      onError: (err) => {
        console.error('Stream error:', err);
        abortTask = null; // Clean up
      },
    }
  });
}

// Imagine this is called by a "Stop" button click
function stopStream() {
  if (abortTask) {
    console.log('Manually aborting stream...');
    abortTask();
  }
}

Notes

• Run any registered agent API using its unique taskKey. Create and manage your task agents on the agent functions page.
• For long tasks, prefer streaming mode to get progressive feedback.
• Both modes use foldspace.agent('AGENT-API-NAME').runTask(): behavior changes based on whether streamOptions is provided.