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}`);
}
};
Command Reference
For a complete list of available commands and their usage, refer to our Command Reference Guide.
Advanced Topics
Custom Renderers
Create specialized renderers for unique use cases:
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>
);
}