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, you can provide guidance on how the agent should use the app actions available to it - for example, describing the sequence in which tools should be called, or which tool to use for which purpose. This is useful when the order of tool calls matters or when the agent needs additional context to determine which action to invoke.

That said, much of what previously required prompt instructions for app actions can now be configured directly in the UI. When adding an app action to the agent card, you can specify exactly how each input should be populated using one of three modes:

Agent determines inputs (default) - The agent dynamically determines what to pass to each input and collects required data as needed. This is the default behavior and requires no additional configuration.
Hard-coded value - A fixed value is set directly on the input. The agent always uses that value regardless of the conversation.
Insert a previously collected variable - A variable collected earlier in the Guided Conversation flow is explicitly mapped to the input. The agent uses that variable directly rather than determining it dynamically.

Using the hard-coded value or variable mapping modes removes the need to write prompt instructions for that purpose, which keeps prompts shorter and makes the behavior more explicit and reliable.

Prompt-level tool guidance is still useful for sequencing and intent - for example, describing which tool to call first or what the agent should do with the result. But for controlling what gets passed to a specific input, the UI configuration is the preferred approach.

Example (sequencing guidance, appropriate for the prompt): "Call 'get-hair-salon-services' first to retrieve service options. Once the user has selected a service, call 'get-hair-salon-availability' to find available times."

Example (input mapping, use UI instead of prompt): Rather than writing "use the account number the user provided as the input to 'lookup-account'," map that variable directly to the input field on the app action in the Dev Platform Apps section of the card.

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.

Exit Conditions

The Exit Conditions field tells the AI Agent when it should end the conversation and hand off to the next step in the Guided Conversation flow. It appears on the AI Agent card directly below the main Prompt field.

The field is pre-populated with a default prompt that instructs the agent to exit when the user's intent has been resolved or they indicate they want to stop. You can edit or replace this default at any time. A Reset to default link below the field restores the original default prompt if needed.

The LLM evaluates the Exit Conditions on each turn and responds with exactly true to exit the conversation, or false to continue. This is a binary contract - the field should be written as an instruction that the model can evaluate to one of those two outcomes.

Exit Conditions support Guided Conversation variable substitution using the same {{variable_name}} syntax as the main Prompt field. This allows exit logic to reference data collected earlier in the flow.

Tips for Writing Exit Conditions

Be specific about what "resolved" means for your use case. The default is intentionally broad - if your agent has a narrow objective, tighten the exit condition to match.
If the agent handles multiple distinct tasks, describe the completion state for each so the agent exits at the right time regardless of which path the conversation took.
Avoid writing exit conditions that could trigger prematurely - for example, exiting as soon as any question is answered, when the agent's goal is to handle multiple questions in a session.

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

Provide a clear, specific description for each variable. The agent uses this description to identify and collect the correct information - vague descriptions lead to inaccurate collection.
Variable names must start with a letter and can only contain lowercase letters and underscores (e.g., first_name).
Mark a variable as Required only when you genuinely need that information outside the agent card. Required variables are collected upfront, before the agent progresses through other objectives. Overusing required variables disrupts natural conversation flow.
You do not need to define variables for data that app actions will collect on their own. If an app action requires a specific piece of information to execute, the agent will collect it automatically at the time the action is called. Defining a required variable in this section for the same purpose is redundant and can interfere with the natural collection flow.
For cases where you want a specific variable to be passed as input to an app action, use the variable mapping mode directly on the app action input in the Dev Platform Apps section rather than writing prompt instructions or defining an extra variable here. See the Dev Platform Apps section below for details.
Optional variables will be collected as the conversation progresses, but are not guaranteed to be collected if the conversation does not naturally require them.

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.

Controlling App Action Inputs

By default, the agent determines what to pass to each app action input dynamically based on the conversation. You can also take direct control of specific inputs using the configuration options on each input field:

Agent determines inputs (default) - The agent collects and passes the appropriate value based on the conversation. No additional configuration needed.
Hard-coded value - Set a fixed value directly on the input. The agent will always use that exact value when calling this action, regardless of what was said in the conversation.
Insert a previously collected variable - Map a variable collected earlier in the Guided Conversation flow directly to this input. The agent uses that variable's value rather than determining it dynamically.

Using hard-coded values or variable mapping for specific inputs removes the need to write prompt instructions for that purpose. This makes the behavior more reliable, easier to audit, and keeps the prompt focused on higher-level guidance.

Note: If a field is left empty when a manual input mode is active, the agent will still attempt to populate it. Confirm the expected behavior through testing when using these modes.

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:

Was this article helpful?