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
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: falseUse 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.
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"
}