---
title: Citations
excerpt: ''
deprecated: false
hidden: false
metadata:
  title: ''
  description: ''
  robots: index
next:
  description: ''
---
> ⚠️ _Citations only work in Compound Actions_
>
> _You will need to add a compound action to your Conversation Process if you would like to be able to return citations in your plugin_

# What are citations?

[Citations](/docs/lifecycle-of-an-utterance#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.

![](https://files.readme.io/8e1ee535519e460682f3e6a2cb3a30d375756072e2dc4a2480f954f2b1eb8be6-CleanShot_2024-12-11_at_17.58.142x.png)

![](https://files.readme.io/ed2c851ba71e90cb4c3b7bf56b3b0b8e39178f3c71340cc069a1a56229692535-CleanShot_2024-12-11_at_18.04.172x.png)

# Configuring Citations

Citations are automatically created from the `return` statement in your [Compound Action](/docs/compound-actions) or output mappers in a [Conversation Process](/docs/plugin-process). You have two options:

## 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:

```yaml Compound Action
steps:
  - action:
      action_name: get_company_info
      output_key: action_result
      input_args:
        company_id: data.company_id
  - return:
      output_mapper:
        result:
          MERGE():
            - data.action_result
            - id: data.action_result.system_id
              friendly_id: data.action_result.name
```

Say the output of `action_result` was:

```json
{
  "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
  "name": "Pied Piper Inc.",
  "state": "California",
  "num_employees": 4000
}
```

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

```json
{
  "result": {
    "id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
    "friendly_id": "Pied Piper Inc.",
    "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
    "name": "Pied Piper Inc.",
    "state": "California",
    "num_employees": 4000
  }
}
```

## 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

```yaml Compound Action
steps:
  - action:
      action_name: get_company_list
      output_key: action_result
      input_args:
        region: data.region
  - return:
      output_mapper:
        results:
          MAP():
            converter:
              MERGE():
                - item
                - id: item.system_id
                  friendly_id: item.name
            items: data.action_result.list_of_records
```

#### Output without Citation

```json
{
  "list_of_records": [
    {
      "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
      "name": "Pied Piper Inc.",
      "state": "California",
      "num_employees": 4000
    },
    {
      "system_id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
      "name": "Dunder Mifflin",
      "state": "New York",
      "num_employees": 8500
    }
  ]
}
```

#### Output with Citation

```json
{
  "results": [
    {
      "id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
      "friendly_id": "Pied Piper Inc.",
      "system_id": "86b7657c-10b1-4a2e-b85c-be1f590dd89d",
      "name": "Pied Piper Inc.",
      "state": "California",
      "num_employees": 4000
    },
    {
      "id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
      "friendly_id": "Dunder Mifflin",
      "system_id": "df2cdf0f-0dff-4c82-a142-787661ef67b1",
      "name": "Dunder Mifflin",
      "state": "New York",
      "num_employees": 8500
    }
  ]
}
```

# 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](/docs/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

```yaml
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

```yaml
result:
	id: data.action_result.system_id  # Use unique ID like "TASK-17431"
  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.