Tutorial: Creating the Empower agent on Agent builder

​

Before your begin

​

Empower: An agent for employee success

​

ServiceNow and Customer care examples

​

Customer care and ServiceNow agents

1. Create a folder to structure your agents and tools. For instance, name this folder as agents.
2. In the new folder, create a YAML file with a text editor of your preference. Name the file as customer_care_agent.
3. Insert the following code into the customer_care_agent.yaml file.
   YAML

   Copy

   Ask AI

   spec_version: v1
   style: react
   name: customer_care_agent
   llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
   description: >
       You are an agent who specializes in customer care for a large healthcare institution. You should be compassionate
       to the user.
       
       You are able to answer questions around benefits provided by different plans, the status of a claim,
       and are able to help direct people to the nearest provider for a particular ailment.
   instructions: >
       Use the search_healthcare_providers tool to search for providers. If more than 1 is returned format as a github
       formatted markdown table. Otherwise simply return the output in a kind conversational tone. Do not expand speciality acronyms.
       
       Use the get_healthcare_benefits tool to fetch the benefits coverage for a particular ailment, or for generic plan 
       comparisons. Respond to get_healthcare_benefits requests in a github style formatted markdown table. Be specific about
       the expected coverage type if a particular condition is mentioned.
       
       Use the get_my_claims tool to fetch your open medical claims. Make sure to respond in a direct tone and 
       do not negotiate prices. Format the output of get_my_claims as a github style markdown table.
   collaborators:
       - service_now_agent
   tools:
       - search_healthcare_providers
       - get_healthcare_benefits
       - get_my_claims
   

   See all 26 lines
4. Save your file.
5. Create another YAML file, but name it as service_now_agent.
6. Insert the following code into the service_now_agent.yaml file.
   YAML

   Copy

   Ask AI

   spec_version: v1
   style: react
   name: service_now_agent
   llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
   description: >
       You are an agent who specializes in customer care for a large healthcare institution. You should be compassionate
       to the user.
       
       You are able to help help a user create tickets in service now for processing by a human later. Examples of when to do
       do this include for adding members to plans or helping users with documentation.
   instructions: >
       If a user is having difficulty either generating benefits documents or adding additional members to their plan,
       create a new incident for our support team using service_now_create_incident tool. Be compassionate about the user
       facing difficulty.
       
       The output of get_service_now_incidents should be formatted as a github style formatted markdown table.
   collaborators: []
   tools:
       - create_service_now_incident
       - get_my_service_now_incidents
       - get_service_now_incident_by_number
   

   See all 21 lines
7. Save your file.

​

Creating the Customer care tools

1. Create a new folder to insert the tools of your examples. For instance, name this folder as tools.
2. In the new folder, create another one to insert the customer care tools. Name this folder as customer_care.
3. In the customer_care folder, create a Python file with a text editor of your preference. Name the file as get_healthcare_benefits.
4. Insert the following code into the get_healthcare_benefits.py file.
   Python

   Copy

   Ask AI

   from enum import Enum
   
   from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
   import requests
   
   class Plan(str, Enum):
       HDHP = 'HDHP'
       HDHP_Plus = 'HDHP Plus'
       PPO = 'PPO'
   
   
   @tool
   def get_healthcare_benefits(plan: Plan, in_network: bool = None):
       """Retrieves a comprehensive list of health benefits data, organized by coverage type and plan variant.
   
       This data includes details such as annual deductibles, out-of-pocket maximums, and various co-pays or
       percentages for medical services under different network plans (HDHP, HDHP Plus, and PPO).
   
       Args:
           plan (str, optional): The plan the user is currently on. Can be one of "HDHP", "HDHP Plus", or "PPO".
               If not provided, all plans will be returned.
           in_network (bool, optional): Whether the user wants coverage for in-network or out-of-network.
               If not provided, both will be returned.
   
       Returns:
           list[dict]: A list of dictionaries, where each dictionary contains:
               - 'Coverage': A description of the coverage type (e.g., 'Preventive Services').
               - 'HDHP (In-Network)': The cost/percentage coverage for an in-network HDHP plan.
               - 'HDHP (Out-of-Network)': The cost/percentage coverage for an out-of-network HDHP plan.
               - 'HDHP Plus (In-Network)': The cost/percentage coverage for an in-network HDHP Plus plan.
               - 'HDHP Plus (Out-of-Network)': The cost/percentage coverage for an out-of-network HDHP Plus plan.
               - 'PPO (In-Network)': The cost/percentage coverage for an in-network PPO plan.
               - 'PPO (Out-of-Network)': The cost/percentage coverage for an out-of-network PPO plan.
       """
       resp = requests.get(
           'https://get-benefits-data.1sqnxi8zv3dh.us-east.codeengine.appdomain.cloud/',
           params={
               'plan': plan,
               'in_network': in_network
           }
       )
       resp.raise_for_status()
       return resp.json()['benefits']
   

   See all 43 lines
