Skip to main content

Using JSONata with Agents in AI12Z Copilot

Introduction​

AI12Z Copilot is a powerful tool that enables seamless interaction between users and various agents, such as forms for user input, CRM systems like HubSpot, and external APIs like weather forecasts. To ensure these agents communicate effectively, data often needs to be transformed into specific formats.

JSONata is a lightweight, declarative query and transformation language designed for manipulating JSON data. It allows you to extract, transform, and create new JSON structures using a simple yet powerful syntax. In AI12Z Copilot, JSONata is used to transform both the requests sent to agents and the responses received from them.

This guide will walk you through how to use JSONata with agents in AI12Z Copilot, demonstrating how to transform data efficiently using the built-in AI-powered wizard.

Table of Contents​

  1. Transforming Requests with JSONata
  2. Transforming Responses with JSONata
  3. Using the JSONata Wizard in AI12Z Copilot
  4. Additional Resources
  5. Conclusion

Transforming Requests with JSONata​

Example: Formatting Data for HubSpot Agent​

When integrating with CRM systems like HubSpot, it's crucial to send data in the format expected by their APIs. Here's how you can use JSONata to transform user input data before sending it to the HubSpot agent.

Steps:​

  1. Capture User Input

    • When a user signs up for a newsletter, the Copilot uses the Form Agent to capture necessary details such as first name, last name, email, and phone number.

  2. Understand HubSpot's Data Format

    • HubSpot expects the body of the POST request to be in a structured JSON format with specific field names and values.

  3. Access the HubSpot Agent Configuration

    • In AI12Z Copilot, navigate to the HubSpot Custom Agent settings.

  4. Generate JSONata Transformation

    • Click on the "Generate JSONata" button to start the wizard.

  5. Enter Test Data

    • Input sample data as it would come from the LLM (Large Language Model).
    • Example: 
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "123-456-7890"
      }
    • Click Next.

  6. Define the Expected Output

    • Enter a description or provide a JSON example of the format that HubSpot expects.
    • Example description:
      • "Transform the data to match HubSpot's contact properties, including email, firstname, lastname, and phone."

  7. Generate JSONata Expression

    • Click the "Generate JSONata" button.
    • The wizard uses AI to create the JSONata expression based on your input.

  8. Review and Save

    • The middle text box displays the generated JSONata expression.
    • Example JSONata: 
      {
        "properties": [
          {"property": "email", "value": email},
          {"property": "firstname", "value": firstName},
          {"property": "lastname", "value": lastName},
          {"property": "phone", "value": phone}
        ]
      }
    • Review the results to ensure it meets your expectations.
    • Click Save to apply the JSONata transformation to the agent.

Benefits:​

  • Data Consistency: Ensures that the data sent to HubSpot is in the correct format, preventing errors.
  • Efficiency: Automates the data transformation process, saving time.

Transforming Responses with JSONata​

Example: Simplifying Data from Weather Forecast Agent​

APIs like weather services often return extensive data, which may include information you don't need. You can use JSONata to simplify the response before passing it to the LLM, reducing processing time and focusing on relevant data.

Steps:​

  1. Access the Weather Forecast Agent

    • Navigate to the Weather Forecast Agent configuration in AI12Z Copilot.

  2. Test the Agent

    • Run a test to see the full data being returned.
    • Identify the specific data points you need (e.g., temperature, humidity, weather description, and time).

  3. Initiate the JSONata Wizard

    • Click on the "Generate JSONata" button to start the wizard.

  4. Enter Test Data

    • Provide sample input parameters required to call the Weather Forecast API.
    • Example: 
      {
        "city": "New York",
        "units": "metric"
      }
    • Click Next.

  5. Describe Desired Output

    • Write a description of what you want to get back.
    • Example description:
      • "Extract the temperature, humidity, weather description, and time for each forecast entry."

  6. Generate JSONata Expression

    • Click the "Generate JSONata" button.
    • The wizard generates a JSONata expression that filters the response accordingly.

  7. Review and Accept

    • The transformed output should now only include the specified fields.
    • Example JSONata: 
      forecasts{
        "time": dt_txt,
        "temperature": main.temp,
        "humidity": main.humidity,
        "description": weather[0].description
      }
    • Click Accept to use the generated JSONata expression.

  8. Save the Agent Configuration

    • Save the changes to apply the JSONata transformation to the agent.

  9. Verify the Transformation

    • Test the agent again to confirm that the response data is now reduced to only the necessary fields.
    • The result should be significantly smaller and focused.

Benefits:​

  • Performance Improvement: Reduces the amount of data processed by the LLM, improving response times.
  • Clarity: Provides only the relevant information needed for your application.

Using the JSONata Wizard in AI12Z Copilot​

The JSONata wizard in AI12Z Copilot simplifies the process of creating JSONata expressions, making it accessible even if you're not familiar with the syntax.

Steps to Use the Wizard:​

  1. Start the Wizard

    • In the agent configuration page, click the "Generate JSONata" button.

  2. Enter Test Data

    • Input sample data as it would be received from the LLM or external source.
    • This helps the wizard understand the data structure.

  3. Define the Desired Output

    • Provide either:
      • A JSON Example: The exact JSON structure you expect in the output.
      • A Textual Description: A clear description of the data you want to extract or how you want to transform it.

  4. Generate the JSONata Expression

    • Click "Generate JSONata".
    • The wizard, powered by AI, creates the JSONata expression based on your input.

  5. Review the Generated Expression

    • The generated JSONata expression will appear in the middle text box.
    • Below it, you can see a preview of the transformed output using your test data.

  6. Adjust if Necessary

    • If the output isn't as expected, refine your description or test data.
    • Regenerate the JSONata expression as needed.

  7. Save the Expression

    • Once satisfied, click Save to apply the transformation to the agent.

Advantages of the Wizard:​

  • No Prior Knowledge Required: You don't need to know JSONata syntax.
  • AI-Powered Assistance: The wizard uses AI to interpret your descriptions.
  • Time-Saving: Quickly generate complex transformations without manual coding.

Additional Resources​

  • Learn More About JSONata

    • Visit the JSONata Official Website to explore the language in depth.
    • Access tutorials, documentation, and examples to enhance your understanding.

  • AI12Z Copilot Support

    • Refer to the AI12Z Copilot user guide for comprehensive instructions.
    • Contact the support team for personalized assistance.

Conclusion​

Using JSONata with agents in AI12Z Copilot enhances your ability to manipulate and transform JSON data efficiently. Whether you're formatting user inputs for integration with HubSpot or simplifying API responses from a weather service, the AI-powered JSONata wizard makes the process straightforward.

By following the steps outlined in this guide, you can ensure data consistency, improve performance, and streamline your workflows without needing to learn complex transformation languages. Embrace the power of AI12Z Copilot and JSONata to elevate your data handling capabilities.

Thank you for using AI12Z Copilot. If you have any questions or need further assistance, please don't hesitate to reach out to our support team.