Skip to main content

Getting Started

AI agents are autonomous software tools that perform tasks, make decisions, and interact with their environment in an intelligent and rational manner. Cartesian is built on top of a layer of AI agents that help the system understand your user's needs and interact with them to help them make the most of what your ecosystem has to offer.

The Agents SDK is the mechanism to connect our agents to your platform. It has an analytics component that provides the Agents and the system with an understanding of what the users are doing inside the platform, as well as integrations to your UI to recommend solutions to your users.

tip

To learn more about the various types of AI agents, we recommend reading this article from GitHub.

The primary component for integrating and creating Cartesian agents is our Agents SDK, which integrates into your front end as well as any existing agents you already have in your environment. This guide walks you through the setup process, authentication requirements, and basic implementation to get up and running with Cartesian agents.

Integrating the SDK will also initialize the Cartesian Agent Analytics, which means Cartesian will start learning and understanding your users' behavior

Creating an Agent configuration​

Before you can connect an Agent to an app, you need to create an Agent configuration in the Ecosystem Hub:

  • Log in to the Ecosystem Hub and select Agents from the side menu.

    Agents Menu

  • Click the Create agent button in the top left corner.

    create Agent

  • Name your agent. We recommend using a descriptive name, such as the name of the app or page to which you are adding the agent.

    Agent Name

  • Hooray! You have created your agent's configuration. Note the agent ID at the top of the configuration page; it will be used in the next steps of this tutorial.

    Agent ID

Adding the SDK​

You can integrate the Cartesian Agents SDK by either adding a small snippet of HTML code or installing an NPM package. Both methods provide the same functionality. We support both options, allowing you to choose the one that best suits your development workflow.

tip

The configuration page will also have an installation tab with code snippets pre-configured with your agent ID, ready to be copied and pasted. We recommend you use those when possible.

1. Script Snippet Integration​

The script snippet method provides a quick way to get started. It automatically handles script loading and initialization. The snippet should be placed in your application's HTML, ideally before the closing </body> tag.

tip

We recommended that you add the minified version to any production environment

<script data-cartesian="true">
  (function (c, a, r, t, e, s, ia, n) {
    c[t] =
      c[t] ||
      function (i, ...o) {
        (c[t].q = c[t].q || []).push([i, o]);
      };
    c[t]('agent-id:set', s);
    ia = a.createElement(r);
    ia.type = 'text/javascript';
    ia.async = true;
    ia.dataset['cartesian'] = 'true';
    ia.src = e;
    n = a.getElementsByTagName(r)[0];
    n.parentNode.insertBefore(ia, n);
  })(window, document, 'script', 'Cartesian', 'https://agent.cartesian.io/bootloader.js', '<%= agentId %>');
</script>

Next, you need to call the window.Cartesian function within a <script> tag like this:

window.Cartesian('user:login', myLoginFunction);

You will need to replace the myLoginFunction with your own function that fetches the signed JWT. See the Authentication section for additional assistance.

2. NPM Package Installation​

You can also integrate Cartesian via our NPM package.

   npm i @cartesianio/agent-sdk

In your front-end codebase, you need to add:

    import { load } from '@cartesianio/agent-sdk'

    ... (other code)

    load(agentId, [ myLoginFunction, myLoginStatusFunction ]);

Authentication​

info

Cartesian requires users to be authenticated at all times.

Cartesian requires JWT (JSON Web Tokens) for secure user authentication. This ensures:

  • Secure user verification
  • Stateless authentication
  • Configurable token expiration

You can add a function that fetches the JWT from your server by calling:

window.Cartesian('user:login', yourJWTFunction, onLoginNotificationFunction);

yourJWTFunction is a function that is called whenever we need to fetch or refresh the user's JWT.

For example:

const userId = 'myUserId';
function myJWTFetcher() {
  return fetch(`https://my-server/my-auth/${userId}`).then((data) => data.jwt);
}

window.Cartesian('user:login', myJWTFetcher);

Handling Login Events​

The login function allows you to pass a callback that is called once the login is completed. This function has an error that will be populated if the login failed:

window.Cartesian('user:login', myJWTFetcher, (error) => {
  if (error) {
    // Handle login failure
    console.error('Login failed:', error);
  } else {
    // Handle successful login
    console.log('User logged in successfully');
  }
});

If authentication fails, the Agent will stop. You can subscribe to the stopped event to handle such cases:

window.Cartesian('subscribe', 'stopped', (error) => {
  if (error) {
    console.error('Agent stopped due to authentication failure:', error);
  }
});