5. Save your file.
6. In the same folder, create another Python file and name it as get_my_claims.
7. Insert the following code into the get_my_claims.py file.
   Python

   Copy

   Ask AI

   from ibm_watsonx_orchestrate.agent_builder.tools import tool
   
   
   @tool
   def get_my_claims() -> list[dict]:
       """Retrieves detailed information about submitted claims.
   
       The details include claim status, submission and processing dates, amounts claimed and approved,
       provider information, and services included in the claims.
   
       Returns:
           list[dict]: A list of dictionaries, each containing details about a specific claim:
               - claimId (str): Unique identifier for the claim.
               - submittedDate (str): Date when the claim was submitted.
               - claimStatus (str): Current status of the claim (e.g., 'Processed', 'Pending', 'Rejected').
               - processedDate (str or None): Date when the claim was processed (None if not processed yet).
               - amountClaimed (float): Total amount claimed.
               - amountApproved (float or None): Amount approved for reimbursement (None if pending, 0 if rejected).
               - rejectionReason (str, optional): Reason for rejection if applicable (only present if claimStatus is 'Rejected').
               - provider (str or dict): Provider details, either as a simple string or a dictionary with detailed provider information.
               - services (list[dict]): List of services included in the claim, each with:
                   - serviceId (str): Identifier for the service.
                   - description (str): Description of the service provided.
                   - dateOfService (str): Date the service was provided.
                   - amount (float): Amount charged for the service.
       """
   
       claims_data = [
           {
               "claimId": "CLM1234567",
               "claimStatus": "Processed",
               "amountClaimed": 150.00,
               "amountApproved": 120.00,
               "provider": {
                   "name": "Healthcare Clinic ABC",
                   "providerId": "PRV001234",
                   "providerType": "Clinic"
               },
               "services": [
                   {"serviceId": "SVC001", "description": "General Consultation", "dateOfService": "2025-02-28", "amount": 100.00},
                   {"serviceId": "SVC002", "description": "Blood Test", "dateOfService": "2025-02-28", "amount": 50.00}
               ]
           },
           {
               "claimId": "CLM7654321",
               "claimStatus": "Pending",
               "amountClaimed": 300.00,
               "amountApproved": None,
               "provider": "City Health Hospital",
               "services": [
                   {"serviceId": "SVC003", "description": "X-ray Imaging", "dateOfService": "2025-02-14", "amount": 300.00}
               ]
           },
           {
               "claimId": "CLM9876543",
               "claimStatus": "Rejected",
               "amountClaimed": 200.00,
               "amountApproved": 0.00,
               "rejectionReason": "Service not covered by policy",
               "provider": "Downtown Diagnostics",
               "services": [
                   {"serviceId": "SVC003", "description": "MRI Scan", "dateOfService": "2025-02-05", "amount": 200.00}
               ]
           }
       ]
   
       return claims_data
   

   See all 67 lines
8. Save your file.
9. In the same folder, create another Python file and name it as search_healthcare_providers.
10. Insert the following code into the search_healthcare_providers.py file.
    Python

    Copy

    Ask AI

    from typing import List
    
    import requests
    from pydantic import BaseModel, Field
    from enum import Enum
    
    from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
    
    
    class ContactInformation(BaseModel):
        phone: str
        email: str
    
    
    class HealthcareSpeciality(str, Enum):
        GENERAL_MEDICINE = 'General Medicine'
        CARDIOLOGY = 'Cardiology'
        PEDIATRICS = 'Pediatrics'
        ORTHOPEDICS = 'Orthopedics'
        ENT = 'Ear, Nose and Throat'
        MULTI_SPECIALTY = 'Multi-specialty'
    
    
    class HealthcareProvider(BaseModel):
        provider_id: str = Field(None, description="The unique identifier of the provider")
        name: str = Field(None, description="The providers name")
        provider_type: str = Field(None, description="Type of provider, (e.g. Hospital, Clinic, Individual Practitioner)")
        specialty: HealthcareSpeciality = Field(None, description="Medical speciality, if applicable")
        address: str = Field(None, description="The address of the provider")
        contact: ContactInformation = Field(None, description="The contact information of the provider")
    
    
    @tool
    def search_healthcare_providers(
            location: str,
            specialty: HealthcareSpeciality = HealthcareSpeciality.GENERAL_MEDICINE
    ) -> List[HealthcareProvider]:
        """Retrieves a list of the nearest healthcare providers based on location and optional specialty.
    
        The function can infer the specialty of the location from the request.
    
        Args:
            location (str): Geographic location to search providers in (city, state, zip code, etc.).
            specialty (str, optional): Medical specialty to filter providers by. Must be one of:
                "ENT", "General Medicine", "Cardiology", "Pediatrics", "Orthopedics", "Multi-specialty".
    
        Returns:
            list: A list of healthcare providers near the specified location for the given specialty.
        """
        resp = requests.get(
            'https://find-provider.1sqnxi8zv3dh.us-east.codeengine.appdomain.cloud',
            params={
                'location': location,
                'speciality': specialty
            }
        )
        resp.raise_for_status()
        return resp.json()['providers']
    

    See all 58 lines

