Sessions

This is a guide to using Sessions when invoking Agents.

Sessions are used to:

• Cache data between agents or activations
• Pass data between skills within an activation

When an Agent is invoked a Session is automatically created. By default the activationId is saved as the sessionId.

Optionally, you may assign a sessionId when you invoke the Agent. The sessionsId is passed in as a parameter.

The sessionId is passed to all Skills in the Agent during execution. The sessionId is available as part of the activation record.

A sessionId is passed to another activation, Agent, or Skill in the same project.

Sessions are managed using the Python Library in an IDE of your choice or by directly calling the Cortex v6: Sessions API methods. (NOTE: There is no CLI or Console component for managing sessions.)

How to Use Sessions - Overview

How to use Sessions:

1. Create a session in your IDE using the Python library method (or pass a SessionId as a property in the Agent invoke CLI command).

   start_session(ttl=None,  description='No description given') → str

2. Invoke the agent. The sessionId is returned.

   cortex agents get-activation '9f2127d7-7832-45c4-b755-xxxx'

   Response

   {
   "success": true,
   "requestId": "aaf60796-c8e2-4557-963e-xxxx",
   "agentName": "splitter",
   "inputServiceName": "input",
   "sessionId": "aaf60796-c8e2-4557-963e-xxxx",
   "projectId": "test-1",
   "username": "cortex@example.com",
   "payload": {
     "number": 6
   },
   "start": 1618946201383,
   "status": "COMPLETE",
   "response": "{\"wrote\":\"ModelEven Even 6\"}",
   "end": 1618946201532
   }

3. Pass the sessionId to all the invokes for the agent to share the data.

   cortex agents invoke default/splitter predict --params '{“sessionId”:“ses1”, "payload":{"users":[1,2,3,4,5,6]}}'

Use Sessions CLI

Create sessions

To create a session save a session.json file locally.

Session.json file example:

{
"sessionId": "unique id",
"ttl": 1000,
"description": "Session Description"
}

Where: sessionId is a human readable label for session description is the description of session for listing ttl is the number of seconds that session keys persist

Then run the following command to save the session to Fabric.

cortex sessions save </local/file.json> --project myProject

Now you can pass the sessionId while invoking Agents or Skills for caching.

List Sessions

Run the following CLI command to view a list of sessions that have been created.

cortex sessions list --project myProjet

Response

┌────────────────────┬────────────┬───────────────────────────────────────┐
│ Session ID         │ TTL        │ Description                           │
├────────────────────┼────────────┼───────────────────────────────────────┤
│ mySession1234      │ 1000       │ for skill one                         │
├────────────────────┼────────────┼───────────────────────────────────────┤
│ mySession222       │ 1200       │ for mySkill                           │
├────────────────────┼────────────┼───────────────────────────────────────┤
│ Session67          │ 36000      │ Skills in myAgent                     │
└────────────────────┴────────────┴───────────────────────────────────────┘

View Session Details

To view the details of a Session run the following command:

cortex sessions describe <sessionId> --project myProject

Where: sessionId is the human readable identifier for the session whose details you wish to view.

{
  "success": true,
  "state": {},
  "description": "for skills one",
  "ttl": 1000
}

Delete sessions

To delete a session run the following command, specifying the identifier for the session you want to delete.

cortex sessions delete <sessionId>

A success message is displayed as the response.

Use Sessions: Python Library

Client for the Cortex Sessions API: cortex.session.SessionClient

Prerequisites: Python Library

From your IDE:

1. Import Cortex-Python library

   from cortex import Cortex

2. Create the Cortex client context

   client = Cortex.client()

   Pass in Project ID, auth token, and apiEndpoint. (comma delimited):

   (e.g. cortex_client = Cortex.client(project=input_msg.projectId, token=input_msg.token, api_endpoint=apiEndpoint))

   Token can be obtained following the instructions in Access API.

Create Sessions

Sessions are automatically created when an Agent is invoked. You can also manually create a session with a specified ttl and human readable description using the following method.

To start a new session with a set ttl run:

start_session(ttl=None, description='No description given') → str

Parameters

• ttl – Resets sessions expiration; default is 15 minutes. TTL applies to all keys in a session, if a TTL is defined.
• description – An optional human readable description for the session

Returns

The new sessionId.

View Session Details

To view session details for a specified session run:

get_session_data(session_id, key=None) → Dict[str, object]

Parameters

• session_id (activation_id) – The ID of the session to query.
• key – An optional key in the session memory; the entire session memory is returned if a key is not specified.

Returns

A dict (a Python key-value store) containing the requested session data.

Share Data

To share session data from one session to another activation, agent or skill run:

put_session_data(session_id, data: Dict)

note

You cannot update a session TTL or description using this method. You must create a new session to update these properties.

Parameters:

• session_id (activation_id) – The identifier of the session to update.
• data – Dict (Python key-value store) containing the new session keys to set

Return

Success/Failure message

Delete Sessions

To delete a specified session:

delete_session(session_id)

Parameters

• session_id (activation_id) – The identifier of the session to delete.

Returns

Success/Failure message

Use Sessions: API

Sessions can also be run from the SENSA Fabric OpenAPI.

Authenticate to the API and refer to the Cortex V6: Sessions API specification.

Example: Create Session

$ curl -i -H "Authorization: bearer $CORTEX_TOKEN" -H "content-type: application/json" $(~/projects/cortex6/cortex-local/kubernetes/geturl.sh)/fabric/v4/projects/johan/sessions -d '{"description": "ttl test", "ttl": 100}'
HTTP/2 200
x-dns-prefetch-control: off
x-frame-options: SAMEORIGIN
strict-transport-security: max-age=15552000; includeSubDomains
x-download-options: noopen
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
access-control-allow-origin: *
server: istio-envoy
content-type: application/json
date: Mon, 15 Mar 2021 22:12:35 GMT
content-length: 145
x-envoy-upstream-service-time: 16

Response

{"success":true,"sessionId":"b490f7d1-ec49-42fb-8839-xxxx","message":"Session b490f7d1-ec49-42fb-8839-xxxx created successfully"}%