Skip to main content
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?

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. Sample code: 
if (
  obj.event === "function_call" &&
  obj.tool_name.startsWith("authenticate_")
) {
  setLinkToken(obj.result);
}
  1. 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: 
{
  "connector": "<connector-slug>"
}
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. 
import { useAgentHandlerLink } from "@mergeapi/react-agent-handler-link";

const { open: openLink, isReady} = useAgentHandlerLink({
  linkToken: "<ADD-GENERATED-LINK-TOKEN>",
  onSuccess: () => {},
  onExit: () => {
    setLinkToken(undefined);
  },
});

open()
ParameterTypeDescription
linkTokenstringInitializing token from step 1
onSuccessfunctionFunction you can define to signal when there is a successful authentication of the user
onExitfunctionFunction you can define to signal when there is a failed authentication of the user

​
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!