@formio/uag 1.10.2 → 1.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +66 -107
  2. package/package.json +9 -4
package/README.md CHANGED
@@ -1,101 +1,40 @@
1
- # The Form.io Universal Agent Gateway (UAG)
2
- The Universal Agent Gateway (UAG) introduces the power of [Form.io](https://form.io) forms to AI agents.
1
+ <p align="center">
2
+ <img src="./examples/images/logo-formio-uag.png" alt="The Form.io Universal Agent Gateway (UAG)" width="40%">
3
+ </p>
3
4
 
4
- The Form.io UAG uses the [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/docs/getting-started/intro) to enable Form.io interaction through an AI agent workflow. By providing AI agents with the **dynamic context** of how to use Form.io JSON forms, the UAG allows a user to interact with any aspect of their enterprise system served by the Form.io Platform directly through their AI agent.
5
+ The Universal Agent Gateway (UAG) leverages the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) to enable in-process agentic automation using Form.io. It provides to an AI Agent the same thing that our [JavaScript Renderer](https://github.com/formio/formio.js) provides to a human; an interpretation of the Form JSON schema into an understandable format. In the case of UAG, it transforms the Form JSON model into an AI readible markdown format so that the Agent can easily understand the purpose and structure of the data that needs to be collected.
5
6
 
6
- ---
7
-
8
- ## Table of Contents
9
-
10
- - [The Form.io Universal Agent Gateway (UAG)](#the-formio-universal-agent-gateway-uag)
11
- - [Introduction](#introduction)
12
- - [The Model Context Protocol (MCP)](#the-model-context-protocol-mcp)
13
- - [Dynamic Context](#dynamic-context)
14
- - [The Role of the UAG](#the-role-of-the-uag)
15
- - [Technical Overview](#technical-overview)
16
- - [MCP Tools](#pre-defined-mcp-tools-providing-dynamic-context)
17
- - [Agentic Workflows](#agentic-workflows)
18
- - [Claude Integration](#integrations)
19
- - [Custom Modules](#custom-modules)
20
- - [Module Documentation](./module)
21
- - [Deploying UAG](#deploying-uag)
22
- - [Runtime Environments](#runtime-environments)
23
- - [Docker](#docker)
24
- - [Node.js (Express)](#nodejs-express)
25
- - [Environment Variables](#environment-variables)
26
- - [Running on Public Domain](#running-on-public-domain)
27
- - [Using with Form.io Enterprise Server](#using-with-formio-enterprise-server)
28
-
29
- ---
30
-
31
- ## Introduction
32
- The core purpose of the UAG is to equip AI agents with the ability to forward a user's inputs to the Form.io platform. It allows the AI agent to apply natural language requests, scanned documents, and any other input it can parse into Form.io functionality, as defined by selected forms and fields.
7
+ ![Diagram showing how the UAG provides an AI Agent the ability to read and understand a Form.io Form JSON. Similar to how the JavaScript renderer provides a Human the ability to visually see a rendered form.](./examples/images/uag-agent-rendering.png)
33
8
 
34
- ### The Model Context Protocol (MCP)
35
- The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems.
9
+ There are two primary scenarios that the UAG enables:
36
10
 
37
- The MCP essentially puts an AI agent's hands on the controls of an external system. In the case of Form.io, the MCP describes a discrete set of tools the AI agent can use to interact with forms, fields, and submissions. While some tools are delivered off-the-shelf, this functionality can be extended, modified, or refined through custom built modules.
11
+ - **Unstructured content conversion to deterministic structured data**: This capability uses the JSON schema of a Form.io form to produce a deterministic structured data object provided a Natural Language input.
38
12
 
39
- ### Dynamic Context
40
- What does it mean to say MCP provides a dynamic context for how to use these tools?
13
+ ![Conversion of natural language to structured data using UAG.](./examples/images/uag-natural-language.png)
41
14
 
42
- The power of AI agents is their ability to parse free-form inputs, like natural language, and infer a user's intent rather than take rote input like a command line. The dynamic context delivered by MCP gives the AI agent guidance on how to correlate the user's prompt to the tools and data available within Form.io. When the AI agent receives a prompt, it uses this dynamic context to determine what tool it should use, what elements of the prompt are inputs to that tool, and what additional input might be necessary.
15
+ - **Agentic Form.io Workflows**: UAG provides an AI Agent the ability to take existing submission data + "context" criteria in order to prompt an AI Agent to provide its own data and analysis within a workflow scenario. The following example, which shows a college application process using a Form.io application form, shows how this primary scenario works.
43
16
 
44
- ### The Role of the UAG
45
- The UAG is the package that contains everything sitting between the Form.io Platform and the AI agent.
46
- It contains the stock MCP server, the authorization infrastructure, and any custom tools or modules that extend the functionality.
17
+ ![Agentic workflow automation example diagram using UAG](./examples/images/uag-agent-provide-data.png)
47
18
 
48
- By equipping an AI agent with Form.io capabilities, the UAG brings the AI agent much deeper into the broader application ecosystem.
49
- Form.io's drag-and-drop Form Builder simultaneously defines the look of the form and the structure of the data. This makes it easy to use data collected through Form.io forms elsewhere in an application or as an input to other enterprise systems.
50
- ![](./examples/images/form-interfaces.png)
51
-
52
- When the UAG is able to map the freeform inputs that an AI agent receives to the data model defined by a form, it means that data can be quickly supplied to the enterprise tools that depend on the Form.io platform without additional interpretation or transformation.
53
- This allows the UAG and Form.io to serve as a reliable middleware between an AI agent and countless other systems.
54
-
55
- The same role-based access control that governs all Form.io forms and submissions still applies to any interaction through the UAG. This addresses many potential issues some users may have with connecting AI agents to enterprise systems.
56
-
57
- Here is a visual graphic of the layers provided by the UAG to achieve a trusted and deterministic interface between AI Agents to external systems through the UAG + Form.io Server.
19
+ For more information on Agentic workflows, checkout the dedicated [Agentic Workflows](#agentic-workflows) section
58
20
 
59
- ![](./examples/images/agents_to_formio.png)
60
-
61
- ## Technical Overview
62
- The UAG can be thought of as consisting of many layers of functionality. Each layer is broadly either serving to fetch dynamic context, or submit deterministic data structures. The following layers are leveraged within the UAG:
21
+ ---
63
22
 
64
- 1. **MCP Interface**: The entry point of the UAG is the MCP interface that sits between the AI agent and the tools that are executed on the server.
65
- 2. **Authorization**: As part of the MCP specification, every interaction between the AI agent and the backend service must pass through an Authorization process leveraging OIDC (PKCE) authentication. The UAG takes this process one step further, however, by adding an OIDC (PKCE) authentication layer on top of the existing authentication flexibilities that Form.io already provides. Because of this, it is possible to authenticate with the UAG if you are using SAML, Form.io Authentication, OIDC, or even Custom Authentication processes through the Form.io platform.
66
- 3. [**Pre-defined MCP Tools providing Dynamic Context**](#pre-defined-mcp-tools-providing-dynamic-context): The UAG utilizes the MCP to provide a number of pre-defined tools that provide AI agents with dynamic context based on the Forms and Resources marked as compatible within the Form.io platform. These tools are described in more detail in a section below.
67
- 4. **Custom Tools** (provided by [Custom Modules](#custom-modules)): This enables developers to introduce any new tools that can leverage Form.io forms and submission data structures to provide additional capabilities introduced to the AI agents. This would allow for custom agent interactions to achieve certain goals for specific use cases.
68
- 5. **Custom Actions** (provided by [Custom Modules](#custom-modules)): Enables developers to create composable middleware that will be executed once all data provided by the AI agent has been sanitized and validated. This provides the ability to interface the data collected from AI agents with any backend system or workflow.
69
- 6. **Built-in Actions**: In addition to any custom actions introduced via a Module, the UAG supports a handful of existing Actions that can be assigned to any form or resource. Actions such as the **Webhook** that will send a REST API call to any endpoint once any submission has been made by an AI agent. This can be used to point to any serverless function to instigate backend workflows that are triggered from the interactions from AI agents.
70
- 7. **Pre-defined Forms and Resources** (provided by [Custom Modules](#custom-modules)): Allows a developer to release a module that provides default data structures to the AI agent. This would be useful if a developer wishes to create a module that achieves a specific goal, where the data structures required for that goal need to follow a pre-determined set of fields provided by a form or resource. For example, if a developer wishes to release a CRM module for the UAG, then it would make sense that the module would also provide the default **Customer** and **Company** resources that commonly accompany most CRM implementations.
71
- 8. **Custom Database** (provided by [Custom Module](#custom-modules)): By default, the UAG performs the data collection and retrieval via a "Submission Proxy", whereas the data is submitted via REST API to either the Enterprise Server project or the Open Source server. This, however, could be modified to send the data directly to and from a Database. This can be achieved via the Database Interface provided from the UAG. For more information, see the **Module** documentation. This feature does require that the UAG is connected to the Enterprise Server.
72
-
73
- Here is a diagram to understand how all of these layers are organized to make up the UAG.
23
+ One of the many benefits that the UAG has to offer is the ability to inject **Dynamic Context** into an AI processing cycle. This is achieved from the dynamic nature of the Form JSON schemas that can easily be modified and deployed to any enviornment without the need to update your application or re-train the agents within the process. Because of this, dynamic context changes can be injected seamlessly into an existing running process which will automatically update the behaviors of the Agents utilzing the UAG.
74
24
 
75
- ![](./examples/images/uag-overview.png)
25
+ ## Try it out!
26
+ The quickest way to try out the UAG run the [Local Example](examples/local) which will spin up a local instance of Form.io Open Source and UAG. This can then be connected to an AI agent, which will have the ability to interact with the included example forms. The local example can be run entirely free, with no trial or license required.
76
27
 
77
- ### Pre-defined MCP Tools providing Dynamic Context
78
- The following tools provided by the UAG can be described as follows:
28
+ **[Go to Local Example &raquo;](examples/local)**
79
29
 
80
- | Tool Name | Tool Description |
81
- |-----------------|----------------------|
82
- | get_forms | Provides the AI agent with a list of available forms. <br/>It will only return forms that have been tagged `uag`. |
83
- | get_form_fields | When the AI agent infers the user intends to use a specific form, this tool provides the agent with a high level overview of all the fields needed (along with the field data path) to submit that form. |
84
- | get_field_info | Once the fields have been determined using `get_form_fields`, this tool provides specific information about the requested fields, such as validation, conditionals, input formats, etc. <br/>This tool instructs the AI agent on how to format and structure the data that is sent to the MCP server. |
85
- | collect_field_data | Provides the AI agent with a mechanism to dynamically collect the required information from the user. It can parse the user's input into multiple fields at once, and will identify additional inputs from the user if needed. <br/>This tool supports complex and structured data collection and is compatible with nested or multi-value fields like nested forms, data grids, etc. |
86
- | confirm_form_submission | This tool is used to provide a summary of all data collected before a submission is made to the form. |
87
- | submit_completed_form | Provides the AI agent with the ability to submit all of the data collected from the user to create the form submission. |
88
- | find_submissions | Enables the agent to parse a user's natural language request into a query for a submission, or a specific field of a particular submission. |
89
- | submission_update | Provides the AI agent with the ability to update an existing submission, either by supplying unfilled fields or updating existing ones if allowed. Provides the AI agent with the context of the existing field values, allowing inline changes or edits. |
90
- | agent_provide_data | Enables an AI Agent to be able to analyze existing submission data according to rules defined with a configurable **Criteria**. It will then instruct the Agent to provide generated data for fields configured for a specific **persona** using the `submission_update` tool. Please read the [**Agentic Workflows**](#agentic-workflows) section for more information about this toolset. |
91
- | fetch_external_data | This tool enables an AI Agent to pull external data into a form workflow through the use of either a Resource component, Select with URL, or a Data Source component. |
30
+ ---
92
31
 
93
32
  ## Agentic Workflows
94
33
  One of the more powerful features of the **UAG** is the `agent_process_data` tool. This tool provides the ability to instruct a generically trained agent how to analyze existing submission data, and then produce its own data by following a configurable **Criteria**. This behavior historically could only be achieved using a specifically trained agent, which does not provide any benefits of dynamic configurability that the Form.io platform offers. This tool is able to achieve this goal by providing a generally trained agent with the necessary "context" it needs to accurately produce its own data as part of an automated workflow. This feature is particularly helpful if you wish to utilize the UAG within an Agentic Workflow, where the AI Agent is capable of understanding structured data, and then contribute its own data by following the configured **Criteria** "context" provided by the UAG.
95
34
 
96
35
  For example, let's suppose you wish to automate the backend administration behind a College Application Process. In this example, a potential student submits an application that consists of many different fields of data, such as Academnics, Extra curricular activities, Honors, Volunteer work, as well as possibly written Essays. Historically, these applications would be reviewed by an administrator in order to assess the candidates qualifications for acceptance. With the `agent_provide_data` tool, it is now possible to automate this process as the following diagram illustrates.
97
36
 
98
- ![](./examples/images/uag-agent-provide-data.png)
37
+ ![Process example of using the UAG `agent_provide_data` to achieve Agentic workflow automation](./examples/images/uag-agent-provide-data.png)
99
38
 
100
39
  To achieve this feat, the `agent_provide_data` tool utilizes the following information, which is then fed to the Generally trained agent to produce its own submission data.
101
40
 
@@ -109,11 +48,11 @@ To achieve this feat, the `agent_provide_data` tool utilizes the following infor
109
48
  #### Agent "Criteria" component
110
49
  The first thing that needs to be configured is a special **Content Component** that instructs the AI Agent how to interpret the data. For example, here is a Criteria content block that was written to instruct an AI Agent on how to assess the submission of a College Application Essay.
111
50
 
112
- ![](./examples/images/criteria-example.png)
51
+ ![An example content of criteria](./examples/images/criteria-example.png)
113
52
 
114
53
  The goal of this content is to be written as you would write an instruction manual for a new employee who needs to learn how to analyze and understand the submission data that is provided. It is also used to instruct the AI Agent on how to populate the form values that are configured for that criteria. Once this criteria is written, It will then need to be "flagged" as a UAG field by adding a property called `uag` and the value of that property is to be thought of as the `persona` of the Agent. This provides the ability to have more than one agent assume different roles as it analyzes the submission data to provide their own values. In addition, the "criteria" content will also need to be provided a `uagField` property with the value equal to `criteria`. Below is what a properly configured `uag` criteria content component looks like.
115
54
 
116
- ![](./examples/images/criteria-properties.png)
55
+ ![Image showing how to configure the "criteria" and "persona" fields within a form used within an agentic automation task.](./examples/images/criteria-properties.png)
117
56
 
118
57
  Once you have added this `Criteria` **Content Component** to your form, the next object is to add the fields you wish for the Agent to populate. These are called the **Agent Fields**.
119
58
 
@@ -122,22 +61,24 @@ Anywhere in your form, you can drag and drop fields that can be flagged as Agent
122
61
 
123
62
  For example, lets suppose that we have created a form for College Application essays. Below the **Criteria** may be some fields that the Agent needs to "score" the essays according to the provided **Criteria**. This may look like the following...
124
63
 
125
- ![](./examples/images/agent-fields.png)
64
+ ![Example showing how the agent fields are paired along with the criteria so that the agent is aware of what fields it can populate.](./examples/images/agent-fields.png)
126
65
 
127
66
  In order to "flag" each of these fields as Agent Fields, you simply need to add the `uag` property with the same persona flag that was giving to the `Criteria` content.
128
67
 
129
- ![](./examples/images/agent-field-property.png)
68
+ ![Image showing how the `uag` custom property is used to flag that this is a field that can be populated via the agent.](./examples/images/agent-field-property.png)
130
69
 
131
70
  **Nested Components**
132
71
  It is also possible to "flag" a collection of fields with the `uag` property. This can be done by wrapping all of these fields within a **Nested Component** (such as Panel, Container, Fieldset, etc), and then all the fields within this nested component will be added to the context of that agent with that persona.
133
72
 
134
- ### Multiple Persona's per form
135
- It is also possible to achieve multiple persona's per-form. This is very helpful if there are several isolated evaluations that need to occur within a process. For example, if we look at the flow chart diagram shown above, we can see a College Application Form. The first agentic evaluation occurs when the form is submitted by the applicant, where their application is assessed to be accepted or not. From that point, IF the applicant is accepted, a completely different evaluation needs to occur to award Financial Aid or even Scholarships to the applicant. These would require completely different criteria to assess the submission data differently from one another.
73
+ ### Multiple Personas per form
74
+ It is also possible to achieve multiple personas per-form. This is very helpful if there are several isolated evaluations that need to occur within a process. For example, if we look at the flow chart diagram shown above, we can see a College Application Form. The first agentic evaluation occurs when the form is submitted by the applicant, where their application is assessed to be accepted or not. From that point, IF the applicant is accepted, a completely different evaluation needs to occur to award Financial Aid or even Scholarships to the applicant. These would require completely different criteria to assess the submission data differently from one another.
136
75
 
137
76
  To achieve this, you simply need to "flag" the components `uag` property value differently with the persona that applies for that field. For the example above, you would add a Content component to assess the if the applicant should be accepted, and then provide the following `uag` property to that content. `uag="application"`. Any fields that need to be filled out by the AI Agent for application approval would also be flagged with the property `uag="application"`. Then, in a different section of the form, you would create a separate Content component with the criteria for the financial admin AI Agent. This content would be flagged with the property `uag="finance"`. Any fields that the finance admin AI Agent need to fill out would also be flagged with `uag="finance"`. This provides a truely flexible and dynamic AI engagement where multiple generically trained agents can be "taught" dynamically how to read and interpret data that is only relevant to that part of the agentic process.
138
77
 
139
78
  ## Integrations
140
- In order to a aid in the "agentification" of the UAG, we have also provided some "integrations" that can be used to directly communicate with the Generically trained AI Agents to utilize the UAG to accomplish automated AI Agent behaviors. This involves providing a single API endpoint that is capable of triggering the AI Agent process along with the connections to your deployed UAG. These API endpoints can then be triggered using a simple Webhook action within a form to start an Agentic process as the result of a Form submission.
79
+ In order to a aid in the "agentification" of the UAG, we have also provided some "integrations" that can be used to directly communicate with the Generically trained AI Agents to utilize the UAG to accomplish automated AI Agent behaviors. This involves providing a single API endpoint that is capable of triggering the AI Agent process along with the connections to your deployed UAG. These API endpoints can then be triggered using a simple Webhook action within a form to start an Agentic process as the result of a Form submission. Here is a diagram of how specific integrations can be used to achieve a single API call to accomplish an agentic task.
80
+
81
+ ![Agentic process flow via single API call into Claude Integration](./examples/images/agent-flow.png)
141
82
 
142
83
  These integrations can be found within the **integrations** folder. The following **integrations** are provided to enable automated Agentic workflows.
143
84
 
@@ -145,15 +86,42 @@ These integrations can be found within the **integrations** folder. The followin
145
86
 
146
87
  Please click on one of these integration links to read how they work.
147
88
 
148
- ### Custom Modules
149
- While the UAG can be used as a stand-alone system to enable the interaction between AI agents and dynamic JSON forms, the true power of this platform will be realized when developers extend the capabilities of this platform to solve industry specific use cases through the use of Custom Modules and Tools. It is possible for a developer to create a **Module** that introduces a number of custom tools, actions, and pre-defined resources and forms to achieve interactions with industry specific technologies.
89
+ ---
150
90
 
151
- For example, by creating a UAG Module for Salesforce, you can produce a system that can dynamically provide Customer and Company resource data structures to any AI agent, and then through the use of Custom Actions, you can integrate that structured data directly to Salesforce via their own API's as the following image illustrates.
91
+ ## Technical Overview
92
+ The UAG can be thought of as consisting of many layers of functionality. Each layer is broadly either serving to fetch dynamic context, or submit deterministic data structures. The following layers are leveraged within the UAG:
152
93
 
153
- <sub>This is just an example.</sub>
154
- ![](./examples/images/uag-custom-module.png)
94
+ 1. **MCP Interface**: The entry point of the UAG is the MCP interface that sits between the AI agent and the tools that are executed on the server.
95
+ 2. **Authorization**: As part of the MCP specification, every interaction between the AI agent and the backend service must pass through an Authorization process leveraging OIDC (PKCE) authentication. The UAG takes this process one step further, however, by adding an OIDC (PKCE) authentication layer on top of the existing authentication flexibilities that Form.io already provides. Because of this, it is possible to authenticate with the UAG if you are using SAML, Form.io Authentication, OIDC, or even Custom Authentication processes through the Form.io platform.
96
+ 3. [**Pre-defined MCP Tools providing Dynamic Context**](#pre-defined-mcp-tools-providing-dynamic-context): The UAG utilizes the MCP to provide a number of pre-defined tools that provide AI agents with dynamic context based on the Forms and Resources marked as compatible within the Form.io platform. These tools are described in more detail in a section below.
97
+ 4. **Custom Tools** (provided by [Custom Modules](#custom-modules)): This enables developers to introduce any new tools that can leverage Form.io forms and submission data structures to provide additional capabilities introduced to the AI agents. This would allow for custom agent interactions to achieve certain goals for specific use cases.
98
+ 5. **Custom Actions** (provided by [Custom Modules](#custom-modules)): Enables developers to create composable middleware that will be executed once all data provided by the AI agent has been sanitized and validated. This provides the ability to interface the data collected from AI agents with any backend system or workflow.
99
+ 6. **Built-in Actions**: In addition to any custom actions introduced via a Module, the UAG supports a handful of existing Actions that can be assigned to any form or resource. Actions such as the **Webhook** that will send a REST API call to any endpoint once any submission has been made by an AI agent. This can be used to point to any serverless function to instigate backend workflows that are triggered from the interactions from AI agents.
100
+ 7. **Pre-defined Forms and Resources** (provided by [Custom Modules](#custom-modules)): Allows a developer to release a module that provides default data structures to the AI agent. This would be useful if a developer wishes to create a module that achieves a specific goal, where the data structures required for that goal need to follow a pre-determined set of fields provided by a form or resource. For example, if a developer wishes to release a CRM module for the UAG, then it would make sense that the module would also provide the default **Customer** and **Company** resources that commonly accompany most CRM implementations.
101
+ 8. **Custom Database** (provided by [Custom Module](#custom-modules)): By default, the UAG performs the data collection and retrieval via a "Submission Proxy", whereas the data is submitted via REST API to either the Enterprise Server project or the Open Source server. This, however, could be modified to send the data directly to and from a Database. This can be achieved via the Database Interface provided from the UAG. For more information, see the **Module** documentation. This feature does require that the UAG is connected to the Enterprise Server.
102
+
103
+ Here is a diagram to understand how all of these layers are organized to make up the UAG.
104
+
105
+ ![Technical diagram explaining the stack of UAG](./examples/images/uag-overview.png)
155
106
 
156
- Custom modules are able to achieve this custom integration capabilities through the use of the following mechanisms:
107
+ ### Pre-defined MCP Tools providing Dynamic Context
108
+ The following tools provided by the UAG can be described as follows:
109
+
110
+ | Tool Name | Tool Description |
111
+ |-----------------|----------------------|
112
+ | get_forms | Provides the AI agent with a list of available forms. <br/>It will only return forms that have been tagged `uag`. |
113
+ | get_form_fields | When the AI agent infers the user intends to use a specific form, this tool provides the agent with a high level overview of all the fields needed (along with the field data path) to submit that form. |
114
+ | get_field_info | Once the fields have been determined using `get_form_fields`, this tool provides specific information about the requested fields, such as validation, conditionals, input formats, etc. <br/>This tool instructs the AI agent on how to format and structure the data that is sent to the MCP server. |
115
+ | collect_field_data | Provides the AI agent with a mechanism to dynamically collect the required information from the user. It can parse the user's input into multiple fields at once, and will identify additional inputs from the user if needed. <br/>This tool supports complex and structured data collection and is compatible with nested or multi-value fields like nested forms, data grids, etc. |
116
+ | confirm_form_submission | This tool is used to provide a summary of all data collected before a submission is made to the form. |
117
+ | submit_completed_form | Provides the AI agent with the ability to submit all of the data collected from the user to create the form submission. |
118
+ | find_submissions | Enables the agent to parse a user's natural language request into a query for a submission, or a specific field of a particular submission. |
119
+ | submission_update | Provides the AI agent with the ability to update an existing submission, either by supplying unfilled fields or updating existing ones if allowed. Provides the AI agent with the context of the existing field values, allowing inline changes or edits. |
120
+ | agent_provide_data | Enables an AI Agent to be able to analyze existing submission data according to rules defined with a configurable **Criteria**. It will then instruct the Agent to provide generated data for fields configured for a specific **persona** using the `submission_update` tool. Please read the [**Agentic Workflows**](#agentic-workflows) section for more information about this toolset. |
121
+ | fetch_external_data | This tool enables an AI Agent to pull external data into a form workflow through the use of either a Resource component, Select with URL, or a Data Source component. |
122
+
123
+ ### Custom Modules
124
+ While the UAG can be used as a stand-alone system to enable the interaction between AI agents and dynamic JSON forms, the true power of this platform will be realized when developers extend the capabilities of this platform to solve industry specific use cases through the use of Custom Modules and Tools. It is possible for a developer to create a **Module** that introduces a number of custom tools, actions, and pre-defined resources and forms to achieve interactions with industry specific technologies. They are able to achieve this custom integration capabilities through the use of the following mechanisms:
157
125
 
158
126
  1. **Pre-defined Form and Resources**: Using the Form.io template system, a custom module can include a template export of a Form.io project that includes a number of Forms, Resources, and Actions (as well as any Roles and Permissions associated with them). By using the module, this will then automatically "register" these assets so that the AI agent is immediately aware of those assets.
159
127
  For example, imagine a module includes a Customer resource with "First Name", "Last Name", and "Email" fields. If you then simply ask an AI agent, "I would like to add a new Customer" the agent will automatically be aware of the context for the customer data structures and know exactly what your intent is when making that request.
@@ -162,24 +130,20 @@ Custom modules are able to achieve this custom integration capabilities through
162
130
  4. **Custom Authentication**: A module can also modify the "authentication" landing page to assist with any custom requirements that are needed around Authentication.
163
131
  5. **Behavior Overrides**: A module also has the ability to "override" any default behavior from the UAG. This ensures that whomever is using a certain module can "tweak" certain tools and responses to achieve better results as it pertains their their industry specific needs.
164
132
 
165
- Form.io aims to enable developers to build and contribute their own custom modules to the broader community through GitHub and NPM. For example, once these modules proliferate, it may be possible to install the salesforce module for UAG with the following.
133
+ Form.io aims to enable developers to build and contribute their own custom modules to the broader community through GitHub and NPM.
166
134
 
167
- <sub>This is just an example.</sub>
168
- ```
169
- npm install salesforce-uag
170
- ```
171
-
172
- and then use it as follows.
135
+ #### Using a Custom Module
136
+ Once a custom module is developed, anyone can install that module (via NPM) and then easily use your module in the following way...
173
137
 
174
138
  <sub>This is just an example.</sub>
175
139
  ```js
176
140
  import { UAGServer } from '@formio/uag';
177
- import { SalesforceUAG } from 'salesforce-uag';
141
+ import { ExampleUAG } from '@example/uag';
178
142
  import Express from 'express';
179
143
  try {
180
144
  (async function () {
181
145
  const server = new UAGServer();
182
- server.use(SalesforceUAG);
146
+ server.use(ExampleUAG);
183
147
  const app = Express();
184
148
  app.use(await server.router());
185
149
  const port = process.env.PORT || 3200;
@@ -199,12 +163,7 @@ To get started in building your own custom module, go to the help documentation
199
163
  ## Deploying UAG
200
164
  The following sections describe the process of creating a running instance of UAG, connecting it to the Form.io Platform, and configuring an AI agent to use it.
201
165
 
202
- This documentation focuses on using UAG with Form.io Open Source. For documentation on using UAG with Form.io Enterprise, refer to [Help.Form.io/UAG](https://help.form.io/uag).
203
-
204
- ### Local Example
205
- The quickest way to become familiar with the UAG is to first walk through our Local Example, which will spin up a local instance of Form.io Open Source and UAG. This can then be connected to an AI agent, which will have the ability to interact with the included example forms. The local example can be run entirely free, with no trial or license required.
206
-
207
- **[Go to Local Example &raquo;](examples/local)**
166
+ This documentation focuses on using UAG with Form.io Open Source. For documentation on using UAG with Form.io Enterprise, refer to [https://help.form.io/uag](https://help.form.io/uag).
208
167
 
209
168
  ### Runtime Environments
210
169
  There are currently two run-time environments that work with the UAG:
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@formio/uag",
3
- "version": "1.10.2",
3
+ "version": "1.11.1",
4
+ "mcpName": "io.form/uag",
4
5
  "description": "The Form.io Universal Agent Gateway (UAG).",
5
6
  "main": "lib/index.js",
6
7
  "types": "lib/index.d.ts",
@@ -21,7 +22,11 @@
21
22
  "start": "node --no-node-snapshot index.js",
22
23
  "claude": "node --no-node-snapshot ./integrations/claude/index.js"
23
24
  },
24
- "author": "",
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "https://github.com/formio/uag.git"
28
+ },
29
+ "author": "Form.io Developers",
25
30
  "license": "MIT",
26
31
  "dependencies": {
27
32
  "@formio/appserver": "^2.12.2",
@@ -52,12 +57,12 @@
52
57
  "@types/jsonwebtoken": "^9.0.10",
53
58
  "@types/lodash": "^4.17.24",
54
59
  "@types/mocha": "^10.0.10",
55
- "@types/node": "^25.3.2",
60
+ "@types/node": "^25.5.0",
56
61
  "@types/supertest": "^7.2.0",
57
62
  "chai": "^6.2.2",
58
63
  "mocha": "^11.7.5",
59
64
  "supertest": "^7.2.2",
60
- "terser": "^5.46.0",
65
+ "terser": "^5.46.1",
61
66
  "ts-node": "^10.9.2",
62
67
  "tsx": "^4.21.0",
63
68
  "typescript": "^5.9.3"