Tools

In xFlow, the AI Agent State leverages tools to enhance the capabilities of AI agents by integrating various actions and functions into the workflow. This documentation explains the usage of tools within AI agents, how these tools are supported by xFlow, and how they are distributed and executed by the xFlow workflow engine.

Tools in AI Agent State

Tools in AI Agent State are designed to perform specific tasks or actions that enhance the functionality of the AI agent. These tools can range from searching documents, processing transactions, to interacting with other services. The configuration of each tool includes properties such as the tool's name, description, parameters, output, execution mode, and metadata.

Tool Properties

Name

• Name: name

• Type: string

• Description: The name of the tool. This is a unique identifier used to reference the tool within the workflow.

• Example:

  name: "SEARCH_DOCUMENTS"

Description

• Name: description

• Type: string

• Description: A brief description of what the tool does. This helps in understanding the purpose and functionality of the tool.

• Example:

  description: "Search for relevant documents based on the user's query."

Parameters

• Name: parameters

• Type: object

• Description: The JSON schema that describes the parameters required by the tool. These parameters are inputs needed for the tool to perform its action. The parameters schema helps the LLM understand what inputs are required to execute the tool properly.

• Example:

  parameters: 
    schema: 
      type: "object"
      properties: 
        query: 
          type: "string"
          description: "The search query"
      required: ["query"]

Output

• Name: output

• Type: object

• Description: The JSON schema that describes the output of the tool. This defines the structure of the data that the tool returns after execution. The output schema helps the LLM understand what to expect as a result of the tool's execution.

• Example:

  output: 
    schema: 
      type: "object"
      properties: 
        documents: 
          type: "array"
          items: 
            type: "string"
            format: "uri"
      required: ["documents"]

Execution

• Name: execution

• Type: object

• Description: Defines how the tool's actions are to be executed. This includes the action mode (sequential or parallel) and the list of actions to be performed.

• Example:

  execution:
    actionMode: "sequential"
    actions:
      - name: "FetchDocuments"
        functionRef:
          refName: "FetchDocumentsFunction"
          arguments:
            query: "${ .request.query }"

Metadata

• Name: metadata

• Type: object

• Description: Additional metadata for the tool. This can include information such as version, author, and other relevant details.

• Example:

  metadata:
    version: "1.0"
    author: "Developer Name"

Execution of Tool Actions in xFlow

Distributed Execution

The xFlow workflow engine supports distributed execution of tool actions. When a tool action is triggered, it can be executed by a distributed worker in the xFlow engine. This built-in support ensures that actions are performed efficiently, leveraging the distributed nature of the workflow engine to handle multiple tasks concurrently.

Sequential Execution

In sequential execution mode, the actions defined in the tool are executed one after the other, in the order they are specified. This mode is useful when the actions are dependent on the output of the previous action.

• Example:

  execution:
    actionMode: "sequential"
    actions:
      - name: "FetchDocuments"
        functionRef:
          refName: "FetchDocumentsFunction"
          arguments:
            query: "${ .request.query }"
      - name: "ProcessDocuments"
        functionRef:
          refName: "ProcessDocumentsFunction"
          arguments:
            documents: "${ .FetchDocuments.results }"

Parallel Execution

In parallel execution mode, the actions defined in the tool are executed simultaneously. This mode is useful for independent actions that can be performed concurrently to save time and resources.

• Example:

  execution:
    actionMode: "parallel"
    actions:
      - name: "FetchDocuments"
        functionRef:
          refName: "FetchDocumentsFunction"
          arguments:
            query: "${ .request.query }"
      - name: "FetchMetadata"
        functionRef:
          refName: "FetchMetadataFunction"
          arguments:
            query: "${ .request.query }"

Example Usage in AI Agent State

Here is an example of how to configure an AI Agent State with a tool that searches for documents:

- name: ExampleAIState
  type: aiagent
  agentName: ExampleAgent
  aiModel: gpt-4o
  systemMessage: "You are an assistant designed to provide accurate answers."
  userMessage: '${ "User: " + .request.question }'
  output: 
    {
      "type": "object",
      "properties": {
          "response": {
              "type": "string",
              "description": "The AI's response to the user question"
          }
      },
      "required": ["response"]
    }
  maxToolExecutions: 5
  memory: 
    memoryId: "session123"
    memoryType: "message_window"
    maxMessages: 10
  tools:
    - name: SEARCH_DOCUMENTS
      description: "Search for relevant documents based on the user's query."
      parameters: 
        schema: 
          type: "object"
          properties: 
            query: 
              type: "string"
              description: "The search query"
          required: ["query"]
      output: 
        schema: 
          type: "object"
          properties: 
            documents: 
              type: "array"
              items: 
                type: "string"
                format: "uri"
          required: ["documents"]
      execution:
        actionMode: "sequential"
        actions:
          - name: "FetchDocuments"
            functionRef:
              refName: "FetchDocumentsFunction"
              arguments:
                query: "${ .request.query }"
  agentOutcomes:
    - condition: '${ $agentOutcome.returnValues.response != null }'
      transition: SuccessState
    - condition: '${ $agentOutcome.returnValues.response == null }'
      transition: ErrorState

For more detailed information and advanced configurations, refer to the AI Agent Development Documentation.