{"id":51626220,"url":"https://github.com/hcompai/hai-agents-ts","last_synced_at":"2026-07-13T01:32:36.344Z","repository":{"id":367366395,"uuid":"1253315866","full_name":"hcompai/hai-agents-ts","owner":"hcompai","description":"TypeScript SDK for H Company's Computer-Use Agent API","archived":false,"fork":false,"pushed_at":"2026-07-03T11:29:17.000Z","size":3273,"stargazers_count":31,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T12:07:41.323Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hub.hcompany.ai/computer-use-agents","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hcompai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T10:44:04.000Z","updated_at":"2026-07-03T11:28:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hcompai/hai-agents-ts","commit_stats":null,"previous_names":["hcompai/hai-agents-ts"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/hcompai/hai-agents-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fhai-agents-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fhai-agents-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fhai-agents-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fhai-agents-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hcompai","download_url":"https://codeload.github.com/hcompai/hai-agents-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fhai-agents-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35407393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-13T01:32:35.762Z","updated_at":"2026-07-13T01:32:36.338Z","avatar_url":"https://github.com/hcompai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/hcompai/hai-agents-ts/blob/main/assets/banner-dark.gif?raw=true\" /\u003e\n    \u003cimg src=\"https://github.com/hcompai/hai-agents-ts/blob/main/assets/banner-light.gif?raw=true\" alt=\"Computer-Use Agents\" width=\"700\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/hai-agents\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/hai-agents.svg\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/hai-agents\"\u003e\u003cimg src=\"https://img.shields.io/node/v/hai-agents.svg\" alt=\"Node version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  TypeScript SDK for \u003ca href=\"https://hcompany.ai\"\u003eH Company\u003c/a\u003e's \u003ca href=\"https://hub.hcompany.ai/computer-use-agents\"\u003eComputer-Use Agents\u003c/a\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e\u003ca href=\"https://hub.hcompany.ai/computer-use-agents\"\u003eDocumentation\u003c/a\u003e\u003c/b\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://platform.hcompany.ai/settings/api-keys\"\u003eGet an API key\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://www.npmjs.com/package/hai-agents\"\u003enpm\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/hcompai/hai-agents-python\"\u003ePython SDK\u003c/a\u003e\n  \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://hcompany.ai\"\u003eH Company\u003c/a\u003e\n\u003c/p\u003e\n\n## Installation\n\n```bash\nnpm install hai-agents\n```\n\nNode.js 18 or newer is required. Get an API key at [platform.hcompany.ai/settings/api-keys](https://platform.hcompany.ai/settings/api-keys) and export it:\n\n```bash\nexport HAI_API_KEY=hk-...\n```\n\n## Quickstart\n\nLaunch the built-in `h/web-surfer-pro` agent, which ships with its own browser, and describe the task in plain language. `runSession` polls until the agent finishes and returns the final answer.\n\n```ts\nimport { HaiAgentsClient } from \"hai-agents\";\n\nconst client = new HaiAgentsClient();\n\nconst result = await client.runSession({\n  agent: \"h/web-surfer-pro\",\n  messages: \"What are the top 3 stories on Hacker News right now?\",\n});\n\nconsole.log(result.status);\nconsole.log(result.answer);\n```\n\n`new HaiAgentsClient()` reads `HAI_API_KEY` from the environment.\n\n`result` is a `SessionRunResult`: `id`, `status`, `answer`, the accumulated `events`, and `finalChanges`.\n\n## How a session works\n\nA session is one run of an agent against a task. It moves through a small set of states: `pending`, `running`, and then a settled state such as `completed`, `idle`, `failed`, `timed_out`, or `interrupted`.\n\nYou drive a session two ways. `runSession` creates it and resolves once it settles, which suits one-shot tasks. `startSession` creates it and returns a handle right away, so you can read and steer the agent while it works.\n\n```ts\nconst session = await client.startSession({\n  agent: \"h/web-surfer-pro\",\n  messages: \"Find the top story on Hacker News\",\n});\n\nconsole.log(session.id);\nconst result = await session.waitForCompletion();\nconsole.log(result.status, result.answer);\n```\n\n## Watch and steer a running session\n\nA handle bound to the session `id` exposes the full lifecycle. Read the agent's progress at three levels of detail:\n\n```ts\nawait session.status();\nawait session.changes({ fromIndex: 0 });\nawait session.get();\n```\n\n`status()` is a cheap snapshot with the state, step count, and token usage. `changes({ fromIndex: 0 })` long-polls for new events and the final answer. `get()` returns the full Session resource.\n\nWhile the session is not in a terminal state, you can intervene:\n\n```ts\nawait session.sendMessage({ type: \"user_message\", message: \"Only consider the last 24 hours\" });\nawait session.pause();\nawait session.resume();\nawait session.forceAnswer();\nawait session.cancel();\n```\n\n`sendMessage` redirects the agent on its next step and wakes an `idle` session. `pause` halts with state preserved until `resume`. `forceAnswer` makes the agent stop exploring and answer from what it has. `cancel` ends the session as `interrupted`.\n\n## Multi-turn sessions\n\nBy default a session ends as soon as the agent answers. Set `idleTimeoutS` to keep it open: after each answer the session goes `idle` and waits that long for your next message, carrying its full context and browser state across turns.\n\n```ts\nconst session = await client.startSession({\n  agent: \"h/web-surfer-pro\",\n  idleTimeoutS: 600,\n  messages: \"Find the top story on Hacker News\",\n});\nconst first = await session.waitForCompletion();\n\nawait session.sendMessage({ type: \"user_message\", message: \"Now summarize its comments\" });\nconst second = await session.waitForCompletion();\n```\n\n## Structured output\n\nPass a [Zod v4](https://zod.dev) schema as `answerSchema` and the agent's final answer resolves as a parsed, typed value. The schema is sent as the agent's answer format; the raw wire value stays at `result.finalChanges.answer`. Zod is an optional peer dependency, only needed when you use this.\n\n```ts\nimport { HaiAgentsClient } from \"hai-agents\";\nimport { z } from \"zod\";\n\nconst Jobs = z.object({\n  jobs: z.array(z.object({ title: z.string(), company: z.string() })),\n});\n\nconst client = new HaiAgentsClient();\nconst result = await client.runSession({\n  agent: \"h/web-surfer-pro\",\n  messages: \"Find 3 open ML engineering roles in Paris.\",\n  answerSchema: Jobs,\n});\n\nfor (const job of result.answer?.jobs ?? []) {\n  console.log(job.title, \"@\", job.company);\n}\n```\n\nA completed answer that does not match the schema throws `AnswerValidationError`, with the raw payload on `.raw`. Sessions that end without completing resolve with their raw answer untouched.\n\n## Custom tools\n\nGive the agent tools that run in your own process. Declare each tool with a JSON schema and a function; the SDK registers them on the session, runs them when the agent calls them, and posts the results back so the agent can continue.\n\n```ts\nimport { HaiAgentsClient, tool } from \"hai-agents\";\n\nconst getWeather = tool({\n  name: \"get_weather\",\n  description: \"Get the current weather for a city.\",\n  inputSchema: {\n    type: \"object\",\n    properties: { city: { type: \"string\" } },\n    required: [\"city\"],\n  },\n  fn: async ({ city }) =\u003e `Sunny in ${city}, 24C`,\n});\n\nconst client = new HaiAgentsClient();\n\nconst result = await client.runSession({\n  agent: \"h/web-surfer-pro\",\n  messages: \"What should I wear in Paris today?\",\n  tools: [getWeather],\n});\n\nconsole.log(result.answer);\n```\n\nTool functions may be sync or async. A tool that throws is reported to the agent as a tool error rather than crashing the run.\n\n### Prebuilt: one-time passwords (2FA)\n\nThe SDK ships ready-made tools. `otpTool` lets the agent ask for a one-time password, verification code, or confirmation link when a login or signup step needs one. Without a handler it prompts on stdin; `imapOtpHandler` reads the code straight from a mailbox over IMAP (requires the optional dependencies `imapflow` and `mailparser`; for Gmail, use an app password).\n\n```ts\nimport { HaiAgentsClient, imapOtpHandler, otpTool } from \"hai-agents\";\n\nconst handler = imapOtpHandler({\n  host: \"imap.gmail.com\",\n  username: \"agent-inbox@gmail.com\",\n  password: process.env.GMAIL_APP_PASSWORD!,\n});\n\nconst client = new HaiAgentsClient();\nconst result = await client.runSession({\n  agent: \"h/web-surfer-pro\",\n  messages: \"Log in to example.com and check for new notifications\",\n  tools: [otpTool({ handler })],\n});\n```\n\nLike every custom tool, the handler runs entirely in your process: the IMAP credentials never leave your machine, and the agent only receives the single extracted code or link -- never mailbox contents.\n\n## Browser profiles and vaults\n\nStart a session on a browser that already knows the user. A [browser profile](https://hub.hcompany.ai/computer-use-agents/browser-profiles) restores saved cookies and storage from an earlier session, and a [vault](https://hub.hcompany.ai/computer-use-agents/vaults) lets the agent sign in to sites with secrets that never enter its context. Bind both through per-run overrides:\n\n```ts\nconst result = await client.runSession({\n  agent: \"h/web-surfer-pro\",\n  messages: \"Open my dashboard and report any new alerts\",\n  overrides: {\n    \"agent.environments[kind=web].browser_profile_id\": \"\u003cprofile-id\u003e\",\n    \"agent.environments[kind=web].vault_id\": \"\u003cvault-id\u003e\",\n  },\n});\n```\n\n## Inspect and share sessions\n\nList past sessions and create a public replay link:\n\n```ts\nconst page = await client.sessions.listSessions({ size: 10 });\nfor (const summary of page.items) {\n  console.log(summary.id, summary.status);\n}\n\nconst link = await client.sessions.shareSession({ id: \"\u003csession-id\u003e\" });\nconsole.log(link.shareUrl);\n```\n\n## Regions and configuration\n\nThe client targets the EU region by default; pass `environment` to use the US region instead:\n\n```ts\nimport { HaiAgentsClient, HaiAgentsEnvironment } from \"hai-agents\";\n\nconst client = new HaiAgentsClient({ environment: HaiAgentsEnvironment.Us });\n```\n\nThe client also accepts a custom `baseUrl`, and an `apiKey` when you do not want to use the environment variable:\n\n```ts\nconst client = new HaiAgentsClient({ baseUrl: \"https://agp.hcompany.ai\", apiKey: \"hk-...\" });\n```\n\n## Errors\n\n```ts\nimport { HaiAgentsError, HaiAgentsTimeoutError, AnswerValidationError } from \"hai-agents\";\n```\n\n`HaiAgentsError` is the base for HTTP failures and carries `.statusCode` and `.body`. `HaiAgentsTimeoutError` is thrown when a request exceeds its time budget. `HaiAgents.UnprocessableEntityError` is the 422 raised when a request fails validation. `AnswerValidationError` is thrown when a completed answer does not match `answerSchema`, with the unparsed value on `.raw`.\n\n## Webhooks\n\nVerify the signature on an incoming webhook before trusting it:\n\n```ts\nimport { verifyWebhook, WebhookVerificationError } from \"hai-agents\";\n\nconst event = verifyWebhook(rawBody, signature, timestamp, secret);\nconsole.log(event.type, event.data);\n```\n\n## Documentation\n\nGuides, core concepts, and the full API reference live at **[hub.hcompany.ai/computer-use-agents](https://hub.hcompany.ai/computer-use-agents)**.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcompai%2Fhai-agents-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhcompai%2Fhai-agents-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcompai%2Fhai-agents-ts/lists"}