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.
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:
A list of Agents that have been developed for your project is returned:
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:
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:
To view additional systems details (for backward compatibility) you can append the command with
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.
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 responds with the name of the service and that service's
Example list-services query and response:
Optional command parameters:
|The profile to use.|
|the Project under which the Agent resides|
|Output results using JSON.|
|A JMESPath query to use in filtering the response data.|
list-services command can also output service details in JSON. To output service details in JSON, use the following command:
Cortex responds with more detailed information for each service, including the
Get service names - CLI
--json response can be filtered using the
In this example, Cortex responds with a JSON string of each service's name inside the Agent:
Alternatively you can run the
agents describe command as follows:
sources array returned includes all input and output services added to the Agent.
Get Service names - Fabric Console
- Log in to the Fabric Console and select your Project.
- Click Agents in the left navigation panel.
- Click the link on the name of Agent in the list view.
- 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.
- 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
activationIdthat identifies the request.
- Use the
activationIdto get the results.
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.
Invoke agent command
|The name of the Agent being invoked.||String|
|The name of the input service being invoked||String|
|(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.|
|An optional parameter that when specified can be used to group activations for analysis or troubleshooting or to enable one Agent to call another|
|Set the sync flag to |
NOTE: Only daemons can be run synchronously
|boolean (set to true by adding |
Simple Agent invoke command and response example:
Agent invoke with properties and parameters:
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.
ONLY Skills of type Daemon can be invoked synchronously.
To run an Agent synchronously add the
--sync flag to the
cortex agents invoke command.
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
inputSeviceName to invoke; include the
payload to submit when invoking the Agent service if there is one defined.
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.
The response is that same as when you invoke using the CLI.
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
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.