Agent
Represents a known agent instance.
Related Help article: Build Agent
Properties
id
An integer value that is the unique agent identificator.
name
The public agent name. Cloud agent names are typically formed by appending the unique instance name to the parent cloud profile name.
typeId
Returns the unique ID of the agent category. Local standalone have unique type IDs whereas cloud agents spawned from the same cloud image have the same type ID.
connected
Returns true if the agent is connected to the TeamCity server; otherwise, false. Connected agents are those that can communicate with the TeamCity server.
enabled
Returns true if the agent is enabled; otherwise, false. Enabled agents are those that are ready to process new bulds.
Send PUT requests to the /app/rest/agents/{agentLocator}/enabledInfo endpoint to manually enable or disable agents.
authorized
Returns true if the agent is authorized on the server; otherwise, false. Authorized agents are those that are granted permission to execute building tasks on this TeamCity server.
Send PUT requests to the /app/rest/agents/{agentLocator}/authorizedInfo endpoint to manually authorize or unauthorize agents.
uptodate
Returns true if both outdated and pluginsOutdated properties return false; false if any of these properties returns true.
outdated
Returns true for outdated agents that require an update; false for agents that are up to date. Agents typically update their software automatically and do not require any actions from your side.
pluginsOutdated
Returns false if all plugins installed on this agent are of the latest version; true if some of plugins are outdated. Plugins installed from the JetBrains Marketplace are typically updated automatically.
javaOutdated
Returns true the Java version installed on the agent machine is outdated; otherwise, false.
ip
The IP address of the agent machine.
protocol
Returns the agent-server communication protocol type:
unidirectional — the default one-way communication protocol. Unidirectional agents establish an HTTP(S) connection to the TeamCity server, and periodically poll it for server commands.
bidirectional — no longer supported in TeamCity 2021.2 and newer.
version
The actual version of the agent software or 'unknown' if the agent is disconnected. If this version differs from the version expected by the server (the currentAgentVersion property), the agent is considered outdated.
currentAgentVersion
The version of the agent software that is expected by the current TeamCity server. Matches the build number of this server (can be obtained from the /app/rest/server/build endpoint).
lastActivityTime
The timestamp of the last comminication between this agent and the TeamCity server.
To get the last time this agent performed an activity different from periodic server polling (for example, ran a build), use the idleSinceTime property instead.
idleSinceTime
The timestamp of the last meaningful agent activity (for example, running a build). For agents that never ran a build after they were authorized by the server, this timestamp is typically equal to the registrationTimestamp property value.
disconnectionComment
The summary that explains why this agent was disconnected. Returns null for connected agents.
registrationTimestamp
The timestamp of the first successful agent authorization on this server.
host
The name of the agent machine host.
cpuRank
An integer value that is the benchmarking score of the agent machine's CPU.
port
The port used by the TeamCity server to connect to the agent.
href
Returns the shortened (without the server URL) link to the current agent. To obtain the full URL, use the webUrl property instead.
webUrl
Returns the full web link to access this agent. To get a shortened link without the server URL, read the href property instead.
build
Returns the build currently processed by this agent, or null if the agent is idle.
links
Returns the collection of links to this build.
enabledInfo
An EnabledInfo object that stores the information about the agent availability: the current state, the scheduled time this state should automatically flip (for temporarily disabled agents), and metadata related to the last time this state was modified (the timestamp, the user who did it, and their optional comment).
Send PUT requests to the /app/rest/agents/{agentLocator}/enabledInfo endpoint to manually enable or disable agents.
authorizedInfo
An AuthorizedInfo object that returns the current agent authorization state and the metadata related to the last time this state was changed (the timestamp, the user who did it, and their optional comment).
Send PUT requests to the /app/rest/agents/{agentLocator}/authorizedInfo endpoint to manually authorize or unauthorize agents.
properties
The list of all standard and custom parameters known to the agent.
cloudInstance
The cloud instance that runs this agent. A cloud instance is an individual cloud machine spawned from a cloud image.
Cloud instance objects store infrastructure information about the agent's machine: its network address, state (starting, running or stopped), errors that prevent it from starting, and so on.
cloudImage
The cloud image that spawned a cloud instance on which the current agent runs.
environment
Returns an object that stores the agent machine's OS version and type
pool
Returns an object that specifies the pool to which this agent belongs.
Send a POST request to the /app/rest/agentPools/{agentPoolLocator}/agents endpoint to move an agent to a different pool.
compatibilityPolicy
Returns whether the agent can run only builds of specific build configurations.
If the agent can run builds of any compatible configuration (the default behavior), the
compatibilityPolicy.policyproperty returns 'any' andcompatibilityPolicy.buildTypesis null.If the agent has specific build configurations assigned to it, the
compatibilityPolicy.policyproperty is 'selected' and thecompatibilityPolicy.buildTypeslist returns these assigned build configurations.
compatibleBuildTypes
Returns the list of all build configurations whose builds can be processed by this agent. An agent can be incompatible with specific build configurations if it does not meet agent requirements of these configurations.
incompatibleBuildTypes
Returns all build configurations incompatible with this agent as a list of Compatibility objects. Each Compatibility object includes a BuildType instance that represents an incompatible configuration and a list of unmet requirements (the Requirements object).
builds
The build history of this agent (the list of builds processed by it).
locator
Schema
Below, you can find a full schema of this object, in XML and JSON formats. You can choose what fields to submit depending on your current needs. Different methods might expect different fields: the best approach is to request this entity via GET and use the response as a base for the following POST request.
A link to another object implies that you can substitute it with the schema of the linked object, if it is required for your call.