Agents

A collection of common tasks with agents using the GraphQL API.

You can test out the Buildkite GraphQL API using the Buildkite explorer. This includes built-in documentation under the Docs panel.

Get a list of agent token IDs

Get the first five agent token IDs for an organization.

query token {
  organization(slug: "organization-slug") {
    id
    name
    agentTokens(first: 5) {
      edges {
        node {
          id
          description
        }
      }
    }
  }
}

Search for agents in an organization

query SearchAgent {
   organization(slug:"organization-slug") {
    agents(first:500, search:"search-string") {
      edges {
        node {
          name
          hostname
          version
        }
      }
    }
  }
}

Revoke an agent token

Revoking an agent token means no new agents can start using the token. It does not affect any connected agents.

First, get the token ID. You can find it in the Buildkite dashboard, in Agents > Reveal Agent Token, or you can retrieve a list of agent token IDs using this query:

query GetAgentTokenID {
  organization(slug: "organization-slug") {
    agentTokens(first:50) {
      edges {
        node {
          id
          uuid
          description
        }
      }
    }
  }
}

Then, using the token ID, revoke the agent token:

mutation {
  agentTokenRevoke(input: {
    id: "token-id",
    reason: "A reason"
  }) {
    agentToken {
      description
      revokedAt
      revokedReason
    }
  }
}

Stop an agent

First, get the agent's ID. Search for the agent in the organization where the search-string matches the agent name and retrieve the agent's ID.

query SearchAgent {
   organization(slug:"organization-slug") {
    agents(first:500, search:"search-string") {
      edges {
        node {
          name
          id
        }
      }
    }
  }
}

Then, using the agent ID, stop the agent gracefully:

mutation {
  agentStop(input: {
     id: "QWdlbnQtLS0wMThkYWUyZi02NjRjLTQxYjgtOWE4Ny1mMGY5ODhkZWRhM2Q=",
     graceful: true
  }) {
    agent{
      id,
      connectionState
    }
  }
}