How to Create Your Agent

This guide will walk you through the process of creating and configuring your own agent in Clarity.

Getting Started

Before you can create or manage agents in your Clarity dashboard, your use case must be approved. If you have not yet requested approval, please visit Request Process for Custom Agent and API Access before submitting your Request Form.

Jump to a Section

Settings box

This option will appear only after your use case has been approved.

Go to the Manage Agents Page

  1. Sign in to Clarity 
  2. Open Settings by selecting the gear icon next to your name and profile picture
  3. Click the Manage Agents link to see a list of all agents you own or co-manage. 
Manage agents page with a red arrow pointing to the New Agent button

Create a New Agent

Step 1: Click New Agent button

  1. On the Manage Agents page, click on New Agent + button
General tab page is open and displays the fields that must be completed to create a new agent

Step 2: General

Add basic information to create your agent:

  • Display name*: This name will display in the drop-down menu when selecting an agent. 
  • Expiration Date (Optional): Set a date if the agent will only be used for a limited time. 
  • Description*: Used for internal purposes and should include basic details about the agent. 
  • Welcome Message*: The message users will see when they start a new conversation with your agent. 
  • Chat Model*: Choose the LLM (AI model) for your agent. To learn more about which models, refer to the model information on our Agents page.

Once all required fields are complete, click Create. Your agent is now active, and you can proceed with configuring your agent.

TIPS

  • Use Shift+Enter for line breaks in the Welcome Message. Using only Enter will move the cursor to the next field.
  • The Chat Model cannot be changes once the agent has been created. Experiment with different models by creating up to 5 different agents.
System Prompt page displaying the system prompt field where text can be entered.

Configure Your Agent

Step 1: System Prompt

The System Prompt instructs the Custom Agent on how to behave and respond when interacting with users.  

To add a system prompt:
  1. Click the text box and edit the content in the System Prompt field 
  2. Click Save when finished

TIP

The system prompt affects the response quality. It can be altered at any time by anyone with Owner or Contributor access to the agent. This is helpful for testing and refining your agent’s responses. Please refer to our page on System Prompts to learn more.

Step 2: Tools and Knowledge

Control the user’s ability to upload files to their conversations and manage which files the Custom Agent should reference when generating responses.

Displays the User Portal File Upload toggle button
User Portal File Upload Toggle 

Allow users to upload files when chatting with your Custom Agent: 

  • ON: Users can attach files during conversations 
  • OFF: Users cannot upload files 
Manage files page with box for uploading file
Managing Knowledge Sources 
To add files:  
  1. Click “choose files” or drag and drop files into the Upload File(s) area   
  2. Click the Upload Files button
  3. Wait for the upload to complete 

To learn more about supported file formats please reference the Working with Files webpage. 

Displays files that have been uploaded with the option to delete the file with a trash can icon
To remove files: 
  1. Find the file in the Existing File(s) list 
  2. Click on the trash icon 

TIP

If a file needs to be updated, remove the old version and upload the new one.

Share Your Agent

After configuring and testing your agent, you can share it with other users. 

Before sharing, please keep the following in mind:

  • Yale users only: You can only grant access to existing Clarity users. If a Yale-affiliated user does not appear in the user role dropdown menu, they have not yet been granted access to the Clarity platform. In that case, they should contact the AI Platform Services team to request access.
  • No external users: Access cannot be granted to users outside of Yale. Clarity is available to Yale-affiliated users only.

Understanding Access Roles

It is essential to understand the different roles before granting access to your agent.

Role  View and Use the Custom Agent in the User Portal  Edit Settings  Manage User Access  Can be Primary Contact 
Reader  Yes  No  No  No 
Contributor  Yes  Yes  No  No 
Owner  Yes  Yes  Yes  Yes 

Shareable Agent Link

A Shareable Agent Link (also called an Agent Deep Link) is a special URL that takes you directly to a specific agent in Clarity and instantly starts a new conversation with it. It is designed to make it quick and easy to share your Custom Agent with colleagues, so you can get straight to the agent without any extra navigation steps through the Agent dropdown. To retrieve the Shareable Agent Link for your Custom Agent, refer to the documentation on how to generate and copy the link.

