Skip to content

Editorial improvements for #669 #688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Editorial improvements for #669 #688

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 32 additions & 28 deletions app/en/get-started/agent-frameworks/langchain/use-arcade-with-langchain/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,15 @@ title: "Setup Arcade with LangChain"
description: "Learn how to use Arcade tools in LangChain agents"
---

<!-- Editorial: Voice and tone - Changed "we" references that referred to reader as part of Arcade team; Structure - Added intro line and improved page structure -->

import { Steps, Tabs, Callout } from "nextra/components";

# Setup Arcade with LangChain

LangChain is a popular agentic framework that abstracts a lot of the complexity of building AI agents. It is built on top of LangGraph, a lower level orchestration framework that offers more control over the inner flow of the agent.
Learn how to integrate Arcade tools into LangChain agents using LangChain primitives.

LangChain is a popular agentic framework that abstracts a lot of the complexity of building AI agents. LangGraph builds it on top of a lower level orchestration framework that offers more control over the inner flow of the agent.

<GuideOverview>
<GuideOverview.Outcomes>
Expand Down Expand Up @@ -35,11 +39,11 @@ Learn how to integrate Arcade tools using LangChain primitives

## LangChain primitives you will use in this guide

LangChain provides multiple abstractions for building AI agents, and it's very useful to internalize how some of these primitives work, so you can understand and extend the different agentic patterns LangChain supports.
LangChain provides multiple abstractions for building AI agents, and understanding some of these primitives helps you understand and extend the different agentic patterns LangChain supports.

