Skip to main content
Generate an image from a Node.js application. Use Node.js 22.22 or later for these examples.

Install

The Agent SDK is in alpha. Install the version used in this guide:

Configure your credentials

Create a fal API key with the AGENT permission preset. Set your API key in the environment:
Replace YOUR_API_KEY with your key. The SDK sends Agent requests to https://fal.ai/api/agent-v2/sdk. Keep the API key on your server. Do not include it in browser code.

Create a client

Create client.ts. The other examples in this guide import this client.

Run your first task

Create agent.mts next to client.ts:
Run the file:
run() returns when execution stops or needs user input. Check status and fal.phase before using the result. Media generation can incur charges.

Stream progress

Use stream() to observe updates as the task runs:
Each update contains the complete response snapshot. Replace the displayed text on each update instead of appending it. This example starts a new task. Use responses.stream(responseId) to observe an existing task.

Continue the conversation

Replace CONVERSATION_ID with response.fal.conversation_id from the earlier response:
A follow-up creates a new response in the same conversation. To answer a pending question, use responses.answer() with the existing response ID.

Next steps