Version: latest

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.

In Skill definitions, parameters define the required structure of the Skill's inputs and outputs.
In type definitions, parameters specify the type's structure.

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

A parameter object that is a list of ordered parameters.
A reference object that points to a predefined type definition.

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

caution

Type parameter names must be unique for the schema (e.g. You cannot have two parameters called “name”)

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

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

Use the CLI to save your type to Cortex:

cortex types save --yaml sample_type.yaml

Save a type defined with JSON

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
    }
  ]
}

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 Name	Type	Format	Comments
integer	`integer`	`int32`	signed 32 bits
long	`integer`	`int64`	signed 64 bits
float	`number`	`float`
double	`number`	`double`
string	`string`
byte	`string`	`byte`	base64 encoded characters
binary	`string`	`binary`	any sequence of octets
boolean	`boolean`
date	`string`	`date`	As defined by `full-date` - RFC3339
dateTime	`string`	`date-time`	As defined by `date-time` - RFC3339
object	`object`		embedded/nested object
array	`array`	A valid type	embedded/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:

Get a list of Types created for your project.
```
cortex types list --project myProject
```

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.

Attribute	Type	Description
`activationId`	string	The ID of the Agent execution that activated the Skill.
`sessionId`	string	Identifies the session store used for the Skill's invocation.
`channelId`	string	The unique ID of the Skill that sends the message to the action.
`snapshotId`	string	The unique Identifier generated during snapshot creation for the Agent BOM that is packaged for export.
`timestamp`	integer	The time at which the input message was created.
`token`	string	The JWT token associated with the account that initiated the input action.
`apiEndpoint`	string	The base URL of the Cortex instance in which the Skill is deployed.
`properties`	array	The configured properties defined for the Skill. It is an array of name-value pairs.
`payload`	any valid JSON	The message body submitted as the input to the Skill. It can be any valid JSON.
`projectId`	string	Identifies the Project where the service is implemented
`agentName`	string	The name of the Agent where the service is implemented
`skillName`	string	The name of the Skill that the service inputs to
`outputName`	string	The name of the output that can be referenced for input routing to other Agents.
`headers`	string	Provides 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"
}

Parameters definition​

Type definitions​

Save a type defined with YAML file​

Save a type defined with JSON​

Types CAMEL reference​

Formats defined by the CAMEL specification​

Types Examples​

Delete Types​

Input message schema​