Skip to main content

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.

Example:

<Agent>
<Personality src="bio.txt">
<Mood="happy" />
<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.

You can talk to your agent via the provided mobile chat frontend, or connect via WebSocket.

Agents operate in multiplayer, allowing for human-to-agent and agent-to-agent interactions. They can also be set to run autonomously and collaborate with other agents, creating 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.

Teh SDK is built on top of Cloudflare Workers (workerd), Supabase, and Base.

Getting started

To get started, install the SDK with your favorite package manager:

Installation

npm i -g usdk

Create 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; use `usdk help create` for a list of available templates

This will create the agent files for local development.

Then, start your agent with:

usdk dev chat

This will start a development server for your agent and put you into a CLI chat room with them. The dev server supports hot code reloading; your agent will automatically reload when you edit the source files.

Agent basics

This section describes the basics of agent development.

Files

When you create an agent, several files are created by default:

agent.json

Render functions

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.

Miscellaneous

Profile

~/.usdk is used as the storage location for your local data.

Upstreet account

You can develop your agent locally (usdk dev) without any dependencies, but deploying your agent requires you to log in.

Agent's Ethereum wallets

Each agent has their own wallet which is created when the agent is deployed. For local development, a shared local wallet is used.