Connect applications to agents

This tutorial shows you how to connect a JavaScript application to a SkillFlaw agent.

With an agent, your application can use any connected tools to retrieve more contextual and timely data without changing any application code. The tools are selected by the agent's internal LLM to solve problems and answer questions.

Prerequisites

• Install and start SkillFlaw
• Create a SkillFlaw API key
• If you plan to use the JavaScript example, use Node.js 18+ or another runtime with fetch support
• Create an OpenAI API key

This tutorial uses an OpenAI LLM. If you want to use a different provider, you need a valid credential for that provider.

Create an agent flow

The following steps modify the Simple Agent template to connect a Directory component and a Web Search component as tools for an Agent component. The Directory component loads all files of a given type from a target directory on your local machine, and the Web Search component performs a DuckDuckGo search. When connected to an Agent component as tools, the agent has the option to use these components when handling requests.

1. In SkillFlaw, click New Flow, and then select the Simple Agent template.

2. Remove the URL and Calculator tools, and then add Directory and Web Search components to your flow.

3. In the Directory component's Path field, enter the directory path and file types that you want to make available to the Agent component.

   In this tutorial, the agent needs access to a record of customer purchases, so the directory name is customer_orders and the file type is .csv. Later in this tutorial, the agent will be prompted to find email values in the customer data.

   You can adapt the tutorial to suit your data, or, to follow along with the tutorial, you can download customer-orders.csv and save it in a customer_orders folder on your local machine.

4. In the Directory and Web Search components' header menus, enable Tool Mode so you can use the components with an agent.

5. Connect the Directory and Web Search components' Toolset ports to the Agent component's Tools port.

6. In the Agent component, enter your OpenAI API key.

   If you want to use a different provider or model, edit the Model Provider, Model Name, and API Key fields accordingly.

7. To test the flow, click Playground, and then ask the LLM a question, such as Recommend 3 used items for carol.davis@example.com, based on previous orders.

   Given the example prompt, the LLM would respond with recommendations and web links for items based on previous orders in customer_orders.csv.

   The Playground prints the agent's chain of thought as it selects tools to use and interacts with functionality provided by those tools. For example, the agent can use the Directory component's as_dataframe tool to retrieve a DataFrame, and the Web Search component's perform_search tool to find links to related items.

Add a Prompt Template component to the flow

In this example, the application sends a customer's email address to the SkillFlaw agent. The agent compares the customer's previous orders within the Directory component, searches the web for used versions of those items, and returns three results.

1. To include the email address as a value in your flow, add a Prompt Template component to your flow between the Chat Input and Agent components.

2. In the Prompt Template component's Template field, enter Recommend 3 used items for {email}, based on previous orders. Adding the {email} value in curly braces creates a new input in the Prompt Template component, and the component connected to the {email} port is supplying the value for that variable. This creates a point for the user's email to enter the flow from your request. If you aren't using the customer_orders.csv example file, modify the input to search for a value in your dataset.

   At this point your flow has six components. The Chat Input component is connected to the Prompt Template component's email input port. Then, the Prompt Template component's output is connected to the Agent component's System Message input port. The Directory and Web Search components are connected to the Agent component's Tools port. Finally, the Agent component's output is connected to the Chat Output component, which returns the final response to the application.

   

Send requests to your flow from a JavaScript application

With your flow operational, connect it to a JavaScript application to use the agent's responses.

1. To construct a JavaScript application to connect to your flow, gather the following information:

   • SKILLFLAW_SERVER_ADDRESS: Your SkillFlaw server's domain. The default value is 127.0.0.1:7860. You can get this value from the code snippets on your flow's API access pane.
   • FLOW_ID: Your flow's UUID or custom endpoint name. You can get this value from the code snippets on your flow's API access pane.
   • SKILLFLAW_API_KEY: A valid SkillFlaw API key.