- [_Agents_](https://docs.langchain.com/oss/javascript/langchain/agents): Most agentic frameworks, including LangChain, provide an abstraction for a ReAct agent.
- [_Interrupts_](https://docs.langchain.com/oss/javascript/langgraph/interrupts): Interrupts in LangChain are a way to control the flow of the agentic loop when something needs to be done outside of the normal ReAct flow. For example, if a tool requires authorization, you can interrupt the agent and ask the user to authorize the tool before continuing.
- [_Checkpointers_](https://docs.langchain.com/oss/javascript/langgraph/persistence): Checkpointers are how LangChain implements persistence. A checkpointer stores the agent's state in a "checkpoint" that can be resumed later. Those checkpoints are saved to a _thread_, which can be accessed after the agent's execution, making it very simlpe for long-running agents and for handling interruptions and more sophisticated flows such as branching, time travel, and more.
- [_Interrupts_](https://docs.langchain.com/oss/javascript/langgraph/interrupts): Interrupts in LangChain allow you to control the flow of the agentic loop when something needs to happen outside of the normal ReAct flow. For example, if a tool requires authorization, you can interrupt the agent and ask the user to authorize the tool before continuing.
- [_Checkpointers_](https://docs.langchain.com/oss/javascript/langgraph/persistence): Checkpointers are how LangChain implements persistence. A checkpointer stores the agent's state in a "checkpoint" that you can resume later. The system saves those checkpoints to a _thread_, which you can access after the agent's execution, making it simple for long-running agents and for handling interruptions and more sophisticated flows such as branching, time travel, and more.

## Integrate Arcade tools into a LangChain agent

Expand Down Expand Up @@ -85,27 +89,27 @@ import chalk from "chalk";
import readline from "node:readline/promises";
```

This is quite a number of imports, let's break them down:
This is a number of imports, here's the breakdown:

- Arcade imports:
- `Arcade`: This is the Arcade client, used to interact with the Arcade API.
- `Arcade`: This is the Arcade client, which you use to interact with the Arcade API.
- `type ToolExecuteFunctionFactoryInput`: Encodes the input to execute Arcade tools.
- `isAuthorizationRequiredError`: Checks if a tool requires authorization.
- `toZod`: Converts an Arcade tool definition into a [Zod](https://zod.dev) schema (Zod provides type safety and validation at runtime).
- `executeZodTool`: Executes an Zod-converted tool.
- `executeZodTool`: Executes a Zod-converted tool.
- LangChain imports:
- `createAgent`: Creates a LangChain agent using the ReAct pattern.
- `tool`: Turns an Arcade tool definition into a LangChain tool.
- `interrupt`: Interrupts the ReAct flow and asks the user for input.
- `Command`: Communicates the user's decisions to the agent's interrupts.
- `MemorySaver`: Stores the agent's state, and is required for checkpointing and interrupts.
- `MemorySaver`: Stores the agent's state, and the system requires it for checkpointing and interrupts.
- Other imports:
- `chalk`: This is a library to colorize the console output.
- `readline`: This is a library to read input from the console.

### Configure the agent

These variables are used in the rest of the code to customize the agent and manage the tools. Feel free to configure them to your liking.
These variables apply to the rest of the code to customize the agent and manage the tools. Feel free to configure them to your liking.

```ts filename="main.ts"
// configure your own values to customize your agent
Expand All @@ -129,7 +133,7 @@ const threadID = "1";

### Write a helper function to execute Arcade tools

This is a wrapper around the `executeZodTool` function. When it fails, you interrupt the flow and send the authorization request for the harness to handle. If the user authorizes the tool, the harness will reply with an `{authorized: true}` object, and the tool call will be retried without interrupting the flow.
This is a wrapper around the `executeZodTool` function. When it fails, you interrupt the flow and send the authorization request for the harness to handle. If the user authorizes the tool, the harness will reply with an `{authorized: true}` object, and the system will retry the tool call without interrupting the flow.

```ts filename="main.ts"
function executeOrInterruptTool({
Expand Down Expand Up @@ -176,7 +180,7 @@ function executeOrInterruptTool({
})(input);
return result;
} else {
// If the user didn't authorize the tool, throw an error, which will be handled by LangChain
// If the user didn't authorize the tool, throw an error, which LangChain will handle
throw new Error(
`Authorization required for tool call ${toolName}, but user didn't authorize.`
);
Expand All @@ -192,7 +196,7 @@ function executeOrInterruptTool({

Here you get the Arcade tools you want the agent to use, and transform them into LangChain tools. The first step is to initialize the Arcade client, and get the tools you want to use. Then, use the `toZod` function to convert the Arcade tools into a Zod schema, and pass it to the `executeOrInterruptTool` function to create a LangChain tool.

This helper function is fairly long, here's a breakdown of what it does for clarity:
This helper function is long, here's a breakdown of what it does for clarity:

- retrieve tools from all configured MCP servers (defined in the `MCPServers` variable)
- retrieve individual tools (defined in the `individualTools` variable)
Expand Down Expand Up @@ -281,7 +285,7 @@ const tools = await getTools({

### Write the interrupt handler

In LangChain, each interrupt needs to be "resolved" for the flow to continue. In response to an interrupt, you need to return a decision object with the information needed to resolve the interrupt. In this case, the decision is whether the authorization was successful, in which case the tool call will be retried, or if the authorization failed, the flow will be interrupted with an error, and the agent will decide what to do next.
In LangChain, each interrupt needs a "resolution" for the flow to continue. In response to an interrupt, you need to return a decision object with the information needed to resolve the interrupt. In this case, the decision is whether the authorization was successful, in which case the system will retry the tool call, or if the authorization failed, the system will interrupt the flow with an error, and the agent will decide what to do next.

This helper function receives an interrupt and returns a decision object. Decision objects can be of any serializable type (convertible to JSON). In this case, you return an object with a boolean flag indicating if the authorization was successful.

Expand Down Expand Up @@ -336,7 +340,7 @@ const agent = createAgent({

### Write the invoke helper

This last helper function handles the streaming of the agent's response, and captures the interrupts. When an interrupt is detected, it is added to the `interrupts` array, and the flow is interrupted. If there are no interrupts, it will just stream the agent's to your console.
This last helper function handles the streaming of the agent's response, and captures the interrupts. When the system detects an interrupt, it adds it to the `interrupts` array, and the flow pauses. If there are no interrupts, it will just stream the agent's response to your console.

```ts filename="main.ts"
async function streamAgent(
Expand Down Expand Up @@ -370,7 +374,7 @@ async function streamAgent(

Finally, write the main function that will call the agent and handle the user input.

Here the `config` object is used to configure the `thread_id`, which tells the agent to store the state of the conversation into that specific thread. Like any typical agent loop, you:
Here the `config` object configures the `thread_id`, which tells the agent to store the state of the conversation into that specific thread. Like any typical agent loop, you:

1. Capture the user input
1. Stream the agent's response
Expand All @@ -387,7 +391,7 @@ async function main() {
output: process.stdout,
});

console.log(chalk.green("Welcome to the chatbot! Type 'exit' to quit."));
console.log(chalk.green("Welcome to the chatbot Type 'exit' to quit."));
while (true) {
const input = await rl.question("> ");
if (input.toLowerCase() === "exit") {
Expand All @@ -405,13 +409,13 @@ async function main() {
const interrupts = await streamAgent(agent, agentInput, config);

if (interrupts.length === 0) {
break; // No more interrupts, we're done
break; // No more interrupts, finished
}

// Handle all interrupts
const decisions: any[] = [];
for (const interrupt of interrupts) {
decisions.push(await handleAuthInterrupt(interrupt, rl));
decisions.push(await handleAuthInterrupt(interrupt));
}

// Resume with decisions, then loop to check for more interrupts
Expand Down Expand Up @@ -449,11 +453,11 @@ You should see the agent responding to your prompts like any model, as well as h

## Key takeaways

- Arcade tools can be integrated into any agentic framework like LangChain, all you need is to transform the Arcade tools into LangChain tools and handle the authorization flow.
- You can integrate Arcade tools into any agentic framework like LangChain, all you need is to transform the Arcade tools into LangChain tools and handle the authorization flow.
- Context isolation: By handling the authorization flow outside of the agent's context, you remove the risk of the LLM replacing the authorization URL or leaking it, and you keep the context free from any authorization-related traces, which reduces the risk of hallucinations.
- You can leverage the interrupts mechanism to handle human intervention in the agent's flow, useful for authorization flows, policy enforcement, or anything else that requires input from the user.

## Next Steps
## Next steps

1. Try adding additional tools to the agent or modifying the tools in the catalog for a different use case by modifying the `MCPServers` and `individualTools` variables.
2. Try refactoring the `handleAuthInterrupt` function to handle more complex flows, such as human-in-the-loop.
Expand Down Expand Up @@ -520,22 +524,22 @@ function executeOrInterruptTool({
})(input);
return result;
} catch (error) {
// If the tool requires authorization, we interrupt the flow and ask the user to authorize the tool
// If the tool requires authorization, interrupt the flow and ask the user to authorize the tool
if (error instanceof Error && isAuthorizationRequiredError(error)) {
const response = await client.tools.authorize({
tool_name: toolName,
user_id: userId,
});

// We interrupt the flow here, and pass everything the handler needs to get the user's authorization
// Interrupt the flow here, and pass everything the handler needs to get the user's authorization
const interrupt_response = interrupt({
authorization_required: true,
authorization_response: response,
tool_name: toolName,
url: response.url ?? "",
});

// If the user authorized the tool, we retry the tool call without interrupting the flow
// If the user authorized the tool, retry the tool call without interrupting the flow
if (interrupt_response.authorized) {
const result = await executeZodTool({
zodToolSchema,
Expand All @@ -545,7 +549,7 @@ function executeOrInterruptTool({
})(input);
return result;
} else {
// If the user didn't authorize the tool, we throw an error, which will be handled by LangChain
// If the user didn't authorize the tool, throw an error, which LangChain will handle
throw new Error(
`Authorization required for tool call ${toolName}, but user didn't authorize.`
);
Expand Down Expand Up @@ -693,7 +697,7 @@ async function main() {
output: process.stdout,
});

console.log(chalk.green("Welcome to the chatbot! Type 'exit' to quit."));
console.log(chalk.green("Welcome to the chatbot Type 'exit' to quit."));
while (true) {
const input = await rl.question("> ");
if (input.toLowerCase() === "exit") {
Expand All @@ -711,13 +715,13 @@ async function main() {
const interrupts = await streamAgent(agent, agentInput, config);

if (interrupts.length === 0) {
break; // No more interrupts, we're done
break; // No more interrupts, finished
}

// Handle all interrupts
const decisions: any[] = [];
for (const interrupt of interrupts) {
decisions.push(await handleAuthInterrupt(interrupt, rl));
decisions.push(await handleAuthInterrupt(interrupt));
}

// Resume with decisions, then loop to check for more interrupts
Expand All @@ -739,4 +743,4 @@ async function main() {
// Run the main function
main().catch((err) => console.error(err));
```
</details>
</details>