asterai Documentation

Overview

Create, integrate and deploy your AI agents with asterai - a platform for developing and deploying modular AI agents and fully featured AI applications.

What is asterai?

asterai is a platform for developing and deploying modular AI agents and fully featured AI applications.

asterai lets you create an AI application such as an agent or assistant and easily add integrations and features to it in a modular way. Program custom features and logic with plugins, or click to instantly add existing functionality from the plugin marketplace.

With asterai, you can write plugins using different programming languages, such as AssemblyScript, a TypeScript-like language, and deploy them from your terminal into your agent to instantly activate the plugin.

This allows you to expose application functionality to LLMs (Large Language Models, such as ChatGPT's GPT-4) as well as to other plugins.

From within a plugin, you have access to a wide range of tools out of the box such as AI search, LLM calls, HTTP requests, WebSocket connections, and more, allowing you to seamlessly integrate a powerful AI stack to your application.

asterai lets you focus on your app, saving your time by giving you all the managed AI infra and tools you need in a simple way.

Key Features of asterai

  • Plugin-based, modular AI agent building framework
  • AI search with a managed knowledge base and vector DBs
  • SDK for building plugins
  • SDK for querying agents: consume both structured data and natural language
  • REST API endpoints for querying agents from any client
  • CLI for deploying plugins
  • Cloud console for managing agents

What can I do with asterai?

Lots cool of things!

  • make natural language an additional input type for your application
  • integrate AI search to make your app more efficient
  • easily build custom, reliable chatbots, assistants and AI agents
  • create system workflows capable of handling natural language
  • get instant access to AI tools without worrying about infrastructure or scaling

Example use cases

Upload files to a knowledge base and connect it to your agent so that it can answer questions specific to your application. Your agent can also perform authenticated actions for your users, such as CRUD operations that would normally be used via buttons instead.

Or, with the knowledge base, return structured results to build an AI search engine rather than an assistant or agent. You can also do both, for different parts of your app, with the same knowledge base. That is, your search bar and chatbot can use the same underlying technology.

Function Calls and Structured Outputs

Query your application from any environment using our REST API or our SDKs, and consume structured outputs as well as natural language, allowing you to show front-end widgets and triggering front-end function calls alongside an AI assistant response.

For example, create an agent with a Weather plugin. The plugin can respond with an object containing the city name and temperature, allowing your front-end to consume that object to show a weather "widget" along with the natural language provided by the LLM.

Querying an asterai agent

With the JavaScript & TypeScript client library

You can use our TypeScript library to easily query an asterai agent from a web client or web server with Node, Bun, Deno etc. For a full interactive example in React, check out yeet-the-cube.

Examples

Query an agent and obtain a full text response back

import { AsteraiClient } from "@asterai/client";

const client = new AsteraiClient({
  appId: ASTERAI_APP_ID,
  queryKey: ASTERAI_PUBLIC_QUERY_KEY,
});

const response = await client.query({
  query: "how's the weather like in NY?"
});

console.log(await response.text());

Query an agent and obtain a response back token by token

import { AsteraiClient } from "@asterai/client";

const client = new AsteraiClient({
  appId: ASTERAI_APP_ID,
  queryKey: ASTERAI_PUBLIC_QUERY_KEY,
});

const response = await client.query({
  query: "how's the weather like in NY?"
});

let llmResponse = "";
response.onToken(token => {
  llmResponse += token;
});

response.onEnd(() => {
  // The full response has been received.
  console.log(llmResponse);
});

With the HTTP API

To query an app, use the HTTP request below:

POST https://api.asterai.io/app/:app_id/query/:query_mode

HTTP Response format

Currently the only supported query mode is sse, where the response will be an SSE of app response events.

Each SSE data event line will begin with one of these prefixes:

SSE data event line prefixDescription
"llm-token: "An LLM response token
"plugin-output: "Plugin output message serialized with protobuf

Authorization

Note that you must set the Authorization header to an app query key. Find our more about app query keys below.

Query keys

To query your app, you need a query key. You can generate a new public query key via the dashboard.

There are two types of keys: public keys and user keys.

Public query key

When querying an app with a public key, there is no associated user data.

This is used for when you want everyone to have the same experience in your app, or when the end user is not logged in.

Note that "public" in this context simply means that there is no associated user for the key. Whether your app is open to the public is your choice. If your app accesses internal or sensitive systems even without an user being logged in, the "public query key" should not be leaked for security reasons. This depends on the design of your app and plugins.

User query keys

When querying an app with a user key, there is an associated user ID which allows plugins to work with user-specific features, such as accessing user key-value storage.

It is possible to generate a user query key using the following endpoint:

GET https://api.asterai.io/app/:app_id/query/key/user/:app_user_id

Response example:
{"key":"00000000-0000-0000-0000-000000000000"}

Where :app_id is your app's ID and :app_user_id is the ID of your app's user, as a unique string (maximum of 64 characters).

Note that this is an authenticated request, so you must set the Authorization header to your API key which can be found in your account page in the dashboard.

Once you have the user query key, you can query your app with the user key by setting the Authorization header in the regular app query endpoint (POST /app/:app_id/query).

Client libraries for other languages

If you'd like to show your interest in a client library for a specific programming language, join us on Discord and let us know!

Cloud Console & CLI

this section is a work in progress

The cloud console can be accessed from the asterai website. It lets you create and manage agents.

The CLI tool, which can be installed on your computer via NPM, is used to deploy plugins into your agents.

Once a plugin has been added to an agent, you can access the cloud console from asterai's website and turn that plugin on or off, or delete the plugin. Other features, such as Vector DBs, can also be managed from the cloud console.

To learn about how to create a plugin for your agent, check this guide.

Plugins

Plugins are the core feature of Asterai agents. It allows agents to interact with external resources through functions, also known as tools.

Plugins can expose functionality such as interacting with HTTP APIs, knowledge bases, databases and also other plugins.

A plugin is a program that is compiled into a WebAssembly module and deployed into your agent.

Plugins can be written in any language that can be compiled to WebAssembly, such as TypeScript, Python, Go, Rust, and many others.

Plugins can be as simple or complex as required for your agent. Asterai offers a range of pre-existing tools to make common use cases extremely simple to implement, such as having your agent answer questions from a knowledge base.

Plugin Interface

The Plugin Interface defines what functions your plugin has. The interface file is in the WIT file format.

An example plugin interface file looks like this:

package your-asterai-username:burger-shop@0.1.0;

world plugin {
  import asterai:host/api@0.1.0;

  export order-burger: func(order: order) -> order-result;

  record order {
    // The address to deliver the burger to.
    address: string,
  }

  record order-result {
    error: option<string>,
  }
}

The first line defines the username of the owner of the plugin and the name of the plugin. In this case, the plugin name is burger-shop. It also defines a version, 0.1.0. Plugins must have unique versions when deployed, so the same version can't be deployed twice.

This example plugin has a single function, order-burger, which takes in one argument, the order object, and returns another object, order-result, which contains an optional error string.

The interface imports the asterai:host interface, which allows your plugin to interact with asterai's SDK to do things such as sending messages from the plugin to the agent.

Plugin Module

The plugin module is the source code of the plugin, i.e. its implementation. This can be written in any programming language that compiles to WebAssembly.

For example, the TypeScript implementation for the previous plugin interface example could look something like this:

import * as asterai from "asterai:host/api@0.1.0";
import {
  Order,
  OrderResult
} from "your-asterai-username:burger-shop/plugin@0.1.0";

export const orderBurger = (order: Order): OrderResult => {
  // TODO: call order API.
  console.log(`burger order for address: ${order.address}`);
  // Tell agent about the outcome.
  asterai.sendResponseToAgent(`burger was delivered to "${order.address}"`);
  return {
    error: undefined
  } satisfies OrderResult;
};

For more information about how to build and deploy plugins, look at this guide.

Marketplace

this section is a work in progress

The asterai marketplace is a platform where users can list their own plugins and consume plugins made by other asterai users.

Hello World

This step-by-step guide shows how to create a custom plugin using TypeScript.

This plugin will expose a function that returns a hardcoded string ("hello, world!"). This function can be called by your agent.

To create and deploy the plugin, follow these steps:

  1. Sign in to asterai
  2. Create a new agent. You can call it hello-world-agent.
  3. Install the asterai CLI. Example using npm:
npm install -g @asterai/cli
  1. Generate a new API key in your asterai dashboard, and use it to authenticate your CLI:
asterai auth <your_api_key>
  1. Initialise a new plugin project called hello-world-plugin. This will create a new directory with a template plugin project.
asterai init hello-world-plugin
  1. Install dependencies on the new project:
cd hello-world-plugin
npm i
  1. Inspect the contents of plugin.wit, the plugin interface file.
  2. Inspect the contents of plugin.ts, the plugin implementation.
  3. Modify the contents of plugin.wit, removing the example mul function and adding a new function for getting a secret phrase. Also rename the plugin name to hello-world-plugin and ensure to replace your-username in plugin.wit with your asterai username, as otherwise you will not be able to deploy the plugin.
package your-username:hello-world-plugin@0.1.0;

world plugin {
  import asterai:host/api@0.1.0;

  export get-secret-phrase: func() -> string;
}
  1. Run npm run build. This will generate the utility types, but building will fail -- this is expected.
  2. Update plugin.ts to implement the get-secret-phrase function. It needs to return a string. The function will also send a message to the agent with that same string, by calling asterai.sendResponseToAgent("string-here"). Your plugin.ts will look like this:
import * as asterai from "asterai:host/api@0.1.0";

export const getSecretPhrase = (): string => {
  const phrase = "hello, world!";
  // Send the secret phrase to the agent.
  asterai.sendResponseToAgent(phrase);
  return phrase;
};
  1. Build the plugin with npm run build to check that everything is correct.
  2. Get your agent ID from the cloud console.
  3. Deploy the plugin:
asterai deploy --agent <your_agent_id>
  1. Refresh the page in the cloud console. You should see the new plugin that was just deployed.
  2. In the playground section, ask "what is the phrase?". The agent should reply mentioning "hello, world!".
  3. You can query the agent programmatically with a library or HTTP REST API.

Hopefully this hello world example illustrates how asterai can be used to connect AI to applications. Within plugins, it is possible to access LLMs, Vector DBs, make HTTP calls and even use WebSockets.