Link

Learn how to setup the UI component for your users to authenticate.

Merge Agent Handler Link is the frontend UI component that your users will input their credentials into in order to make authenticated tool calls.

When to call Link?

Before your user can make authenticated tool calls, there must be credentials associated with the given user. There are two ways to gather credentials from a given user:

1. At query time using tool call - if your user prompts an action that requires interacting with a connector they have not authenticated to, your LLM will call the authenticate_meta tool for the given connector. The authenticate_meta tool will respond with a linkToken that must be used to open Merge Agent Handler Link and collect the connector credentials.

2. Ad-hoc using endpoint - if your user authenticates to the different systems they use prior to interacting with your agent. This method can be used if you have a Settings or Connectors page. You can call our /link-token API endpoint to get a linkToken, which can be used to open Merge Agent Handler Link and collect connector credentials.

How to call Link?

Step 1: Grab link token

As mentioned above, there are two ways to get a link token from Merge. It can be done through the calling of the authenticate_meta tool, or via the /link-token endpoint.

1. At query time using tool call:

In your backend, build a way to collect the linkToken when the authenticate_meta tool is called for a given user.

1
if (
2
  obj.event === "function_call" &&
3
  obj.tool_name.startsWith("authenticate_")
4
) {
5
  setLinkToken(obj.result);
6
}

2. Ad-hoc using endpoint:

In your backend, set up a POST request to initialize a Merge Link session and get a link_token from this URL:

URL: /api/registered-users/<registered-user-id>/link-token

POST Request Body:

1
{
2
  "connector": "<connector-slug>"
3
}

Step 2: Make Merge Agent Handler Link appear in your product

In your frontend, use the linkToken from the step 1 to open Merge Agent Handler Link. The Merge Agent Handler react component can be found here.

1
import { useAgentHandlerLink } from "@mergeapi/react-agent-handler-link";
2
3
const { open: openLink, isReady} = useAgentHandlerLink({
4
  linkToken: "<ADD-GENERATED-LINK-TOKEN>",
5
  onSuccess: () => {},
6
  onExit: () => {
7
    setLinkToken(undefined);
8
  },
9
});

1
open()

Step 3: User authenticates

Now that you’ve opened Merge Agent Handler Link, your user can input their credentials to authenticate to a given a connector. Once the process is completed, your user can now access the rest of the tools enabled within your tool pack and make authenticated tool calls!