# Agent Platform (AgP) Javascript SDK

[![npm version](https://badge.fury.io/js/agp-js-sdk.svg)](https://badge.fury.io/js/agp-js-sdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

> Build AI-powered web automation into your applications with just a few lines of code.

**[H Tech Hub](https://hub.hcompany.ai/)** • **[Portal-H](https://portal.hcompany.ai)**

---

# Get started

To successfully execute a task using the AgP JS SDK, you need to implement the following and run them asynchronously in your browser:

- **Authenticate**: Establish a valid session to access the AgP API.
- **Run the task**: Define the task objective, for example "search for noise-cancelling headphones," and execute it.
- **Attach a listener**: See the task's progress and receive updates in real time.
- **Wait for completion:** Ensure the task finishes before proceeding.

## Run your first task

Follow these instructions to set up the SDK and run your first task.

### Step 1: Add the below script
This loads the AgP JS SDK in your browser:

```html
<script src="https://unpkg.com/agp-js-sdk"></script>
```

### Step 2: Authenticate
To initialize the SDK, you must first authenticate via JWT or API key, both of which are created and obtained through [Portal-H](https://portal.hcompany.ai/). The SDK will attempt an authentication when initializing.

**Authenticate via JWT**

The SDK automatically checks for existing authentication. If login is required, the `authCallback` is triggered with a `login` function that opens a Portal-H popup window where users authenticate:

```html
<script src="https://unpkg.com/agp-js-sdk"></script>
<script>
const agent = await AGP.WebAgent.init({
  authCallback: (login) => {
    const loginBtn = document.getElementById('login-btn');
    loginBtn.style.display = 'block';
    loginBtn.onclick = login; // Opens Portal-H login popup
  }
});
</script>
```

**Authenticate via API Key**

If you prefer using an API key, please refer to the [H Tech Hub](https://hub.hcompany.ai/agentplatformdrafttestdns123/generateanapikeyDNSINTERNAL) for detailed instructions on how to create one.

*Please use your API key in a browser-only setup, strictly for testing.*


### Step 3: Add a task
Using the `agent.run` function, run a task that includes both an **Objective** and **startUrl**.

```javascript
const task = await agent.run('Search for best noise-cancelling headphones', {
  startUrl: 'https://google.com'
});
```

### Step 4: Attach a listener
Add an event listener to monitor task progress and receive real-time updates as the agent runs.

```javascript
task.onUpdate((event) => {
  console.log(event.type, event.data);
});
```

### Step 5: Wait for completion
Add the following code to be notified in real time when your task has finished executing.

```javascript
await task.waitForCompletion();
```

### Step 6: Put it all together

Here’s a complete example that combines authentication, task execution, and real-time updates. You can run this script directly in your browser.

```html
<button id="loginBtn" style="display:none;">Login to Portal-H</button>

<script src="https://unpkg.com/agp-js-sdk"></script>
<script>
(async () => {
  const agent = await AGP.WebAgent.init({
    authCallback: (login) => {
      const btn = document.getElementById('loginBtn');
      btn.style.display = 'block';
      btn.onclick = login;
    }
  });

  const task = await agent.run('Search for best noise-cancelling headphones', {
    startUrl: 'https://google.com'
  });

  task.onUpdate((event) => {
    console.log(event.type, event.data);
  });

  await task.waitForCompletion();
})();
</script>
```

---
# Using the AgP JS SDK

This section covers key methods and functions you can use to modify your agent task runs and customize how you work with the AgP JS SDK. First, here are some general requirements and best practices for using the SDK effectively.

- **`task` object**: Represents a single task run by the SDK. Use this to control, monitor, and interact with the agent.

- **`async()` function**: SDK calls must be wrapped in an asynchronous function to ensure proper sequencing and allow the use of await.
  
- **Load or initialize the SDK:** You must include the SDK script in your page (or import it in Node) before calling any SDK methods.
  
- **Authenticate via Portal-H:** You need to sign in via [Portal-H](https://portal.hcompany.ai/) to create a valid agent session before running tasks.
  
- **Event listeners (Optional but recommended):** Attach listeners like `onUpdate`, `onStatusChange`, or `onWebAction` to observe task progress and agent behavior in real time.

## Authentication

The SDK supports authentication via JWT or API key, both obtainable via Portal-H.

**Authentication via JWT**: The SDK automatically checks for existing authentication on initialization. If login is needed, the `authCallback` is triggered with a `login` function that opens a Portal-H popup window:

```html
<button id="loginBtn" style="display:none;">Login to Portal-H</button>

<script src="https://unpkg.com/agp-js-sdk"></script>
<script>
(async () => {
  const agent = await AGP.WebAgent.init({
    authCallback: (login) => {
      const btn = document.getElementById('loginBtn');
      btn.style.display = 'block';
      btn.onclick = login; // Opens Portal-H login popup
    }
  });

  const task = await agent.run('Your task here');
})();
</script>
```

**Authentication via API key:** Please check the [H Tech Hub](https://hub.hcompany.ai) for examples and instructions.

*Please use your API key in a browser-only setup, strictly for testing.*

---

## Core Methods

Essential methods for creating agents and running tasks with the AgP JS SDK.

### `run()` : Execute a task

Start an agent task that runs autonomously and provides real-time updates.

```javascript
const task = await agent.run('Your objective', {
  startUrl: 'https://example.com',
  timeout: 300,
  autoStart: true
});
```

### `runStepByStep()` : Manual control

Execute tasks one step at a time with manual approval between actions. Ideal for debugging.

```javascript
const task = await agent.runStepByStep('Your objective');
await task.stepForward();  // Resume execution
await task.pause();        // Pause again if needed
await task.resume();       // Continue automatically
```

### `runAndWait()` : Wait for completion

Run a task and automatically wait for it to complete.

```javascript
const task = await agent.runAndWait('Search for TypeScript tutorials');
console.log('Status:', task.status);
```

---

## Event Monitoring

Track agent progress with event listeners for updates, status changes, thoughts, and browser actions.

```javascript
const task = await agent.run('Your task');

// All events
task.onUpdate((event) => {
  console.log(event.type, event.data);
});

// Status changes
task.onStatusChange((status) => {
  console.log('Status:', status); // pending, running, completed, failed
});

// Agent thoughts and reasoning
task.onChatMessage((message) => {
  if (message.data.type === 'thought') {
    console.log('Agent thinking:', message.data.content);
  }
});

// Browser actions (clicks, typing, navigation)
task.onWebAction((action) => {
  console.log('Action:', action.data.action.action_type);

  // Screenshots are public URLs
  const screenshot = action.data.post_action_screenshot;
  document.querySelector('img').src = screenshot;
});
```

---

## Task Control

Pause, resume, or stop running tasks, and wait for specific events or completion.

```javascript
await task.pause();
await task.resume();
await task.stop();

// Wait for specific events
await task.waitForCompletion();
await task.waitForEvent('action_completed');
```

---

## Need Help?

- **Docs**: [hub.hcompany.ai](https://hub.hcompany.ai)
- **Support**: support@hcompany.ai
- **Portal-H**: [portal.hcompany.ai](https://portal.hcompany.ai)