The following topics cover the best practices you should adhere to:
Agent development best practices
These best practices ensure that agents and tools are developed consistently and effectively throughout Nextworld.
General
Ensure each of your agents handles a specific role, and that each of your tools accomplishes a specific task. In general, large language models (LLMs) perform better when they're given specific prompts. For example, you might need to to create an agent that summarizes each section of a document. It would be more effective to give the agent two tools, one to break the content into sections, and then another to summarize each section, than it would be to create a single tool.
Check that every table that your agents can access or modify has the proper security defined. Agents acting on behalf of your users are only able to display data or perform actions the user would otherwise be allowed to do.
Agents
Consider the structure of your agent relationships. Keep in mind that the more agent relationships and tools a single agent has, the less likely a LLM is to accurately determine which child agents to call upon or which tool to execute.
The following table describes the suggested agent hierarchy:
| Level | Description and considerations | Examples |
|---|---|---|
| Family-level agent | Typically, each product family should have a single agent that includes Ed as its parent agent. Each module level agent should be a child of this agent. However, there are some cases where it may be appropriate to create multiple agents for a single family. For example, for the Foundation product family, it makes sense to have multiple top-level agents, such as Directory, TimeEntry, and ItemMasterData. | Financials, Sales, Inventory |
| Module-level agent | Each of your product modules should have a distinct agent. These agents should include the family-level agent as a parent agent, but not Ed. | AccountsRecieveable, AccountsPayable, Items |
| Application-level agent | If your module-level agents become too robust, you may also create an additional tier of agents, called application-level agents. These agents should list the module-level agent as their parent agent, and should not have any child agents. Typically, these agents relate specifically to a single application or process. | SalesOrders, SalesCredits, CustomerInvoices |
If you create two similar agents, they should not share a parent agent. For example, if you create a SalesInvoicing agent as well as a Sales agent and specify Ed as a parent agent of both, Ed may struggle to determine which agent to call upon.
The name and Agent Description Prompt for each of your agents should be unique.
Tools
Tools should be specific to a single action on the platform.
Avoid using the exact user prompt as a tool input.
You should configure an output that describes the details of the action that was completed, or any errors that occured.
If the display application for your data retrieval tool uses company or org-unit overrides, use a pre-run logic block to default these filter values from the user.
If any of the inputs for your tools is a table lookup, you must use a semantic search definition to allow the user to select the correct record. To ensure the user only needs to select the record once in the course of an agent flow, you should create a tool to identify the correct entity. Learn more in Logic block tools that identify a specific record.
Logic blocks
All logic blocks used in agent tools should have a Security Option of Public.
Naming conventions
Across all agents, toolsets, tools, and logic blocks, avoid any obvious or unnecessary words such as ‘agent,’ ‘chat,' 'tool,' or 'toolset.' Keep names short, clear, and descriptive. Do not use any proper nouns. All object names should be unique.
| Object | Naming convention | Considerations | Examples |
|---|---|---|---|
| Family-level agents | <Family><Context> | <Context> is optional. |
|
| Module-level agents | <Module><Context> | <Context> is optional. | AccountsReceivables, AccountsPayable, Items |
| Application-level agents | <Application><Context> | <Context> is optional. <Application> may also refer to a single process spanning multiple applications. | SalesOrders, SalesCredits, SalesQuotes, WorkOrders, CustomerInvoices |
| Toolsets | <Toolset>Actions | Name the toolset according to the general functionality of the included tools. Append the word 'Actions' to the end of each toolset. | SalesOrderActions, SharedDirectoryActions |
| Tools | <Verb><Object> Acceptable verbs: Create (not Write), Answer, Display (not Retrieve), Determine, Release | Acceptable verbs:
For data retrieval tools, use the verb 'Display.' Do not use the verb 'Retrieve.' | Logic block tools: DetermineSalesQuoteInformation,SendSalesQuote,ReleaseSupplierHoldsCalculateTaxForSalesOrderData retrieval: DisplaySalesOrderLines, DisplayInventoryCommitments |
| Embedding definitions | <TableName><Context> | <Context> is optional, but should be a singular noun if included. | ReceivablesHeader, SalesOrderHeader, Items, ShipmentHeader, Directory |
| Semantic search definitions | <NameOfEmbeddingDefinition><Grouping> | <Grouping> is optional, but should be a plural noun if included. You should always create at least one semantic search definition with no filters applied. | SalesOrderHeaderOrders, DirectoryCompanies, DirectoryEmployees |
Logic block tools that identify a specific record
If an agent needs to perform an action or retrieval data using a specific record, you should build a logic block tool that leverages semantic search to determine the correct record and then include the tool in the agent's toolset.
When an agent runs one of these tools, options that match the user's request are presented to them in the chat interface. After they indicate the correct record, the agent flow can continue. Learn more in Semantic search.
Each of these tools should follow the naming convention of Determine[Entity Name]. For example, DetermineCustomerInformation. Most user queries require that an agent act on an existing record. Your agents should have one of these logic block tools for each type of record the agent can act on.
Configuration
To configure a logic block tool to identify a record, add the table lookup data item as an input field and specify a semantic search definition in the Search Configuration field.
Additionally, you should configure your logic block to output the nwID of record the user selects. These outputs should always be Shared, so that the agent can use the nwID later in the agent flow. Rename the outputs using the convention of <Entity>RecordID.
Example
The Directory agent is equipped with a data retrieval tool called DisplayCustomerHolds. In order to properly execute this tool, the agent must first determine the customer to display holds for, so it uses a different tool, DetermineCustomerInformation.
The DetermineCustomerInformation logic block tool includes a prompted input field of Customer, which includes a semantic search definition. It also includes a Shared output field of CustomerRecordID. This allows the DisplayCustomerHolds tool to include a fetch field option that maps in the CustomerRecordID value determined in the first tool.
When a user asks Ed, "Show me all the holds placed on Bobby Jones," Ed calls on the Directory agent. The agent executes its DetermineCustomerInformation tool, which pauses the agent flow until the user determines the correct customer in the chat interface. After the agent has the CustomerRecordID for Bobby Jones' directory record, it can execute its DisplayCustomerHolds tool and show all of Bobby's active holds to the user.
Semantic search and embeddings best practices
These best practices ensure that embedding definitions and semantic search definitions are configured consistently and effectively throughout Nextworld.
Embedding definitions
Embed the text fields used to identify each record in the table. These field values from each record are concatenated into a single string, and each of these strings are processed by a model from OpenAI that turns them into an embedding. The more fields you embed, the longer each string, and the less likely that semantic search results are helpful. Do not embed number fields, or fields that are commonly empty.
For example, an embedding definition for the Directory table may contain the Name and Nickname fields. However, an embedding definition over the DataCatalog table contains the DataCatalogName, DataCatalogDescription, and DataCatalogSourceTextTL fields. This is because searches of the data catalog may be by either the data catalog name, or, less commonly, the source table. The description field is included to add weight to searches by the data catalog name, since the description is often similar.
Limit the number of filters you include in the Source Table Filter field. This allows for additional flexibility for any semantic search definitions built over the embedding definition.
Semantic search definitions
Include nwId as an exact match field for each of your semantic search definitions in case another tool has already determined the nwId for the record.
When you include the Name field as an exact match field, always use NameName, as Name is a complex data item. If you expect your users to search using a Last Name, First Name format, you can also include NameNameInverted.
Nextworld Intelligence documentation best practices
The following best practices ensure features that use Nextworld Intelligence are documented consistently across the platform.
Terminology for different audiences
For content serving general audiences, such as business users and system administrators, use the term Nextworld Intelligence when you refer to features that leverage machine learning models, automated machine learning models, prompt definitions, agents, or tools. For example, you can say that a feature is "powered by Nextworld intelligence," or that "the value in this field is derived using Nextworld Intelligence."
For content serving application builders, it's okay to reference machine learning, large language models, prompting, and other terminology that is important for application development with Nextworld Intelligence.
Use AI note and attribute icon in Content Builder
When you create a new topic on an AI feature, select Artificial Intelligence in the Attribute Icon field. This adds an icon next to the topic when viewed in Nextworld Help, indicating that it's about an AI feature.
You can use the AI note in Content Builder to inform the user about an AI feature. You can also use it to direct them to more content on the AI feature.
For example:
Adhere to the Nextworld ethics policy of digital transparency
When you use Nextworld Intelligence features in your applications, you should include complementary documentation and help text that informs your users that they are interacting with an intelligent solution, and if applicable, how their data is used. Describe the inputs used, capabilities, intended purpose, potential impacts, and limitations of the features. Learn more in the Nextworld AI ethics policy.
The following table provides some examples of AI features with different scopes, and how they are documented:
| Feature | Scope | Necessary help text and documentation |
|---|---|---|
Prompt definition runs to determine if the Contact Type of a new directory record is a Person or Organization |
| Help text for the Contact Type field should indicate that the value is derived by Nextworld Intelligence. |
| Creating a new application in Developer Studio by uploading a spreadsheet |
| AI notes in the Application Builder and and Developer Studio topics that lets application developers know about the feature and its potential limitations. |
| Login anomaly detection |
| Comprehensive documentation in Nextworld Help, application listings, and field level help. Appropriate warnings about limitations, requirements, and the use of user data. |