What are citations?

Citations present users with verifiable information when an AI agent responds. These greatly improve user trust in your AI agents and we highly recommend using citations whenever your plugins return data.

1. Citations "anchor" to a human-friendly "id" that references an object returned by your plugin (in this case "Ritwik Raj" is the friendly ID and has a (1) superscript next to it)
2. Citations show up in the conversation experience for an inline verification of the business object (in this case a User card)

3. Citations show up in the reference pop-up with full details.

How do I return citations for my plugins?

Return Statements

Citations are automatically created from the return statement in your Compound Action. You have two options:

1. Return a list of objects - Here you should return a list of objects under the results key
   JSON

   {
     "results": [
       {
         "id": "1",
         "friendly_id": "TASK-001",
         "task_title": "Write design document"
       },
       {
         "id": "2",
         "friendly_id": "TASK-002",
         "task_title": "Implement prototype"
       }
     ]
   }
   

2. Return a single object - Here you should return a single object under the result key.
   JSON

   {
     "result": {
         "id": "1",
         "friendly_id": "TASK-001",
         "task_title": "Write design document"
     }
   }
   

Citation Object Schema

Your citation objects must also conform to a specific schema:

• Each object MUST have a string-based id
• The id for EACH object in a list of objects must be unique.
• Each object MAY have a friendly_id (optional).

Examples

Returning a single object

steps:
- action:
		output_key: action_result
    ...
    
- return:
  	output_mapper:
    	result:
      	MERGE():
        	- data.action_result

	        - id: data.action_result.system_id
  	        friendly_id: data.action_result.name

In this example, we got back some data in action_result, but say that it looked like this:

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

We need to make sure that an id and friendly_id exist, so we tell the MERGE operation to combine the raw action_result (line 10) with a new dictionary that matches the citation schema (lines 12 & 13). The resulting return statement produces the following payload that meets the requirements for a citation.

{
  "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,
  ...
}

You can learn more about our data mapper language here.

Returning a list of objects

This excerpt behaves very similarly to the previous example. The only different is that it has a MAP() function that applies the MERGE() builder to a list_of_records

return:
  output_mapper:
    results:
      MAP():
        converter:
          MERGE():
            - item
            - id: item.system_id
              friendly_id: item.name
        items: data.action_result.list_of_records

So in this case, the following payload

{
  "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,
      ...
    }
	]
}

Turns into this

{
  "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

My citation isn't appearing

If you do not satisfy the citation object schema above, all data under the result or results key will be deleted from the plugin response.