Visual Studio Team Services Support
Our friendly support bot is here to help!
We are here to help
What do I need to do to deploy a build agent on windows?
Deploy an agent on Windows
Team Services | TFS 15 Preview | TFS 2015 | Previous versions (XAML builds)To build and release Windows, Azure, and other Visual Studio solutions you'll need at least one Windows agent. Windows agents can also build Java and Android apps.
Before you begin:
- If your code is in Visual Studio Team Services and the hosted pool meets your needs, you can skip setting up an on-premises agent.
- If your code is in an on-premises Team Foundation Server (TFS) 2015 server, see Deploy an agent on Windows for on-premises TFS 2015.
RequirementsWindows System Pre-requisites
Prepare permissionsMake sure you have credentials that enable you to join the agent to the pool.
Confirm you have permissionMake sure you have been added as an agent pool administrator on the Agent pools control panel tab ▼
Team ServicesAfter you've confirmed you are an administrator, get a PAT token. It's fine to limit the scope to Agent Pools (read, manage).
TFS 15 PreviewYou can use either a domain user or a local Windows user on each of your TFS AT servers.Where can I learn more about agent pools?How does the agent authenticate and communicate with the TFS AT?
ProxyIf you need to run your agent behind a web proxy, see Run the agent behind a web proxy.
Download and configure the agent
- Go to the Agent pools control panel tab ▼
- Click Download agent.
- Click Windows.
- Click the Download button.
- Run PowerShell as Administrator.
- Run the commands under Create the agent.
- Respond to the prompts.
- You're asked if you want to run the agent as a service.
Run interactivelyAfter you've configured the agent, we recommend that you first try it in interactive mode to make sure it works. Also, in some cases you might need to run the agent interactively for production use. For example, if you need to run an elevated process or run UI tests.If you configured the agent to run interactively, to run it:
Run as a serviceAfter you've verified that the agent is working, for production use, we recommend that you run the agent as a service. The main advantage is that the agent stays more reliably in a running state. For example, it starts automatically when you restart the machine and after some kinds of failures.After you configure the agent to run as a service (see above), it starts automatically. You can view and control the agent running status from the Services snap-in. Run
services.mscand look for "VSTS Agent (name of your agent)".If you need to change the logon account, don't do it from the services snap-in. Instead, see the information below to re-configure the agent.
Replace an agentWhen you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer
Y, then make sure you remove the agent (see below) that you're replacing. Otherwise after a few minutes of conflicts, one of the agents will shut down.
Remove and re-configure an agentTo remove the agent:
After you've removed the agent, you can configure it again.
Help on other optionsTo learn about other options:
The help provides information on authentication alternatives and unattended configuration.
Run the agent behind a web proxyIn the agent root directory, create .proxy file with your proxy server url.
If your proxy doesn't require authentication, then you're ready to configure and run the agent as explained above.Note: For backwards compatibility, if the proxy is not specified as described above, the agent also checks for a proxy URL from the VSTS_HTTP_PROXY environment variable.
echo http://name-of-your-proxy-server:8888 | Out-File .proxy
Proxy authenticationIf your proxy requires authentication, the simplest way to handle it is to grant permissions to the user under which the agent runs. Otherwise, you can provide credentials through environment variables.
Provide credentials through environment variablesWhen you provide credentials through environment variables, the agent keeps the credentials secret by masking them in job and diagnostic logs.
- Set the following environment variables:
batch set VSTS_HTTP_PROXY_USERNAME=proxyuser set VSTS_HTTP_PROXY_PASSWORD=proxypassword
LimitationsThis procedure enables the agent infrastructure to operate behind a web proxy. Your build definition and scripts must still handle proxy configuration for each task and tool you run in your build. For example:
- If you use Git, you must configure a proxy for it.
- If you are using a task that makes a REST API call, you must configure the proxy for that task.
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
How does the agent authenticate and communicate with the TFS AT?The agent pool administrator role is needed only when you register an agent. At that time, the agent downloads an OAUth token so that it can listen to the queue. The account that you use in this role has no bearing on future communication between the agent and the TFS AT.When a build is run, it generates an OAuth token for the scoped identity selected on the general tab of the build definition. That token is short lived and is used to access resources on the application tier.
How do I make sure I have the latest version?
- Go to the Agent pools control panel tab ▼
- Click the pool that contains the agent.
- Make sure the agent is enabled.
- Click Agents.
- Click Capabilities.
- Look for the
You can check this value against the latest published agent version. See Visual Studio Team Services Build and Release Agent and check the page for the highest version number listed.
- To update your agents, right-click the pool, and then click Update all agents.
The agent automatically updates itself when it runs a task that requires a newer version of the agent.Note: If your agent version is older than 102.1, then you must download and configure the agent to get the newest version.