diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..007463b --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +root = true + +[*] +indent_size = 2 +indent_style = space +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..2916bbb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,55 @@ +name: ๐Ÿ› Bug report +description: Report a bug to help us improve the template. +labels: [bug] +body: + - type: markdown + attributes: + value: | + Before reporting a bug, please search existing [issues](https://github.com/browser-use/browser-agent-template/issues). If the bug was already reported, add your reaction instead of opening a duplicate. + - type: textarea + id: env + attributes: + label: Environment + description: | + For example: + - OS: macOS 15 + - Browser: Chrome 131 + - Node.js: 24.x + - Package manager: npm 10.x + validations: + required: true + - type: input + id: version + attributes: + label: Version + placeholder: main or commit SHA + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction + description: Minimal steps to reproduce the issue. + placeholder: | + 1. Clone the repo and follow Quick Start in README + 2. ... + validations: + required: true + - type: textarea + id: description + attributes: + label: Description + description: What happened vs what you expected. + validations: + required: true + - type: textarea + id: additional + attributes: + label: Additional context + description: Screenshots, logs, or related configuration. + - type: textarea + id: logs + attributes: + label: Logs + description: Paste relevant terminal or browser logs (avoid screenshots of text). + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..55f3a11 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: GitHub Discussions + url: https://github.com/browser-use/browser-agent-template/discussions + about: Ask questions and discuss ideas with the community diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000..04c598a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,20 @@ +name: ๐Ÿš€ Feature request +description: Suggest an idea or enhancement for the template. +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Before requesting a feature, please search existing [issues](https://github.com/browser-use/browser-agent-template/issues). If it was already requested, add your reaction instead of opening a duplicate. + - type: textarea + id: description + attributes: + label: Description + description: What would you like to add or improve, and what problem does it solve? + validations: + required: true + - type: textarea + id: additional + attributes: + label: Additional context + description: Mockups, links, or implementation ideas. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..064901f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,15 @@ +name: โ“ Question +description: Ask a question about setup, customization, or deployment. +labels: [question] +body: + - type: markdown + attributes: + value: | + Check [README](https://github.com/browser-use/browser-agent-template#readme) and [docs/](https://github.com/browser-use/browser-agent-template/tree/main/docs) first. For open-ended discussion, consider [GitHub Discussions](https://github.com/browser-use/browser-agent-template/discussions). + - type: textarea + id: description + attributes: + label: Question + description: What are you trying to do, and where are you stuck? + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..c1a351a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ + + +### ๐Ÿ”— Linked issue + + + +### ๐Ÿ“š Description + + + +### ๐Ÿ“ Checklist + +- [ ] I have linked an issue or discussion. +- [ ] I have updated the documentation accordingly. +- [ ] `npm run typecheck` passes locally. diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..a381a42 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,44 @@ +changelog: + exclude: + labels: + - ignore-for-release + categories: + - title: Breaking Changes ๐Ÿ’ฅ + labels: + - breaking + - title: Features ๐Ÿš€ + labels: + - feature + - title: Enhancements ๐ŸŒˆ + labels: + - enhancement + - title: Bug Fixes ๐Ÿž + labels: + - bug + - title: Build System ๐Ÿ›  + labels: + - build + - title: Continuous Integration ๐Ÿ”„ + labels: + - ci + - title: Documentation ๐Ÿ“š + labels: + - documentation + - title: Tests ๐Ÿงช + labels: + - test + - title: Refactoring ๐Ÿ›  + labels: + - refactor + - title: Dependency Updates ๐Ÿ“ฆ + labels: + - dependencies + - title: Performance Improvements โšก๏ธ + labels: + - performance + - title: Style ๐Ÿ’… + labels: + - style + - title: Revert ๐Ÿ”„ + labels: + - revert diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..fd02ab2 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,25 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - uses: actions/setup-node@v6 + with: + node-version: 24 + cache: npm + + - run: npm ci + - run: npm run typecheck + - run: npm run build diff --git a/.github/workflows/semantic-pull-request.yml b/.github/workflows/semantic-pull-request.yml new file mode 100644 index 0000000..b2a629e --- /dev/null +++ b/.github/workflows/semantic-pull-request.yml @@ -0,0 +1,66 @@ +name: Validate PR title + +on: + pull_request: + types: + - opened + - reopened + - edited + - synchronize + +permissions: + pull-requests: write + +jobs: + validate-pr: + name: Validate PR title + runs-on: ubuntu-latest + steps: + - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6 + id: lint_pr_title + with: + scopes: | + deps + app + agent + docs + types: | + breaking + feat + fix + build + ci + docs + enhancement + chore + performance + style + test + refactor + revert + subjectPattern: ^(?![A-Z]).+$ + subjectPatternError: | + The subject "{subject}" found in the pull request title "{title}" + didn't match the configured pattern. Please ensure that the subject + doesn't start with an uppercase character. + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4 + if: always() && (steps.lint_pr_title.outputs.error_message != null) + with: + header: pr-title-lint-error + message: | + We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/). + + Details: + + ``` + ${{ steps.lint_pr_title.outputs.error_message }} + ``` + + - if: ${{ steps.lint_pr_title.outputs.error_message == null }} + uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4 + with: + header: pr-title-lint-error + delete: true diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5185f36 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[GitHub issues](https://github.com/browser-use/browser-agent-template/issues). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8c993a2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing to Browser Agent Template + +Thank you for your interest in contributing! + +## Reporting Bugs + +- Search [existing issues](https://github.com/browser-use/browser-agent-template/issues) before opening a new one +- Include steps to reproduce, expected behavior, and actual behavior +- Include your environment (Node version, OS, browser) +- Use the [bug report template](https://github.com/browser-use/browser-agent-template/issues/new?template=bug-report.yml) + +## Suggesting Features + +- Open a [feature request](https://github.com/browser-use/browser-agent-template/issues/new?template=feature-request.yml) +- Describe the use case and why it would be valuable for a **template** (reusable by many forks) +- If possible, outline a proposed implementation + +## Development Setup + +```bash +git clone https://github.com/browser-use/browser-agent-template.git +cd browser-agent-template + +npm install +cp .env.example .env.local +npm run dev +``` + +Set real values in `.env.local`. Never commit secrets. + +## Project Structure + +``` +browser-agent-template/ +โ”œโ”€โ”€ agent/ # Eve agent: channels, tools, skills, sandbox +โ”œโ”€โ”€ app/ # Next.js UI (chat + live browser panel) +โ”œโ”€โ”€ components/ # UI components (ai-elements + shadcn/ui) +โ”œโ”€โ”€ lib/ # Shared utilities +โ””โ”€โ”€ docs/ # Documentation (architecture, env, customization) +``` + +## Making Changes + +1. Fork the repository +2. Create a feature branch (`git checkout -b feat/my-feature`) +3. Make your changes +4. Run checks: + ```bash + npm run typecheck + ``` +5. Commit with a [Conventional Commits](https://www.conventionalcommits.org/) message +6. Open a pull request + +## Pull Request Process + +1. Ensure `npm run typecheck` passes +2. Update documentation if your change affects user-facing behavior +3. Add a clear description of what changed and why +4. Link related issues when applicable + +PR titles must follow Conventional Commits (enforced by CI). Scopes: `app`, `agent`, `docs`, `deps`. + +## Customizing the Template + +If you are forking for your own agent (not contributing upstream), see [docs/CUSTOMIZATION.md](./docs/CUSTOMIZATION.md). + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE). diff --git a/README.md b/README.md index 7179c48..3560085 100644 --- a/README.md +++ b/README.md @@ -6,57 +6,133 @@ # Browser Agent Template -**Template.** Fork it, deploy it, and you have an AI agent that browses the real web. +[![CI](https://img.shields.io/github/actions/workflow/status/browser-use/browser-agent-template/ci.yml?branch=main&color=black)](https://github.com/browser-use/browser-agent-template/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/github/license/browser-use/browser-agent-template?color=black)](https://github.com/browser-use/browser-agent-template/blob/main/LICENSE) +[![Vercel](https://img.shields.io/badge/Vercel-black?logo=vercel&logoColor=white)](https://vercel.com) -A [Vercel **eve**](https://eve.dev) agent with a web chat UI and a [Browser Use](https://browser-use.com) -**cloud browser**. Ask it to look something up, scrape a page, fill a form, or -take a screenshot โ€” and watch it work live. +**Template.** Fork it, customize it, and deploy your own web-browsing agent. -[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fbrowser-use%2Fbrowser-agent-template&env=BROWSER_USE_API_KEY,AI_GATEWAY_API_KEY&envDescription=BROWSER_USE_API_KEY%20from%20browser-use.com%20%7C%20a%20model%20credential%20for%20the%20AI%20Gateway&project-name=browser-agent&repository-name=browser-agent) +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fbrowser-use%2Fbrowser-agent-template&env=BROWSER_USE_API_KEY,AI_GATEWAY_API_KEY&envDescription=BROWSER_USE_API_KEY%20from%20browser-use.com%20%7C%20a%20model%20credential%20for%20the%20AI%20Gateway&envLink=https%3A%2F%2Fgithub.com%2Fbrowser-use%2Fbrowser-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md&project-name=browser-agent&repository-name=browser-agent) --- +Open-source agent that browses the real web. A [Vercel eve](https://eve.dev) agent with a web chat UI and a [Browser Use](https://browser-use.com) cloud browser โ€” one codebase, durable sessions, watch it browse live. + ## Features -- **Web chat UI** โ€” a Next.js chat app (streaming responses, tool calls rendered inline). -- **Cloud browser** โ€” the agent opens a real [Browser Use](https://browser-use.com) browser to navigate, scrape, click, and screenshot the live web. -- **Watch it work** โ€” every browsing session returns a **liveUrl** you can open to watch the browser in real time. -- **Hardened** โ€” your `BROWSER_USE_API_KEY` stays in the app runtime, never in the agent's sandbox. +### Web Chat โ€” Tasks in the Browser + +Chat with your agent in the browser. Responses stream in, and every tool call (open browser, navigate, extract) renders inline as it happens. + +### Cloud Browser โ€” The Real Web + +The agent opens a real [Browser Use](https://browser-use.com) cloud browser to navigate pages, scrape content, fill forms, click, and screenshot โ€” no scraping APIs, the live web. + +### Watch It Work โ€” Live Browser Panel + +Every browsing session returns a **liveUrl**. The UI embeds it in a side panel, so you watch the agent's browser in real time, right next to the chat. + +### Hardened โ€” Key Stays Server-Side + +Your `BROWSER_USE_API_KEY` lives in the app runtime and is never exposed to the agent's sandbox or the model. Browsing is powered by [`@browser_use/eve`](https://www.npmjs.com/package/@browser_use/eve). -Browsing is powered by [`@browser_use/eve`](https://www.npmjs.com/package/@browser_use/eve). +## [Architecture](./docs/ARCHITECTURE.md) + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Web chat (Next.js) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ eve agent (instructions, skill, tools) โ”‚ +โ”‚ mounted into Next.js via withEve() โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ @browser_use/eve โ€” provisions a Browser Use cloud browser โ”‚ +โ”‚ (key stays server-side; agent drives it via CDP) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ–ผ + Browser Use cloud browser +``` + +It's a single Next.js service: `withEve()` in [`next.config.ts`](next.config.ts) mounts the eve agent into the app, so the chat UI and the agent deploy together. ## Quick Start ### Deploy to Vercel -Click the button above. You'll be asked for: +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fbrowser-use%2Fbrowser-agent-template&env=BROWSER_USE_API_KEY,AI_GATEWAY_API_KEY&envDescription=BROWSER_USE_API_KEY%20from%20browser-use.com%20%7C%20a%20model%20credential%20for%20the%20AI%20Gateway&envLink=https%3A%2F%2Fgithub.com%2Fbrowser-use%2Fbrowser-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md&project-name=browser-agent&repository-name=browser-agent) -- `BROWSER_USE_API_KEY` โ€” from [browser-use.com](https://browser-use.com) -- a **model credential** โ€” link the Vercel project for the AI Gateway, or set `AI_GATEWAY_API_KEY` +You'll be asked for a `BROWSER_USE_API_KEY` (from [browser-use.com](https://browser-use.com)) and a model credential (link the Vercel project for the AI Gateway, or set `AI_GATEWAY_API_KEY`). -### Run locally +### Self-hosting -**Requirements:** Node 24+ +**Requirements:** Node.js 24+ ```bash -git clone https://github.com/browser-use/browser-agent-template +git clone https://github.com/browser-use/browser-agent-template.git cd browser-agent-template + npm install -cp .env.example .env.local # fill in BROWSER_USE_API_KEY + a model credential +cp .env.example .env.local npm run dev ``` -Open the app, and ask: *"Go to news.ycombinator.com and give me the top 5 posts."* +Open [http://localhost:3000](http://localhost:3000) and ask: _"Go to news.ycombinator.com and give me the top 5 posts."_ + +**Required environment variables:** + +```bash +BROWSER_USE_API_KEY=bu_... # from browser-use.com +AI_GATEWAY_API_KEY=... # or link a Vercel project for the AI Gateway +``` + +See [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the full reference. + +## Customization + +See the [Customization Guide](./docs/CUSTOMIZATION.md) for how to: + +- Rename your agent and rewrite its instructions +- Change the AI model +- Add tools and skills +- Configure the cloud browser (proxy country, profile, timeouts) +- Set up auth for a public deployment +- Deploy your fork + +## How It Works + +> For the full technical deep-dive, see [Architecture](./docs/ARCHITECTURE.md). + +1. **Chat**: The web UI streams through eve's built-in Web Chat channel (`useEveAgent`). +2. **Browse**: On a web task, the agent loads the `browser-use` skill and calls `open_cloud_browser`. +3. **Provision**: `@browser_use/eve` spins up a Browser Use cloud browser (key stays server-side) and returns a liveUrl. +4. **Drive**: The agent drives the browser with `browser-harness-js` (raw, typed CDP) inside eve's sandbox. +5. **Watch**: The UI embeds the liveUrl in a side panel; `stop_cloud_browser` ends the session. + +## Development + +```bash +npm run dev # Start the dev server (Next.js + eve) +npm run typecheck # TypeScript check +npm run build # Production build +``` + +See [AGENTS.md](./AGENTS.md) for notes aimed at AI coding assistants. + +## Built With + +- [eve](https://eve.dev) โ€” Durable agent framework +- [@browser_use/eve](https://www.npmjs.com/package/@browser_use/eve) โ€” Browser Use cloud browser for eve +- [Browser Use](https://browser-use.com) โ€” Cloud browser infrastructure +- [Next.js](https://nextjs.org) โ€” React framework +- [AI SDK](https://ai-sdk.dev) โ€” Model access -## How it works +## Contributing -- The chat UI is [eve](https://eve.dev)'s built-in Web Chat (Next.js), mounted via `withEve()` in `next.config.ts`. -- The agent's browsing comes from `@browser_use/eve` โ€” four thin files under `agent/` (`sandbox`, `skills/browser-use`, `tools/open_cloud_browser`, `tools/stop_cloud_browser`). -- On a browse request: `open_cloud_browser` provisions a cloud browser (key stays app-side) โ†’ the agent drives it with `browser-harness-js` โ†’ `stop_cloud_browser` ends it. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved. -## Customize +## License -- **Identity / behavior:** `agent/instructions.md` -- **Model:** `agent/agent.ts` -- **Auth:** `agent/channels/eve.ts` ships with a placeholder that blocks browser requests in production. For an open public demo use `none()` (anyone can use your keys/credits โ€” be careful); for real users add an auth provider (Auth.js, Clerk). -- **More browser config** (proxy country, profile, timeouts): see [`@browser_use/eve`](https://www.npmjs.com/package/@browser_use/eve). +[MIT](./LICENSE) diff --git a/agent/agent.ts b/agent/agent.ts index 93c6a6f..8a41a99 100644 --- a/agent/agent.ts +++ b/agent/agent.ts @@ -1,5 +1,5 @@ import { defineAgent } from "eve"; export default defineAgent({ - model: "anthropic/claude-sonnet-4.6", + model: "anthropic/claude-opus-4.8", }); diff --git a/app/_components/agent-chat.tsx b/app/_components/agent-chat.tsx index 449c107..aeee9e9 100644 --- a/app/_components/agent-chat.tsx +++ b/app/_components/agent-chat.tsx @@ -1,6 +1,6 @@ "use client"; -import { useEveAgent } from "eve/react"; +import { type EveMessage, useEveAgent } from "eve/react"; import { AlertCircleIcon } from "lucide-react"; import { Conversation, @@ -15,16 +15,34 @@ import { } from "@/components/ai-elements/prompt-input"; import { cn } from "@/lib/utils"; import { AgentMessage } from "./agent-message"; +import { BrowserPanel } from "./browser-panel"; const AGENT_NAME = "browser-agent-template"; const BETA_TERMS_HREF = "https://vercel.com/docs/release-phases/public-beta-agreement"; type AgentStatus = ReturnType["status"]; +/** The latest cloud-browser liveUrl, found anywhere in the conversation (the + * open_cloud_browser tool result or the agent's text). */ +function extractLiveUrl(messages: readonly EveMessage[]): string | null { + // Origin-safe: only match when the host is followed by a path/query/fragment + // or a boundary โ€” so userinfo tricks like ...com@evil.com don't slip through. + const re = /\bhttps:\/\/live\.browser-use\.com(?:[/?#][^\s"'\\]*)?(?=$|[\s"'\\])/; + let found: string | null = null; + for (const message of messages) { + for (const part of message.parts) { + const match = JSON.stringify(part).match(re); + if (match) found = match[0]; + } + } + return found; +} + export function AgentChat() { const agent = useEveAgent(); const isBusy = agent.status === "submitted" || agent.status === "streaming"; const isEmpty = agent.data.messages.length === 0; + const liveUrl = extractLiveUrl(agent.data.messages); const handleSubmit = async (message: PromptInputMessage) => { const text = message.text.trim(); @@ -41,7 +59,8 @@ export function AgentChat() { ); return ( -
+
+
{isEmpty ? null : (
@@ -113,7 +132,9 @@ export function AgentChat() { ) : null}
{composer}
-
+ + {liveUrl ? : null} + ); } diff --git a/app/_components/browser-panel.tsx b/app/_components/browser-panel.tsx new file mode 100644 index 0000000..f60a6e6 --- /dev/null +++ b/app/_components/browser-panel.tsx @@ -0,0 +1,21 @@ +"use client"; + +/** A live view of the agent's cloud browser โ€” just an iframe of the liveUrl. */ +export function BrowserPanel({ liveUrl }: { readonly liveUrl: string }) { + return ( +