AI Agent Card
AI Agent Card Overview
Using Agents in Conversations
The AI Agent Card is unique within guided conversations because this one single card can take the place of many other cards available. It provides the ability to create a fully agentic conversation guided by a prompt, tool access, and data source selections.
This card can be used in two different ways:
Fully Agentic Flows
A guided conversation that only utilizes one or more AI Agent cards to facilitate the conversation.
- Agents handles the conversation flow dynamically based off of the instructions provided and the user's replies
- Off-ramp instructions are provided via the prompt and resolution instructions
Hybrid Flows
The ability to traverse through structured nodes and an agentic node within the same conversation flow.
Setup options could include be to:
- Collect structured information upfront and then move to agentic
- Start with agentic until a certain subject, topic, or task is presented and off-ramp to the structured nodes/cards
Fully structured flows are any flows that are not using an agentic component. The entire flow, order, and actions are all completely controlled by the structure of the conversation.
- Conversation follows predefined paths
- Each node or step in the conversation has defined boundaries of what it communicates, collects, or takes action on
To access the AI Agent Card, select it from the card menu within a conversation underneath the Actions header.
Prompt
Creating a good prompt is crucial as it defines what the AI Agent is supposed to do, how it should behave, and the context it operates within. A well-constructed prompt can ensure the agent performs consistently and as expected. Poor prompts can also directly lead to poor performing agents.
Below are simply guidelines for defining the prompt for your agents. These are not meant to replace individualized prompt writing and testing. Each use case will require a thoughtful approach of what aspects of the prompt are needed and how to best define the instructions.
Components of the Prompt
Agent's Role, Objective, & Tone
- Role: Define what the agent is (e.g., Customer Support Assistant, Data Analyzer).
- Objective: Clearly state the primary goal (e.g., answer customer inquiries, analyze sales trends).
- Tone: Specify the desired communication style (e.g., friendly, professional, empathetic).
Example: You are a friendly customer support agent for [x company]. Your goal is to resolve customer inquiries efficiently while maintaining a positive tone.
Boundaries on Subject Matter & Data Sources
While access to the specific data sources are defined in the Data Sources section of the agent, you can still provide additional guidance in the prompt to help the agent in case certain sources are better for certain tasks or subjects. You can also outline topics that the agent should avoid and end or escalate.
- Subject Matter: Outline the common topics that the agent will typically handle as well as topics the agent needs to avoid.
- Example: Topics that you should answer effectively - (address information, contact numbers, membership rates, class schedules, etc.). If the user engages on discounts, refunds, or cancelation - do not attempt to handle that and tell the user to contact support directly.
- Data Source Guidance: Outline instructions for the agent how it should access and use the data sources it has access to. Provide specifics if multiple sources are enabled so the agent can be more efficient.
- Example: Use only the website's content - do not guess or invent. Your job is to answer questions using only the website search tool and always search first before responding. For contact related information, check the contact us page first.
- Example: For lending approval guidelines and questions, use the Lending Guideline documents in our KB. For general customer inquiries, use the website's content first. In either case, do not guess or invent the data.
App Action & Tool Usage Guidelines
Within your prompt it will be important to provide instructions on which tools should be used for whic purpose. This can also be part of a section in the prompt where you outline the details of the agent's tasks, but it is important to specify which app actions are to be used for which purpose.
Example: Call "get-hair-salon-services" to get service details and the duration of services. After gathering their preferred information call "get-hair-salon-availability" to get available appointment times.
Task Boundaries & Inventory
Detail out the specific tasks the agent is responsible fore and clarify any exceptions. Depending on the complexity of the agent's goal, you may need to break down the steps of the tasks into sections. More generalized agents require less task-driven instruction. However, if it is an agent who has a very specific objective like booking salon appointments, then you should outline the specific tasks needed to get that done, potentially even step by step.
General Tips for Writing Good Prompts
- Clarity Over Complexity: Use simple language to avoid misunderstandings. Avoid jargon or ambiguous terms.
- Specify Context: Short explanations about context can significantly improve agent performance.
- Iterate and Test: Continuously refine based on agent performance and user feedback.
- Use Examples: Where possible, provide examples to illustrate complex instructions.
- Length and Focus: Keep prompts succinct but comprehensive. Focusing on key instructions helps maintain relevance.
- Consistency: Use consistent language across agents to avoid confusion.
- Structure: Use bulleted or numbered lists and sections in your prompt to organize the information and make it easy to read and scan.
Model Options
Model Selection
At Capacity, we offer several different LLM models to use within the platform. Select an AI model that best suits your project. Each AI model varies in capabilities and accuracy, make sure to choose the one that aligns with your specific objectives.
For more information on our models, please refer to our Selecting an AI Model article.
Temperature
The Temperature setting controls the randomness of the output from the AI language model. The range is 0.0 - 2.0. Here’s what you need to know:
Lower Temperature: A lower temperature results in more predictable and conservative responses. This setting is useful when the conversation requires straightforward, precise information. Near-zero values make the AI more deterministic and repetitive.
Higher Temperature: A higher temperature increases randomness, leading to more creative and varied responses. It’s ideal for more open-ended questions where diverse output can be beneficial.
When configuring this setting, consider the context of the conversation and the expectations of the conversation participants.
Groundedness Safeguard
This is another setting that assists in minimizing potential hallucinations or inaccurately generated results.
When enabled, the system will check the LLM results compared to the search/RAG results and validate if it is grounded. If not, it will re-fetch or correct the information. Otherwise, the data will not be returned and the LLM will communicate it does not have the information available. Enabling this setting may impact latency because it could require the system to re-fetch data to validate results prior to communicating the response.
Filler Settings
A filler is a response that is generated to minimize gaps in the conversation. Fillers are sometimes helpful when the agent has to go out to external tools that may have longer response times like API endpoints or large search results. There are times where those actions can result in dead space in a conversation. Fillers help smooth out the conversation by providing the user a response as the task is being worked.
Filler Types
No Filler
When this is selected, the agent will offer no fillers and will wait until it has its response prior to providing any update to the user.
Default Fillers
This option uses the LLM to generate the appropriate filler messages.
Additional Settings:
- Initial Filler Wait Time - Adjusts the seconds of wait time for the initial response filler (as needed)
- Subsequent Filler Wait Time - Adjusts the seconds of wait time for the subsequent filler messages (as needed)
User Defined
When selected, the user can provide a set of filler phrases and the agent will only used those phrases provided.
Additional Settings:
- Filler Phrases - Comma separated list of filler phrases. Maximum 500 characters total. Up to 20 phrases allowed. Each phrase must be 50 characters or less.
- Initial Filler Wait Time - Adjusts the seconds of wait time for the initial response filler (as needed)
- Subsequent Filler Wait Time - Adjusts the seconds of wait time for the subsequent filler messages (as needed)
Status Fillers
These are system generated fillers that are contextually relevant to the specific task the agent is performing, e.g. "Looking that information up in the search results right now."
Additional Settings:
- Initial Filler Wait Time - Adjusts the seconds of wait time for the initial response filler (as needed)
Data Sources
The AI Agent card can use multiple data sources as the basis for how it gathers information to respond in the conversation. Unlike other cards, the AI Agent can access one or more of these sources, as defined in the set up. When setting up the card, be mindful of the preciseness of the information you want to allow the agent to have access to. We provide discreet controls for targeting specific directories, folders, and sources to allow you to have as wide or narrow of a net as needed to provide to the agent card.
It is generally best practice to provide the agent with access only to the sources it needs. More information is not always better especially if the information is not fully relevant to the conversations you expect the agent to handle.
Capacity KB Sources
The native Capacity Knowledge Base consists of any files that you have directly uploaded to Capacity. You have the ability to store documents in a folder structure and organization that you control. For use in the AI Agent card, we give you the option to select which KB sources you want to grant the agent access to, at varying levels of granularity, from the entire KB - all the way down to the individual dialogue/file.
As noted above though, it is best to scope the Knowledge Base source to only those that are relevant to the agent's objective and purpose.
Answer Engine Sources
If you are using the Capacity Answer Engine, we will surface any of the indexed sources in this section. You can select one or more sources from any of the ones configured and connected within your organization.
Capacity Article Sources
For any Sites that you have setup on the Capacity platform, you can use these as sources for the agent to draw information from. You have the ability to limit the scope to certain sites.
Web Sources
Capacity has the ability to search external websites in near real-time to get answers and knowledge for the agent to respond. This option is great for use cases where your website is your main source of knowledge for various subjects. You can add one or more website URLs for the agent to use as a source. It is best to make sure you know all of the content published on any of the websites provided.
Agent Variables
Within the agent card you have the ability to define variables that you may want the agent to collect during the conversation. The information that is collected for these variables will persist after the AI Agent card for use later in the conversation or to be passed to a workflow. This is a completely optional section of the card and is not required if collecting specific data for use outside of the agent card is not necessary.
Variable Best Practices
- When defining variables it is important that you provide a clear description on what the variable is. This will improve the accuracy of the agent assigning and collecting the correct data.
- Variable names must start with a letter and can only contain lowercase letters and underscores, e.g. first_name.
- Required variables will be collected upfront before progressing through any other objectives of the prompt. Only use required variables when you absolutely need the information for use outside of the agent card.
- You do not need to define the variables that may be required for a Developer platform app call. If a specific app action that you are adding to the agent requires a specific piece of information, the agent will automatically collect it in order to complete the app action. Making a required variable in the Agent Variables section for this purpose is redundant and will disrupt the ideal data collection flow.
- Optional variables will be collected as the agent goes through the conversation, but since they would be optional, it is not guaranteed that the agent will prompt for the information if it is not necessary or helpful for the conversation flow.
Dev Platform Apps
Within this section, you have the option to select one or more App Actions from any application that is enabled in your Capacity organization. These apps can be enabled in the App Center.
It is general best practice not to overload an agent tools/app actions. Similar to data sources, you want to ensure that you are only providing the agent access to actions and endpoints that are relevant and necessary for the agent's purpose.
To select an app action, you can click on the Add button to pull up a modal that will allow you to search and select the app actions you want to make available to the agent.
After selecting the app actions, you will have the option to see the specific inputs and outputs for each action.
Any required inputs will be collected by the agent automatically at the time it chooses to use the app action. This view can also help you understand what information will be captured as outputs in your conversation.
Resolutions
Resolutions are what we use to determine how to classify an outcome of a conversation. Within the AI Agent card, we allow you to define instructions for multiple resolution types - giving the agent the ability to assign the appropriate resolution based off of your instructions. Pro-tip: Provide clear instructions that have specifics to improve the accuracy in which the agent assigns the resolutions.
For more helpful information, please visit: