Agent types

An agent type definition is a YAML file that describes how Agent Control should identify, download, configure, and run a specific agent. Its declared variables also form the configuration schema that Fleet Control exposes to operators when deploying or updating a sub-agent from the fleet. Every definition consists of three main sections, metadata, variables, and deployment, plus a top-level protocol_version field that versions the schema language the file is written against.

Metadata

The metadata section identifies the agent type: its name, namespace, version, target platform (host or kubernetes), and operating_system (required for host-based types). Agent Control uses these fields to uniquely address the definition and dispatch it to the correct deployment engine.

Variables

The variables section declares the configurable inputs that operators can set when adding a sub-agent to their configuration. Each variable has a type (such as string, bool, or yaml), an optional default, and an optional variants list of accepted values. Variables are referenced throughout the deployment section using ${nr-var:variable_name}.

Deployment

The deployment section describes how Agent Control installs and runs the agent on the target platform. It is composed of several sub-sections:

• packages: OCI artifacts to download before the agent starts — typically the agent binary or integration package.
• executables: the list of processes Agent Control will start, monitor, and restart. An agent type without this section is treated as a managed integration (OHI): Agent Control handles its artifacts but delegates execution to another agent.
• health: how Agent Control determines whether the agent is healthy — via process presence, an HTTP endpoint check, or both.
• filesystem: individual files or directories that Agent Control writes to the host before starting the agent, such as configuration files or certificates.
• shared_filesystem: entries written into a shared drop zone accessible to other agents managed by the same Agent Control instance. Used by OHI agent types to hand their configuration and binaries to the Infrastructure Agent.

For the full schema reference and all available fields, see Agent type schema reference.

Linked agent types

Two agent types are linked when one writes artifacts (configuration, binaries, or other files) into the shared filesystem and the other is configured to read from those same paths. The writer may have no executables section, Agent Control manages its artifacts but never starts a process for it. Instead, the reader agent has the built-in logic to discover and execute binaries and configurations from a well-known path in the shared filesystem, effectively running the add-on on the writer's behalf.

The shared filesystem root is:

All agents managed by the same Agent Control instance share this root. Subdirectory names are chosen by convention between the linked agent types.

On Host Integrations (OHI)

On-Host Integrations (OHIs) are the primary example of linked agents in Agent Control; where other agents have a process started by Agent Control, OHI agents have no process of their own and Agent Control never starts them. They let Agent Control manage the full lifecycle of New Relic infrastructure integrations, downloading, configuring, upgrading, and uninstalling them while delegating their execution to the Infrastructure Agent, which discovers and runs the integration binaries from the shared filesystem.

The Infrastructure Agent and OHI agent relationship

1. When an OHI agent type is installed, Agent Control downloads the integration binary via OCI and writes two entries into the shared filesystem:

   • A config file under infra-agent-ohi-configs/ (e.g. nri-redis.yaml)
   • The integration binary under infra-agent-ohi-binaries/ (e.g. nri-redis)

2. The Infrastructure Agent sub-agent is configured with environment variables that point it at these shared directories:

   Variable	Shared filesystem path	Purpose
   NRIA_PLUGIN_DIR	…/infra-agent-ohi-configs	Integration config discovery
   NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR	…/infra-agent-ohi-binaries	Integration binary discovery
   NRIA_SAFE_BIN_DIR	…/infra-agent-ohi-binaries	Allowed binary execution path

3. The Infrastructure Agent picks up the config and binary on its next scan cycle and begins running the integration.

   shared-filesystem/
   ├── infra-agent-ohi-configs/      # Integration YAML configs (read by NRIA_PLUGIN_DIR)
   │   ├── nri-redis.yaml
   │   └── nri-mysql.yaml
   └── infra-agent-ohi-binaries/     # Integration binaries (read by NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR)
       ├── nri-redis
       └── nri-mysql

   Copy

Supported agent types

Current support

The following table shows which agent types Agent Control supports and their availability across environments.

Required permissions per agent type

The following table lists the key permissions each agent type requires and the environments where it applies.