Basics

Modify your agent's output easily with skills and actions

The Carter Object can detect custom triggers which are returned with the CarterAPI response. You can combine these with carter-js skills in order to customise the output.

It begins with registering a skill with your Carter Object. A skill contains a name, action, and some options. The name must match the name of your custom trigger in the Carter dashboard. The action is a function which takes in data from your custom trigger and the initial CarterAPI response, and allows you to return a new output. It looks something like this:

// already created a CarterObject called carter

const options = {
    auto: true
}

carter.registerSkill("Weather Request", (response, metadata, entities) => {
    // Do whatever you like here
    return CarterSkillOutput
}, options)

registerSkill() accepts an action function. An action allows you to modify the output based on this information and any code you run inside it. An action MUST take in three parameters as carter-js will call this function with all three parameters behind the scenes. response is the initial output text from CarterAPI. metadata is the metadata you have defined in your custom trigger on the CarterAPI dashboard. entities are any entities detected by CarterAPI. Both metadata and entities may be undefined depending on how your custom trigger is set up and if CarterAPI has detected any entities.

If your action doesn't modify your agent's output then you need not return anything from this function. If you would like your action to modify the agent's output then you can return a SkillOutput object.

CarterSkillOutput {
    output: string, // the new agent output text
    skillData: any // custom data you can access from inside the triggered skills array
}

How your return affects the interaction output depends on whether your skill is an automatic skill or not.

Skill Options

You can pass currently pass one option when you register a skill.

auto

A carter skill can be either automatic or manual. Manual is the default, if you wish to make it automatic you must set auto to true when you register the skill.

By default, when a trigger is detected the corresponding skill is returned with the interaction response. These skills are added to the interaction.triggeredSkills array. The output text and audio link remain the same. If you wish to execute the skill and retreive the modified output you can call await skill.execute() on that skill and the new response text will be returned. The text and audio link in interaction.data.output will remain the same.

When auto is set to true, the skill will be executed automatically when detected and interaction.data.output will be modified. The skill will then be added to the interaction.executedSkills array.