​

Creating the ServiceNow tools

1. In the tools folder, create a new folder named as servicenow.
2. In the servicenow folder, create a Python file and name it as create_service_now_incident.
3. Insert the following code into the create_service_now_incident.py file.
   Python

   Copy

   Ask AI

   import base64
   import json
   from typing import Optional
   
   import requests
   from requests.auth import HTTPBasicAuth
   
   from pydantic import Field, BaseModel
   
   from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
   from ibm_watsonx_orchestrate.run import connections
   
   from ibm_watsonx_orchestrate.agent_builder.connections import ConnectionType
   
   CONNECTION_SNOW = 'service-now'
   
   class ServiceNowIncidentResponse(BaseModel):
       """
       Represents the response received after creating a ServiceNow incident.
       """
       incident_number: str = Field(..., description='The incident number assigned by ServiceNow')
       sys_id: str = Field(..., description='The system ID of the created incident')
   
   
   class ServiceNowIncident(BaseModel):
       """
       Represents the details of a ServiceNow incident.
       """
       incident_number: str = Field(..., description='The incident number assigned by ServiceNow')
       short_description: str = Field(..., description='A brief summary of the incident')
       description: Optional[str] = Field(None, description='Detailed information about the incident')
       state: str = Field(..., description='Current state of the incident')
       urgency: str = Field(..., description='Urgency level of the incident')
       created_on: str = Field(..., description='The date and time the incident was created')
   
   
   @tool(
       permission=ToolPermission.READ_WRITE,
       expected_credentials=[
           {"app_id": CONNECTION_SNOW, "type": ConnectionType.BASIC_AUTH}
       ]
   )
   def create_service_now_incident(
           short_description: str,
           description: str = None,
           urgency: int = 3
   ):
       """Creates a new ServiceNow incident.
   
       Args:
           short_description (str): A brief summary of the incident.
           description (str, optional): Detailed information about the incident.
           urgency (int, optional): Urgency level. Must be 1 (High), 2 (Medium), or 3 (Low). Defaults to 3.
   
       Returns:
           dict: The created incident details, including the incident number and system ID.
       """
   
       creds = connections.basic_auth(CONNECTION_SNOW)
       base_url = creds.url
       url = f"{base_url}/api/now/table/incident"
   
       headers = {
           'Content-Type': 'application/json',
           'Accept': 'application/json'
       }
       payload = {
           'short_description': short_description,
           'description': description,
           'urgency': urgency
       }
   
       response = requests.post(
           url,
           headers=headers,
           json=payload,
           auth=HTTPBasicAuth(creds.username, creds.password)
       )
       response.raise_for_status()
       data = response.json()['result']
   
       number, sys_id = data['number'], data['sys_id']
   
       url = f"{base_url}/api/now/table/incident/{sys_id}"
       response = requests.get(
           url,
           headers=headers,
           json=payload,
           auth=HTTPBasicAuth(creds.username, creds.password)
       )
       response.raise_for_status()
       data = response.json()['result']
   
       return ServiceNowIncident(
           incident_number=data['number'],
           sys_id=data['sys_id'],
           short_description=data['short_description'],
           description=data.get('description', ''),
           state=data['state'],
           urgency=data['urgency'],
           created_on=data['opened_at']
       ).model_dump_json()
   
   # if __name__ == '__main__':
   #     incident = create_service_now_incident(short_description='Test Incident', description='This is a test incident')
   #     print(json.dumps(incident.dict(), indent=2))
   
   

   See all 107 lines
