TypeScript SDK for H.AI Agent Platform - easily integrate AI web automation into your applications
npm install agp-js-sdk
> Build AI-powered web automation into your applications with just a few lines of code.
---
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.
Follow these instructions to set up the SDK and run your first task.
``html`
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`
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.
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'
});
`$3
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);
});
`$3
Add the following code to be notified in real time when your task has finished executing.javascript
await task.waitForCompletion();
`$3
Here’s a complete example that combines authentication, task execution, and real-time updates. You can run this script directly in your browser.
html
`---
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.
-
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:`html
`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.
$3
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
});
`$3
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
`$3
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');
``---
- Docs: hub.hcompany.ai
- Support: support@hcompany.ai
- Portal-H: portal.hcompany.ai