--- name: schematics-sc-agent-update title: Updating agents description: Update an agent configuration in the currently selected Schematics region to work directly in your cloud infrastructure. Updating an agent does not validate or deploy your agent. Select the agent version to update. You can analyze the activity logs and recover the update. last-updated: 2026-07-28 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/schematics?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Updating agents {: #update-agent-overview} Update an agent configuration in the currently selected Schematics region to work directly in your cloud infrastructure. Updating an agent does not validate or deploy your agent. Select the agent version to update. You can analyze the activity logs and recover the update. {: shortdesc} Following are the scenarios that you must use agent upgrade. - To incorporate the issues, features, or vulnerable images by Schematics. For example, you are using agent version is `1.0.0`. If Schematics releases `v1.0.x`, you can use agent update to upgrade `v1.0.0` - `v1.1.1`. - To update an agent metadata such as `name`, `description`, `tags`, `resource group`, `version`, and `agent_metadata` attributes. - You can use `agent update` to revoke the updated version to its existing version. Agent update cannot be done on a deployed agent through `terraform init`, `terraform plan`, and `terraform apply` on the workspace with the deployed agent. {: important} ## Before you begin {: #update-prereq} Review and select your [agent version](https://cloud.ibm.com/docs/schematics?topic=schematics-update-agent-overview&format=markdown#agent_version-releases) to update. {: shortdesc} When upgrading an Agent in the `ca-mon` cluster, make sure both the `private` and `public` service endpoints are enabled. These endpoints are required only during installation or upgrade. After the successful installation or upgrade, you can disable the `public` service endpoint. However, you must re-enable the `public` service endpoint for future Agent upgrades. {: note} ## Updating an agent definition {: #update-agent-ui} {: ui} Update your agent configuration by choosing the cluster and IBM Cloud Object Storage of your choice. 1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}. 2. Click the **Menu** icon ![hamburger icon](images/icon_hamburger.svg) > **Platform Automation** > **Schematics** > [**Extensions**](https://cloud.ibm.com/automation/schematics/extensions/agents){: external}. - Select your agent: - Select **Actions** > **Edit Agent** - You can edit the **Description**, **Cluster**, **COS instance name**, **COS bucket name**, **COS bucket region**, or **Agent version** as in the requirement. 3. Click **Update and validate** to validate the cluster and IBM Cloud Object Storage configuration. 4. Click **Deploy** to redeploy an agent. ## Creating an agent definition through CLI {: #update-agent-cli} {: cli} Select the IBM Cloud region where you want to update and manage your agent. Set the [CLI region command](https://cloud.ibm.com/docs/cli?topic=cli-ibmcloud_cli&format=markdown#ibmcloud_target) by running `ibmcloud target -r `. Select the same region as the `location` specified on the `agent create` command. The IBM Cloud Object Storage bucket location must be of the form `eu-gb` or `us-south` and not a city name. For more information, see the [agent update](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-cli-reference&interface=cli&format=markdown#schematics-agent-update) command. Example ```sh ibmcloud schematics agent update --id AGENT_ID --location --agent-location --version <1.0.0> --infra-type --cluster-id --cluster-resource-group --cos-instance-name --cos-bucket --cos-location --resource-group ``` {: pre} ## Verifying agent update {: #verify-agent-update-cli} {: cli} ```sh ibmcloud schematics agent get --id agent-ga-prod-cli-jan-10.soA.cd1c ``` {: pre} ## Updating an agent through API {: #update-agent-api} {: api} Follow the [steps](https://cloud.ibm.com/docs/schematics?topic=schematics-setup-api&format=markdown#cs_api) to update an IAM access token and authenticate with Schematics through the API. For more information, see [Update an agent](https://cloud.ibm.com/apis/schematics/schematics#update-agent-data). You can use the `refresh_token` to get a new IAM access token if you IAM token is expired. {: important} Example ```json curl -X PUT https://schematics.cloud.ibm.com/v2/agents/{agent_id} \-H 'Authorization: Bearer ' -H 'X-Feature-Agents: true' -H 'refresh_token: ' -d '{ "name": "AgentName", "description": "New Description", "resource_group": "Default", "tags": [ "tag1", "tag2" ], "version": "v1.0.0", "schematics_location": "us-south", "agent_location": "us-south", "agent_infrastructure": { "infra_type": "ibm_kubernetes", "cluster_id": "cluster_id", "cluster_resource_group": "Default", "cos_instance_name": "blueprint_basic", "cos_bucket_name": "sample_bucket_name", "cos_bucket_region": "us-east" }, "agent_inputs": [ { "name": "ibmcloud_api_key", "value": "", "metadata": { "secure": true } }, { "name": "ansible_pull_ibmcloud_api_key", "value": "jenkins api_key for pulling agents images", "metadata": { "secure": true } }, { "name": "devops_api_key", "value": "api_key where you want to create agent and run fvts", "metadata": { "secure": true } } ], "user_state": { "state": "enable" } }' ``` {: codeblock} Verify that the agent definition is created successfully as shown in the output. Record the agent ID for use in subsequent commands. For example, `agentb1-gsmforvpc.soA.115c`. Now, run the `agent deploy` API with the `agent ID` to update the Schematics workspace that deploys the agent. The `agent deploy` operation starts both the `agent validate`, and `agent deploy` operations to setup the agent. Syntax ```json PUT /v2/agents//deploy HTTP/1.1 Host: schematics.cloud.ibm.com Content-Type: application/json Authorization: Bearer ``` {: codeblock} ## Agents version history {: #agent_version-releases} Find a summary of changes for each version of Schematics Agents. Be sure to keep your Schematics Agents up-to-date so that you can use all the available features. {: shortdesc} | Version | Release date | Changes | | ----- | ------- | -------------- | | 1.8.0 | 24 July 2026 | Schematics [agent version v1.8.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-jul2426) supports Terraform versions `1.13` and `1.14`.| | 1.7.0 | 05 March 2026 | Schematics [agent version v1.7.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-mar0526) added support for Virtual Private Endpoints (VPE) way of deployments.| | 1.6.0 | 15 December 2025 | Schematics [agent version v1.6.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-dec1525) platform alignment (Replatforming), security fixes, log collection fix, and multi-credential support.| | 1.5.0 | 31 July 2025 | Schematics [agent version v1.5.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-jul3125) is now supported in the `ca-mon` region and supports Terraform version `1.10`, `1.11`, `1.12`.| | 1.4.0 | 25 April 2025 | Schematics [agent version v1.4.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-apr2525) is now supported in the `ca-tor` region.| | 1.3.1 | 28 February 2025 | Schematics [agent version v1.3.1](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-feb2025) fixes the Ansible inventory generation in the UI for Windows system credentials.| | 1.3.0 | 30 October 2024 | Schematics [agent version v1.3.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-oct3024) supports `schematics-agent-ansible-job` instead of an existing `schematics-ansible-job` and Terraform version 1.9.| | 1.2.0 | 23 September 2024 | Schematics [agent version v1.2.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-sept2324) supports Terraform `version 1.5` and `version 1.6`.| | 1.1.1 | 23 July 2024 | Schematics [agent version v1.1.1](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-july2324) enhanced the agent deletion timeout period and agent deploy issues are fixed.| | 1.1.0 | 19 March 2024 | Schematics [agent version v1.1.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-mar2524) added support for the Schematics Agents on the Red Hat OpenShift Kubernetes Service.| | 1.0.0 | 10 January 2024 | Schematics [agent version v1.0.0](https://cloud.ibm.com/docs/schematics?topic=schematics-schematics-relnotes&format=markdown#schematics-mar2524) support for agent is generally available (GA) with full production support.| {: caption="Schematics Agents version history" caption-side="bottom"} ## Next steps {: #agent-update-nextsteps} - You can [delete an agent](https://cloud.ibm.com/docs/schematics?topic=schematics-delete-agent-overview&interface=cli&format=markdown), [display an agent](https://cloud.ibm.com/docs/schematics?topic=schematics-display-agentb1-overview&interface=terraform&format=markdown#display-agent-terraform), or [create an agent](https://cloud.ibm.com/docs/schematics?topic=schematics-deploy-agent-overview&interface=terraform&format=markdown#create-agent-terraform). - You can check out the [agent FAQ](https://cloud.ibm.com/docs/schematics?topic=schematics-faqs-agent&format=markdown) for any common questions that are related to deleting an agent.