Going from Zero to Hero in GraphQL and Agentic AI on the Now Platform Part 1 of 5

zackfanning · 4 hours ago

Agentic AI and GraphQL

This is a guide for anyone interested in the intersection of Agentic AI and GraphQL, two powerful technologies and how they can be used with the Now platform.

We will start with the assumption that you have no experience with either and give you the need-to-know behind the technologies and how they are used to unleash the power of workflows on the Now platform. By Part 5 you will be a pro! We will go into the background behind both GraphQL and Agentic AI but if you are interested in more information I would suggest reading the introduction from the GraphQL Org before starting this just to get some familiarity with terms and some of the benefits of GraphQL versus REST.

Inspiration from this article series was drawn from Setting up and Testing your first GraphQL API Tutorial by @Jon G Lind.

Note: Initially we planned for this article to have a narrower focus strictly on leveraging Agentic AI, but the use case assumes GraphQL knowledge and thus turned from 2 parts into 5. If you already are a GraphQL pro you can skip straight to part 4!

Part 1 GraphQL Basics

Part 2 GraphQL Beyond the Basics

Part 3 GraphQL Security & Testing

Part 4 Agentic AI and GraphQL Basics

Part 5 Agentic AI and GraphQL Advanced

Context for the Lesson

Background Information: APIs and Web Services

If you are reading this article you are likely already familiar with ServiceNow. What you may or may not already know is that the NOW platform is built to leverage a number of different APIs (Application Programming Interface) to enable data interchange in and out of the ServiceNow platform. A core type of API that is leveraged by the ServiceNow platform is the web service API which exists to help move and share data between systems. Some examples of web services are integrations that pull data into the CMDB, the user table, or maybe even importing incidents from another system into ServiceNow.

What is GraphQL?

GraphQL is a query language and runtime for APIs. You can think of GraphQL as being a newer web service capability that can be used to fetch or send data to or from a ServiceNow instance. GraphQL is gaining popularity in the software development ecosystem due to its flexibility and efficiency with deeply connected data referenced in different data tables.

What is Agentic AI

Agentic AI is a system that can work independently to solve problems on behalf of customers or employees. ServiceNow is a pioneering Agentic AI to empower workflows that can independently act to understand business context and code to resolve issues using cutting edge AI technology.

Why Does this Matter?

GraphQL and Agentic AI are awesome because they let your AI do more than just fetch data. They can actually decide what data they need and what to do with it. GraphQL makes it easy to grab exactly the information you want without getting extra stuff you do not need, while Agentic AI can reason and take action based on that data. Put them together on the Now Platform, and your AI agents can pull data, make decisions, and drive workflows all in one smooth process; faster and smarter than using traditional REST APIs.

Start Exploring

Note: Unfortunately this tutorial cannot be done in a personal developer instance due to limitations on the capabilities that PDIs are given.

First things first to work on this tutorial you need an instance with the Now Assist AI Agents[sn_aia] plugin activated (for parts 4 & 5). There will be some navigation so I suggest utilizing tabs so you do not have to keep searching things repeatedly. Use the application navigator to find System Web Services > GraphQL > Properties. We are going to enable the second and third properties:

Enable/Disblae debug logging for GraphQL
Enable/Disable introspective queries for users to discover the supported GraphQL queries and types. Introspection request require graphql_schema_admin role

Now that we have updated the properties let us check out the GraphQL Explorer under System Web Services > GraphQL > GraphQL Explorer. GraphQL Explorer is like the REST API Explorer although it has a bit more of a sandbox feel to it.

Try typing and using the structure you learned from the GraphQL intro to see how the autocomplete will help you find something (even if you are not quite sure what you are looking for)

Demo Data

This demo assumes you have demo data that we will be querying (this is not required; the alternative would be to query existing data). Commit the follow update set to use the demo data

User GraphQL Tutorial Demo Data.xml

Create Our First GraphQL API

Let us start with a basic example using the User table as our use case. Navigate to System Web Services > GraphQL > GraphQL APIs and click “New”. Now let us create our GraphQL API record.

Give it a Name of “User GraphQL Tutorial”, the Schema namespace should automatically populate (just make sure to wait for the page to fully load)
Set Requires authentication to false (we will revisit this in a future part)
Set Requires ACL authorization to false (we will handle this differently at record level as opposed to API level)
Update the Schema to remove the mutation sections and remove the Mutation type
We will create a basic function called getUser that passes user ID as a string and returns a User type
Since we are returning an User type from getUser we will also create that and define name and email as strings to be returned

Hopefully after looking through the GraphQL introduction this mostly looks familiar. So, in the above when you query getUser you will be required to provide a string and if you receive a User (since the return is optional) it will have both name and email. Please note that your Application namespace could be different – and if you did this in a different scope then your Application will be different as well.

Note: The one thing that might not be obvious is the exclamation marks – those just indicate that something is mandatory i.e. a type property will not return something null. If ‘!’ is used as an argument to a function that argument is required or if used as the return of a function it will return some non-null value.

Testing Our API

Go back to your tab with the GraphQL Explorer.

To execute a query, follow this order for calling your GraphQL API

Operation
Application namespace
Schema namespace
Query or Mutation function

Try to query the getUser function for "david.loo" and ask for their name and email and then try executing the query. If you are unsure check against the code snippet in the spoiler

Spoiler

query {
  snc {
    userGraphQLTutorial {
      getUser(userID: "david.loo") {
        name
        email 
      }
    }
  }
}

query { snc { userGraphQLTutorial { getUser(userID: "david.loo") { name email } } } }

Now while we have the correct GraphQL query syntax and have passed in a valid argument the instance does not know what to do with what we passed and so you should see something like this.

Our next step will be to create a Resolver which will tell ServiceNow how to fulfill the query.

Creating Resolvers and Linking Them

About Resolvers

In the GraphQL API, resolvers are execution logic that are used to map fields to a function. Resolvers are used to circumvent some of the performance bottlenecks that can be encountered with older APIs like REST. They are a useful part of the orchestration layer of the GraphQL API and help us to get the exact data that we need in the most efficient manner.

Creating a Resolver

Navigate back to your tab with your GraphQL API that we named “User GraphQL Tutorial” and scroll down to the GraphQL Scripted Resolvers related list and click “New”. Set the name to Get User and update the script to return an object with a name and email property. This is going to return a static response (we will configure a real response in a future part).

This Resolver says that when it is called to return these hard-coded values. Go back to your GraphQL API that we named “User GraphQL Tutorial” and scroll down to the GraphQL Resolver Mappings related list and click “New”. Set the following values

This lets the system know when the getUser method is called to use the Get User Resolver to return a response. This getUser method is now connected to a Resolver and when executed will return what the Resolver returns.

Re-testing Our API

Go back to your tab with the GraphQL Explorer. If you did not close it just hit the execute query button. If you did close it copy the code from above and then execute the query. You should be getting a response now

Try changing the argument you pass to getUser and what you are asking for. You should see the argument has no effect (since our resolver is hard coded) but removing name or email removes them from the returned value. Removing both name and email should result in an error!

Part 2 GraphQL Beyond the Basics

After completing this part you should be comfortable creating a GraphQL API, resolver, and resolver mapping. Consider creating additional static methods like we did in Part 1 to get more comfortable with the pattern of

Create query method
Create resolver
Create resolver mapping
Test in GraphQL explorer

This pattern is the foundational piece for every extension of a GraphQL API. Part 2 GraphQL Beyond the Basics will cover how to query using the User table (and beyond!).