Configure TFS 2015 Agent

This article explains how to configure/unconfigure TFS 2015 Agent software. An Agent is an installable software that runs one build or deployment job at a time. At least one Agent is required to build or deploy your code. More agents are required as people and code grows.

What is TFS Agent?

An Agent is an installable software that runs one build or deployment job at a time. At least one Agent is required to build or deploy your code. More agents are required as the code grows.

Agent types

There are two types of agent -

• Microsoft-hosted agents: These are run in Azure Pipelines on Microsoft Virtual Machines which are discarded after one use.
• Self-hosted agents: These can run in Azure Pipelines or TFS on-premise.

Agents can be installed on Windows, Linux, or MacOS machines. Linux Docker containers can also be used.

Agent pools

These are used to organize the agents based on project collections and projects so that the agents don't have to be managed individually.

Prerequisites

• An OS that supports VS 2013 or higher
• VS 2013 or 2015 (For information on issues faced with VS latest versions, check this article)
• PowerShell 3 or higher

Capabilities

This tells us what the agent can do. Capabilities are name-value pairs that are either automatically discovered by the agent software, in which case they are called system capabilities, or those that you define, in which case they are called user capabilities. While queueing a build these can be set as demands in the General tab to identify suitable agents.

These capabilities are recognized by the registry information which can be found under HKLM on Windows machines.

Some of the generally required capabilities are,

• MS build
• Visual Studio
• VS Test
• Microsoft SDKs
• PowerShell

Additional software can be installed on an Agent as required by the code to be built, e.g., a software that packages your code after building an MSI and can be invoked by a build task in your build definition through a batch file or PowerShell command.

Additional Tip

Restart the Agent Service after installing the additional software for the capability to show up.

Download and configure the Agent

1. Login as Agent Pool Administrator.
2. Navigate to the Agent Pool tab: http://{your_server}:8080/tfs/_admin/_AgentPool
3. Click on Download Agent. Unzip the package under C:\Agent.
4. Run "ConfigureAgent.cmd" as administrator and respond to the prompts.
5. Stick to the defaults initially to install the agent in the Default pool if you're not really familiar with the environment.
6. Install the Agent as a service. Make sure the Agent is running under Services.msc with the provided domain credentials. The credentials should have required permissions e.g. on the Drop folder where the code will be Published using the Build definition.
7. The C:\Agent\Agent\VsoAgent.exe is found under Services snap-in as VSO Agent.

If you need to change the credentials later the following command can be used,

C:\Agent\Agent\VsoAgent.exe /ChangeWindowsServiceAccount

The TFS on-premise agent cannot be upgraded unless the TFS version is upgraded. The Agent version which is used which is shipped along with TFS.

The list of configured Agents can be found under,

http://{your_server}:8080/tfs/_admin/_AgentPool

Unconfigure Agent

Start cmd as Administrator.

Go to the Agent folder C:\Agent\Agent and run the following command.

.\agent\vsoagent.exe /unconfigure

Comments are welcome for improvements!