IBM watsonx.ai Flows Engine

Build a Tool

  • Overview
  • Installation
  • Authentication
  • Getting Started
  • Node.js CLI
    • Build a Tool
    • Import a Tool
    • Register Tools
    • Deploying Tools

Build a Tool from Your Data Source

With watsonx.ai Flows Engine, you can turn any data source (REST APIs, GraphQL, Databases) into a tool you can use with an LLM. To build a tool, you need to have the watsonx.ai Flows Engine Node.js CLI installed and sign up for a free account.


Import Your Data Source

The data sources used as tools should be specified as a GraphQL schema. To generate a GraphQL schema for your data sources, you can either use the CLI or create GraphQL schemas from scratch.


Using the CLI

You can use the Node.js CLI to generate a GraphQL schema for the following data sources:

To use the CLI, you need to have Node.js and npm installed on your machine.

1. Install the CLI by following the instructions

2. Authenticate using your account information:

wxflows login
  • Provide your account name
  • Provide the admin key

3. Create a new directory for your project, and run the

command:

mkdir my-project
wxflows init

You'll be asked to set the endpoint name for your project.

4. Run the

command for your data source in your terminal or command line:

wxflows import curl
wxflows import openapi
wxflows import graphql
wxflows import mysql
wxflows import postgresql
wxflows import snowflake

You can append the

flag to see all the required values for each command. For example,
will return usage instructions for importing a REST API as a GraphQL schema.

5. Modify the generated files:

After importing your data source as a GraphQL file, you can make changes to the generated

files. The CLI is using IBM API Connect Essentials as the engine, see this guide for more information.

6. Proceed to registering your tool(s):

Finally, go to the next section to learn how to register your tool(s) and make them available for use in your application.


In some cases, you may need to write the GraphQL schema manually. This is necessary when using data sources not supported by the CLI (like MSSQL, Presto, Singlestore, Trino, or SOAP/XML) or when importing your supported data source fails due to authorization constraints like self-signed certificates.


Write a GraphQL Schema

If you choose not to use the CLI, you can write the GraphQL schemas for your data sources manually. This requires using a custom directive to connect to the data source. You can find detailed information about creating schemas with custom directives here.

Below is an example of a GraphQL schema:

type Customer {
  email: String
  id: ID
  name: String
}
type Query {
  customerById(id: ID!): Customer
    @rest(endpoint: "https://introspection.apis.stepzen.com/customers/$id")
}

In this schema, the

custom directive connects to a REST endpoint. The
field takes one parameter (
), which is dynamically passed to the connected REST API. You can customize additional details such as headers, methods, request body, or response field names. See this documentation for all available options.

Any

file you create should be included in the
file in the root of your project:

schema
  @sdl(files: ["custom/index.graphql"]) { # Add your file here
  query: Query
}

The following custom directives are currently supported:

After writing the GraphQL schema, proceed to the next section to learn how to register your tool(s) and make them available for use in your application.