# List agents

URL: https://docs.hanzo.ai/docs/openapi/compute/listmachineagents

> Returns every agent↔machine binding in the caller's org — which machines are running which cloud Agent, with vm's own reconciled status.

`GET /v1/compute/machines/agents`

> [Compute →](https://docs.hanzo.ai/docs/openapi/compute) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                   |
| ------------- | ------------------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/compute/machines/agents` |
| **Method**    | `GET`                                             |
| **Operation** | `listMachineAgents`                               |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`            |

Returns every agent↔machine binding in the caller's org — which
machines are running which cloud Agent, with vm's own reconciled status.

## Request

`GET /v1/compute/machines/agents` takes no parameters and no body — the credential is the whole request.

## Response

| Status    | Body                | Meaning |
| --------- | ------------------- | ------- |
| `200`     | compute.bindingList | ok      |
| `default` | problem-details     | refused |

`200` body — 13 fields.

| Field                         | In   | Type                    | Always | Description                                                                                                                                                       |
| ----------------------------- | ---- | ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentBindings`               | body | compute.agentBinding\[] | —      | AgentBindings is one row per bound machine, emitted verbatim as vm reports it.                                                                                    |
| `agentBindings[].agentName`   | body | string                  | —      | AgentName is the cloud Agent (/v1/agent) this machine runs — the agent a message to the bot is actually run against.                                              |
| `agentBindings[].botVersion`  | body | string                  | —      | BotVersion pins the @hanzo/bot runtime version the machine runs.                                                                                                  |
| `agentBindings[].createdTime` | body | string                  | —      | CreatedTime is when the binding was first made.                                                                                                                   |
| `agentBindings[].machineId`   | body | string                  | —      | MachineId is the bound machine as vm addresses it, owner-qualified ("\<org>/\<machine>").                                                                         |
| `agentBindings[].message`     | body | string                  | —      | Message is vm's human-readable detail on Status ("machine provisioning; @hanzo/bot runtime not yet confirmed") — the reason behind the state, not a second state. |
| `agentBindings[].name`        | body | string                  | —      | Name is the binding's own key, which is the machine's id: a machine hosts at most one agent, so the binding is named for it.                                      |
| `agentBindings[].org`         | body | string                  | —      | Org is the Hanzo tenant the binding belongs to.                                                                                                                   |
| `agentBindings[].owner`       | body | string                  | —      | Owner is the tenant vm filed the binding under, resolved from the ?owner it was called with — which is the caller's validated org and never a body field.         |
| `agentBindings[].provider`    | body | string                  | —      | Provider is the cloud the bound machine runs on, carried here so a bindings list says where each bot lives without a second read per machine.                     |
| `agentBindings[].publicIp`    | body | string                  | —      | PublicIp is the bound machine's public address as vm recorded it on the binding.                                                                                  |
| `agentBindings[].status`      | body | string                  | —      | Status is the binding's lifecycle in VM's OWN words — "Pending" while the machine provisions and the runtime is unconfirmed, "running" once vm has confirmed it.  |
| `agentBindings[].updatedTime` | body | string                  | —      | UpdatedTime is when vm last reconciled it — the age of Status.                                                                                                    |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo compute machines agents
```

**SDK**

**.ts**

```ts
import { Configuration, ComputeApi } from 'hanzoai';

const api = new ComputeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.listMachineAgents();
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ComputeApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ComputeApi(client).list_machine_agents()
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ComputeAPI.ListMachineAgents(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, compute_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = compute_api::list_machine_agents(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ComputeApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ComputeApi(client).listMachineAgents();
```

**HTTP**

```bash
curl https://api.hanzo.ai/v1/compute/machines/agents \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

Tool `compute`, op `listMachineAgents` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`.

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "compute",
         "arguments": {
           "op": "listMachineAgents",
           "input": {}
         }
       }
     }'
```

---

[Compute API](https://docs.hanzo.ai/docs/openapi/compute) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)