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

Create a New Agent

Create a New Agent

Step 1: Go to the Manage Agents page

  1. Sign in to Clarity  
  2. Click the Manage Agents button above your name and profile picture to see a list of all agents you own or co-manage. 

Step 2: Click New Agent button

  1. On the Manage Agents page, click on the + New Agent button.
General tab in the Create Agent setup

Step 3: General Tab

Add basic information to create your agent: 

  • Display name*: This name will display in the drop-down menu when selecting an agent.  
  • Description*: Used for internal purposes and should include basic details about the agent.  
  • Expiration Date (Optional): Set a date if the agent will only be used for a limited time.  
  • 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. 
  • Welcome Message*: The message users will see when they start a new conversation with your agent.  

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

  • 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.
Configurations tab in the Create Agent Setup

Configure Your Agent

Step 1: Configuration Tab 

Use the settings in this tab to configure your Custom Agent’s system prompt and user experience. 

The System Prompt defines how the Custom Agent behaves and responds 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.  

The settings under the Portal User Experience section control which UI features are visible to users when interacting with the Custom Agent in the Agent Portal. You can toggle the following options on and off: Allow File Uploads, Show Token Count, Show Message Rating, Show View Prompt, Show Content Artifacts, and Enable Conversation History. 

Changes are saved using the main Save button. 

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.

Speech tab in the Agent Configuration Setup

Step 2. Speech Tab 

Enable Real-Time Speech to have spoken conversations with your Custom Agent. When this feature is enabled, you can speak directly to your Custom Agent, which will listen and respond aloud. You can continue to submit written prompts while using Real-Time Speech. For more information, please refer to our documentation.

Turning the Enable Real-Time Speech toggle on will prompt you with additional voice settings, allowing you to customize the speech experience. 

This setting is enabled by default for new agents. Changes are saved with the main Save button. 

Tools tab in the Create Agent Setup

Step 3. Tools Tab 

Use this tab to configure which tools your Custom Agent can use, including Code, Knowledge and Image Generation

Note that Image Generation is disabled in new agents by default. Changes are saved with the main Save button.

Enabling Code allows your Custom Agent to read, analyze, and work with files you upload such as spreadsheets, datasets, or code files. Think of it as giving your agent the ability to do data analysis, code, math, finance, build charts, produce new files, and handle Excel formulas.

What your agent can do with this tool:

  • Analyze data from uploaded files (e.g., Excel spreadsheets, CSV files)
  • Perform complex calculations
  • Generate charts and visual graphs to help you understand your data
  • Transform, clean, or reformat data as needed
  • Create and produce new files for you to download

When should you enable this? Enable this tool if you plan to upload data-heavy files such as Excel sheets, CSV files, or code files and you want your Custom Agent to work with and analyze that data.

Enabling Knowledge allows your Custom Agent to read and search through documents you upload, using them as a reference when answering your questions. Instead of relying only on what the agent already knows, it can look directly into your uploaded files to find the answers.

What your agent can do with this tool:

  • Search through your uploaded files for specific information
  • Pull out relevant sections or excerpts from documents
  • Provide answers that are grounded in your actual content

When should you enable this? Enable this tool if you plan to upload text-based documents such as Word files, PDFs, or plain text files and you want your Custom Agent to reference and retrieve information from those documents during conversations.

Enabling Image Generation allows your Custom Agent to create images based on the prompt you provide to the Custom Agent. Simply describe what you’d like, and the agent will generate an image for you. Please refer to the following page for more information on image generation in Clarity.

When should you enable this? Enable this tool if you want your Custom Agent to be able to create visual content such as images or concept visuals.

A Note on Tool Behavior

You may occasionally notice that your Custom Agent produces an answer without appearing to use the Code Interpreter or Knowledge tool, even when you have them enabled. This is normal!

Behind the scenes, your Custom Agent is designed to be smart about when it actually needs to use a tool. If your question is straightforward enough to answer directly, or if an uploaded file is small enough to be read without a full search, the agent will handle it on its own without calling on a specific tool.

Knowledge tab in the Custom Agent Setup

Step 4. Knowledge Tab 

Use this tab to manage which knowledge files the Custom Agent should reference when generating responses. 

To add files:
  1. Click Choose Files or drag and drop files into the Upload File(s) area.  
  2. Wait for the upload to complete. Uploaded files will appear in the Knowledge Files list.

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

Remove Files from the Knowledge Files List
To remove files: 
  1. Find the file in the Knowledge files list.
  2. Click on the trash icon.

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. 

Managing Users

All users who have access to your agent will be listed in the Role assignments table.

Sharing tab in the Create Agent Setup

To add a user: 

  1. Click the Add Role Assignment button. 
  2. Search for the user by name, email or NetID. 
  3. For fewer search results, Use “Last name, First name” format. 
  4. Select the user from the search results. Their name will appear below the role dropdown.   
  5. Select the appropriate role to assign the user from the drop-down menu.  
  6. Click the Add Role Assignment button to add the user. 

NOTE

  • 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.
Remove a user from the Role Assignment List

To remove a user:

  1. Find the user in the Role assignments 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. 

Edit Your Agent

You can edit your Custom Agent once it has been created. 

Edit Agent
  1. Sign in to Clarity.  
  2. Click the Manage Agents button to see a list of all agents you own or co-manage.
  3. Find the Custom Agent you want to edit in the list.
  4. Click the Pencil icon in the Actions column.
  5. Follow the instructions in the Configure Your Agent section on this page.
Delete Agent

Delete Your Agent

You can delete your Custom Agent once it has been created. 

  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