Usdk NPM | npm.io

Agents SDK

This SDK lets you develop and deploy AI agents written in React, locally and in the cloud.

Agents are intelligent entities implemented as a React renderer, allowing them to perceive events and perform actions. React components allow for easy composition, customization, and sharing of every part of the stack, while retaining the full flexibility of Typescript to dig down to a lower level.

<Agent>
  <Personality src="bio.txt">
  <AlwaysHappy />
  <Prompt>
    She has a cat named {catsName}.
  </Prompt>
  <DiscordBot token={/* ... */} />
</Agent>

Implementations of RAG (Retrieval Augmented Generation) and other common techniques are provided by default as components.

Talk to your agent via the provided mobile chat frontend, or connect via WebSocket.

Agents operate in multiplayer rooms, allowing for human-to-agent and agent-to-agent interactions. They can also be set to run autonomously and collaborate with other agents for emergent behaviors.

Model integrations for popular platforms let you choose the right inference, while a "battery" system lets you track costs and set spend limits. The SDK provides tools for inspecting and debugging.

Built on top of Cloudflare Workers (workerd), Supabase, and Base.

To get started, install the SDK:

npm i -g usdk

Your first agent

To create an agent, use:

mkdir my-agent # create a directory for your agent
cd my-agent # enter the directory
usdk create # -t basic or another template; `usdk ls` for full list

This will set up agent files for local development.

Then, start your agent with:

usdk dev chat

This will start a development server with hot reload and put you into a chat room with them, right in the CLI. Your agent will be automatically updated when you edit the source files.

How it works

Agents are defined as a React render function returning the components that make up your agent.

<Agent>
{/* ... components ... */}
</Agent>

Each agent must provide an implementation of each of the following component categories. If any of them are omitted, a generous default will be used.

You can use as many components as you wish; they will be applied in the order they are defined.

<Prompt>: Defines the dynamic prompt that the agent will use during LLM inference
<Perception>: Defines how an agent should respond to an incoming event, such as a chat message
<Parser>: Implements interpretation of the LLM response into actions
<Action>: Specifies how the agent should perform an LLM action
<Schedule>: Controls how the agent should behave over time

Here is a detailed breakdown of each:

Prompt component

E.g.

<Prompt>Use UwU speak.</Prompt>

This component allows you to dynamically craft the LLM prompt used by your agent. The child text of the component will be included in the prompt. Multiple <Prompt>s concatenate in order of definition.

While static prompts are allowed, you will probably want to make use of one of the low-level APIs that allow you to access the agent's state and conversational environment, and use these in your prompt.

Perception component

E.g.

<Perception
  type="nudge"
  handler={e => {
    /* ... */
  }}
/>

This component allows you to define how your agent should respond to an external event, such as a new chat message. The type parameter specifies which event is being handled, and the handler function implements how to handle it.

The most common types of perception events are:

message: a new chat message came in
nudge: it is time for the agent to think, based on its schedule

Action component

E.g.

<Action
  name="say"
  description="The character speaks a line of dialogue"
  example="Alice: Hi, Bob!"
  handler={e => {
    /* ... */
  }}
/>

This component allows you to implement the actions that your agent is capable of performing. The name, description, and example properies are used to generate the prompt to use (by default), and the handler is called when the LLM generates a message matching the given name.

Note that actions depend on the <Prompt>s used in order for the agent to function, because inference must know about the allowed actions it can emit. This functionality is provided by the default <ActionsJsonPrompt>, although you are free to provide your own implementation.

Additionally, the format used in the example is significant and must match the <Parser> used.

Parser component

E.g.

<Parser
  parseFn={s => {
    /* ... */
  }}
/>

This component allows you to customize the interpretation of the LLM response, in terms of actions. For example, if the prompt specifies to output the response in JSON (the default), the parser might use JSON.parse to get an object representation of it.

parseFn must output an object of the ActionMessage type:

{
  method: string;
  args: object;
  timestamp: number;
}

Scheduler component

This component allows you to define when the agent acts. The scheduler returns the timestamp at which the agent should next be nudged (nudge perception event).

E.g.

<Scheduler
  scheduleFn={() => Date.now() + 1000}
/>

Low-level API

To be written...

SDK Commands

Deploy agent

To deploy your agent to the cloud, first you will need to log in with Supabase:

usdk login

Then, deploy your agent with:

usdk deploy

List agents

To list your deployed agents:

usdk ls

Chat with agent

To chat with a deployed agent:

usdk chat <guid>

You can also listen to the agent's events without chatting with them:

usdk listen <guid>

Delete agent

To delete an agent:

usdk rm -i <guid>

Project structure

An agent consists of an agent.json, which specifies the agent's properties, like the model to use, and where to find the React component file. The SDK builds your projeft.