Invoke Agents

This is a guide to running Agents and services in a development cluster.

When you invoke an Agent, you are executing the services and Skills in the pattern or flow you have configured for that Agent. To cache data or share data between Skills or Agents in Fabric use Sessions.

Payload Considerations

View Invoke Skills: Payload Considerations.

List and describe Agents

You can view a list of Agents in the Fabric Console by authenticating, selecting your project, and clicking Agents in the left menu.

You can also get a list of Agents using the CLI. Authenticate to the CLI with or without a project context. If you authenticate without a project run:

cortex agents list --project project-name

A list of Agents that have been developed for your project is returned:

┌───────────────────┬────────────────────┬────────────────┬─────────────┬───────────────┐
│ Name              │ Title              │ Description    │ Modified    │    Author     │
├───────────────────┼────────────────────┼────────────────┼─────────────┼───────────────┤
│ default/test123   │ test123            │ -              │ 2 days ago  │ swinchester   │
├───────────────────┼────────────────────┼────────────────┼─────────────┼───────────────┤
│ sparkbatchpredict │ sparkbatchpredict  │ -              │ 4 weeks ago │   bsinger     │
├───────────────────┼────────────────────┼────────────────┼─────────────┼───────────────┤

To view the details of an Agent record including the metadata, input services, output services, skills, mapping, and properties in the Console, you can click on the name of an Agent to open the Agent Composer view. Click anywhere in the grid that is NOT designated as a Skill to display the Agent details in the Properties pane at the far right.

To view the Agent details as JSON using the CLI run the following command:

cortex agents describe sparkbatchpredict --project project-name

This returns the following detail about the Agent named in the command, including metadata, inputs (parameters and routing to the agent), outputs, properties, tags, and actions:

{
  "camel": "1.0.0",
  "name": "spark-batch-predict",
  "title": "Spark Batch Predict",
  "description": "Spark bulk batch prediction skill",
  "inputs": [
    {
      "name": "params",
      "title": "input",
      "parameters": {
        "$ref": "BulkBatchRequest"
      },
      "routing": {
        "all": {
          "action": "spark-batch-predict",
          "runtime": "cortex/jobs",
          "output": "response"
        }
      }
    }
  ],
  "outputs": [
    {
      "name": "response",
      "title": "Job result",
      "parameters": {
        "$ref": "BulkBatchResponse"
      }
    }
  ],
  "properties": [
    {
      "validValues": [],
      "name": "connection-name",
      "title": "Connection Name",
      "description": "Connection is used to read and write files.",
      "required": false,
      "type": "string",
      "secure": false,
      "defaultValue": "spark-s3-conn"
    },
    {
      "validValues": [],
      "name": "experiment-name",
      "title": "Experiment Name",
      "description": "Experiment name to retrieve experiment details",
      "required": false,
      "type": "string",
      "secure": false,
      "defaultValue": "sv_experiment"
    },
    {
      "validValues": [],
      "name": "run-id",
      "title": "Run ID",
      "description": "Run id of the experiment",
      "required": true,
      "type": "string",
      "secure": false
    },
    {
      "validValues": [],
      "name": "aws-secret",
      "title": "AWS Secret",
      "description": "AWS Secret",
      "required": false,
      "type": "string",
      "secure": true
    },
    {
      "validValues": [],
      "name": "mongo-uri",
      "title": "Mongo URI",
      "description": "Mongo URI for Input dataset",
      "required": false,
      "type": "string",
      "secure": true
    },
    {
      "validValues": [],
      "name": "output-path",
      "title": "S3 Output path",
      "description": "Output S3 path to save the predictions",
      "required": false,
      "type": "string",
      "secure": false
    },
    {
      "validValues": [],
      "name": "output-collection",
      "title": "Mongo Output collection",
      "description": "Output collection to save the predictions",
      "required": false,
      "type": "string",
      "secure": false
    },
    {
      "validValues": [],
      "name": "outcome",
      "title": "Prediction class or label",
      "description": "Prediction class or label in the dataset",
      "required": false,
      "type": "string",
      "secure": false
    }
  ],
  "tags": [
    {
      "label": "template",
      "value": "template"
    }
  ],
  "actions": []
}

To view additional systems details (for backward compatibility) you can append the command with --verbose.

List Agent services

Services provide a way to send data to and retrieve data from Agents. When you invoke an Agent you are essentially starting an input service message.

To invoke an Agent you begin by listing input services associated with a specific Agent, including each service's endpoint. Then that endpoint can be called via the API.

The list-services command provides users with a complete view of which services inside the Agent can be invoked.

To list an Agent's services, use the following command:

cortex agents list-services <agent-name>

Cortex responds with the name of the service and that service's Endpoint URL.

Example list-services query and response:

cortex agents list-services sucess-job-agent

┌───────────────┬─────────────────────────────────────────────┬─────────────────────────────────┐
│ Service Name  │ Service Endpoint URL                        │ Parameters                      │
├───────────────┼─────────────────────────────────────────────┼─────────────────────────────────┤
│ input         │ https://api.dci-dev.../...sucess-job-agent… │ -Name: text, Type: string       │
└───────────────┴─────────────────────────────────────────────┴─────────────────────────────────┘

Optional command parameters:

Parameter	Description
--profile [profile]	The profile to use.
--project	the Project under which the Agent resides
--json	Output results using JSON.
--query [query]	A JMESPath query to use in filtering the response data.

JSON output

The list-services command can also output service details in JSON. To output service details in JSON, use the following command:

cortex agents list-services <agent-name> --json

Cortex responds with more detailed information for each service, including the signalID, parameters, and outputs:

[
  {
    "signalType": "Service",
    "name": "text-service",
    "title": "text-input",
    "signalId": "0b4577a2-3b51-4e53-9ee9-89a13bc0ef73",
    "parameters": [
      {
        "name": "text",
        "required": true,
        "title": "text",
        "type": "string"
      }
    ],
    "output": "text-service",
    "url": "https://api.<dci-base-domain>/v3/agents/promote-agent-aks/echo-agent/services/text-service"
  }
]

Get service names - CLI

The --json response can be filtered using the --query parameter:

cortex agents list-services default/trading-insights-agent --json --query [*].name

In this example, Cortex responds with a JSON string of each service's name inside the Agent:

[
  "generate-insights",
  "training-status",
  "view-insights",
  "feedback"
]

Alternatively you can run the agents describe command as follows:

cortex agents describe <agent-name>

The sources array returned includes all input and output services added to the Agent.

Get Service names - Fabric Console

1. Log in to the Fabric Console and select your Project.
2. Click Agents in the left navigation panel.
3. Click the link on the name of Agent in the list view.
4. In the Agent Composer view go to the Inputs panel at the top left. Click the Input name to display the Service details in the Properties panel on the far right.
5. The service name is listed as the header.

Invoke an Agent

Agents can be invoked from either the CLI or by making direct REST API calls. Regardless of which you choose, the general process is the same:

• Submit a request to invoke the Agent/Service. At a minimum the request must identify the input service to which the payload is submitted. Service invocations are asynchronous requests.
• The response includes an activationId that identifies the request.
• Use the activationId to get the results.

note

Only the latest version of an Agent may be invoked.

You cannot invoke a snapshot or specific Agent version in the development environment. Snapshots may be used to capture Agent versions and push a bill-of-materials to another environment using the FabricOps tool.

Agent-invoke statuses

• PENDING
• COMPLETE
• ERROR

Invoke agent command

cortex agents invoke <agent-name> <input-service-name> {payload}

Invocation parameters

Parameter	Description	Type
agentName	The name of the Agent being invoked.	String
inputServiceName	The name of the input service being invoked	String
payload	(optional) The payload to submit to the service when invoking the Agent. Includes any properties that can be passed in as key value pairs, expressed as JSON.	{ }
correlationId	An optional parameter that when specified can be used to group activations for analysis or troubleshooting or to enable one Agent to call another	{ }
sync	Set the sync flag to true to invoke the Skills in the Agent synchronously; by default Agents run Skills asynchronously for optimal performance. NOTE: Only daemons can be run synchronously	boolean (set to true by adding --sync to command string)

Simple Agent invoke command and response example:

cortex agents invoke my-agent my-service

{
  "success": true,
  "activationId": "d873f7e7-6646-4e45-bb9b-xxxx"
}

Agent invoke with properties and parameters:

cortex agents invoke my-agent my-service --params '{"payload": {"text": "test"}, "properties": {"secure-name": "ref-key"}}' --project my-project

The Agent runtime kicked off by invoking the Agent results in a status, logs, and activations.

The activation provides access to the predictive insights that are used by external applications.

You can access a list of activations in the Fabric Console or using the CLI.

Invoking Agents synchronously

You may opt to invoke an Agent with Skills that contain daemon actions to run synchronously to observe the performance or output of individual Skills in the Agent.

note

ONLY Skills of type Daemon can be invoked synchronously.

To run an Agent synchronously add the --sync flag to the cortex agents invoke command.

EXAMPLE

cortex agents invoke my-agent my-service --params '{"payload": {"text": "test"}, "properties": {"secure-name": "ref-key"}}' --sync --project my-project

note

Invoking Agents synchronously adversely affects performance.

Invoke using a JSON file

In this example, the parameters are defined in a separate JSON file.

First, create a params file that specifies the agentName and inputSeviceName to invoke; include the payload to submit when invoking the Agent service if there is one defined.

Example invoke_payload.json:

{
  "agentName": "sucess-job-agent",
  "inputServiceName": "input",
   "payload":{
      "text":"This is a test."
   }
   "properties":{
     "secure-name":"ref-key"
   }
}

Then, invoke the Agent using the invoke_payload. Pass in the Agent name, the name of the service to invoke (input in the example below), and a path to the params file to use when invoking the Agent.

cortex agents invoke sucess-job-agent input \
--params-file /path/to/invoke_payload.json

The response is that same as when you invoke using the CLI.

Use Secrets

Agents may use secrets which are expressed as properties as in the examples above. Secrets are configured in the Console or CLI.

To call a secret at runtime the secret must be applied to the Skill either by selecting the secret value in the Skill property panel in the Agent Composer and by adding the property to the skill.yaml.

Send Message Agent

Agent and Skill logs

You can view the runtime logs of Agents and Skills. See the details about how to view logs on the Skill and Agent Logs page.