2. Copy the following script into a JavaScript file, and then replace the placeholders with the information you gathered in the previous step. If you're using the customer_orders.csv example file, you can run this example as-is with the example email address in the code sample. If not, modify the const email = "isabella.rodriguez@example.com" to search for a value in your dataset.

   
   

   _72

   const SKILLFLAW_SERVER_ADDRESS = 'SKILLFLAW_SERVER_ADDRESS';

   _72

   const FLOW_ID = 'FLOW_ID';

   _72

   const SKILLFLAW_API_KEY = 'SKILLFLAW_API_KEY';

   _72

   const email = "isabella.rodriguez@example.com";

   _72

   _72

   function extractChatText(data) {

   _72

   return (

   _72

   data?.outputs?.[0]?.outputs?.[0]?.results?.message?.data?.text

   _72

   ?? data?.outputs?.[0]?.outputs?.[0]?.results?.text?.data?.text

   _72

   ?? ''

   _72

   );

   _72

   }

   _72

   _72

   async function runAgentFlow() {

   _72

   try {

   _72

   console.log(`Connecting to SkillFlaw server at: ${SKILLFLAW_SERVER_ADDRESS} `);

   _72

   console.log(`Flow ID: ${FLOW_ID}`);

   _72

   console.log(`Email: ${email}`);

   _72

   _72

   console.log('\nSending request to agent...');

   _72

   const response = await fetch(`${SKILLFLAW_SERVER_ADDRESS}/api/v1/run/${FLOW_ID}`, {

   _72

   method: 'POST',

   _72

   headers: {

   _72

   'Content-Type': 'application/json',

   _72

   'x-api-key': SKILLFLAW_API_KEY,

   _72

   },

   _72

   body: JSON.stringify({

   _72

   input_value: email,

   _72

   input_type: 'chat',

   _72

   output_type: 'chat',

   _72

   session_id: email,

   _72

   }),

   _72

   });

   _72

   _72

   if (!response.ok) {

   _72

   throw new Error(`SkillFlaw run failed: ${response.status} ${response.statusText}`);

   _72

   }

   _72

   _72

   const data = await response.json();

   _72

   const chatMessage = extractChatText(data);

   _72

   _72

   console.log('\n=== Response from SkillFlaw ===');

   _72

   console.log('Session ID:', email);

   _72

   _72

   // Extract URLs from the chat message

   _72

   console.log('\n=== URLs from Chat Message ===');

   _72

   const messageUrls = chatMessage.match(/https?:\/\/[^\s"')\]]+/g) || [];

   _72

   const cleanMessageUrls = [...new Set(messageUrls)].map(url => url.trim());

   _72

   console.log('URLs from message:');

   _72

   cleanMessageUrls.slice(0, 3).forEach(url => console.log(url));

   _72

   _72

   } catch (error) {

   _72

   console.error('Error running flow:', error);

   _72

   _72

   // Provide error messages

   _72

   if (error instanceof Error) {

   _72

   if (error.message.includes('fetch')) {

   _72

   console.error('\nMake sure your SkillFlaw server is running and accessible at:', SKILLFLAW_SERVER_ADDRESS);

   _72

   }

   _72

   if (error.message.includes('401') || error.message.includes('403')) {

   _72

   console.error('\nCheck your API key configuration');

   _72

   }

   _72

   if (error.message.includes('404')) {

   _72

   console.error('\nCheck your Flow ID - make sure it exists and is correct');

   _72

   }

   _72

   }

   _72

   }

   _72

   }

   _72

   _72

   // Run the function

   _72

   console.log('Starting SkillFlaw Agent...\n');

   _72

   runAgentFlow().catch(console.error);

   
   

3. Save and run the script to send the request and test the flow.

   Your application receives three URLs for recommended used items based on a customer's previous orders in your local CSV, all without changing any code.

   Result

   The following is an example response from this tutorial's flow. Due to the nature of LLMs and variations in your inputs, your response might be different.

   
   

   _15

   Starting SkillFlaw Agent...

   _15

   _15

   Connecting to SkillFlaw server at: http://localhost:7860

   _15

   Flow ID: local-db-search

   _15

   Email: isabella.rodriguez@example.com

   _15

   _15

   Sending request to agent...

   _15

   _15

   === Response from SkillFlaw ===

   _15

   Session ID: isabella.rodriguez@example.com

   _15

   _15

   URLs found:

   _15

   https://www.facebook.com/marketplace/258164108225783/electronics/

   _15

   https://www.facebook.com/marketplace/458332108944152/furniture/

   _15

   https://www.facebook.com/marketplace/613732137493719/kitchen-cabinets/

   
   

4. To quickly check traffic to your flow, open the Playground. New sessions are named after the user's email address. Keeping sessions distinct helps the agent maintain context. For more on session IDs, see Session ID.

Next steps

For more information on building or extending this tutorial, see the following:

• Model Context Protocol (MCP) servers
• SkillFlaw deployment overview