AI Agents Integration

Overview

This document details the integration between the xFlow system and AI agents developed by any AI framework via REST API. The integration includes the communication protocols, data structures, and the sequence of interactions.

Communication Protocol

• Protocol: REST API

• Data Format: JSON

• Request Initiator: xFlow system

• Response Receiver: xFlow system (via webhook)

API Endpoints

• Request Endpoint: https://<aiagent-execution-endpoint>/api/execute

• Response Webhook Endpoint: https://xfai/api/agentProxy/sendResult

Integration Flow Details

Detailed Integration Flow

AI Agent Integration Flow

1. Request Initialization:

   • The xFlow system initializes a request to the AI agent. This request includes data conforming to the ExecuteAIAgentProxyRequest schema.

   • The request contains the agentConfig, agentContext, and workflowId.

2. Sending the Request:

   • The xFlow system sends the request to the AI agent's endpoint https://aiagent-execution-endpoint/api/execute.

   • The AI agent acknowledges the request and returns a unique UUID as the request ID.

3. Processing the Request:

   • The AI agent processes the request based on its internal logic, using the provided agentConfig and agentContext.

   • This may involve various computations, interactions with other services or tools, and generating a response.

4. Returning the Response:

   • Upon completing the processing, the AI agent sends the response back to the xFlow system via the webhook endpoint https://xfai/api/agentProxy/sendResult.

   • The response data conforms to the AIAgentProxyExecutionResponse schema.

   • The xFlow system uses the UUID received earlier to correlate the response with the original request.

Data Structures

ExecuteAIAgentProxyRequest

Property	Type	Description
agentConfig	object	Configuration details for AI agent execution, including agent name and message
agentContext	object	Context for AI agent execution, including input message, chat memory, etc.
workflowId	string	Unique identifier for the workflow

agentConfig

Property	Type	Description
agentName	string	Name of the agent
systemMessage	string	The system message provided to the agent helps customize its behavior if supported.

agentContext

The context for the AI agent proxy execution.

Property	Type	Description
input	string	Message to be processed by the agent
memoryId	string	The unique identifier for the memory storage provided to the agent helps customize its behavior if supported; otherwise, the agent may use its own memory strategy.
chatHistory	array	Array of chat messages. See chatHistory
intermediateSteps	array	Array of intermediate steps taken by the agent. See intermediateSteps
data	object	Additional data related to the agent execution
authContext	object	The authentication context requested by the chatbot system initiates a new agent workflow instance, providing information about the client's security context. See authContext

chatHistory

The chat conversation history consists of an array of messages exchanged. It is optional and will not be sent to the AI agent if memory was specified. Below is the structure of each message:

Property	Type	Description
text	string	The message text
type	string	The type of the message (USER or SYSTEMor AI or TOOL_EXECUTION_RESULT)

intermediateSteps

The intermediate steps exchanged by other agents during the execution of agent workflow. Each step includes an action and an observation. It is optional and will not be sent to the AI agent if memory was specified. Below is the structure of each step:

Property	Type	Description
stepName	string	The name of the intermediate step
details	string	Additional details about the intermediate step

authContext

Property	Type	Description
userId	integer	Unique identifier for the user
globalEmail	string	User's global email address
userCode	string	User's unique code
fullName	string	User's full name
identity	string	User's identity
tenantCode	string	Code for the tenant
appId	integer	Unique identifier for the application
appCode	string	Code for the application
channel	string	Communication channel (e.g., ZALO, TEAMS)

AIAgentProxyExecutionResponse

Property	Type	Description
requestId	string	The request id returned at the Sending the Request step.
result	object	The AI Agent execution result. See AIAgentProxyExecutionResult

AIAgentProxyExecutionResult

Property	Type	Description
agentOutcome	object	Outcome of the AI agent's execution

agentOutcome

Property	Type	Description
finish	object	Final result of the AI agent's execution. AI Agent return this value if the execution is successful. See finish
error	object	Errors occurred during the AI agent's execution. AI Agent return this value if the execution is failed. See error
messages	array	(Optional) List of messages exchanged during the execution. The messages and intermediateSteps in the result are optional. The AI agent can choose to share this data with other agents if necessary.
intermediateSteps	array	(Optional) List of intermediate steps taken during the execution. The messages and intermediateSteps in the result are optional. The AI agent can choose to share this data with other agents if necessary.

finish

Final result of the AI agent's execution. AI Agent return this value if the execution is successful.

Property	Type	Description
result	string	The final result of the AI agent's execution

error

Errors occurred during the AI agent's execution. AI Agent return this value if the execution is failed.

Property	Type	Description
code	string	Error code
message	string	Error message
details	string	Additional details about the error

Example Requests and Responses

Example ExecuteAIAgentProxyRequest

Request:

{
  "agentConfig": {
    "agentName": "ExampleAgent",
    "systemMessage": "You are a helpful AI Assistant."
  },
  "agentContext": {
    "input": "What is the weather like today?",
    "memoryId": "mem123",
    "chatHistory": [
      {
        "text": "Hi, how can I help you today?",
        "type": "SYSTEM"
      }
    ],
    "intermediateSteps": [],
    "data": {},
    "authContext": {
      "userId": 123,
      "globalEmail": "[e-mail]",
      "userCode": "XBOT#A4B#[e-mail]",
      "fullName": "John Doe",
      "identity": "[e-mail]",
      "tenantCode": "A4B",
      "appId": 1,
      "appCode": "XBOT",
      "channel": "ZALO"
    }
  },
  "workflowId": "workflow123"
}

Response:

{
  "requestId": "uuid12345"
}

Example AIAgentProxyExecutionResponse

Response:

{
  "requestId": "uuid12345",
  "result": {
    "agentOutcome": {
      "finish": {
        "result": "The weather in New York is sunny."
      },
      "error": null,
      "messages": [
        {
          "text": "What is the weather like today?",
          "type": "USER"
        },
        {
          "id": "toolReq1",
          "name": "WeatherAPI",
          "arguments": "location=New York",
          "type": "TOOL_EXECUTION_RESULT"
        },
        {
          "text": "The weather in New York is sunny.",
          "type": "AI"
        }
      ],
      "intermediateSteps": []
    }
  }
}

By following this documentation, developers can ensure a smooth integration between the xFlow system and various AI agents, enabling efficient orchestration and execution of AI-driven tasks.