UserProxyAgent State

The UserProxyAgentState is used to define an agent whose role is a bridge between the workflow and the user. This state outlines the configuration of the agent, including the communication context, user messages, roles, data schemas, known data, and outcomes. This specification provides a comprehensive overview of the UserProxyAgentState and its related objects.

UserProxyAgentState

The UserProxyAgentState is a specialized state in a serverless workflow designed to facilitate communication between the workflow and a user through an AI agent. This state specifies the agent's role, communication channels, messages, data schemas, and possible outcomes.

Parameter	Description	Type	Required
agentName	The name of the agent.	string	yes
agentRole	The role of the agent in the conversation. Can be 'relay' or 'facilitator'. Default is 'relay'.	string	no
userMessage	The user message.	string	no
relayMessage	Used for the 'relay' role, message to relay to the user. See UserMessageDef.	object	no
collectDataSchema	Used for the 'facilitator' role, JSON schema for data to ask the user for. See DataSchema.	object	no
knownData	The data that the agent already knows about the user and the conversation in JSON format.	string	no
agentOutcomes	Define list of agent outcomes. Each outcome is described by the OnAgentOutcome schema.	array	yes
dataFilter	Filter to apply to the state data.	string	no

DataSchema

The DataSchema object describes the schema for date-related outputs.

Field	Type	Description	Required
schema	string	URI of the JSON Schema used to describe the agent data output	yes

UserMessageDef

The UserMessageDef object describes the structure of the user messages sent to the AI agent.

Field	Type	Description	Required
text	string	The text of the user message	yes
media	array	The media file URLs of the user message, each described by MediaContent schema.	no
mediaExp	string	The jq expression for list of media file URLs of the user message	no

MediaContent

The MediaContent object defines the structure for media files associated with user messages.

Field	Type	Description	Required
uuid	string	The unique identifier of media content.	yes
url	string	The URL of the media file	One of url or base64Data must be provided
base64Data	string	The base64 encoded data of the media file	One of url or base64Data must be provided
mimeType	string	The mime type of the media file	no
description	string	The description of media content.	no

OnAgentOutcome

The OnAgentOutcome object defines the actions to be performed based on the outcome of the AI agent. The actions are executed if the outcome matches the specified conditions.

Field	Type	Description	Required
condition	string	Expression, if defined, must evaluate to true for this outcome to be matched. If false, the outcome is disregarded.	yes
finish	boolean	If true, the agent will finish after this action is executed. If false, the agent will continue to process.	yes
dataFilter	object	Event data filter described by the EventDataFilter schema.	no
transition	object	The outgoing transition when the outcome is selected, if not defined the default transition will be used.	no

Example:

Relay role example:

YAML

states: - name: InformRagResult agentName: InformRagResult type: userproxyagent agentRole: relay conversationId: ${ .request.userChannelContext.conversationId } userMessage: '${ .request.question }' userChannelContext: ${ .request.userChannelContext } userContext: ${ .request.userContext } relayMessage: text: ${ ._ai_agent_state.RagAgent.agentOutcome.finish.output.returnValues.answer } mediaExp: ${ ._ai_agent_state.RagAgent.agentOutcome.finish.output.returnValues.images } output: |- { "type": "object", "properties": { "answer": { "type": "string" } }, "required": ["answer"] } agentOutcomes: - condition: '${ true }' finish: true transition: Finish

Facilitator role example:

YAML

states: - name: BuyProductTransactionUserProxy agentName: BuyProductTransactionUserProxy type: userproxyagent agentRole: facilitator userMessage: '${ .request.question }' conversationId: ${ .request.userChannelContext.conversationId } userChannelContext: ${ .request.userChannelContext } userContext: ${ .request.userContext } collectDataSchema: |- { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "sku": { "type": "string", "description": "Unique sku code of the product, this field can be identified by trying to identify by product name in user request and check if it match with the name of the product from the list of available products. If cannot identity, ask user to select the product from the list of available products" }, "fullName": { "type": "string", "description": "Customer full name" }, "phoneNumber": { "type": "string", "description": "Customer phone number" }, "address": { "type": "string", "description": "Customer address to deliver the product" } }, "required": ["sku", "fullName", "phoneNumber", "address"] } knownData: |- ${ { "fullName": .request.customer.fullName, "phoneNumber": .request.customer.phoneNumber, "userRequest": .request.question, "availableProducts": .request.products } } output: |- { "type": "object", "properties": { "sku": { "type": "string", "description": "Unique sku code of the product" }, "fullName": { "type": "string", "description": "Customer full name" }, "phoneNumber": { "type": "string", "description": "Customer phone number" }, "address": { "type": "string", "description": "Customer address to deliver the product" } }, "required": ["sku", "fullName", "phoneNumber", "address"] } agentOutcomes: - condition: '${ true }' finish: true transition: CollectOrderInfo transition: Finish

---

This document provides a detailed view of the UserProxyAgentState state and its related objects, including comprehensive schema definitions, required fields, and descriptions for each attribute within the UserProxyAgentState and associated schemas. This specification ensures clarity and completeness for integrating AI agents within serverless workflows.