Agent Platform (AgP) Javascript SDK

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

H Tech Hub • Portal-H

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:

<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. 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:

<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 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.

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.

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.

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.

<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 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:

<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 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.

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.

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.

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.

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.

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
• Support: [email protected]
• Portal-H: portal.hcompany.ai