Install both packages and mount your first agent.

1. Install frontend widget (npm)

npm i bsquare-widget

If you prefer a script tag bundle, use the global build file from your static assets pipeline.

2. Install backend host package (Python)

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install getbsquare

Package name on PyPI is getbsquare. Import path in code is bsquare_host.

3. Minimal backend (FastAPI + PydanticAI)

from dataclasses import dataclass

from fastapi import FastAPI
from pydantic_ai import Agent, RunContext
from bsquare_host import AgentState, host_action_proxy, mount_agent_app

@dataclass
class State(AgentState):
    pass

@dataclass
class Deps:
    state: State

agent = Agent("google-gla:gemini-2.5-flash", deps_type=Deps)

@agent.tool
@host_action_proxy(timeout=3.0, auto_format=True)
async def navigate_to_page(ctx: RunContext[Deps], page: str) -> str:
    return f"Navigated to {page}"

app = FastAPI()
mount_agent_app(agent, app, lambda: Deps(state=State()), cors_origins=["*"])

4. Minimal frontend mount

<script src="bsquare-widget.global.js"></script>
<script>
  window.BSquare.mountAgent({
    apiUrl: "https://your-backend.example.com",
    hostActions: [
      {
        name: "navigate_to_page",
        description: "Go to a section",
        parameters: { page: { type: "string", required: true } },
        handler: (p) => {
          location.hash = p.page;
          return { success: true };
        }
      }
    ]
  });
</script>