> For the complete documentation index, see [llms.txt](https://help.integrail.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.integrail.ai/sdk-documentation.md).

# SDK Documentation

This guide provides a brief overview of how to use the Integrail.ai Cloud SDK in your TypeScript/JavaScript applications.

### Initializing `IntegrailCloudApi`

Import the `IntegrailCloudApi` class from the `integrail-sdk-cloud` package and initialize it with your API token:

```javascript
import { IntegrailCloudApi } from "integrail-sdk-cloud";

const cloudApi = new IntegrailCloudApi({
  apiToken: "YOUR_API_TOKEN",
});
```

Replace `"YOUR_API_TOKEN"` with your actual API token obtained from the Integrail.ai dashboard.

### Using `agent.execute`

You can execute an agent in two ways: streaming or non-streaming.

#### Streaming Execution

In streaming execution, events are sent from the server and handled by the `onEvent` callback. When the execution finishes, `onFinish` is called.

```javascript
const agentId = "YOUR_AGENT_ID";
const accountId = "YOUR_ACCOUNT_ID";

const onEvent = (event, execution) => {
  console.log(event);
};

const onFinish = (execution) => {
  console.log(execution);
};

cloudApi.agent.execute(
  agentId,
  accountId,
  { inputs: { param1: "value1" }, stream: true },
  onEvent,
  onFinish,
).catch(error => {
  console.error("Error:", error);
});
```

**Parameters:**

* `agentId`: The ID of the agent you want to execute.
* `accountId`: Your account ID.
* `inputs`: An object containing input parameters for the agent.
* `stream`: Set to `true` to enable streaming of execution events.

**Callbacks:**

* `onEvent(event, execution)`: Handles execution updates.
* `onFinish(execution)`: Called when execution is finished.

#### Non-Streaming Execution

For non-streaming, background execution, omit the `onEvent` and `onFinish` callbacks. The method returns immediately with an execution ID.

```javascript
cloudApi.agent.execute(
  agentId,
  accountId,
  { inputs: { param1: "value1" } }
).then(execution => {
  console.log("Execution ID:", execution._id);
}).catch(error => {
  console.error("Error:", error);
});
```

### Using `agent.executeMultipart`

The `executeMultipart` method allows you to upload a file and use it as an agent input in the same request, eliminating the need to upload it separately.

```javascript
const agentId = "YOUR_AGENT_ID";
const accountId = "YOUR_ACCOUNT_ID";

const onEvent = (event, execution) => {
  console.log(event);
};

const onFinish = (execution) => {
  console.log(execution);
};

// Fetch the file as a Blob
const response = await fetch("FILE_URL");
const blob = await response.blob();

cloudApi.agent.executeMultipart(
  agentId,
  accountId,
  { inputs: { foo: "bar" }, stream: true },
  { qwe: blob },
  onEvent,
  onFinish,
).catch(error => {
  console.error("Error:", error);
});
```

**Parameters:**

* `inputs`: Agent input parameters.
* `stream`: Set to `true` for streaming execution.
* File inputs: An object where keys are parameter names and values are `Blob` objects.

**Note:** This method simplifies the process of using files as inputs by combining upload and execution into one step.

### Notes

* **Streaming vs. Non-Streaming Execution:**
  * **Streaming Execution:** Use `stream: true` and provide `onEvent` and `onFinish` callbacks to receive real-time updates.
  * **Non-Streaming Execution:** Omit `stream`, `onEvent`, and `onFinish` to execute in the background and receive an execution ID immediately.

***

We’d love to hear from you! Reach out to **<documentation@integrail.ai>**