4. Save your file.
5. In the same folder, create another Python file and name it as get_my_service_now_incidents.
6. Insert the following code into the get_my_service_now_incidents.py file.
   Python

   Copy

   Ask AI

   import json
   from typing import Optional, List
   
   import requests
   from pydantic import Field, BaseModel
   import base64
   
   from requests.auth import HTTPBasicAuth
   
   from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
   from ibm_watsonx_orchestrate.run import connections
   
   from ibm_watsonx_orchestrate.agent_builder.connections import ConnectionType
   
   
   CONNECTION_SNOW = 'service-now'
   
   class ServiceNowIncident(BaseModel):
       """
       Represents the details of a ServiceNow incident.
       """
       incident_number: str = Field(..., description='The incident number assigned by ServiceNow')
       short_description: str = Field(..., description='A brief summary of the incident')
       description: Optional[str] = Field(None, description='Detailed information about the incident')
       state: str = Field(..., description='Current state of the incident')
       urgency: str = Field(..., description='Urgency level of the incident')
       created_on: str = Field(..., description='The date and time the incident was created')
   
   @tool(
       expected_credentials=[
           {"app_id": CONNECTION_SNOW, "type": ConnectionType.BASIC_AUTH}
       ]
   )
   def get_my_service_now_incidents() -> List[ServiceNowIncident]:
       def fetch_user_incidents() -> list[dict]:
       """Fetches all ServiceNow incidents authored by the user.
   
       Returns:
           list[dict]: A list of incident details, including:
               - number (str): The incident number.
               - sys_id (str): The system ID of the incident.
               - description (str): The incident description.
               - state (str): The current state of the incident.
               - urgency (str): The urgency level of the incident.
       """
       creds = connections.basic_auth(CONNECTION_SNOW)
       base_url = creds.url
       url = f"{base_url}/api/now/table/incident"
   
       headers = {
           'Content-Type': 'application/json',
           'Accept': 'application/json'
       }
       
       query_params = {}
       query_params['sys_created_by'] = 'admin'
       
       response = requests.get(
           url,
           headers=headers,
           params=query_params,
           auth=HTTPBasicAuth(creds.username, creds.password)
       )
       response.raise_for_status()
       data = response.json()['result']
       
       lst =  [ServiceNowIncident(
           incident_number=d['number'],
           short_description=d['short_description'],
           description=d.get('description', ''),
           state=d['state'],
           urgency=d['urgency'],
           created_on=d['opened_at']
       ) for d in data]
       lst.sort(key=lambda o: o.created_on, reverse=True)
       lst = lst[:min(len(lst), 10)]
       return lst
   
   # if __name__ == '__main__':
   #     incidents = get_my_service_now_incidents()
   #     print(incidents)
   

   See all 81 lines
7. Save your file.
8. In the same folder, create another Python file and name as get_service_now_incident_by_number.
9. Insert the following code into the get_service_now_incident_by_number.py file.
   Python

   Copy

   Ask AI

   import json
   from typing import Optional
   
   import requests
   from pydantic import Field, BaseModel
   import base64
   
   from requests.auth import HTTPBasicAuth
   
   from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
   from ibm_watsonx_orchestrate.run import connections
   
   from ibm_watsonx_orchestrate.agent_builder.connections import ConnectionType
   
   CONNECTION_SNOW = 'service-now'
   
   class ServiceNowIncident(BaseModel):
       """
       Represents the details of a ServiceNow incident.
       """
       incident_number: str = Field(..., description='The incident number assigned by ServiceNow')
       short_description: str = Field(..., description='A brief summary of the incident')
       description: Optional[str] = Field(None, description='Detailed information about the incident')
       state: str = Field(..., description='Current state of the incident')
       urgency: str = Field(..., description='Urgency level of the incident')
       created_on: str = Field(..., description='The date and time the incident was created')
   
   @tool(
       expected_credentials=[
           {"app_id": CONNECTION_SNOW, "type": ConnectionType.BASIC_AUTH}
       ]
   )
   def get_service_now_incident_by_number(incident_number: str):
       """Fetches a ServiceNow incident based on incident ID, creation date, or other filters.
   
       Args:
           incident_number (str): The uniquely identifying incident number of the ticket.
   
       Returns:
           dict: The incident details, including number, system ID, description, state, and urgency.
       """
       creds = connections.basic_auth(CONNECTION_SNOW)
       base_url = creds.url
       url = f"{base_url}/api/now/table/incident"
   
       headers = {
           'Content-Type': 'application/json',
           'Accept': 'application/json'
       }
       
       query_params = {}
       if incident_number:
           query_params['number'] = incident_number
       
       response = requests.get(
           url,
           headers=headers,
           params=query_params,
           auth=HTTPBasicAuth(creds.username, creds.password)
       )
       response.raise_for_status()
       data = response.json()['result']
       data = data[0]  # Assuming only one incident is returned
       
       return ServiceNowIncident(
           incident_number=data['number'],
           short_description=data['short_description'],
           description=data.get('description', ''),
           state=data['state'],
           urgency=data['urgency'],
           created_on=data['opened_at']
       ).model_dump_json()
   
   # if __name__ == '__main__':
   #     incident = fetch_service_now_incident(incident_number='INC0010311')
   #     print(json.dumps(incident.dict(), indent=2))
   

   See all 76 lines
   Up until here, you created the tools for the service now example. Before finishing, you must create the requirements file.
