Overview

The Upstreet Agents SDK is the first React-based SDK for building and deploying headless AI agents, locally and in the cloud.

React Agents is a groundbreaking framework that brings the power and familiarity of React to AI agent development. Built on React's reconciliation engine, it enables developers to create intelligent, autonomous agents using the same tools and patterns they love from React development.

Quick Start

import { Agent, Action } from '@upstreet/agents';
import { z } from 'zod';
 
function SmartHomeAgent() {
  return (
    <Agent>
      <Action
        name="turnOnLights"
        description="Turn on the lights in my room"
        schema={z.object({ lightName: z.string() })}
        examples={[{ lightName: 'bedroom' }]}
        handler={(e) => {
          turnOnLights();
          e.data.agent.monologue(`Lights changed: ${e.data.message.args.lightName}`);
        }}
      />
    </Agent>
  );
}

Core Concepts

The React Agents Architecture

React Agents leverages the React Reconciler API to create a custom renderer specifically designed for AI agents. This architecture provides several key advantages:

Server-First Design: Optimized for server-side execution
Platform Agnostic: Ready for multi-platform and edge deployments
Declarative: Uses React's component model and lifecycle
Type Safety: Full TypeScript support throughout the stack

Traditional React vs React Agents

Let's compare how you'd implement similar functionality in traditional React versus React Agents:

Traditional React

// User interface focused
function LightControl() {
  const [lightName, setLightName] = useState('');
  
  return (
    <form onSubmit={(e) => turnOnLights(e.target.lightName.value)}>
      <label>Light Name:</label>
      <input
        type="text"
        value={lightName}
        onChange={(e) => setLightName(e.target.value)}
      />
      <button type="submit">Turn On Light</button>
    </form>
  );
}

React Agents

// Agent behavior focused
function LightControlAgent() {
  return (
    <Agent>
      <Action
        name="turnOnLights"
        description="turn on the lights in my room"
        schema={z.object({ lightName: z.string() })}
        examples={[{ lightName: 'bedroom' }]}
        handler={handleLightChange}
      />
    </Agent>
  );
}

The key difference lies in the focus: traditional React components render user interfaces, while React Agents components render agent behaviors and capabilities.

Core Components

Agent

The root component that initializes an agent instance.

<Agent
  name="HomeAssistant"
  description="A helpful assistant for home automation"
>
  {/* Agent actions and behaviors */}
</Agent>

Action

Defines discrete capabilities that an agent can perform.

<Action
  name="setTemperature"
  description="Set the temperature of a room"
  schema={z.object({
    room: z.string(),
    temperature: z.number()
  })}
  handler={handleTemperatureChange}
/>

How It Works

React Agents operates through a sophisticated pipeline:

JSX Transformation: Your component code is transformed into an agent execution plan
Prompt Generation: The execution plan is converted into a series of prompts
Chain-of-Thought Runtime: Prompts are processed through a reasoning engine
Action Execution: The agent performs actions based on its reasoning
State Updates: Results are reconciled back through React's system

Best Practices

1. Schema Definition

Always define precise schemas for your actions:

const schema = z.object({
  action: z.enum(['on', 'off']),
  device: z.string(),
  room: z.string().optional()
});

2. Provide Examples

Include clear examples for better agent understanding:

const examples = [
  { action: 'on', device: 'lights', room: 'living room' },
  { action: 'off', device: 'thermostat' }
];

3. Error Handling

Implement robust error handling in your handlers:

const handler = async (e) => {
  try {
    await performAction(e.data.message.args);
    e.data.agent.monologue('Action completed successfully');
  } catch (error) {
    e.data.agent.monologue(`Error: ${error.message}`);
  }
};

const customRenderer = createAgentRenderer({
  supportedEvents: ['custom.event'],
  transformEvent: (event) => ({
    type: 'custom.event',
    payload: event
  })
});

State Management

Integrate with existing React state management solutions:

function AgentWithState() {
  const [state, dispatch] = useReducer(reducer, initialState);
  
  return (
    <Agent context={{ state, dispatch }}>
      {/* Agent components */}
    </Agent>
  );
}