# Get an agent

Where an agent stands in one call: status, configuration revision, readiness (what is missing), open drafts, latest version, plan features and what this token may do with it.

|  |  |
| --- | --- |
| REST | `GET /api/v1/agents/{agent_id}` |
| MCP tool | `get_agent` |
| Classification | **Read** (changes nothing) |
| Scope | `agents:read` |
| Minimum role on the agent | editor |
| Confirmation | Not needed |
| Retry safety | Safe to retry with the same input |
| Success status | 200 |

## What it does

Where an agent stands in one call: status, configuration revision, readiness (what is missing), open drafts, latest version, plan features and what this token may do with it.

## Side effects

None. It only reads.

## Inputs

| Name | Type | Required | In | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | string | yes | path | The agent id (agt_...), from list_agents. |

## Example

REST:

```bash
curl "https://covo.lanaai.io/api/v1/agents/agt_4edc89bb2964" \
  -H "Authorization: Bearer $COVO_TOKEN"
```

MCP (POST /mcp):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_agent",
    "arguments": {
      "agent_id": "agt_4edc89bb2964"
    }
  }
}
```

## Response

Returns an object with `id`, `name`, `represents`, `status`, `revision`, `latest_version`, `open_drafts`, `url`, `readiness`, `plan`, `permissions` and `resources`. This is a real response, shortened to two items per list.

200 response:

```json
{
  "id": "agt_4edc89bb2964",
  "name": "Avery Quinn's Concierge",
  "represents": "Avery Quinn",
  "status": "draft",
  "revision": 4,
  "latest_version": null,
  "open_drafts": 0,
  "url": "https://covo.lanaai.io/avery",
  "readiness": {
    "state": "ready",
    "steps": [
      {
        "id": "who",
        "done": false,
        "summary": "Not chosen yet"
      },
      {
        "id": "introduce",
        "done": true,
        "summary": "Avery Quinn"
      }
    ],
    "issues": [
      {
        "step": "knowledge",
        "field": null,
        "severity": "recommended",
        "message": "Add a few common questions. Short, specific answers work best."
      },
      {
        "step": "capabilities",
        "field": null,
        "severity": "recommended",
        "message": "Add a link or an offer so your Concierge can point people somewhere."
      }
    ]
  },
  "plan": {
    "name": "Pro",
    "features": {
      "removeWatermark": true,
      "customGreeting": true,
      "customWallpaper": true,
      "brandThemes": true,
      "wrapperMode": true,
      "integrations": true,
      "httpTools": true,
      "humanVerification": true,
      "booking": true,
      "humanMode": true,
      "advancedAnalytics": true,
      "websiteEmbed": true
    }
  },
  "permissions": {
    "role": "owner",
    "scopes": [
      "agents:read",
      "agents:write"
    ],
    "can_read": true,
    "can_edit": true,
    "can_remove": true,
    "can_test": true,
    "can_publish": true,
    "can_read_conversations": true
  },
  "resources": {
    "configuration": "concierge://agents/agt_4edc89bb2964/configuration",
    "versions": "concierge://agents/agt_4edc89bb2964/versions",
    "deployment": "concierge://agents/agt_4edc89bb2964/deployment",
    "diagnostics": "concierge://agents/agt_4edc89bb2964/diagnostics"
  }
}
```

Over MCP the same object comes back as the tool result, in `structuredContent` and as JSON text.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthorized` | No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect. |
| 403 | `account_suspended` | The account that owns the token is paused. |
| 403 | `insufficient_scope` | The token lacks `agents:read`. |
| 404 | `agent_not_found` | Unknown agent, or not reachable with this token. |
| 400 | `bad_request` | An input is invalid; `field` names it. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |