GraphQL Endpoint

Overview and Purpose

Using GraphQL as the data source for your Agent provides a flexible, efficient, and structured way to query and retrieve the information you need. Instead of dealing with separate endpoints or large payloads, GraphQL allows you to specify precisely what you want in a single request, leading to more consistent, optimized, and maintainable integrations.

This section guides you through connecting your Agent to a GraphQL endpoint, configuring parameters, and processing the returned data with an LLM. The images provided illustrate how the Agent, GraphQL endpoint, parameters, and the LLM processing integrate into your solution.

Agent Could Use GraphQL as an Endpoint

1. Precise Data Retrieval:
   GraphQL allows you to request exactly the data you need. Unlike REST endpoints where you often receive large, fixed payloads, GraphQL queries can be written to return only the fields that your Agent will use.

2. Single Endpoint for Multiple Queries:
   With GraphQL, you use a single endpoint to access a wide variety of data resources. This reduces complexity and simplifies your Agent’s configuration since you don’t have to manage multiple endpoints.

3. Efficient Data Fetching:
   By tailoring queries to your needs, you minimize over-fetching and under-fetching of data. Your Agent can operate more efficiently, improving performance and reducing unnecessary network load.

4. Strong Typing and Validation:
   GraphQL schemas define strict types and validation rules. This helps ensure data consistency and reduces runtime errors, as both the Agent and the LLM receive well-structured responses.

5. Flexible Integrations:
   GraphQL can be used with a wide range of data sources, including CMSs, databases, and third-party APIs. For example, integrating with platforms like Shopify’s Storefront API can seamlessly bring product, inventory, and order data into your Agent’s flow.

6. Versioning Simplicity:
   GraphQL’s schema-driven approach eliminates the need for multiple API versions. The schema evolves over time, and clients (or in this case, the Agent) can simply query the parts they are interested in, making upgrades smoother.

7. Client-Driven Queries:
   The Agent, acting as a GraphQL client, defines the queries, which empowers you to rapidly iterate or add new data fields without backend changes. This client-driven approach simplifies experimentation and evolution of your solution.

8. Easier Documentation and Introspection:
   GraphQL endpoints often come with introspection capabilities and tooling that make it easy to explore data structures. Agents can quickly discover available fields and data types, improving development speed and reducing guesswork.

---

Understanding the Components

Block Diagram

This diagram shows the flow of data from the GraphQL endpoint to the Agent and through the LLM:

• GraphQL (URL, Headers, Document, Variables):
  You provide a GraphQL endpoint URL, any required headers (such as Content-Type or authorization tokens), and a GraphQL query or mutation document. Variables can be passed into the GraphQL query to make it dynamic.

• JSONata (Optional):
  Once the data is returned from the GraphQL endpoint, you may optionally transform it using JSONata before sending it to the LLM. This step allows you to reshape, filter, or clean up the data as needed.

• Custom Function (Python) Integration (Optional):
  If your Agent configuration includes a custom Python function, the transformed data can be further processed before being handed off to the LLM. This allows for advanced formatting, calculations, or additional logic.

• LLM Processing:
  Finally, the LLM receives the final data payload and can generate a user-friendly response, summaries, or insights based on the GraphQL-fetched content.

-- Handle Response

Agent Parameters for Data Source GraphQL and LLM

In this interface, you define how the Agent interacts with the GraphQL endpoint:

• Name and Description:
  Provide a descriptive name and explanation so that future users know the purpose of this Agent.
• Data Source:
  Select "GraphQL" as the data source. This tells the Agent where it should retrieve data from.
• Handle Response (LLM to Process Data):
  After retrieving JSON from the GraphQL endpoint, the LLM can be used to process and present the data in a more readable form.

Setup of the GraphQL Endpoint and LLM Parameters

Here, you specify:

• URL:
  The endpoint URL of your GraphQL API (e.g., https://countries.trevorblades.com/graphql).

• Headers:
  Define the headers needed, such as Content-Type: application/json. Additional headers like authentication tokens can also be added here.

• Document (GraphQL Query/Mutation):
  Enter the GraphQL query or mutation you want to execute. For example, to fetch details about a country by its code:

  query GetCountry($code: ID!) {
    country(code: $code) {
      name
      native
      capital
      emoji
      currency
      languages {
        code
        name
      }
    }
  }

• Variables:
  Add variables in JSON format. For instance, to dynamically supply the country code based on Agent parameters:

  {
    "code": "{{code}}"
  }

  This makes the query flexible and reusable for different inputs.

LLM Property Code

Each LLM parameter can be configured to be required or optional, and can accept defaults. In this example, the parameter code is used to pass the 2-letter country code into the GraphQL query. You can set a default value like US to ensure the Agent always has a starting query parameter.

Information Returned by GraphQL

The response from the GraphQL endpoint, once processed by the LLM, can be presented in a clean, user-friendly format. For example, asking for information on the United States (using code: "US") could return details like:

• Name: United States
• Native Name: United States
• Capital: Washington D.C.
• Currency: USD, USN, USS
• Languages: English
• Emoji: 🇺🇸

Your Agent, powered by a GraphQL endpoint and an LLM, can thus deliver highly tailored and easily digestible responses to user queries, making your application more intuitive and valuable.