Working with the Agents control API

Analytics API for agent control

IMPORTANT: When quering and changing configuration through the orchestration API it is highly recommended to use a dedicated service account for this task and not an individual user account. Agents use JWT tokens for authentication and these will expire if the user account is deleted.

Overview

The control and orchestration of Skylight sensor: agents is part of the Analytics cloud platform in this first release. This means that all control of agents are done using the same API credentials as for other Analytics services.
In a later release, it will be possible to deploy these orchestration services also on-prem for local access to the control API and metrics data streams.

API Documentation

All API functions are documented in the AgentServiceV3 section of the Skylight Analytics API, see API Documentation for more information.

API Structure and Objects

Each agent, once created and defined in the orchestration API, will be represented with a unique agent object in the system, referred to by its agentId.

Any agent-specific parameters for communication, localization, identification, etc. reside in this configuration block. The agent configuration typically doesn't change but is static for the full lifecycle of the agent once configured.

Each agent also has a status object that can be read through the API. On the status node, the agent reports current version, state, etc. that can be used to check for reachability of the agent.

The API syntax for retreiving these two blocks of information for an agent can be seen below.

Retreive agent status:

GET
https://my.tenant.io/api/orchestrate/v3/agents/<agentId>

Retreive agent configuration:

GET
https://my.tenant.io/api/orchestrate/v3/agents/configuration/<agentId>

Before an agent is deployed, an agent configuration needs to be created on the agent orchestrator. This is also a prerequisite for accessing the SSL secret required for authentication and encryption of the agent communication flows. See Agent Installation Guidelines for information on how to create the initial agent configuration object, retreive the secret through the API and how to deploy and register your agent.

Typical API Workflow for Agent Control

All agents, sessions and tests are identified with a unique UUID string; this allows for seamless control of an agent, regardless through which RoadRunner service it is connected, and allows for Analytics to keep track of the agent's reported metrics even if the agent name should change.

For each agent there are typically two parts of configuration that can be defined:

• Agent configuration - these parameters relate to the agent itself, such as metadata for address, region or geocoordinates.
• Test or measurement configuration - these parameters define the characteristics of the test that the agent should perform.

Typical workflow for creating a new test or session

• Look up agentID that should be responsible for the test

Use GET for inventory at /api/orchestrate/v3/agents

• Create a session or test configuration

Example new session object for TWAMP:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "{{agentId}}",
      "session": {
        "sessionId": "{{sessionId}}",
        "sessionName": "my TWAMP session example 😀",
        "sessionType": "twamp-stateful",
        "enable": true,
        "period": "continuous",
        "twamp": {
            "senderPayloadSize": 82,
            "senderRate": 10,
            "reflectorAddr": "10.122.1.254",
            "reflectorPort": 50862,
            "reportInterval": 10
        }
      }
    }
  }
}

• POST new configuration to API

Send the session configuration to
POST to /api/orchestrate/v3/agents/session

• Optionally start the test if not automatically done

See details for each agent type on these pages
Agent: actuate - configuration
Agent: throughput - configuration
Agent: trace- Configuration
Agent: transfer - Configuration