Version: 6.3.3

Service Messages and Types

This is a guide to defining Service Messages, which are the structured inputs to and outputs from Skills.

Cortex messages are the structured inputs to and outputs from Agents; they are:

  • Consumed and produced by Skills
  • Consumed and produced by Agents

Each message that flows through Cortex has a defined structure that has an ordered, paired list of parameter names and their data types. A data type can be, for example, an integer, string, number, boolean, array, etc. A parameter's data type may be further constrained by a format. For example, a string field may have a format of date, meaning it is an RFC3339 full-date.

For more information about the supported types and formats, see the Data Types section of the CAMEL reference.

Parameters definition

Every Skill and type definition in Cortex includes a parameters section that defines the message structure for that component.

There are two ways to define a component's parameters:

The example below shows parameters defined with a parameter object that includes three parameters.

parameters:
- name: doc_1
type: string
description: Document 1
required: true
- name: doc_2
type: string
description: Document 2
required: true
- name: timestamp
description: Request time
type: integer
format: int64
required: false

Alternatively, parameters can point to another type definition using a reference object, as shown below.

parameters:
$ref: cortex/DocStrings

To use a $ref type, the specified type definition must also be saved in the account.

Type definitions

When you save a type using the steps described in this section, the type can be used as a reference structure in Skills. Saved types are also available during Agent creation. For example, when defining a service, any types saved in your account may be selected from the Optional Message Type dropdown to provide a template for the input or output message structure.

Use the CLI to save your custom types. Type definitions can be created using either YAML or JSON. When you create a type, it is available to all users in your account.

Save a type defined with YAML file

  1. Create and save your type as a YAML file.

    sample_type.yaml:

    name: cortex/TextDoc
    camel: 1.0.0
    title: Text Document
    description: Represents a document that contains a title, text, and timestamp.
    parameters:
    - name: title
    type: string
    required: true
    - name: text
    type: string
    required: false
    - name: timestamp
    type: integer
    format: int64
    required: false
  2. Use the CLI to save your type to Cortex:

    cortex types save --yaml sample_type.yaml

Save a type defined with JSON

  1. Create and save your type as a JSON file.

    sample_type.json:

    {
    "name": "cortex/TextDoc",
    "camel": "1.0.0",
    "title": "Text Document",
    "description": "Represents a document that contains a title, text, and timestamp.",
    "parameters": [
    {
    "name": "title",
    "type": "string",
    "required": true
    },
    {
    "name": "text",
    "type": "string",
    "required": false
    },
    {
    "name": "timestamp",
    "type": "integer",
    "format": "int64",
    "required": false
    }
    ]
    }
  2. Use the CLI to save your type to Cortex.

    cortex types save sample_type.json

Types CAMEL reference

Primitive data types in CAMEL are based on the types supported by the JSON Schema Specification. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. Using null as a type is not supported. Data types are defined using the Parameters, which is an extended subset of JSON Schema Specification Wright Draft 00.

Primitives have an optional modifier property: `format`. CAMEL uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.

Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.

Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

Formats defined by the CAMEL specification

Common NameTypeFormatComments
integerintegerint32signed 32 bits
longintegerint64signed 64 bits
floatnumberfloat
doublenumberdouble
stringstring
bytestringbytebase64 encoded characters
binarystringbinaryany sequence of octets
booleanboolean
datestringdateAs defined by full-date - RFC3339
dateTimestringdate-timeAs defined by date-time - RFC3339
objectobjectembedded/nested object
arrayarrayA valid typeembedded/nested array

Types Examples

An integer

{
"type": "integer"
}

A double

{
"type": "number",
"format": "double"
}

A base64 encoded binary

{
"type": "string",
"format": "byte"
}

A date-time string

{
"type": "string",
"format": "date-time"
}

Embedded object

{
"type": "object"
}

Embedded array of numbers

{
"type": "array",
"format": "number"
}

Delete Types

Deleting Types is a protected action in Cortex. When you run the delete command an Impact Assessment is run, and if downstream dependencies are found, the deletion is not allowed, and the resources using that Type are listed. You must remove dependencies to unblock the delete action.

To delete Types using the CLI:

  1. Get a list of Types created for your project.

    cortex types list --project myProject
  2. Delete a type.

    cortex types delete typeName --project myProject

    Response: (When there are no downstream impacts)

    {
    "success": true,
    "message": "type typeName deleted"
    }

Input message schema

Whether you route a Skill's input to a daemon, job, or API, the input message structure sent to the action is always the same.

Daemon and Job actions must be able to parse the input received from a Skill as needed. Actions can also optionally produce outputs to return to Cortex.

The following table describes the full schema of an input message.

AttributeTypeDescription
activationIdstringThe ID of the Agent execution that activated the Skill.
sessionIdstringIdentifies the session store used for the Skill's invocation.
channelIdstringThe unique ID of the Skill that sends the message to the action.
snapshotIdstringThe unique Identifier generated during snapshot creation for the Agent BOM that is packaged for export.
timestampintegerThe time at which the input message was created.
tokenstringThe JWT token associated with the account that initiated the input action.
apiEndpointstringThe base URL of the Cortex instance in which the Skill is deployed.
propertiesarrayThe configured properties defined for the Skill. It is an array of name-value pairs.
payloadany valid JSONThe message body submitted as the input to the Skill. It can be any valid JSON.
projectIdstringIdentifies the Project where the service is implemented
agentNamestringThe name of the Agent where the service is implemented
skillNamestringThe name of the Skill that the service inputs to
outputNamestringThe name of the output that can be referenced for input routing to other Agents.
headersstringProvides the metadata for external api requests/responses made by the Agent to connect to other Agents or applications.

EXAMPLE

The snippet below shows input messages passed to a job Skill.

{
"activationId": "2b50ad7b-35c1-4eb1-b002-05961838726b",
"agentName": "myAgent",
"apiEndpoint": "http://cortex-internal.cortex.svc.cluster.local",
"channelId": "output",
"outputName": "output1",
"payload": {
"text": "yolo"
},
"projectId": "myProject",
"properties": {},
"sessionId": "2b50ad7b-35c1-4eb1-b002-05961838726b",
"skillName": "job1",
"timestamp": 1651683031034,
"token": "xxx"
}