What are citations?

Citations enhance user trust by providing verifiable references to the data returned by AI agents. They consist of in-line verification links anchored to business objects (e.g., a User card or task record) displayed in the AI’s response. Citations are highly recommended whenever plugins return data to ensure transparency and reliability.

Key Benefits

• Trust: Links to source systems allow users to verify information.
• Clarity: Business objects are presented clearly, often as cards or clickable references.

Configuring Citations

Where you configure citations depends on whether your conversational process uses an Action or a Compound Action.

Actions vs. Compound Actions

Citation Object Schema

Each citation object must include:

• id (Required): A unique, string-based identifier for the business object.
• friendly_id(Optional): A human-readable string to describe the object.

Best Practices:

• Unique IDs: Ensure the id is unique to avoid anchoring to unintended parts of the Assistant’s response (e.g., avoid generic IDs like “1” that may appear elsewhere, such as in “1 hour”).
• Single Object per Citation: Each citation should represent one business object to prevent confusion.

Returning a Single Object

Use the result key to return a single citation object.

Example:

1
steps:
2
  - action:
3
      action_name: get_company_info
4
      output_key: action_result
5
      input_args:
6
        company_id: data.company_id
7
  - return:
8
      output_mapper:
9
        result:
10
          MERGE():
11
            - data.action_result
12
            - id: data.action_result.system_id
13
              friendly_id: data.action_result.name

Say the output of action_result was:

1
{
2
  "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
3
  "name": "Pied Piper Inc.",
4
  "state": "California",
5
  "num_employees": 4000
6
}

To meet the citation schema it requires the id and friendly_id and using the MERGE function allows us to do that.

Output with Citation

1
{
2
  "result": {
3
    "id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
4
    "friendly_id": "Pied Piper Inc.",
5
    "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
6
    "name": "Pied Piper Inc.",
7
    "state": "California",
8
    "num_employees": 4000
9
  }
10
}

Returning a List of Objects

Use the results key to return multiple citation objects, processed with the MAP function to apply the citation schema to each item.

Example

1
steps:
2
  - action:
3
      action_name: get_company_list
4
      output_key: action_result
5
      input_args:
6
        region: data.region
7
  - return:
8
      output_mapper:
9
        results:
10
          MAP():
11
            converter:
12
              MERGE():
13
                - item
14
                - id: item.system_id
15
                  friendly_id: item.name
16
            items: data.action_result.list_of_records

Output without Citation

1
{
2
  "list_of_records": [
3
    {
4
      "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
5
      "name": "Pied Piper Inc.",
6
      "state": "California",
7
      "num_employees": 4000
8
    },
9
    {
10
      "system_id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
11
      "name": "Dunder Mifflin",
12
      "state": "New York",
13
      "num_employees": 8500
14
    }
15
  ]
16
}

Output with Citation

1
{
2
  "results": [
3
    {
4
      "id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
5
      "friendly_id": "Pied Piper Inc.",
6
      "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
7
      "name": "Pied Piper Inc.",
8
      "state": "California",
9
      "num_employees": 4000
10
    },
11
    {
12
      "id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
13
      "friendly_id": "Dunder Mifflin",
14
      "system_id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
15
      "name": "Dunder Mifflin",
16
      "state": "New York",
17
      "num_employees": 8500
18
    }
19
  ]
20
}

Troubleshooting

Citation Not Appearing

• Incorrect Schema: Ensure each citation object includes a string-based id. If the schema is invalid, data under result or results will be removed from the response. Verify using the DSL and Mapper Playground.
• ID Not in Response: The AI anchors citations to verbatim instances of id or friendly_id in its response. If the ID (e.g., TOP_10_COMPANY_PALO_ALTO) appears elsewhere (e.g., “View the top 10 companies in Palo Alto”), the citation may fail. Add instructions in the Plugin Result Instructions or plugin description to include the id or friendly_id verbatim.

Example Fix

1
plugin_description: "Always include the task title ({data.task_info.title}) in the response."

Citation Anchoring to Wrong Item

• Non-Unique IDs: If the id or friendly_id is not unique (e.g., id: “1” appears in “1 hour” in the response), the citation may anchor incorrectly. Use specific, unique IDs (e.g., TASK-17431) to avoid conflicts.

Example Fix in Output Mapper

1
result:
2
	id: data.action_result.system_id  # Use unique ID like "TASK-17431"
3
  friendly_id: data.action_result.name

Best Practices

• Unique Identifiers: Choose id values that are unlikely to appear in the AI’s natural language response (e.g., UUIDs or prefixed IDs like TASK-123).
• Clear Friendly IDs: Use friendly_id values that are human-readable and descriptive (e.g., “Write Product Requirements” instead of “Task 1”).
• Single Object per Citation: Avoid creating multiple citations for the same business object to prevent user confusion.