Update REST API agent docs to clarify when connected/disconnected agents are returned
Update REST API agent docs to clarify when connected/disconnected agents are returned

I was surprised to see that state is handled differently by the agent
list and get endpoints.

I'm not sure if we can fix that in the short term. There are scenarios
where it would be helpful to list disconnected agents, but there may be
performance implications. Elastic stack style agent handling can result
in a very high number of disconnected-and-never-coming-back agents.

While we discuss that, we can at least document the current behvaiour.

buildkite/docs,buildkite/docs,buildkite/docs,buildkite/docs