# 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>**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.integrail.ai/sdk-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.