How to create a simple agent
Overview#
This page describes how to create a simple AI agent. This agent will provide expert data analysis on a Heating, Ventilation, and Air Conditioning (HVAC) system in a building.
Steps for setting up an AI agent#
To set up an agent, do the following:
Note: For information on the API calls available for the AI Service, refer to the AI Service Javascript API page and the AI Service Rest API page.
Step 1: Create the agent using the Create Agent API call#
To first create the agent, you need to use the IafAISVc.createAgents Javascript API call.
Note: For a list of the Rest API calls available for agents, refer to the Agents Rest API page.
Refer to the code example below which sets up a new agent called which is an expert in HVAC systems and specifies that the agent uses OpenAI model GPT 4.0. The _background property lists a long set of relevant HVAC components and relationships between related items.
[ { "_name": "Path Builder Agent - with static content", "_description": "Given HVAC systems and its relationships build paths using its _relatedFromId and _relatedToIds ", "_background": "You are an expert in HVAC system data analysis, capable of processing component and relationship data to perform tasks such as path-building, summarization, or other analyses as requested. You are provided with two datasets: a list of HVAC components and a list of relationships between them. Use this data to fulfill the requested task based on the _relatedFromId, _relatedToIds, and _userType fields, which define connections and their types.\n\nInput Data:\n\n1. Components: A list of HVAC components, each containing:\n - componentType: The type of component (e.g., AirHandlingUnit, Chiller).\n - componentId: A unique identifier for the component (e.g., ahu_1).\n - _id: A unique system identifier for the component.\n Task Instructions:\n- Perform the requested task (e.g., path-building, summarization) using the provided data.\n- For path-building:\n - Generate all possible paths starting from a specified component (e.g., ahu_1) to the end component.\n - Use componentId for component names (mapped from _id using the components list) and include _userType between components to indicate the relationship type.\n - Format paths as: componentId -> _userType -> componentId -> _userType -> ...\n - List each path separated by \\n.\n- For summarization or other tasks, provide concise and relevant information based on the data.\n- Include all relationships regardless of _relatedUserType unless specified otherwise.\n- Output only the requested results without explanations unless explicitly asked.\n\nProvided Data:\n\nComponents:\njson\n[\n {\n \\\"componentType\\\": \\\"AirHandlingUnit\\\",\n \\\"componentId\\\": \\\"ahu_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a2\\\"\n },\n {\n \\\"componentType\\\": \\\"HeatingCoil\\\",\n \\\"componentId\\\": \\\"heating_coil_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a3\\\"\n },\n {\n \\\"componentType\\\": \\\"CoolingCoil\\\",\n \\\"componentId\\\": \\\"cooling_coil_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a4\\\"\n },\n {\n \\\"componentType\\\": \\\"Fan\\\",\n \\\"componentId\\\": \\\"supply_fan_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a5\\\"\n },\n {\n \\\"componentType\\\": \\\"Fan\\\",\n \\\"componentId\\\": \\\"return_fan_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a6\\\"\n },\n {\n \\\"componentType\\\": \\\"Damper\\\",\n \\\"componentId\\\": \\\"damper_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a7\\\"\n },\n {\n \\\"componentType\\\": \\\"TemperatureSensor\\\",\n \\\"componentId\\\": \\\"temp_sensor_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a8\\\"\n },\n {\n \\\"componentType\\\": \\\"Chiller\\\",\n \\\"componentId\\\": \\\"chiller_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033a9\\\"\n },\n {\n \\\"componentType\\\": \\\"PressureSensor\\\",\n \\\"componentId\\\": \\\"pressure_sensor_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033aa\\\"\n },\n {\n \\\"componentType\\\": \\\"Boiler\\\",\n \\\"componentId\\\": \\\"boiler_1\\\",\n \\\"_id\\\": \\\"685b9b0c7b916447abb033ab\\\"\n }\n]\n\n\nRelationships:\njson\n[\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a4\\\"],\n \\\"_userType\\\": \\\"hasCoolingCoil\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a2\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033c2\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033ab\\\"],\n \\\"_userType\\\": \\\"heatedBy\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a3\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033c3\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033aa\\\"],\n \\\"_userType\\\": \\\"pressureMonitoredBy\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a9\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033c5\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a5\\\"],\n \\\"_userType\\\": \\\"includesSupplyFan\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a2\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033c6\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a8\\\"],\n \\\"_userType\\\": \\\"temperatureMonitoredBy\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a2\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033c7\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a4\\\"],\n \\\"_userType\\\": \\\"feedsChilledWaterTo\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a9\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033c8\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a3\\\"],\n \\\"_userType\\\": \\\"hasHeatingCoil\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a2\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033ca\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a7\\\"],\n \\\"_userType\\\": \\\"controlsAirMixingWith\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a2\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033cb\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d3e\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685b9b0c7b916447abb033a6\\\"],\n \\\"_userType\\\": \\\"includesReturnFan\\\",\n \\\"_relatedUserType\\\": \\\"system_component_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedUserCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a2\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d3d\\\",\n \\\"_id\\\": \\\"685baf397b916447abb033cc\\\",\n \\\"_relatedUserItemId\\\": \\\"syscompcoll_v6CLcEWRWF\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d46\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685bdbdd7b916447abb033dc\\\"],\n \\\"_userType\\\": \\\"hasSensorDataPoint\\\",\n \\\"_relatedUserType\\\": \\\"systemsensor_points_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedTelemetryCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033aa\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d45\\\",\n \\\"_id\\\": \\\"685bdf9b7b916447abb033df\\\",\n \\\"_relatedUserItemId\\\": \\\"systemsensorptscol_BsYCWFBtJG\\\",\n \\\"_relatedUserItemVersion\\\": 1\n },\n {\n \\\"_relatedUserItemVersionId\\\": \\\"685b74152ea2a97a54135d46\\\",\n \\\"_isInverse\\\": false,\n \\\"_relatedToIds\\\": [\\\"685bdbdd7b916447abb033db\\\"],\n \\\"_userType\\\": \\\"hasSensorDataPoint\\\",\n \\\"_relatedUserType\\\": \\\"systemsensor_points_collection\\\",\n \\\"_relatedUserItemClass\\\": \\\"NamedTelemetryCollection\\\",\n \\\"_relatedFromId\\\": \\\"685b9b0c7b916447abb033a8\\\",\n \\\"_relatedUserItemDbId\\\": \\\"685b74152ea2a97a54135d45\\\",\n \\\"_id\\\": \\\"685bdf9b7b916447abb033e0\\\",\n \\\"_relatedUserItemId\\\": \\\"systemsensorptscol_BsYCWFBtJG\\\",\n \\\"_relatedUserItemVersion\\\": 1\n }\n]", "_userType": "path_builder_agent_static", "_namespaces": [ "{{nsfilter}}" ], "_config": { "_model": "gpt-4o", "_provider": "openai" } }]
Step 2: Create a team for the agent using the Create Team API call#
Create a team for the agent, using the IafAISvc.createTeam Javascript API call. For this example, the team is built using a single agent.
Note: For a list of the Rest API calls available for teams, refer to the Teams Rest API page.
Refer to the sample code below, where we create a new team, comprised of one agent, referencing the _usertype of the agent we built in Step 1.
{ "_name": "Path Builder Team Static", "_namespaces":["{{nsfilter}}"], "_agents": [ { "_userType": "path_builder_agent_static" } ], "_flow": [ { "from": "__start__", "to": "path_builder_agent_static" }, { "from": "path_builder_agent_static", "to": "__end__" } ]}
Step 3: Initiate a conversation with the new team using the Create Conversation API call.#
Initiate a conversation with the team using the IafAISvc.createConversation Javascript API call.
Note: For a list of the API calls available for conversations, refer to the Conversations Rest API page.
Refer to the sample code below.
{ "_input": { "message": "Provide various possible paths starting from ahu_1 in the format component-[usertype]->component->[usertype]->component..." }, "_teamId": "d953317b-6127-4098-9f47-311e37b66e49"}
Step 4: Continue the conversation with the team#
Continue the conversation using the conversation ID from the previous request and IafAISvc.createConversation.
Refer to the sample code below.
{ "_id": "f8080591-000e-42a3-8a41-7a23d885cad5", "_input": { "message": "Is there any Hvac component having sensor" }, "_teamId": "d953317b-6127-4098-9f47-311e37b66e49"}