User Proxy Agent

The User Proxy Agent State in xFlow is designed to facilitate interactions between the workflow and users. This state acts as a mediator, ensuring that user inputs are correctly captured and integrated into the workflow, and that responses from the workflow are appropriately relayed to the user. This documentation explains the purpose of the User Proxy Agent State, the agent roles it supports, and how to implement this state in xFlow workflows.

Purpose of User Proxy Agent State

The User Proxy Agent State serves several critical purposes within xFlow workflows:

1. User Interaction Management: Enables seamless communication between users and the workflow, ensuring that user inputs are captured and processed effectively.

2. AI Assistance: Utilizes AI agents to facilitate user interactions, providing intelligent responses and guidance based on the workflow context.

3. Data Relay: Acts as an intermediary to relay information between the user and the workflow, maintaining context and ensuring data integrity.

4. Flexibility: Supports various agent roles, allowing for customized interactions based on the specific needs of the workflow.

Supported Agent Roles

The User Proxy Agent State supports multiple agent roles, each designed to handle different types of interactions and tasks within the workflow. These roles include:

Relay

• Description: The Relay role is designed to pass information between the user and the workflow without altering the data. It ensures that user inputs are relayed to the workflow and that responses from the workflow are delivered back to the user accurately.

• Use Case: Ideal for scenarios where the primary function is to convey messages between the user and the workflow, such as status updates or simple queries.

• Example:

  agentRole: relay
  userMessage: '${ .request.question }'
  relayMessage:
    text: '${ .response.answer }'
    mediaExp: '${ .response.images }'

Facilitator

• Description: The Facilitator role helps guide the user through complex interactions, providing prompts and collecting necessary data. It can also handle validations and ensure that the required information is obtained before proceeding.

• Use Case: Suitable for scenarios that require multi-step interactions, such as filling out forms, collecting approvals, or conducting surveys.

• Example:

  agentRole: facilitator
  userMessage: '${ .request.question }'
  collectDataSchema: 
    type: "object"
    properties: 
      fullName: 
        type: "string"
        description: "Customer full name"
      phoneNumber: 
        type: "string"
        description: "Customer phone number"
      address: 
        type: "string"
        description: "Customer address"
    required: ["fullName", "phoneNumber", "address"]

Properties of User Proxy Agent State

Agent Role

• Name: agentRole

• Type: string

• Description: Specifies the role of the AI agent within the state. The role determines how the agent will interact with the user and process the data.

• Example:

  agentRole: "relay"

User Message

• Name: userMessage

• Type: string

• Description: The message from the user that the AI agent will process. This is dynamically populated based on the workflow’s data.

• Example:

  userMessage: '${ "User: " + .request.question }'

Relay Message

• Name: relayMessage

• Type: object

• Description: Defines the structure of the message to be relayed back to the user. This includes the text and any media content.

• Example:

  relayMessage:
    text: '${ .response.answer }'
    mediaExp: '${ .response.images }'

Collect Data Schema

• Name: collectDataSchema

• Type: object

• Description: Defines the schema for the data to be collected from the user. This schema ensures that the necessary information is captured and structured correctly.

• Example:

  collectDataSchema: 
    type: "object"
    properties: 
      fullName: 
        type: "string"
        description: "Customer full name"
      phoneNumber: 
        type: "string"
        description: "Customer phone number"
      address: 
        type: "string"
        description: "Customer address"
    required: ["fullName", "phoneNumber", "address"]

How to Implement User Proxy Agent State

To implement a User Proxy Agent State in xFlow, follow these steps:

1. Define the User Proxy Agent State: In your workflow definition, add a User Proxy Agent State with the necessary properties such as agentRole, userMessage, relayMessage, and collectDataSchema.

2. Configure the Agent Role: Specify the role of the AI agent to determine how it will interact with the user. Choose the appropriate role based on the interaction type and workflow requirements.

3. Handle User Messages: Define the userMessage property to capture the user's input dynamically. Ensure that the message content aligns with the workflow context.

4. Relay Messages: If using the relay role, configure the relayMessage property to define the structure of the message to be sent back to the user.

5. Collect Data: If using the facilitator role, define the collectDataSchema to specify the data to be collected from the user. Ensure that all required fields are included and properly described.

Example Workflow Configuration

- name: UserInteractionState
  type: userproxyagent
  agentRole: "relay"
  userMessage: '${ "User: " + .request.question }'
  relayMessage:
    text: '${ .response.answer }'
    mediaExp: '${ .response.images }'
  transition: 
    nextState: "HandleResponseState"

For more detailed information and advanced configurations, refer to the User Proxy Agent State Documentation.