diff --git a/app/en/get-started/agent-frameworks/langchain/use-arcade-with-langchain/page.mdx b/app/en/get-started/agent-frameworks/langchain/use-arcade-with-langchain/page.mdx index fee9dc3d1..355b3e2ea 100644 --- a/app/en/get-started/agent-frameworks/langchain/use-arcade-with-langchain/page.mdx +++ b/app/en/get-started/agent-frameworks/langchain/use-arcade-with-langchain/page.mdx @@ -3,11 +3,15 @@ title: "Setup Arcade with LangChain" description: "Learn how to use Arcade tools in LangChain agents" --- + + 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. @@ -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 @@ -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 @@ -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({ @@ -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.` ); @@ -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) @@ -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. @@ -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( @@ -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 @@ -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") { @@ -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 @@ -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. @@ -520,14 +524,14 @@ 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, @@ -535,7 +539,7 @@ function executeOrInterruptTool({ 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, @@ -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.` ); @@ -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") { @@ -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 @@ -739,4 +743,4 @@ async function main() { // Run the main function main().catch((err) => console.error(err)); ``` - + \ No newline at end of file