Understanding the Agent


The Agent is the combination of bridgehub, filehub and the ability to execute a single handler. The Kinetic Agent was designed to be able to run all peripherals including Bridge Adapters, File Adapters and Handlers.

The Agent can be used to access resources that sit behind a firewall. The application is deployed internal to the network. A purpose of the Agent is to allow kinops to gain access to resources that are not public.

At this time the Agent will be packaged with it’s own UI so that it can be used with Kinetic environments older than Platform v5. Within the interface, Agent administrators will be able to create and re-configure instances of Bridge Adapters, File Adapters and Handlers. Adapter instances can also be configured through the Platform Consoles within Platform v5.

Deployment Options

System Wide Agent

The platform v5 will always be setup with an agent that works with all spaces. This instance of the agent will be responsible for handling all Core Submission and Discussion file uploads. This agent can also be used for bridging with the platform and, when an on-prem agent is not needed, with other systems. Kinops tenants will not be able to add / remove / modify any of the adapters in this agent (only configure instances of them).

On-Prem / Hybrid Cloud Agent

The agent can be deployed inside tenant network. The Agent will not come with any preloaded handlers. For purposes of security, handlers will need to be added manually and the tomcat restarted. A firewall connection will need to be opened for communication. Typically the connection will only be opened to a selective IP range. The port should only be opened to Kinops and any source systems that need to leverage the Agent.

Platform+Agent Diagram

Kinetic outbound traffic: All traffic coming from the kinops environment is HTTP(S), and is sourced from one of 5 IP addresses:


Kinetic incoming traffic: If the solution receives incoming data, all traffic is sent to: https://<domain>.kinops.io/...

Customer incoming traffic responsibilities: Configuring Kinetic Agent hosting server to accept Kinetic outbound traffic. Providing Kinetic Data with the public inbound DNS server name (or IP address) and port number.

Establishing/maintaining SSL configuration(s). Configuring routing between the server(s) hosting the Kinetic Agent and appropriate internal applications.

Customer outgoing traffic responsibilities: Customer is responsible for configuring network to be allowed to send HTTPS traffic to https://<domain>.kinops.io/...

Private Agent Setup Instructions

A specific space can elect to use a "Private Agent". To do this the following setup is required:

  • Download the Agent and any handlers that you want to include.
  • Set the Agent up with an external data directory.
  • Create “handlers” directory in data directory.

    • The handlers directory should be a peer to db, temp, …
    • The other directory are auto created if you set up the data directory and restart tomcat.
  • Unzip the handlers and place inside the agent's handlers directory.
  • Restart tomcat.

Authorization Options: Basic Auth is the simplest option for connecting to the Agent. Default credentials are admin/admin. It is also possible to get more security using a shared secret with Core. The steps below are instructions for setting up the shared secret.

  • Run the agent on a web server. Before starting, set a KINETIC_AGENT_SIGNING_SECRETS environment variable.
  • Within your kinps space, click Space > Settings > Platform Components and select "Use Private Agent".

    • Type in the URL / IP to the agent running in your DMZ
    • Type in the Secret you used

Adapter and Handler Configuration Options: Adapters and handlers can be configured from the Agent UI or form your space. Below are instructions for setting up handers from your space.

  • Click Space > Plugins > Agent Handlers and select the handler you want to configure (the list will include handlers you included in step 1).
  • Give it a name/slug and fill out it's "info" values.

Agent Execution

Handler execution options

Calling the agent proxi via POST https://acme.kinops.io/app/components/agent/app/api/v1/handlers/:slug/execute.

Notice, that is a CORE route -- that request gets proxied through core which validates that the user calling is a space admin, then the request is signed by core using the SECRET setup in previous steps.

Calling the agent directly via POST https://acme.com/kinetic-agent/:space-slug/app/api/v1/handlers/:slug/execute.

Notice, this is calling the kinetic-agent directly. In this case, you would use basic auth and the kinetic-agent configurator user un/pw. Option two allows us to use the agent BEFORE platform v5.

Task execution

The kinetic_agent_handler_execut_v1 Task handler is an option for calling the agent. You pass the agent the handler slug and space along with the parameters required by the handler.