{"_id":"@bini-bar-labs/atomic-web-agent-core","_rev":"3-a905b2c5bfae84fe03f8d3d04850b523","name":"@bini-bar-labs/atomic-web-agent-core","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@bini-bar-labs/atomic-web-agent-core","version":"1.0.0","keywords":["ai","agent","web-automation","playwright","langchain","browser-automation","web-scraping","ai-agent"],"author":{"name":"Bini Barazany","email":"bgt636@gmail.com"},"license":"ISC","_id":"@bini-bar-labs/atomic-web-agent-core@1.0.0","maintainers":[{"name":"binikingi","email":"bgt636@gmail.com"}],"homepage":"https://github.com/binikingi/atomic-web-agent#readme","bugs":{"url":"https://github.com/binikingi/atomic-web-agent/issues"},"dist":{"shasum":"efab0ee866b33214be88cf60cd6e9204f358f429","tarball":"https://registry.npmjs.org/@bini-bar-labs/atomic-web-agent-core/-/atomic-web-agent-core-1.0.0.tgz","fileCount":75,"integrity":"sha512-pkHFGEi0F4eej3wk8SrL6LlB7cF37FEAyZLl0qJGmv30xClWocZT+9a4yWd2Dw1kyByqBagWgXIhBF8+mBETDQ==","signatures":[{"sig":"MEUCIHg5TfYuX6WZiDEIk2CkuqYng7HzchomPFmm+9KfBG0JAiEAgkUAYno+86x0SsYDwGttLpiAmzDYZ5ikeW7AVHhUvSU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74408},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d0933708b19966a6decf6ccc871cdb7611788169","scripts":{"lint":"eslint 'src/**/*.ts'","build":"tsc -b","prepublishOnly":"pnpm build"},"_npmUser":{"name":"binikingi","email":"bgt636@gmail.com"},"repository":{"url":"git+https://github.com/binikingi/atomic-web-agent.git","type":"git","directory":"packages/agent-core"},"_npmVersion":"11.6.2","description":"The core of the Atomic Web Agent, providing essential functionalities for web interaction.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"4.1.13","dedent":"1.7.0","langchain":"1.1.1","playwright":"1.57.0","@langchain/core":"1.1.0","@langchain/openai":"1.1.3","@langchain/anthropic":"1.1.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"4.20.6"},"_npmOperationalInternal":{"tmp":"tmp/atomic-web-agent-core_1.0.0_1766938858847_0.774924378546872","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bini-bar-labs/atomic-web-agent-core","version":"1.0.1","keywords":["ai","agent","web-automation","playwright","langchain","browser-automation","web-scraping","ai-agent"],"author":{"name":"Bini Barazany","email":"bgt636@gmail.com"},"license":"ISC","_id":"@bini-bar-labs/atomic-web-agent-core@1.0.1","maintainers":[{"name":"binikingi","email":"bgt636@gmail.com"}],"homepage":"https://github.com/binikingi/atomic-web-agent#readme","bugs":{"url":"https://github.com/binikingi/atomic-web-agent/issues"},"dist":{"shasum":"11a6d59857b851fcdf01c85d87120ddcb706eb28","tarball":"https://registry.npmjs.org/@bini-bar-labs/atomic-web-agent-core/-/atomic-web-agent-core-1.0.1.tgz","fileCount":79,"integrity":"sha512-QYGS9cfibwzar7c2G4mBOcVT1+oe0DxAAuTvhSGK1Rtf3aDFYmv9cYZfFyZt10dUu2t0+xGLlO7Mfjcp4o9maQ==","signatures":[{"sig":"MEUCIQCpAyPd9C8ePl/a6HWjx3bCoWCzMXoBvJIwiT0kvS+UdwIgLESg9+GCzMIt30+CUeEAbplipw5Fn+HYS7KfGUkNKqE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":89808},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"05b03dcde6e142024829c9293427a32c57666a04","scripts":{"lint":"eslint 'src/**/*.ts'","build":"tsc -b","prepublishOnly":"pnpm build"},"_npmUser":{"name":"binikingi","email":"bgt636@gmail.com"},"repository":{"url":"git+https://github.com/binikingi/atomic-web-agent.git","type":"git","directory":"packages/agent-core"},"_npmVersion":"11.6.2","description":"The core of the Atomic Web Agent, providing essential functionalities for web interaction.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"4.1.13","dedent":"1.7.0","langchain":"1.1.1","playwright":"1.57.0","@langchain/core":"1.1.0","@langchain/openai":"1.1.3","@langchain/anthropic":"1.1.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"4.20.6"},"_npmOperationalInternal":{"tmp":"tmp/atomic-web-agent-core_1.0.1_1766948539636_0.681693870027994","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bini-bar-labs/atomic-web-agent-core","version":"1.0.2","description":"The core of the Atomic Web Agent, providing essential functionalities for web interaction.","main":"dist/index.js","types":"dist/index.d.ts","type":"module","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"lint":"eslint 'src/**/*.ts'","build":"tsc -b","prepublishOnly":"pnpm build"},"keywords":["ai","agent","web-automation","playwright","langchain","browser-automation","web-scraping","ai-agent"],"author":{"name":"Bini Barazany","email":"bgt636@gmail.com"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/binikingi/atomic-web-agent.git","directory":"packages/agent-core"},"bugs":{"url":"https://github.com/binikingi/atomic-web-agent/issues"},"homepage":"https://github.com/binikingi/atomic-web-agent#readme","publishConfig":{"access":"public"},"devDependencies":{"tsx":"4.20.6"},"dependencies":{"@langchain/anthropic":"1.1.3","@langchain/core":"1.1.0","@langchain/openai":"1.1.3","dedent":"1.7.0","langchain":"1.1.1","playwright":"1.57.0","zod":"4.1.13","zod-to-json-schema":"^3.25.1"},"gitHead":"75bc2e1a98cf41c880b803e5ab0a59470f915482","_id":"@bini-bar-labs/atomic-web-agent-core@1.0.2","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-/OwXwOXc4GCwripuG5FkR0BHKTCLv5hTC9eDV3YHO8jm6COaWOQZzs+c1ew4GJzlvrHZcYHnmK6u4XAKGzonqQ==","shasum":"72acb8fa34dfdaf13e3424a6c8d213af1e454508","tarball":"https://registry.npmjs.org/@bini-bar-labs/atomic-web-agent-core/-/atomic-web-agent-core-1.0.2.tgz","fileCount":83,"unpackedSize":103965,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDTONw2ZlEFD3PtS+1KlRi+43IUJZYyyI0oTJWaq1fQcQIhALmc+TVy9kgiGL5gSCLHTJ9/k5phn0e8NJwjh0wW+OCg"}]},"_npmUser":{"name":"binikingi","email":"bgt636@gmail.com"},"directories":{},"maintainers":[{"name":"binikingi","email":"bgt636@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/atomic-web-agent-core_1.0.2_1766954061043_0.3275500038386905"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-28T16:20:58.601Z","modified":"2025-12-28T20:34:21.414Z","1.0.0":"2025-12-28T16:20:58.997Z","1.0.1":"2025-12-28T19:02:19.789Z","1.0.2":"2025-12-28T20:34:21.175Z"},"bugs":{"url":"https://github.com/binikingi/atomic-web-agent/issues"},"author":{"name":"Bini Barazany","email":"bgt636@gmail.com"},"license":"ISC","homepage":"https://github.com/binikingi/atomic-web-agent#readme","keywords":["ai","agent","web-automation","playwright","langchain","browser-automation","web-scraping","ai-agent"],"repository":{"type":"git","url":"git+https://github.com/binikingi/atomic-web-agent.git","directory":"packages/agent-core"},"description":"The core of the Atomic Web Agent, providing essential functionalities for web interaction.","maintainers":[{"name":"binikingi","email":"bgt636@gmail.com"}],"readme":"# @bini-bar-labs/atomic-web-agent-core\n\nThe core of the Atomic Web Agent, providing essential functionalities for AI-powered web interaction and automation.\n\n## Overview\n\n`@bini-bar-labs/atomic-web-agent-core` is a powerful library that combines the capabilities of [Playwright](https://playwright.dev/) for browser automation with [LangChain](https://js.langchain.com/) for AI agent orchestration. It enables you to create intelligent agents that can interact with web applications autonomously.\n\n## Features\n\n- **AI-Powered Browser Automation**: Control browser interactions using AI models (Anthropic Claude, OpenAI GPT)\n- **Built-in Tools**: Pre-configured tools for common web interactions (clicking, typing, navigation, screenshots)\n- **Extensible**: Easy to add custom tools for specific use cases\n- **Type-Safe**: Full TypeScript support with comprehensive type definitions\n- **Accessibility-First**: Uses accessibility snapshots for robust element interaction\n\n## Installation\n\n```bash\nnpm install @bini-bar-labs/atomic-web-agent-core\n```\n\nor with pnpm:\n\n```bash\npnpm add @bini-bar-labs/atomic-web-agent-core\n```\n\n## Quick Start\n\n```typescript\nimport { AWAgent } from \"@bini-bar-labs/atomic-web-agent-core\";\nimport { ChatAnthropic } from \"@langchain/anthropic\";\n\n// Initialize the model\nconst model = new ChatAnthropic({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n  model: \"claude-3-5-sonnet-20241022\",\n});\n\n// Create the agent\nconst agent = new AWAgent(\n  model,\n  \"You are a helpful web automation assistant.\"\n);\n\n// Initialize and run\nawait agent.init();\nawait agent.run(\"Navigate to https://example.com and take a screenshot\");\nawait agent.close();\n```\n\n## Page Validation\n\nThe `test()` method enables you to validate conditions on the current webpage using natural language. It returns `true` if the condition is met, `false` otherwise.\n\n```typescript\n// Example: Check if user is logged in\nconst isLoggedIn = await agent.test(\"The user is logged in\");\nconsole.log(isLoggedIn); // true or false\n\n// Example: Verify form validation\nconst hasError = await agent.test(\"An error message is displayed\");\n\n// Example: Check element state\nconst isButtonDisabled = await agent.test(\"The submit button is disabled\");\n\n// Example: Verify content presence\nconst hasWelcomeMessage = await agent.test(\"A welcome message appears on the page\");\n\n// Example: Complex state validation\nconst isCheckoutReady = await agent.test(\n  \"The shopping cart has items and the checkout button is clickable\"\n);\n```\n\n### Best Practices for test() Conditions\n\n- **Be specific and measurable**: \"The login button is visible\" is better than \"The page looks good\"\n- **Focus on observable state**: Describe what should be visible or present on the page\n- **Avoid subjective interpretations**: Use concrete, verifiable conditions\n- **Keep it atomic**: Test one condition at a time for clearer results\n\n## Data Extraction\n\nThe `extract()` method enables you to extract structured data from webpages using Zod schemas. It returns typed data that matches your schema.\n\n```typescript\nimport { z } from \"zod\";\n\n// Define your data schema\nconst productSchema = z.object({\n  title: z.string().describe(\"The product title\"),\n  price: z.number().describe(\"The product price in dollars\"),\n  description: z.string().describe(\"The product description\"),\n  inStock: z.boolean().describe(\"Whether the product is in stock\"),\n  rating: z.number().optional().describe(\"Product rating out of 5\"),\n});\n\ntype Product = z.infer<typeof productSchema>;\n\n// Extract data from the page\nconst product = await agent.extract<Product>(\n  productSchema,\n  \"Extract product information from this page\"\n);\n\nconsole.log(product);\n// { title: \"...\", price: 99.99, description: \"...\", inStock: true, rating: 4.5 }\n```\n\n### More Examples\n\n```typescript\n// Extract multiple items (array)\nconst itemsSchema = z.object({\n  items: z.array(\n    z.object({\n      name: z.string(),\n      price: z.number(),\n    })\n  ),\n});\n\nconst data = await agent.extract(itemsSchema);\n\n// Extract user profile\nconst profileSchema = z.object({\n  name: z.string(),\n  email: z.string().email(),\n  age: z.number().optional(),\n  isVerified: z.boolean(),\n});\n\nconst profile = await agent.extract(profileSchema);\n\n// Extract with custom instructions\nconst statsSchema = z.object({\n  visitors: z.number(),\n  pageViews: z.number(),\n  bounceRate: z.number(),\n});\n\nconst stats = await agent.extract(\n  statsSchema,\n  \"Look for the analytics dashboard section and extract the key metrics displayed\"\n);\n```\n\n### Features\n\n- **Type-safe**: Full TypeScript support with automatic type inference\n- **Schema validation**: Extracted data is validated against your Zod schema\n- **Native structured output**: Uses LangChain's `providerStrategy` for efficient extraction via model provider's native structured output capability\n- **Automatic field detection**: AI determines how to extract each field\n- **Flexible**: Works with complex nested schemas\n- **Error handling**: Clear validation errors if data doesn't match schema\n\n## API Reference\n\n### AWAgent\n\nThe main class for creating and controlling web agents.\n\n#### Constructor\n\n```typescript\nnew AWAgent(\n  model: ChatAnthropic | ChatOpenAI,\n  systemMessage: string,\n  options?: {\n    overrideTools?: {\n      getDOMSnapshotTool?: (page: Page, registry: ElementLocatorRegistry) => AgentTool;\n    };\n    customTools?: ((page: Page) => AgentTool)[];\n  }\n)\n```\n\n#### Methods\n\n- `init(launchOptions?: LaunchOptions, contextOptions?: BrowserContextOptions): Promise<void>` - Initialize the browser and agent\n- `run(message: string): Promise<void>` - Execute a task with the agent\n- `test(condition: string): Promise<boolean>` - Validate a condition on the current page and return true/false\n- `extract<T>(schema: z.ZodSchema<T>, instructions?: string): Promise<T>` - Extract structured data from the page using a Zod schema\n- `close(): Promise<void>` - Close the browser and clean up resources\n\n### Exports\n\n```typescript\nexport { AWAgent } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport { type PlaywrightPage } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport { createTool } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport { type AgentTool } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport { ElementLocatorRegistry } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport { validateConditionTool } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport { extractDataTool } from \"@bini-bar-labs/atomic-web-agent-core\";\nexport {\n  type ElementSnapshot,\n  type PageSnapshot,\n  generateAccessibilitySnapshot,\n} from \"@bini-bar-labs/atomic-web-agent-core\";\n```\n\n## Built-in Tools\n\nThe agent comes with several pre-configured tools:\n\n- **Navigate**: Navigate to URLs\n- **Click**: Click elements by ID or position\n- **Input**: Type text into input fields\n- **Screenshot**: Capture page screenshots\n- **DOM Snapshot**: Get accessibility-based page structure (with optional extra tags)\n- **Wait**: Wait for specified durations\n- **Console Print**: Output messages to console\n- **Validation**: Return validation results (used by `test()` method)\n\nNote: The `extract()` method uses native structured output via LangChain's `providerStrategy` rather than a custom tool, allowing for more efficient data extraction directly from the model provider.\n\n### DOM Snapshot with Custom Elements\n\nThe DOM Snapshot tool is intelligent and can include additional HTML elements beyond the default interactive elements. The AI can request specific tags to be included in the snapshot.\n\n**How it works:**\n- By default, the snapshot includes only interactive elements (buttons, inputs, links, etc.)\n- The AI can specify additional HTML tags to include using the `extraTags` parameter\n- This is useful for validation tasks that need to examine text content or specific elements\n\n**Example use case:**\nWhen you ask the agent to validate text content on a page, the AI will automatically:\n1. Call `GetDOMSnapshot` with `extraTags: [\"p\", \"span\", \"h1\", \"h2\"]`\n2. Receive a snapshot that includes both interactive elements AND the specified text elements\n3. Validate the condition based on the complete snapshot\n\n**Common tags the AI might request:**\n- Text content: `p`, `span`, `div`\n- Headings: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`\n- Lists: `li`, `ul`, `ol`\n- Labels: `label`\n\nThis feature enables more accurate validation and interaction with webpage content without overwhelming the context with unnecessary elements.\n\n## Custom Tools\n\nYou can extend the agent with custom tools:\n\n```typescript\nimport { AWAgent, createTool } from \"@bini-bar-labs/atomic-web-agent-core\";\n\nconst myCustomTool = (page: Page) =>\n  createTool(\n    async ({ input }) => {\n      // Your custom logic here\n      return \"Result\";\n    },\n    {\n      name: \"my_custom_tool\",\n      description: \"Description of what this tool does\",\n      schema: z.object({\n        input: z.string(),\n      }),\n    }\n  );\n\nconst agent = new AWAgent(model, systemMessage, {\n  customTools: [myCustomTool],\n});\n```\n\n## Requirements\n\n- Node.js >= 18\n- An API key for Anthropic Claude or OpenAI\n\n## License\n\nISC\n\n## Repository\n\n[https://github.com/binikingi/atomic-web-agent](https://github.com/binikingi/atomic-web-agent)\n\n## Issues\n\nReport issues at [https://github.com/binikingi/atomic-web-agent/issues](https://github.com/binikingi/atomic-web-agent/issues)\n\n## Author\n\nBini Barazany <bgt636@gmail.com>\n","readmeFilename":"README.md"}