fal Agent SDK for JavaScript and TypeScript

The fal Agent SDK connects your JavaScript or TypeScript application to fal Agent. Describe a task in natural language to generate images, video, audio, or 3D media through the fal model catalog. The agent chooses models, prepares prompts, and executes the task. Use the Agent SDK when your application needs the agent to coordinate a task across multiple steps. It supports conversations, editable plans, user approvals, and generated media. For a direct call to a specific model, use the fal model clients instead.

The Agent SDK is in alpha. These examples use @fal-ai/client@1.11.0-alpha.4. Media generation can incur charges. See Access and pricing.

Install the SDK

The Agent SDK is part of the @fal-ai/client npm package. It supports JavaScript and includes TypeScript types for requests, responses, and resources. Use Node.js 22.22 or later for these examples. See client configuration for runtime requirements.

npm install @fal-ai/client@1.11.0-alpha.4

yarn add @fal-ai/client@1.11.0-alpha.4

pnpm add @fal-ai/client@1.11.0-alpha.4

Python support

The Agent SDK currently supports JavaScript and TypeScript. The fal Python client supports direct model calls. It does not provide the Agent SDK methods for conversations, plans, or approvals.

Authentication

Create a fal API key with the AGENT permission preset. Set the key in your environment:

export FAL_KEY="YOUR_API_KEY"

Replace YOUR_API_KEY with your key. The SDK reads FAL_KEY when you omit credentials. Keep the API key on your server. For a browser application, use a server endpoint that enforces your users’ permissions. See browser applications.

Generate media

Use agent.run() to submit a task and wait for its result. The agent creates a response that contains the task status, assistant text, generated media, and any questions or approvals. An artifact identifies generated media and can contain files with download URLs. Create agent.mts:

import { createFalClient } from "@fal-ai/client";

const agent = createFalClient().agent;

const response = await agent.run(
  { input: "Generate a product photo of a blue ceramic mug." },
  { timeoutMs: 5 * 60 * 1000 },
);

console.log(response.id, response.status, response.output_text);
console.log(response.pending_inputs, response.error);

for (const artifact of response.artifacts) {
  for (const file of artifact.files ?? []) {
    console.log(file.url);
  }
}

Install tsx to execute the TypeScript example:

npm install --save-dev tsx
npx tsx agent.mts

run() returns when execution stops or needs user input. Check the response before you use its media:

Field	Purpose
`status`	Reports the task’s execution state.
`output_text`	Contains the assistant’s text.
`artifacts`	Contains generated media and optional files with URLs.
`pending_inputs`	Contains questions and approvals that need the user’s answer.

Execution failures appear in response.status and response.error. Request failures throw AgentRequestError. See errors and troubleshooting for failure and recovery details. See media and costs to reuse media or select final results.

SDK methods

Use these methods to submit tasks and control their execution:

SDK method	Purpose
`agent.run()`	Submit a new task and poll until execution stops.
`agent.stream()`	Submit a new task and stream progress.
`agent.responses.create()`	Submit a new task. Return its initial response.
`agent.responses.retrieve()`	Read the current state of an existing task.
`agent.responses.wait()`	Poll an existing task until execution stops.
`agent.responses.stream()`	Stream an existing task.
`agent.responses.answer()`	Answer a question or approval for an existing task.
`agent.responses.cancel()`	Request cancellation of an existing task.

See the method reference for all methods and the type reference for their types.

Progress and user input

Stream progress

Use agent.stream() to start a task with progress updates:

import { createFalClient } from "@fal-ai/client";

const agent = createFalClient().agent;

for await (const response of agent.stream(
  { input: "Generate a product photo of a blue ceramic mug." },
  { timeoutMs: 5 * 60 * 1000 },
)) {
  console.log(response.status, response.output_text);
  console.log(response.artifacts, response.pending_inputs);
}

This example creates a new task. Use responses.stream(responseId) to observe a task that already exists. Each update contains the complete response state, called a snapshot. Replace the displayed state on each update. Do not append each snapshot’s output_text to the previous text.

Questions and approvals

The agent can pause to ask a question or request approval. When pending_inputs contains a request, show it to the user. Collect the user’s answer. Submit the answer with responses.answer() and the same response ID. Then resume observation with responses.wait() or responses.stream(). See questions and approvals for answer formats and examples.

Recovery and cancellation

Save the response ID to reconnect after a process restart, timeout, or lost connection. Use responses.wait() or responses.stream() with that ID to observe the existing task. For an application that stores task state, submit the task with responses.create(). Save the response ID. Then call responses.wait() or responses.stream(). See responses and recovery for submission retries and reconnection options.

A timeout, an aborted signal, or a closed stream does not cancel server execution. Use responses.cancel() to request cancellation of the task.

Next steps

Use the quickstart to run your first task.
Configure credentials, transport, and retries with client configuration.
Control a task’s steps with plans.
Organize tasks with conversations and projects.
Add reusable instructions with skills.
Display execution progress with tool activity.
Find integration guides in guidance for coding agents.

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

fal Agent SDK for JavaScript and TypeScript

Install the SDK

Python support

Authentication

Generate media

SDK methods

Progress and user input

Stream progress

Questions and approvals

Recovery and cancellation

Next steps

​Install the SDK

​Python support

​Authentication

​Generate media

​SDK methods

​Progress and user input

​Stream progress

​Questions and approvals

​Recovery and cancellation

​Next steps

Install the SDK

Python support

Authentication

Generate media

SDK methods

Progress and user input

Stream progress

Questions and approvals

Recovery and cancellation

Next steps