React SDK Reference

Overview

The @ouas/react SDK provides the core bindings necessary to expose your React components to the AI Agent. It handles component registration, strictly typed property validation, and the generation of the component manifest.

Installation

Install the React SDK and its required peer dependencies:

npm install @ouas/react @ouas/core

Core Concepts

1. The withOUAS Higher-Order Component

To expose a component to the AI, you must wrap it using the withOUAS higher-order component. This function registers the component into the global OUAS registry and defines the explicit JSON schema that the AI will use to interface with it.

import { withOUAS } from '@ouas/react';

const WeatherCardBase = ({ city, temperature, condition }) => {
return (
  <div className="weather-card">
    <h3>{city}</h3>
    <p>{temperature}°C - {condition}</p>
  </div>
);
};

export const WeatherCard = withOUAS(WeatherCardBase, {
id: 'weather-card',
schema: {
  city: { type: 'string', required: true, description: 'The name of the city' },
  temperature: { type: 'number', required: true },
  condition: { 
    type: 'string', 
    required: true, 
    enum: ['sunny', 'cloudy', 'rainy', 'snowy'] 
  }
}
});

2. Component Registry

The SDK maintains an internal registry of all components wrapped with withOUAS. When the AI agent requests the component manifest, the SDK dynamically traverses this registry to build the manifest.json.

You do not need to manually manage the registry. Simply importing the wrapped component into your application ensures it is registered.

import { WeatherCard } from '@/components/WeatherCard';
// By importing WeatherCard, it is automatically added to the OUAS Registry.

export default function Page() {
return (
  <main>
    <h1>Dashboard</h1>
    {/* You can still use the component normally in your React tree! */}
    <WeatherCard city="San Francisco" temperature={18} condition="sunny" />
  </main>
);
}

API Reference

withOUAS(Component, config)

Wraps a standard React component and returns an OUAS-compliant component.

Arguments:

• Component (React.ComponentType): The React component to wrap.
• config (Object): The configuration object.
  • id (string): A unique identifier for the component. Must be kebab-case.
  • schema (Object): A key-value map defining the properties the AI is allowed to inject.

Returns: A new React component that can be used normally, but is now strictly tracked by the OUAS engine.