<Action> - Upstreet Documentation

Importing the Action Component Props Example Example Breakdown:Dependencies

The Action component from react-agents represents an action that a React AI agent can perform. It registers a new action with an agent registry, allowing the agent to trigger the action in response to certain events. This component is useful for defining discrete, reusable actions with associated schemas and event handlers, making it easier to define and handle actions within an AI-driven context.

Importing the Action Component

To use the Action component, import it as follows:

import { Action } from 'react-agents';

Props

The Action component accepts the following props:

Prop	Type	Description	Usage
`name`	`string` (required)	The name of the action.	This name is used to identify the action within the agent registry.
`description`	`string` (required)	A human-readable description of what the action does.	Helpful for documenting the action's purpose or behavior.
`state`	`string` (optional)	An optional state associated with the action, which can be used for additional contextual information.	Set the state if the action's behavior or meaning changes based on specific states.
`schema`	`ZodTypeAny` (required)	A Zod schema object that defines the structure and validation of the action's input parameters.	The schema is used to validate the data passed to the action, ensuring it conforms to the expected format.
`examples`	`Array<object />` (required)	An array of example objects demonstrating the expected structure of the action’s inputs.	Provide examples to illustrate typical usage scenarios for this action.
`handler`	`function` (optional)	A function or asynchronous function that handles the action when triggered. Receives a `PendingActionEvent` as its argument.	Define the action’s behavior when invoked. If the handler is asynchronous, ensure it returns a Promise.

Example

Here is an example of how the Action component might be used:

import { Action } from 'react-agents';
import { z } from 'zod';
 
const sendMessageSchema = z.object({
  message: z.string(),
  recipientId: z.string(),
});
 
const handleSendMessage = async (e) => {
  console.log("Sending message:", e);
  // Code to send a message goes here
};
 
function MyComponent() {
  return (
    <Action
      name="SendMessage"
      description="Sends a message to a specific recipient."
      state="ready"
      schema={sendMessageSchema}
      examples={[
        { message: "Hello!", recipientId: "12345" },
        { message: "How are you?", recipientId: "67890" },
      ]}
      handler={handleSendMessage}
    />
  );
}

Example Breakdown:

name is set to "SendMessage" to identify the action. description provides a brief summary of the action's purpose. state is set to "ready" to indicate the current status of the action. schema defines the expected input parameters, validating that message and recipientId are strings. examples show sample data for the message and recipientId inputs. handler is an asynchronous function that handles the SendMessage action when it is triggered. Component Lifecycle When the Action component is mounted, it registers the action with the agent registry using the registerAction method, associating the action with a unique symbol. When unmounted, it unregisters the action, ensuring no memory leaks.

Dependencies

The component recalculates and registers the action if any of the following dependencies change:

name description Serialized schema (printZodSchema) Serialized examples Serialized handler function