Defines an Artificial Intelligence (AI) Agent.
It can interact with various GeneXus objects such as Procedures, Data Providers, APIs, and other business logic objects. This capability allows the integration of generative AI with your business processes, enabling Agents to perform a wide range of Tasks—from updating records in your database to executing complex business operations. This seamless connection between AI and business logic enhances functionality and creates a truly intelligent application that can respond dynamically to user needs.
Agent <AgentName>
{
<Natural language prompt written inline> | <File object with Natural language prompt> | <Document object with Natural language prompt>
#Rules
parm(<Parameters>);
[context(<DataProviders><Procedures>);]
[use(<Procedures><Agents><ExternalGEAITools><ExternalGEAIAgents>);]
#End
#Variables
<Variable Definitions>
#End
}
Where:
AgentName
This is the unique identifier for the Agent object. It should be a descriptive name following GeneXus naming conventions.
Natural language prompt written inline
Prompt with detailed instructions or a description of the task the Agent is to perform. This prompt may include variables received as parameters. It is also possible to reference the context by using the $context placeholder.
Syntax: sentences in natural language that can include “{{&InputParameter1}}” “{{&InputParameter2}}” $context.
File object with Natural language prompt
When the prompt is very long, instead of writing it inline, you can indicate the name of a File object (previously uploaded to the KB with a .txt file or .doc file) that contains the prompt with the detailed instructions.
Syntax: {{file:FileObjectName}}
Document object with Natural language prompt
When the prompt is very long, instead of writing it inline, you can indicate the name of a Document object that contains the prompt with the detailed instructions.
Syntax: {{document:DocumentObjectName}}
Rules
This section contains the operational rules for the Agent, including parameters, context, and various types of tools to help the Agent get the output.
- parm(<Parameters>)
Parm rule that defines the input and output parameters of the Agent. One or more input parameters can be included, and only a single output parameter can be present. The input parameters and the output parameter can be of any data type that can be converted to text (Character, Varchar, JSON). For example, you can send a Numeric variable and/or a variable based on an SDT, and/or a Varchar variable, and you can declare a Numeric output variable. The output variable will be converted, and the returned parameter by the Agent will be a string.
Syntax: parm(in:&InputParameter1,[in:&InputParameterN], out:&OutputParameter);
- context(<DataProviders><Procedures>)
By using the context clause, you can specify additional context information (data) for the Agent, provided by one or more Data Provider or Procedure objects). The invocation of the objects specified in this clause will be performed BEFORE the agent's execution, and the result returned by them will be added to the prompt as read-only data (the purpose of the invoked objects is not to perform actions).
This context can be optionally referenced by the Agent instructions prompt using the $context placeholder.
The context clause is optional.
Syntax: context(DataProvider1(&Parameter1), [DataProvider2(&Parameter2),...Procedure1(&Parameter3)]);
- use(<Procedures><Agents><ExternalGEAITools><ExternalGEAIAgents>)
The use clause allows you to indicate the name of one or more Procedure objects, Agent objects, external Globant Enterprise AI Tools (both Public Tools and Private Tools) and/or external Globant Enterprise AI Agents exposed to public access.
Syntax: use(Procedure1…[,ProcedureN] [,AgentObject1…,AgentObjectN] [,ExternalTool:GEAITool1…, ExternalTool:GEAIToolN] [,ExternalAgent:GEAIAgent1…, ExternalAgent:GEAIAgentN]);
1) When indicating Procedure and/or Agent names, do not include parameters nor parentheses. When the Agent object is impacted, the GeneXus objects referenced in the use clause are also impacted. At that point, the names and descriptions of the IN parameters defined in their Parm rule, are automatically included in the metadata that is sent to Globant Enterprise AI to declare the tools. Therefore, each parameter description must be clearly defined (so that, when invoking the tool, the LLM knows when to use each parameter and provides the correct data). If your parameter descriptions are not sufficiently clear, a warning message like the following may be displayed:
Warning: <agtName>: Parameter %1 of object %2 needs a better description for the AI, the current description id %3.
2) The ExternalTool: and ExternalAgent: prefixes are required to distinguish between Tools and Agents defined in Globant Enterprise AI. Consider that only the public names are needed. No additional configurations are required in the GeneXus environment other than having access to the Globant Enterprise AI project where the Tool or Agent is published.
3) The referenced External Tools and/or Agents must be in the same Organization and Project as the Environment of the Knowledge Base. Otherwise, you may be able to save the Agent, but the following error will be displayed when impacting it:
error: agt0202: Error impacting agent %1
error: Error UnprocessableEntity: Failure on agent publication.
Failed: Agent Impact
The use clause is optional, but if it is used, it must contain an argument.
Variables
This section defines the variables used by the Agent, specifying their properties.
Syntax:
VariableName
[
DataType = 'DataType',
AverageLength = 'AverageLength',
Collection = 'True/False',
ControlType = 'ControlType'
]
The $context placeholder allows for the integration of context-specific data within the Agent's prompt. It is used to dynamically insert contextual information that the Agent needs to perform its Task more effectively.
$context placeholder can be used in two ways:
- Implicit insertion
- Explicit placement
1. Implicit insertion: If the $context placeholder is not explicitly mentioned in the prompt, GeneXus Next automatically appends the context data to the end of the prompt. This ensures that the Agent always has access to the necessary context information without requiring manual specification in every prompt.
Agent GenreRecommendation
{
Suggest movies in the genre of "{{&FavoriteGenre}}" that the user might enjoy.
#Rules
parm(&FavoriteGenre, out: &RecommendedMovies);
context(GenreMoviesDataProvider(&FavoriteGenre));
#End
#Variables
FavoriteGenre
[
DataType = 'VarChar(40)'
]
RecommendedMovies
[
DataType = 'VarChar(500)'
]
#End
}
In this example, even though $context is not mentioned in the prompt, the context from GenreMoviesDataProvider will be appended automatically.
2. Explicit placement: By including $context in a specific location in the prompt, you can control where the context data appears. This is useful for scenarios where the context needs to be positioned strategically within the prompt to enhance the Agent's understanding and response generation.
Agent GenreRecommendation
{
Considering this information: $context suggest movies in the {{&FavoriteGenre}} genre that the user might enjoy.
#Rules
parm(&FavoriteGenre, out: &RecommendedMovies);
context(GenreMoviesDataProvider(&FavoriteGenre));
#End
#Variables
FavoriteGenre
[
DataType = 'VarChar(40)'
]
RecommendedMovies
[
DataType = 'VarChar(500)'
]
#End
}
Here, $context is placed explicitly within the prompt, ensuring that the contextual data is inserted exactly where needed for the most relevant output.
By understanding and using the $context feature, you can enhance the capabilities of GeneXus Agents, ensuring they provide context-aware, accurate, and valuable responses tailored to user needs and interactions.
To use an Agent object, you can call it in three different ways:
- As stand-alone call
- Integrated into a chat
- Integrated into a Business Process Diagram
This is the simplest way to execute an Agent object. It consists of calling the Agent directly from code:
&Result = AgentObjectName(&InputParameter1, [&InputParameterN,] &ChatMessages, &CallResult)
Where:
AgentObjectName
Is the name of the Agent object you want to call.
&InputParameter1, [&InputParameterN]
Input Parameters required by the Agent object.
&ChatMessages
Variable based on GeneXus.ArtificialIntelligence.ChatMessage external object, which must be marked as a collection. It contains a collection of messages that includes both user inputs and agent responses.
&CallResult
Variable based on the CallResult external object that helps to manage the result of the operation. The use of this parameter is advantageous in the following situations:
- Connection issues: If there is a problem connecting to the underlying model or the network, this will be reflected in &CallResult.
- Model errors: Issues related to the LLM, such as timeouts or unexpected behavior, will also be captured.
- Output generation problems: If the model fails to generate the desired output or returns unexpected results, these will be noted in &CallResult. By examining &CallResult, you can determine if the Agent has performed as expected or if any corrective action is needed.
Agent objects support stateful interactions, allowing for complex conversations that maintain context over multiple exchanges (for example, to implement customer support, virtual assistants, and any application requiring interactive dialogue). This use case involves using the Chat Control.
Syntax:
&ChatResult = AgentObjectName.Chat(&ChatMessages, &CallResult)
Where:
AgentObjectName
Is the name of the Agent object you want to call.
&ChatMessages
Variable based on GeneXus.ArtificialIntelligence.ChatMessage external object, which must be marked as a collection. It contains a collection of messages that includes both user inputs and agent responses.
Each entry in the &ChatMessages list contains:
- Role: Specifies who is sending the message ("user" or "agent").
- Content: The text of the message
Sample of &ChatMessages:
{
"role": "user",
"content": "What movies are available today?"
},
{
"role": "agent",
"content": "Here are the movies available today: Movie1, Movie2, Movie3."
},
{
"role": "user",
"content": "Tell me more about Movie1."
}
Before calling the agent, you must add one message with "user" role to the &ChatMessages collection variable (so it acts as the next input). For example,
&ChatMessage=new() //&ChatMessage is a variable based on the ChatMessage external object
&ChatMessage.role = ChatRole.User
&ChatMessage.content = "What movies are available today?"
&ChatMessages.Add(&ChatMessage)
&CallResult
Variable based on the CallResult external object that gives information about the result of the operation.
&ChatResult
Variable based on the ChatResult external object. After invoking the agent, you can iterate over the &ChatResult variable to retrieve the result of the call in chunks, using the methods of the ChatResult external object.
Notes:
- You can find a complete implementation in the article: HowTo: Use the Chat Control associated with a Procedure that calls an Agent.
- Learn more about Reading and writing chunked responses.
- If the Agent calls Tools, for each tool invocation, two messages are added to the &ChatMessages collection variable:
- One message from the LLM requesting which tool to execute.
- Another message from the Tool indicating the result it returned after the execution.
- Keep in mind that if, after processing the agent’s response, you want to invoke the agent again and have the response taken into account, you must explicitly add it to the &ChatMessages collection variable:
&ChatMessage = new()
&ChatMessage.Role = ChatRole.Agent
&ChatMessage.Content = &Response //&Response is a Character or Varchar variable that must contain the concatenation of all the chunks obtained with GetMoreData().
&ChatMessages.Add(&ChatMessage)
The Agent object may be integrated into a Business Process Diagram object to help make a decision or perform an Agent Task, turning the diagram into an Agentic Workflow.
To integrate an Agent object into a Business Process Diagram, you need to add an Agent Task into the Business Process Diagram. This task is available in the Toolbox:
Or you can add a standard Task into the Business Process Diagram and change its Type property to Agent. Once the task is in the diagram, you can associate it with an Agent object using the Agent property of the task.
This links the Task to the Agent, so it runs in the process.
In Exclusive and Inclusive Gateways, the condition evaluation can be handled by an Agent object. To do this, set the Condition Agent property of the Gateway as follows:
By the addition of AI features to a Business Process Diagram, developers and modelers can create powerful AI-driven workflow diagrams that help in automating complex Tasks, offering enhanced user experiences and operational efficiencies.
When an Agent object is created, it is automatically configured to run on the Globant Enterprise AI (GEAI) platform.
By default, each Agent object is exposed as an API within Globant Enterprise AI, allowing for easy integration and interaction with other systems and applications. This exposure as an API allows you to leverage the Agents in various contexts, such as web applications, mobile apps, and third-party services.
Each Agent must have a unique name within a GEAI Project. So, you cannot define two Agents with the same name in the same project, even if they were created in different Knowledge Bases.
Aspects related to the Globant Enterprise AI runtime are configured at the Environment level, meaning that the settings and models used by default are specified once for the entire development Environment. This configuration includes selecting the language models and defining their usage policies, ensuring consistency across all agents running within that Environment. Read more about the AI Provider Project Name property and Default Agents AI Model property.
Although the Environment configuration provides a standard setup, you can configure particular settings for certain Agent objects as needed. This provides flexibility to meet specific requirements or use cases. Read more about the AI Model property.
You can call an Agent object in Procedures, Transactions, Business Components, Web Panels, and Data Providers.
This integration allows you to enhance various aspects of your application with AI capabilities, enabling you to add intelligent processing, decision-making, and dynamic content generation throughout your application.
By leveraging Agent objects in different contexts, you can create more sophisticated and responsive applications that take full advantage of natural language processing and generative AI in your business logic.
This sample describes an Agent that takes a short text input and expands it into a detailed description. To do so:
Agent DescriptionsAgent
{
Expand the following short text into a detailed description: "{{&ShortText}}"
#Rules
parm(in:&ShortText, out: &ExpandedText);
#End
#Variables
ShortText
[
DataType = 'VarChar(40)'
]
ExpandedText
[
DataType = 'VarChar(512)'
]
#End
}
The DescriptionsAgent takes a short text (&ShortText) as input and produces detailed information about the subject mentioned (&ExpandedText) as output.
In this example, ShortText is defined as a 40-character VarChar, which limits the length of the input text, while ExpandedText is a 512-character VarChar, providing enough space for a detailed description.
To use the agent and obtain the expanded description, you can define a Web Panel object that includes the &ShortText variable and a button in its Web Layout. Then, in the event associated with the button, call the agent as shown below:
Event "GET DESCRIPTION"
&ExpandedText = DescriptionsAgent(&ShortText) //pass the input variable (&ShortText) and the result will be returned in the output variable
Endevent
The result at runtime should be like this:
Suppose you need to identify the category identifier of a product based on its category description. To do so, you can define an Agent object as follows:
Agent ProductCategoryAgent
{
Determine the product category with this description: {{&ProductDescription}}.
#Rules
parm(in:&ProductDescription, out:&CategoryId);
context(CategoryList());
#End
#Variables
ProductDescription
[
DataType = 'VarChar(40)',
AverageLength = '0',
Collection = 'False',
ControlType = 'Edit'
]
CategoryId
[
DataType = 'Numeric(4.0)'
]
#End
}
The ProductCategoryAgent receives a product description text (&ProductDescription) as input and returns a category identifier (&CategoryId) selected by the agent from the category collection provided by CategoryList Data Provider.
In the Rules section, in addition to defining these Parameters, a context (a Data Provider named CategoryList()) is included that provides the Agent with a list of available categories for sorting.
The Variables section defines ProductDescription as a 40-character VarChar with additional properties such as AverageLength, Collection, and ControlType, suggesting that this variable could be used in a user interface.
CategoryId is declared only with its DataType and without specific properties, implying that the context of the application can determine its type and use.
To get the category Id from a product description, call the Agent by passing the input text, as follows:
&CategoryId = ProductCategoryAgent(&ProductDescription)
Where variable &CategoryId is based on CategoryId attribute (typically N(4.0))
The goal of this sample is to provide context to an Agent object and using an external Tool.
Suppose you want to get product recommendations based on a customer's purchase history and preferences. To achieve this, define an Agent object as shown below:
Agent ProductRecommenderAgent
{
Recommend products for customer: "{{&CustomerID}}" based on: $context
#Rules
#Rules
parm(in:&CustomerId, out:&RecommendedProducts);
context(CustomerPurchaseHistory(&CustomerId),ProductCatalog());
#End
#Variables
CustomerID
[
DataType = 'Numeric(8,0)',
]
RecommendedProducts
[
DataType = 'VarChar(100)',
]
#End
}
The ProductRecommenderAgent takes a customer ID (&CustomerID) as input and produces a list of recommended products (&RecommendedProducts) as output.
The Rules section defines the input and output Parameters, as well as the context and Tools used by the Agent. The context includes the customer's purchase history (given by the CustomerPurchaseHistory Data Provider) and the product catalog (given by the ProductCatalog data provider), which provide essential information for making recommendations.
In the Variables section, CustomerID is defined as Numeric(8,0). RecommendedProducts is defined as VarChar(100).
DataProvider CustomerPurchaseHistory
{
CustomerPurchases from Invoice
Where CustomerId = &CustomerId
{
CustomerPurchasesItem
{
InvoiceId
InvoiceTotalAmount
}
}
#Rules
Parm(in:&CustomerId);
#End
#Variables
CustomerId
[
DataType = 'Attribute:CustomerId'
]
#End
}
DataProvider ProductCatalog
{
ProductCatalogSDT from Product
{
ProductCatalogSDTItem
{
ProductId
ProductName
ProductPrice
ProductDescription
}
}
}
Calling the agent:
&CustomerId = 1
&RecommendedProduct = RecommendProductsAgent(&CustomerId, , &CallResult)
if &CallResult.Fail()
&Messages = &CallResult.GetMessages()
for &Message in &Messages
msg(&Message.Description)
endfor
endif
The agent result should be like the following:
The goal of this sample is to ask Agent object to search a web site.
Suppose you want to get which products are on sale from a particular web site. To achieve this, you have to define an Agent object to find general information on the web using a public Globant Enteprise AI Tool, as shown below:
Agent SearchWebAgent
{
You must answer the question in "{{&question}}"
If you need to look something up online because
you don't know the answer, use the corresponding tool.
#Rules
parm(in:&question, out:&answer);
use(ExternalTool:com.globant.geai.web_scraper_httpx);
#End
#Variables
question
[
DataType = 'VarChar(512)'
]
answer
[
DataType = 'VarChar(512)'
]
The Agent receives a query to find on sale products in a particular category in a web site. In the Agent definition, you have to instruct it to try to find and answer and use a public Tool to deal with the process of extracting content and data from a website.
In the Variables section, &question and &answer variables are defined as VarChar(512).
To request information from a website, call the agent by passing the question as input. The answer will be returned in the output variable after using the associated web scraping Tool.
&question = "Can you tell me the products of category Computers that are on sale on the website: https://www.amazon.com"
&answer = SearchWebSiteAgent(&question)
The Agent result should be like this:
The goal of this sample is to ask an Agent object to debate with two other agents, and taking a decision on a matter.
Suppose you want to know the answer to a question on a particular topic, and two experts with opposing views debate the issue.
The debate is moderated by an impartial researcher who ensures that each expert defends their position over several iterations. Eventually, based on the arguments presented, the moderator reaches their own conclusion, explaining the reasoning behind it.
You can achieve this using three Agent objects, each fulfilling the role you need.
In the following example, you want to know if intelligent life exists outside Earth.
To do that, you have to create first an agent named IntelligentLifeYesAgent to represent the expert pro-intelligent life outside Earth:
Agent IntelligentLifeYesAgent
{
You are an astrophysicist and astronomer with vast experience, and you are convinced that
intelligent life exists beyond Earth.
If asked whether intelligent life exists outside of Earth, you should argue why it does.
If given counterarguments against this position, you must refute them. Answer the following "{{&question}}"
#Rules
parm(in:&question, out:&answer);
#End
#Variables
question
[
DataType = 'VarChar(50)'
]
answer
[
DataType = 'VarChar(512)'
]
#End
}
and another agent named IntelligentLifeNoAgent to represent the expert against existing intelligent life outside Earth:
Agent IntelligentLifeNoAgent
{
You are an astrophysicist and astronomer with vast experience, and you are convinced that
intelligent life does not exist beyond Earth.
If asked whether intelligent life exists outside of Earth, you should argue why it does not.
If given counterarguments against this position, you must refute them. Answer the following "{{&question}}"
#Rules
parm(in:&question, out:&answer);
#End
#Variables
question
[
DataType = 'VarChar(50)'
]
answer
[
DataType = 'VarChar(512)'
]
#End
}
Then, create a third Agent for the moderator role, with the duty to give us a final conclusion about the existence of intelligent life outside Earth. The agent is named IntelligentLifeModeratorAgent as follows:
Agent IntelligentLifeModeratorAgent
{
You are a researcher and journalist internationally recognized for your professionalism,
coordinating a debate between two scientists highly specialized in astrophysics and
astronomy. The goal is to clarify whether intelligent life exists beyond Earth, or not.
The first question is: "{{&InputArgument}}"
Use the tools IntelligentLifeYesAgent and IntelligentLifeNoAgent to converse with each of the scientists.
You have no more than three interactions between them to reach a conclusion.
At the end, summarize what each scientist presents and provide a result.
You must choose a final answer to the question of whether or not intelligent life
exists beyond Earth, taking into account the responses from each scientist.
#Rules
parm(in:&InputArgument, out:&Result);
use(IntelligentLifeYesAgent, IntelligentLifeNoAgent);
#End
#Variables
InputArgument
[
DataType = 'VarChar(512)'
]
Result
[
DataType = 'VarChar(512)'
]
#End
}
To obtain the final conclusion from the debate between the expert Agents, call the moderator Agent by passing the question as input. The moderator will interact with the two expert Agents internally, analyze their arguments, and return a summarized result with the final answer.
The agent IntelligentLifeModeratorAgent is called as following:
&question = "Is there intelligent life outside of Earth?"
&answer = IntelligentLifeModeratorAgent(&question, , &CallResult)
The moderator agent called the other two agents three times and evaluated their answers, and finally the moderator arose to a final conclusion, giving us an answer as follows:
This example shows how it is possible to make three Agents interact between them several times to solve a problem.
Since GeneXus Next.
CallResult external object