Reference

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

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

MCP (POST /mcp)

{
  "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

{
  "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.