{"slug":"agents","title":"Agents","path":"agents.md","markdown":"# Agents\n\nLists agents owned by your API key’s account (the same owner roster as the product UI). Use an agent’s public `id` (`ag_…`) as `agentId` when creating [tasks](tasks.md) or [schedules](schedules.md).\n\nCreate and edit of agents is not part of this API. Internal agent UUIDs are never returned.\n\n## List\n\n```bash\nkobold-cli agents list\n```\n\n```http\nGET /v1/agents\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nSuccess `200`:\n\n```json\n{\n  \"agents\": [\n    {\n      \"id\": \"ag_7k2m9x4q\",\n      \"name\": \"Researcher\",\n      \"type\": \"\",\n      \"description\": \"…\",\n      \"capabilities\": [],\n      \"status\": \"active\",\n      \"imageUrl\": \"\"\n    }\n  ]\n}\n```\n\n| Field | Notes |\n| ----- | ----- |\n| `id` | Public id (`ag_…`); lazy-minted on first list |\n| `name` | Display name from the owner catalog |\n| `description` | From the owner catalog |\n| `imageUrl` | From the owner catalog |\n| `type` | Always `\"\"` today (field reserved; not populated) |\n| `capabilities` | Always `[]` today (field reserved; not populated) |\n| `status` | Always `\"active\"` today |\n\nUpstream catalog failure → `502`.\n\n## Related\n\n- [Tasks](tasks.md)\n- [Schedules](schedules.md)\n- [CLI reference](cli-reference.md)\n"}