C3 AI Documentation Home

External SDKs

To make programming directly against the C3 AI server APIs more convenient and documentation more consistent, the client framework model is defined as Types that provide APIs in several languages.

All languages that the C3 Agentic AI Platform supports use the same APIs, with only language-specific differences.

The API is exposed through Types, which:

  • provide a source of documentation
  • enforce consistency between languages
  • avoid extensive language-specific extensions

The API provides increasing tiers of functionality, with the lowest tier providing simple REST API wrapping with a correspondingly small footprint:

  • REST — simple RESTful operations with small download size (1 KB)
  • thin — additional Type-aware APIs, but without loading Type metadata (10 KB)
  • full — locally instantiated metadata and ability to execute actions client-side (200 KB + metadata)

All layers have support for synchronous and asynchronous calling. Synchronous calls use the traditional model, which are blocking calls that do not return until either the change has been completed or there has been an error. Asynchronous calls return a promise immediately.

The client library must operate with other libraries in an environment it does not own:

  • the only global variable is C3 defining the C3 AI namespace
  • active connections to multiple servers are permitted
  • multiple versions of the server are allowed simultaneously

Instantiation

A single well-known URL serves the minimal bootstrap code to download an appropriate version of the client. This is a tiny static file, which need never change. The actual client libraries are downloaded by this script from the server to which the user is planning to connect. For the browser, the URL is https://hostname/remote/c3.js, which can be included in a script tag of a web page. It creates the C3 AI namespace and defines the functions required for making a connection: C3.remote.connect and C3.remote.connectAsync. Each function accepts a URL to a C3 AI server and establishes a connection to that server.

Type
connect: function(url: !string, 
                  authz: string, 
                  actionEngine: string serialized Action.Engine, 
                  spec: RemoteConnectSpec): !ServerConnection java | py
  • url — the base URL of the C3 AI server to connect
  • authz — authentication details for a valid user
  • actionEngine — specific Action.Engine required
  • spec — additional options to bootstrap the connection

The connect function returns an instance of the ServerConnection Type, whose implementation is downloaded from that server. This allows connections to different servers and with different versions to exist simultaneously. Note that each connection is separate (there is no caching of connections).

The connectAsync function is the same, except it returns a Promise of the ServerConnection. See the Remote Type for more details.

Type
connectAsync: function(url: !string, 
                       authz: string, 
                       actionEngine: string serialized Action.Engine, 
                       spec: RemoteConnectSpec): !Promise<ServerConnection>
  • url: the base URL of the C3 AI server to connect
  • authz: authentication details for a valid user
  • actionEngine: specific Action.Engine required
  • spec: additional options to bootstrap the connection

Synchronous versus asynchronous calling

Note that the connect API defined above appears as a synchronous Type system function, but is actually declared in two forms: connectAsync (which returns a promise) and connect (which blocks and returns the actual connection or throws an exception).

A Promise is documented as a Type: Type Promise where _V_ is the expected return value. JavaScript uses the built-in Promise object.

Tiers

As described above, the three tiers provide increasing functionality (with increasing local weight).

For a live example of using the different tiers from JavaScript, connect to your local server at https://hostname/remote/index.html.

REST client tier

The simplest and smallest client delivers in a simple REST API. Thin and full tiers also support these APIs, although normally clients use the higher-level APIs instead. All functions in the REST API that make server requests have both a synchronous and an asynchronous variant. See the HttpRequest, HttpResponse and ServerConnection Type for details.

Thin client tier

The thin client tier builds on the REST tier by adding support for a Type proxy, without loading actual Type metadata into the client. Type proxies allow Type-oriented actions, but in a standard form. See the ThinTypeSystem and AsyncThinTypeSystem Types for details.

Full client tier

The full tier is an alternative to the thin tier in having the "full" Type system in the client. This means metadata can be introspected since TypeMeta methods are available locally. It also means the scripts can be executed locally ("js-client"). See the TypeSystem and AsyncTypeSystem Types for details.

See also

  • Remote - Global methods which provide a starting point for using the C3 AI remote feature. This Type represents methods available on the global C3 (JavaScript) or c3 (Python) namespace variable.
  • ServerConnection - A remote connection to a C3 AI server. This should be established by calling
  • TypeSystem - Type for the remote full type system, synchronous version.
  • AsyncTypeSystem - Type for the remote full type system, asynchronous version.
  • ThinTypeSystem - Type for the C3 AI remote thin type system, synchronous version.
  • AsyncThinTypeSystem - Type for the C3 AI remote thin type system, asynchronous version.
  • ServerRequest - All C3 AI remote requests go over HTTP. The only thing we add is connection from which the request was initiated since different connections to different servers may have different metadata and even different implementations.
Was this page helpful?