feat(examples): add browser-based agent example

[michaelruelas]

Description

This PR adds a new example in examples/browser-agent that demonstrates how to implement a Strands Agent in a browser environment.

The example includes:

• Interactive UI: A simple HTML/Tailwind interface with a chat window and a modifiable canvas (DOM element).
• Browser-Ready Agent: Configures OpenAIModel with dangerouslyAllowBrowser: true to run client-side.
• Custom Tool: Implements update_canvas to demonstrate how agents can interact with the webpage DOM.
• Vite Integration: Includes configuration for developing and building the agent with Vite, using path aliases to link against the local SDK source.
• Documentation: Includes a dedicated README for the example and updates the root README.

Related Issues

Closes #382

Documentation PR

N/A

Type of Change

• New feature
• Documentation update

Testing

I manually verified the example by running it locally and interacting with the agent to request UI changes. I captured a demonstration of the agent successfully modifying the canvas based on natural language commands.
I also verified the build pipeline:

• I ran npm run build in examples/browser-agent (verified passing with aligned dependencies)
• I ran npm run check (SDK root tests passing)

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works (Manual verification example provided)
• I have updated the documentation accordingly (Added examples/browser-agent/README.md and updated root README)
• I have added an appropriate example to the documentation to outline the feature
• My changes generate no new warnings
• Any dependent changes have been merged and published

[cagataycali]

👀 Initial Review - Browser Agent Example

Summary

Great example demonstrating browser-based Strands agents! This addresses the "good first issue" #382 nicely.

What I Like

• ✅ Clear PR description with all checklist items completed
• ✅ Proper documentation (README in example + root README update)
• ✅ Demonstrates real DOM manipulation (update_canvas tool)
• ✅ Uses dangerouslyAllowBrowser: true correctly with OpenAI
• ✅ Vite integration for modern development workflow

Observations

The CI is still pending (waiting for integration tests). Once CI passes, this looks ready for maintainer review.

Questions for Maintainers

1. Is the dangerouslyAllowBrowser approach acceptable, or should there be additional warnings in the docs about API key security?
2. Any concerns about the Vite path alias configuration linking to local SDK source?

Looking forward to seeing this merged - it will be a valuable example for the community! 🦆

[Unshure]

I just tried running this example, and it seems like the chat experience is broken now?

Im getting this error when I try to send a message:

Uncaught TypeError: can't access property "_zod", schema is undefined
    process to-json-schema.js:15
    process to-json-schema.js:340
    process to-json-schema.js:539
    process to-json-schema.js:52
    process to-json-schema.js:211
    toJSONSchema to-json-schema.js:819
    ZodTool zod-tool.ts:91
    tool zod-tool.ts:237
    <anonymous> tools.ts:3
[to-json-schema.js:15:21](http://localhost:5173/node_modules/zod/v4/core/to-json-schema.js)
    process to-json-schema.js:15
    process to-json-schema.js:340
    process to-json-schema.js:539
    process to-json-schema.js:52
    process to-json-schema.js:211
    toJSONSchema to-json-schema.js:819
    ZodTool zod-tool.ts:91
    tool zod-tool.ts:237
    <anonymous> tools.ts:3

[github-actions]

@Unshure The Zod error can't access property "_zod", schema is undefined occurs when Vite bundles multiple Zod instances instead of deduplicating them properly.

Root cause: The example has zod as a direct dependency while the SDK also has it as a peer dependency. This creates two separate Zod instances, and z.toJSONSchema() fails because schemas from one instance aren't recognized by the other.

Fix: Remove zod from examples/browser-agent/package.json dependencies and regenerate the lockfile. The example will use the zod version installed at the root level.

@michaelruelas could you verify this fix resolves the issue?

[Unshure]

Hi @michaelruelas, I was messing around with this example locally and made some changes to address the comments I had. I'm going to review this with the rest of my team to try and get it merged asap.

[michaelruelas]

My apologies for the delay in making these changes! 😅 I've updated the browser-agent example to address the feedback and improve the overall developer experience:

Bug Fixes & Security

• Dependency Cleanup: Removed direct zod dependency to resolve schema mismatch errors caused by duplicate instances.
• Security Hardening: Removed eval() execution and the script parameter from tools to eliminate XSS risks.
• Robust Streaming: Added error handling for Markdown parsing to prevent crashes during message streaming.
• Resilient Initialization: Fixed a bug where missing API keys would crash the entire script; the UI (including Settings) now remains interactive even before configuration.

UX & UI Updates

• New Side-by-Side Layout: Redesigned the interface to position the canvas on the left and the chat on the right for better visibility.
• Flexible Configuration: Added an optional OpenAI Base URL override in the settings to support local or alternative endpoints.
• Modernized Model: Switched the default model to a more lightweight and modern option (gpt-5.1-codex-mini).
  Safety Notice: Added a clear warning banner in the UI indicating the example is not production-ready.

Verified with a clean build and ready for review! 🎨✨

[michaelruelas]

In hindsight, perhaps Homer Simpson was not the best example.

[Unshure]

@michaelruelas Are you interested in addressing this feedback? Im happy to take over this pull request and get it merged. I think it brings a lot of value and would like to get it merged soon

[Unshure]

Make this not readonly so we can easily reset the messages array like this:

agent.messages = []

[github-actions]

Note: This changes the public API by removing readonly from the messages property.

This is a reasonable change that enables agent.messages = [] for clearing conversation history. However, since it's a public API change:

1. Users can now accidentally overwrite the messages array with a different object
2. Consider if a clearMessages() method would be a safer API

If the team has discussed this and decided direct assignment is the preferred pattern, this is fine. Just flagging for visibility since it wasn't explicitly mentioned in the PR description.

[Unshure]

@pgrayy Any concerns with this?

[github-actions]

Assessment: Comment (Updated from Request Changes)

Great progress addressing the previous feedback! The critical Zod dependency issue has been fixed, and several other improvements have been made.

Review Summary

Fixed ✅

• Removed zod from direct dependencies (fixes the critical schema error)
• Added error handling for marked.parse()
• Improved credential storage (in-memory instead of localStorage)
• Cleaner project structure (removed unnecessary config files)
• Better UI layout

Needs Clarification 🔍

• The PR comment states eval() was removed, but it's still present in tools.ts. Please clarify if this is intentional or needs to be addressed.

For Awareness 📋

• The SDK change (messages no longer readonly) is a public API modification. If the team has approved this pattern, it's fine.

The example now demonstrates browser-based agents effectively. Nice work on the improvements! 🎉