Agent Client Collector upgrade overview

  • Release version: Australia
  • Updated May 28, 2026
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Agent Client Collector upgrade overview

    The Agent Client Collector (ACC) Framework in ServiceNow automates the upgrade of agent software directly from the instance, eliminating the need for manual updates on individual hosts. Upgrades can be performed either one agent at a time via the UI or in bulk using an auto-upgrade feature that supports scheduled or immediate mass upgrades.

    Show full answer Show less

    Upgrade Methods

    • Single Agent Upgrade: Upgrade individual agents from their records in the UI, useful for validating the upgrade process. Multiple agents (up to 50) can also be selected for batch upgrades through the list view.
    • Mass Upgrade: Upgrade all eligible agents automatically using a built-in scheduled job or a background script. Both methods apply rate limiting to control the pace, with the background script enabling immediate execution.

    Upgrade Stages

    Each upgrade progresses through three key stages, with records maintained in the Agent Upgrade Histories table:

    • InstanceVerification: The ServiceNow instance verifies agent eligibility by checking OS support, version, status, and MID Server connectivity.
    • AgentVerification: The agent checks permissions, disk space, and dependencies to confirm upgrade readiness.
    • Upgrade: The agent downloads the new package, installs it, restarts, and reports the outcome back to the instance.

    Agent Eligibility Criteria

    Agents qualify for auto-upgrade if they meet the following conditions:

    • Status is "Up"
    • Version is between 2.7.0 and below the target upgrade version
    • Not flagged as duplicate
    • Valid MID Server or Pod reference
    • Has not exceeded retry limits on failed upgrades
    • Runs on a supported operating system

    Package Download Sources

    Upgrade packages are downloaded based on agent connectivity:

    • Agents connected via Cloud Services (ICS) download packages from the ServiceNow CDN.
    • Agents connected via MID Server download from the MID Server locally; if unavailable, they fall back to the Install Server.
    • Custom download servers can be configured by setting agent-upgrade-url-path in the agent’s acc.yml file, which overrides default sources.

    Recommended Rollout Strategy

    • Start by upgrading a single agent via the UI to validate the process.
    • Upgrade 5–10 agents from different operating systems via the list view to test diverse environments.
    • Proceed with a full rollout using the scheduled job or background script for mass upgrades.

    Additional Upgrade Scenarios

    • Selective Upgrade: Upgrade up to 50 agents at a time, ideal for agents that are difficult to access, such as cloud-deployed agents.
    • Mass Upgrade: Use the scheduled job or background script to upgrade all eligible agents in controlled batches or immediately.
    • Retrying Failed Upgrades: Clear upgrade history for failed agents to retry high-volume upgrades. Changing the target version automatically triggers upgrades without history clearance.
    • Proxy Configuration: Configure a proxy server to enable agents behind corporate proxies to download upgrade packages from the ServiceNow CDN.

    The Agent Client Collector Framework manages agent upgrades directly from the instance, with no manual action required on individual agent hosts.

    You can upgrade Agent Client Collector agents one at a time through the UI, or upgrade all eligible agents at once using the auto-upgrade feature. After an upgrade starts, each agent downloads the new version, installs it, restarts, and reports the result back to the instance.

    Upgrade methods

    Two upgrade methods are available:

    Single agent upgrade
    Upgrade one agent at a time from the agent record in the UI. Use this method to validate the upgrade process before a broader rollout. You can also select multiple agents from the list view to upgrade up to 50 agents at a time.
    Mass upgrade
    Upgrade all eligible agents automatically using the built-in scheduled job or a background script. The scheduled job applies rate limiting to control the rollout pace. The background script also uses rate limiting, and triggers an immediate upgrade without waiting for the next scheduled run.

    Upgrade stages

    Both single and mass upgrade attempts, progress through the following stages. Each stage creates a record in the Agent Upgrade Histories table.

    InstanceVerification
    The instance confirms the agent is eligible for upgrade. Checks include operating system support, agent version, agent status, and MID Server connectivity.
    AgentVerification
    The agent confirms it can perform the upgrade. Checks include permissions, available disk space, and dependencies.
    Upgrade
    The agent downloads the package, installs it, and restarts with the new version.

    For details on the required properties for agent overview, see Agent Client Collector upgrade properties.

    Agent eligibility

    An agent is eligible for auto-upgrade when it meets all of the following conditions:

    • Status is Up.
    • Version is 2.7.0 or higher and lower than the target upgrade version.
    • Agent is not flagged as a duplicate.
    • Has a valid MID Server or Pod reference.
    • Has not exceeded the retry limit for failed upgrades.
    • Runs on a supported operating system.

    Package download sources

    During upgrade, each agent downloads the new package from one of the following sources, depending on its connection type:

    • Agents connected via Cloud Services (ICS) download from the ServiceNow CDN at https://cdn-install.sncapps.service-now.com.
    • Agents connected via MID Server download from the MID Server directly over the local network.
    • If the MID Server is unavailable, agents fall back to the Install Server at https://install.service-now.com. To enable agent fallback, ensure that the install server is specified on the ServiceNow instance.

    If your agents use a custom download server, configure the agent-upgrade-url-path key in the agent's acc.yml file. This setting takes priority over the default sources.

    Rollout strategy

    Use a phased approach to reduce risk when upgrading a large agent fleet:

    1. Upgrade one agent from the UI to confirm the process works end-to-end.
    2. Upgrade 5–10 agents from the list view, selecting agents across different operating systems.
    3. Perform a full rollout by enabling the scheduled job or running the background script.