NOTE

  • Every Custom Agent must have exactly one Primary Contact. 
  • The agent creator is the Primary Contact by default until updated. 
  • The Primary Contact will be the main point of contact for that agent. 
  • Only users with the Owners role can de designated as the Primary Contact. 
Table displaying all users with access to agent

Managing Users

All users who have access to your agent will be listed in the table on the Share screen.

Open the Add Role Assignment form:
  1. Click Add Role Assignment button
Add New Role Assignment pop-up displays ways to search for a choose the name of a user, a drop-down to choose a role, and an Add Role Assignment button.
To add a user:
  1. Search for the user by name, email or NetID.
    1. Use “Last name, First name” format for fewer results 
  2. Select the user from the search results. Their name will appear below the role dropdown.  
  3. Select the appropriate role to assign the user from the drop-down menu. 
  4. Click Add Role Assignment button to add the user.

NOTE

  • All users who have access to your Custom Agent will be displayed in the list of users on the Share tab. 
  • Only one user can be added at a time, so repeat the steps for each user. 
  • Need to share with a group? Email ai.platforms@yale.edu to request group-based access.
User list in a table, with a trash icon circled in red
To remove a user:
  1. Find the user on the Share page table
  2. Click the trash icon 

Monitoring Your Custom Agent 

As the primary contact of a Custom Agent you have access to a Power BI report where you can monitor key metrics for your Custom Agents including: 

  • Number of unique users who have chatted with your agent  
  • Users’ primary affiliations and where across Yale the agent is being used  
  • Total conversations, message counts, and token usage  

If you have a Custom Agent with API access, you can also monitor: 

  • API token consumption  
  • Input and output token costs you are being billed for 

FAQs 

The report is accessible via the AI Platforms Community of Practice Teams channel or through this link.

Access is automatically granted to the Primary Contact of each agent. If you are listed as an owner and primary contact but do not have access, please reach out to the AI Platform Services Team for assistance. 

Metrics are refreshed weekly every Monday morning and on the first day of each month. 

No. Access to usage metrics is strictly restricted to the Primary Contact(s) of each agent. You will only be able to see metrics for the agents you manage. 

To protect the privacy of each agent’s data and ensure users can only view their own agents’ metrics, access is managed through the Primary Contact role. This allows the AI Platform Services team to maintain proper access controls over time. If you believe you should have access, please contact the AI Platform Services Team. 

Setting icon is circled with an arrow to the settings box

Edit Your Agent

You can edit an agent once it has been created. There are two ways to access an agent to edit the settings:

Option 1: Settings box

Step 1: 
  1. Sign in to Clarity 
  2. Open Settings by selecting the gear icon next to your name and profile picture
Pencil icon is circled in the edit column
Step 2: Choose the agent
  1. Find the agent you want to edit in the list
  2. Click the pencil icon in the Edit column
Edit agent page on the General tab
Step 3: Make changes to your agent
  1. Navigate the agent setting through the tabs
  2. Follow the instructions in the Configure Your Agent section on this page
Settings box

Option 2: Manage Agents page

Step 1: Open the Manage Agents page
  1. Sign in to Clarity 
  2. Open Settings by selecting the gear icon next to your name and profile picture
  3. Click the Manage Agents link to see a list of all agents you own or co-manage. 
manage agents page with the pencil icon circled
Step 2: Choose the agent
  1. Find the agent you want to edit in the list
  2. Click the pencil icon in the Actions column
Edit agent page on the General tab
Step 3: Make changes to your agent
  1. Navigate the agent setting through the tabs
  2. Follow the instructions in the Configure Your Agent section on this page
Manage agents page with the pencil icon circled

Delete Your Agent

  1. Navigate to the Manage Agents page
  2. Find the agent you want to delete in the table
  3. Click the trash icon for that agent

Back to Top