Basics

Modify your agent's output easily with skills and actions

PLEASE NOTE: This feature is currently in beta. This is due to it being untested and the changing nature of this feature on the Carter API end. Please report any issues through a GitHub issue.

The Carter Object can detect forced behaviours which are returned with the Carter API 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 the response 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 skill = {
    name: "weather",
    action: (response) => { // THis function will be called with async by carter-js
        return {"This is my altered response with weather api data"}
    },
    auto: true
}

    // Do whatever you like here
    return CarterSkillOutput(skill)

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 the response parameter, as carter will call it with this parameter behind the scenes.. response is the initial output text from CarterAPI. You could combine this with the personalise feature to build completely custom api responses with your characters personality still at the forefront.

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, this is optional and can be anything
}

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 forced behaviour 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 retrieve 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.carterData.output will remain the same.

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