Connectors - breadboard-ai/breadboard GitHub Wiki

Connectors provide an extensibility point for Breadboard. The core idea behind Connectors is to allow integration a variety of external sources and sinks in a way that feels intuitive and consistent with the UX patterns already present in Breadboard (chiclets, assets, tools, etc.)

At a very high level, a connector is a bundle of tools. These tools are bundled around a particular integration. For example, a Github Connector might contain multiple tools that allow an LLM to operate on a Github repository. In this way, connectors are spiritually similar to the set of tools, exposed by an MCP server.

Some of these tools are assigned a special meaning.

For example, unlike in MCP, there's one tool that is designated as the configurator, and its purpose is to do the necessary work of creating a new instance of a connector.

Practically, a Connector is a BGL file with multiple exports that meets these requirements:

  • it must have a connector tag in its metadata
  • it must have at least one export
  • it may have a connector-singleton tag in its metadata. This indicates that only one instance of a connector can be created.
  • one of its exports must have a connector-configure tag. This export will be called the configurator export.
  • it may have exactly one export with the connector-load tag. If more exports have the same tag, they will be ignored. This export will be called the load export.
  • the load export must have two input ports: instruction: LLMContent and context: LLMContext[] and one context: LLMContent[] output port.
  • it may have exactly one export with the connector-save tag. If more exports have the same tag, they will be ignored. This export will be called the save export.
  • the save export must have context: LLMContent[] input port and context: LLMContent[] output port, passing through the saved data.
  • it may have exactly one export with the connector-tools tag. If more exports have the same tag, they will be ignored. This export will be called the tools export.

When a BGL file has the "published" tag in its metadata, this tells Breadboard that this file is a published connector and it is ready to be used.

Creating a connector instance

Similar to type/instance distinction in programming, each connector represents a type of connection. To make an instance of a connector, the user goes to the asset organizer and selects "Add Connector", then picks from the list of published connectors. The connector may optionally present UI to help with configuration. When the user submits the form, the configuration process begins (some UX affordance). Once configured, the connector instance shows up in the asset organizer. Just like with other assets, the user can rename or delete it.

Implementation details

The configuration has the following methods:

  • initialize -- create initial configuration for the connector instance. Here, the configurator can do some additional work that might be necessary to establish an instance. For example, the Semantic Retriever connector might create a new corpus.

  • read -- read the current state of the configuration. Here, the configurator reads the current instance configuration and returns the schema and the values (very similar to output node) that are to be presented to the user for editing. For instance, the describer might request the user or project name for the Github connector.

  • write - write the values and the configuration supplied and return new configuration value.

  • preview -- similar to read, except it returns an LLMContent value that can be shown as a preview of the connector instance's current state.

When a new instance is created, the methods are called in this sequence:

  1. initialize to create initial configuration
  2. read to create the edit view for the user
  3. wait for the user to edit and submit changes
  4. write to write the changes

When an existing instance is edited, the sequence goes like this:

  1. read to create the edit view for the user
  2. wait for the user to edit and submit changes
  3. write to write the changes

Each method is a stage argument to the configurator export.

Breadboard stores the value that was returned by at the end of the sequence as an asset in /assets/connectors/[instance id] in Breadboard File System. The asset contains two values:

  • url, which is the URL to the connector BGL
  • configuration, which is JSON of the configuration.

Calling tools using tools export

The tools export provides a way for a connector to provide a list of tools that varies between connector instances. For example the list of tools provided by an "MCP Server" connector will vary based on the MCP Server endpoint URL.

The tools export provides discovery and invocation capabilities, separated as methods. The method parameter must be passed during tool export invocation.

There are two methods:

  • list -- return a list of tools provided by this connector instance
  • call -- invoke a specified tool and return the results

Using a connector with the "@" menu

When the user opens the "@" menu, they will see connector instances in these forms:

  • if the connector has the load export, the connector will show up as an asset and can be added as an asset
  • all other exports will show up as a single tool bundle.

When added as an asset, the connector will behave as if it is a regular asset: reading from it will be transparent as if it's a PDF document or text.

When added as tools, the tools export will be used to manage discovery and invocation of tools.

Implementation details sketch

The process of turning a reference to a connector into an asset is called materialization. Materialization happens in the A2 framework.

When connector is added as asset, the chiclet is of type asset, and the path points to the /assets/connectors/* path. This allows the A2 framework to detect connector assets and process them differently.

The A2 framework reads the file at the path, which should contain the URL to the connector. It then

  • invokes the describer for the connector
  • finds the load export.
  • invokes the load export, passing instruction and context, reads the result, and makes the substitution.

Passing instruction and context allows "contextual assets": we can let the asset export adjust what it returns based on them. For instance, it could make an additional LLM call inside of the tool to generate a search query for Google Drive connector, so that it returns back not the entire folder contents, but only entries that match the query.

Using connector to save outputs

When selecting a connector to save outputs, the usage pattern is similar, but instead of assets and tools, only the connectors that are "savable" show.

The connector is savable when it:

  • has a save export
  • the save export reports that this instance accepts saving outputs

Implementation details

The save export accepts a method parameter, which can be one of these two values:

  • canSave -- when this value is supplied, the export will return a boolean canSave output that reports whether or not this particular instance of a connector can be saved
  • save -- when this value is supplied, the export will attempt to save the value provided in the context prarameter into the connector.

If the parameter is not supplied, the export must return an error.

Other parameters supplied:

  • context -- the LLMContent[] of the data to save (ignored when canSave is used)
  • id -- the id of the connector instance
  • info -- the connector instance info.

The info parameter structure is:

export type ConnectorInfo<
  C extends Record<string, JsonSerializable> = Record<string, JsonSerializable>,
> = {
  /**
   * The URL of the connector
   */
  url: string;
  /**
   * The configuration of the connector
   */
  configuration: C;
};

Relevant Concepts

Tool Bundle

A tool bundle looks like a single item in "@" menu, but when inserted, it will automatically expand as multiple tools. For example, I may have "GMail tools" bundle in the "@" menu. When I select it, multiple tools will be added: "read 10 emails", "send email", etc.

"Save Outputs" step

A step that has a single configuration port that allows opening the "@" menu that is limited to only save exports and other node outputs. The key difference with "Combine Outputs" is that the UI only allows adding chiclets, and not other text.