Skip to content

Stable URLs for A2

Jump to bottom
Dimitri Glazkov edited this page Apr 10, 2025 · 7 revisions

The current problems we're experiencing stem from the fact that A2 paths change based on the environment (prod/dev) and the prod deployment of A2 requires a special user "@shared". The problem with the former is two-fold: 1) to push to prod, we have to manually adjust all URLs in the BGL files to point to a different location, which is super-fiddly and 2) there may be duplicates or triplicates of A2 steps/tools appearing in user menu. The problem with the latter is that as we move closer to the unique IDs for BGL, we need the user IDs less and less, and the presence of "@shared" prevents us from removing user IDs from paths, etc.

To solve for this, we'd like to introduce stable URLs for all BGL files in the A2 framework.

The approach

The general approach is:

  1. create a special read-only "board server" that provides a stable URL for the A2 BGL files. This server will be assembled at compile time and all the BGL files from it are preloaded.
  2. make sure that only BGL files from this stable URL are recognized as the official "A2" bits.

This solution will allow us to address all of the issues above. Additionally:

  • it allows us to use the latest A2 bits in sideboards
  • it puts A2 releases in lockstep with deployments

Implementation details

There are two parts: the embedded board server and the translation of existing steps to the new format.

Embedded board server

The embedded board server is a new package, @breadboard-ai/embedded-board-server, which allows taking a bunch of BGL files and turning them into a read-only server for a fixed number of BGLs with stable URLs. The URL format is:

embed://[server-name]/[filename].bgl.json

For A2, the server-name will be a2, so all URLs will be of the format

embed://a2/[filename].bgl.json

Translation of existing steps

To ensure that the existing BGLs work with the new setup, we'll take a three-step approach:

Step 1: Allow the new A2 steps to operate side-by-side with the existing ones served from the @shared user space, with all new instances created using the new stable URLs.

This will involve:

  • switching the fast access, component selector, and organizer UI bits to only draw from the A2 board server
  • manually replacing internal (within A2) references to A2 exports with stable URLs.

Step 2: Remap all references to old A2 steps with the ones to the new URL.

  • writing a script to allow remapping steps (fix #4917)
  • running that script on existing deployments
  • verifying there are no more old A2 references

Step 3: Remove @shared user BGLs from the server

  • deleting the BGL files.

Developing A2

To develop A2 in the new stable URL world:

  • start Visual Editor (the Unified Server will not work)
(cd packages/visual-editor && npm run dev)

  • mount the a2/bgl directory as a file system board server

  • make changes in the A2 files

  • reload the page for them to take change

Clone this wiki locally