Deploy an agent on Windows for TFS 2015
To build and deploy Windows, Azure, and other Visual Studio solutions you may need a Windows agent. Windows agents can also build and deploy Java and Android apps.
Before you begin:
- If you use VSTS or TFS 2017 and newer, then you need to use a newer agent. See Deploy an agent on Windows.
- If you use TFS, you might already have a build and release agent running. An agent is automatically or optionally deployed in some cases when you set up Team Foundation Server.
- Otherwise, you've come to the right place to set up an agent on Windows for TFS 2015. Continue to the next section.
Learn about agents
If you already know what an agent is and how it works, feel free to jump right in to the following sections. But if you'd like some more background about what they do and how they work, see Build and release agents.
Before you begin, make sure your agent machine is prepared with these prerequisites:
Visual Studio 2013 or Visual Studio 2015
PowerShell 3 or newer (Where can I get a newer version of PowerShell?)
Download and configure the agent
Make sure you're logged on the machine as an agent pool administrator. See Agent pools.
Navigate to the Agent pools tab:
Click Download agent.
Unzip the .zip file into the folder on disk from which you would like to run the agent. To avoid "path too long" issues on the file system, keep the path short. For example:
Run Command Prompt as Administrator, and then run:
Respond to the prompts.
Choose interactive or service mode
For guidance on whether to run the agent in interactive mode or as a service, see Agents: Interactive vs. service.
Run as a service
If you chose to run the agent as a Windows service, then the agent running status can be controlled from the Services snap-in. Run services.msc and look for "VSO Agent (<name of your agent>)".
If you need to change the logon account, don't do it from the services snap-in. Instead, from an elevated Command Prompt, run:
If you chose to run interactively, then to run the agent:
You can use command-line parameters when you configure the agent (
ConfigureAgent.cmd) and when you run the agent (
Agent\VsoAgent.exe). These are useful to avoid being prompted during unattended installation scripts and for power users.
Used for configuration commands against a VSTS account. The parameter is used to specify the pool administrator credentials. The credentials are used to perform the pool administration changes and are not used later by the agent.
When using personal access tokens (PAT) authentication type, specify anything for the user name and specify the PAT as the password.
If passing the parameter from PowerShell, be sure to escape the semicolon or encapsulate the entire argument in quotes. For example: '/Login:user,password;AuthType=PAT'. Otherwise the semicolon will be interpreted by PowerShell to indicate the end of one statement and the beginning of another.
Indicates not to prompt and to accept the default for any values not provided on the command-line.
Used for configuration commands to specify the identity to use for the Windows service. To specify a domain account, use the form Domain\SAMAccountName or the user principal name (for example firstname.lastname@example.org). Alternatively a built-in account can be provided, for example /WindowsServiceLogonAccount:"NT AUTHORITY\NETWORK SERVICE".
Required if the /WindowsServiceLogonAccount parameter is provided.
Configure supports the /NoPrompt switch for automated installation scenarios and will return a non-zero exit code on failure.
For troubleshooting configuration errors, detailed logs can be found in the _diag folder under the agent installation directory.
The server URL should not contain the collection name. For example,
The friendly name to identify the agent on the server.
The pool that will contain the agent, for example: /PoolName:Default
The default work folder location is a _work folder directly under the agent installation directory. You can change the location to be outside of the agent installation directory, for example: /WorkFolder:C:_work. One reason you may want to do this is to avoid "path too long" issues on the file system.
Replaces the server registration if a conflicting agent exists on the server. A conflict could be encountered based on the name. Or a conflict could be encountered if based on the ID a previously configured agent is being reconfigured in-place without unconfiguring first.
Used when configuring an interactive agent to indicate the agent should not be started after the configuration completes.
Used to indicate the agent should be configured to run as a Windows service.
Change Windows service account supports the /NoPrompt switch for automated installation scenarios and will return a non-zero exit code on failure.
For troubleshooting errors, detailed logs can be found in the _diag folder under the agent installation directory.
Prints the version number.
Prints usage information.
Your agent's capabilities are cataloged and advertised in the pool so that only the builds and releases it can handle are assigned to it. See Build and release agent capabilities.
In many cases after you deploy an agent you'll need to install software or utilities. Generally you should install on your agents whatever software and tools you use on your dev machine.
For example, if your build includes the npm task, then the build won't run unless there's a build agent in the pool that has npm installed.
After you install new software on a agent, you must restart the agent for the new capability to show up in the pool so that the build can run.
Q & A
What version of PowerShell do I need? Where can I get a newer version?
The Windows Agent requires PowerShell version 3 or later. To check your PowerShell version:
If you need a newer version of PowerShell, you can download it:
- PowerShell 3: Windows Management Framework 3.0
- PowerShell 4: Windows Management Framework 4.0
- PowerShell 5: Windows Management Framework 5.0
Why do I get this message when I try to queue my build?
When you try to queue a build or a deployment, you might get a message such as: "No agent could be found with the following capabilities: msbuild, vsiualstudio, vstest." One common cause of this problem is that you need to install prerequisite software such as Visual Studio on the machine where the build agent is running.
What version of the agent runs with my version of TFS?
|TFS version||Agent version|
Can I still configure and use XAML build controllers and agents?
Yes. If you are an existing customer with custom build processes you are not yet ready to migrate, you can continue to use XAML builds, controllers, and agents.