Data Collector

Overview

The Data Collector is an agent that facilitates data collection from users through structured interactions. It guides users through forms, questionnaires, or data gathering processes while validating input against defined schemas. This agent is particularly useful for scenarios where structured user input, registration processes, surveys, or guided data collection workflows are required in the xbot product.

Configuration Details

Field	Description	Type	Required	Default
name	The unique name of the facilitator agent within the workflow	String	Yes	-
start	Indicates if this is the starting agent of the workflow	Boolean	No	false
transition	Defines the transition to the next flow node after data collection completes. See TransitionDef	Object	No	-
answerAfterFinish	Whether the agent should provide an answer message after finishing data collection	Boolean	No	false
answerMessage	Custom message to display when data collection is complete	String	No	-
userMessage	Message template to prompt users for data collection. Can reference missing fields and known data	String	Yes	-
agentOutcomes	List of outcome handlers that define actions to take based on data collection results. See OnAgentOutcomeDef	List	No	[]
collectDataSchema	Schema definition that specifies the structure and validation rules for data to be collected from users. See DataSchemaDef	Object	Yes	-
knownData	Pre-populated data that is already known about the user or context, reducing the need to collect certain information	Map<String, Object>	No	-
loginRequired	Whether user authentication is required to interact with this facilitator agent	Boolean	No	-

Common Configuration Objects

DataSchemaDef

Data Schema Definition. Defines the structure and validation rules for data used in AI workflows. Contains JSON Schema specifications that ensure data integrity and provide type safety for agent interactions and data transformations.

Field	Description	Type	Required
schema	JSON Schema definition that describes the structure, types, and validation rules for data objects. Must be a valid JSON Schema specification that can be used for data validation and type checking in AI workflows	JsonNode	Yes

OnAgentOutcomeDef

Agent Outcome Definition. Defines conditional actions to be performed based on the outcome of an AI agent's execution. Allows for branching logic, workflow control, and custom responses based on agent results or specific conditions.

Field	Description	Type	Required	Default
condition	Expression that must evaluate to true for this outcome to be matched. Uses workflow expression language to evaluate agent results, context variables, or other conditions	String	Yes	-
finish	Whether the agent should finish execution after this outcome action is performed	Boolean	No	true
transition	The transition definition specifying the next step in the workflow when this outcome is matched	Object	No	-
answerAfterFinish	Whether to provide an answer message after finishing this outcome action	Boolean	No	false
answerMessage	Custom message to display when this outcome is triggered and answerAfterFinish is true	String	No	-

TransitionDef

Transition Definition. Defines the flow control mechanism for moving between different states or agents in a workflow. Specifies either a target destination or workflow termination, enabling complex branching and routing logic in AI agent conversations.

Field	Description	Type	Required	Default
end	Whether this transition marks the end of the workflow execution. When true, the workflow terminates. When false, execution continues to the target agent	Boolean	No	false
targetId	The unique identifier of the target agent or node to transition to. Must correspond to a valid agent name defined in the workflow. Ignored if 'end' is true	String	No	-

Example Configuration

Here's a comprehensive example showing how to configure a Facilitator Agent for user registration data collection:

{
  "type": "facilitator",
  "name": "registrationFacilitator",
  "description": "Facilitator agent for collecting user registration information with validation",
  "start": false,
  "userMessage": "Welcome! To complete your registration, I need to collect some information from you. Please provide: {{missingFields}}",
  "collectDataSchema": {
    "schema": {
      "type": "object",
      "properties": {
        "fullName": {
          "type": "string",
          "description": "Your full legal name",
          "minLength": 2,
          "maxLength": 100
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Your email address for account verification"
        },
        "phone": {
          "type": "string",
          "pattern": "^\\+?[1-9]\\d{1,14}$",
          "description": "Your phone number with country code"
        },
        "dateOfBirth": {
          "type": "string",
          "format": "date",
          "description": "Your date of birth (YYYY-MM-DD)"
        },
        "preferences": {
          "type": "object",
          "properties": {
            "newsletter": {"type": "boolean"},
            "language": {"type": "string", "enum": ["en", "es", "fr"]}
          }
        }
      },
      "required": ["fullName", "email", "phone"],
      "additionalProperties": false
    }
  },
  "knownData": {
    "source": "website",
    "campaign": "summer_promo",
    "referralCode": "FRIEND2024"
  },
  "loginRequired": false,
  "agentOutcomes": [
    {
      "condition": "{{data.email}} != null && {{data.fullName}} != null",
      "finish": false,
      "transition": {
        "targetId": "emailVerificationAgent"
      },
      "answerAfterFinish": true,
      "answerMessage": "Thank you for providing your information! I'm now sending a verification email to {{data.email}}."
    },
    {
      "condition": "{{validation.errors}} != null",
      "finish": false,
      "answerAfterFinish": true,
      "answerMessage": "I noticed some issues with the information provided. Please correct: {{validation.errors}}"
    }
  ],
  "transition": {
    "targetId": "dataProcessingAgent"
  },
  "answerAfterFinish": true,
  "answerMessage": "Registration information collected successfully. Processing your account..."
}

Simple Survey Example

A simpler example for collecting survey feedback:

{
  "type": "facilitator",
  "name": "feedbackSurvey",
  "userMessage": "We'd love to hear your feedback! Please answer these questions:",
  "collectDataSchema": {
    "schema": {
      "type": "object",
      "properties": {
        "satisfaction": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5,
          "description": "How satisfied are you with our service? (1-5)"
        },
        "recommendation": {
          "type": "boolean",
          "description": "Would you recommend us to others?"
        },
        "comments": {
          "type": "string",
          "maxLength": 500,
          "description": "Additional comments (optional)"
        }
      },
      "required": ["satisfaction", "recommendation"]
    }
  },
  "answerAfterFinish": true,
  "answerMessage": "Thank you for your valuable feedback!",
  "transition": {
    "end": true
  }
}