10. Into the servicenow folder, create a TXT file named as requirements.
11. Insert the following code into the requirements.txt file.
    TEXT

    Copy

    Ask AI

    requests==2.32.3
    

​

Installing ServiceNow and Customer care

1. Start the watsonx Orchestrate Developer Edition local server orchestrate server start --env-file={{The path of your .env file}}.
2. Signup for a Sevice Now account at https://developer.servicenow.com/dev.do.
3. Validate your email address (check email).
4. On the landing page, click start building. This allocates a new instance of ServiceNow for you.
5. Back on the landing page, click your profile icon on the upper right. Under “My instance”, click manage instance password.
6. In the terminal, create an application connection by using these credentials:
   BASH

   Copy

   Ask AI

   orchestrate connections add -a service-now
   

   BASH

   Copy

   Ask AI

   orchestrate connections configure -a service-now --env draft --type team --kind basic --url <the instance url>
   

   BASH

   Copy

   Ask AI

   orchestrate connections set-credentials -a service-now --env draft -u admin -p '<password from modal>'
   

7. In the terminal, navigate to the customer_care folder and run the following commands to import the customer care tools:
   BASH

   Copy

   Ask AI

   orchestrate tools import -k python -f ./get_my_claims.py
   

   BASH

   Copy

   Ask AI

   orchestrate tools import -k python -f ./get_healthcare_benefits.py
   

   BASH

   Copy

   Ask AI

   orchestrate tools import -k python -f ./search_healthcare_providers.py
   

8. Go to the servicenow folder and install the tools by running the following commands:
   BASH

   Copy

   Ask AI

   orchestrate tools import -k python -f ./create_service_now_incident.py -r ./requirements.txt -a service-now
   

   BASH

   Copy

   Ask AI

   orchestrate tools import -k python -f ./get_my_service_now_incidents.py -r ./requirements.txt -a service-now
   

   BASH

   Copy

   Ask AI

   orchestrate tools import -k python -f ./get_service_now_incident_by_number.py -r ./requirements.txt -a service-now
   

9. Go to your agents folder and import the agents created previously:
   BASH

   Copy

   Ask AI

   orchestrate agents import -f service_now_agent.yaml
   

   BASH

   Copy

   Ask AI

   orchestrate agents import -f customer_care_agent.yaml
   

10. Run orchestrate chat start.

​

Agent’s profile

1. From the IBM watsonx Orchestrate chat page, click Manage agents.
2. Click Create agent.
3. Choose Create from Scratch.
4. In the Name field, insert Empower and in the Description, insert a text as you prefer to describe the agent. Suggestion: “This agent’s role is to assist employees by answering their questions, providing guidance on supporting tickets, service issues, and referencing FAQs stored in Sharepoint”.
5. Click Create to complete.

​

Agent’s toolset

1. From the Empower agent management screen, click Toolset.
2. In Tools, click Add tool, and select Add from local instance.
3. Select the get_healthcare_benefits tool, and click Add to agent.
4. In Agents, add the agent that collaborates with your agent on running tasks. Click Add agent.
5. Click Add from local instance, select service_now_agent, and click Add to agent.

​

Chat preview

1. From the Empower agent management screen, type in the chat bar “Show my benefits related to mental health”, and press Enter.
2. Wait for the chat response. You can check how your response was generated by clicking How did I get this response.

​

Deploying Empower agent

1. Click Deploy.
2. Click IBM watsonx Orchestrate to return for the chat page.
3. In the Agents list, select the Empower agent, and start by using it directly from the watsonx Orchestrate chat page.
4. You can ask about service now issues, as your agent has the Service now agent collaborating on running tasks.