Task Agent API

Overview

Make your product AI-powered without prompts. Task Agent let you call curated LLM skills from code and receive text or JSON outputs you can trust, with versioning, tests, and observability built in.

When to Use Functions

• Synchronous AI APIs: quick, reliable responses for product features.
• Deterministic contracts: predictable outputs via schemas.
• Non-chat use cases: summaries, classification, extraction, or generation tasks.

Parameters

Basic Usage (Complete Task)

Use foldspace.agent('AGENT-API-NAME').runTask() to execute a task and receive the complete result as a Promise.

Example

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);
  });

Description

The complete (non-streaming) mode waits for the server response and returns the full result once the task finishes.

Returns

The returned Promise resolves with the complete output from the task. The data type depends on the task's configured response type.

• string (for TEXT response types)
• object (for JSON response types)

Streaming Mode

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

For real-time responses, such as AI text generation, incremental updates, or long-running processes, you can enable streaming by providing the streamOptions object.

Example

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);
    }
  }
});

Description

In streaming mode, the server sends incremental chunks of data as they become available. Each chunk triggers the onMessage callback, allowing you to process output progressively.

streamOptions Callbacks

Aborting a Stream Manually

The onStart callback provides an abortStreamTask function. You can store this function and call it at any time to manually stop the stream from the client side.

This is useful for implementing "Stop Generation" buttons, handling user navigation, or enforcing a client-side timeout. Calling abortStreamTask() will gracefully terminate the stream, and the onComplete callback will still be triggered.

Example Implementation:

// 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

• You can run any registered agent API using its unique taskKey. To create and manage your task agents, visit the agent functions page: https://app.foldspace.ai/agent/functions
• For long tasks, prefer streaming mode to get progressive feedback.
• Both modes use the same function: foldspace.agent('AGENT-API-NAME').runTask() — behavior changes depending on whether streamOptions is provided.