## Planning agent of an item (tenant:forge:read)

`GET /api/forge/v1/projects/{key}/items/{number}/agent`

Module: Forge · operationId: `getForgeItemAgent` · Tag: Agent · Auth: access token (`Authorization: Bearer <accessToken>`)

Requires `tenant:forge:read` and edit rights on the item. Answers whether the caller can use the planning
agent (ADR 0028) on the item now (`status`) and the caller's own conversations about it, latest activity first.
A hidden item answers `404`, a visible one the caller may not edit `403`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |
| `number` | path | integer | yes | Item number in the project (12 of APP-12) |

### Responses

- **200** Agent panel (`application/json`)
- **401** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `conversations` (array of AgentConversation, required): The caller's own conversations about the item, latest activity first
  - `createdAt` (string (date-time)): When the conversation was started
  - `credentialId` (string): The tenant model credential the conversation runs on
  - `id` (string (uuid)): Conversation id
  - `itemId` (string): The item the conversation is about
  - `lastActivity` (string (date-time)): Last message, run or decision in the conversation
  - `model` (string): The model the conversation runs on
  - `ownerRef` (string): E-mail of the person who started it (only they see it)
  - `projectId` (string): Project of the item
  - `title` (string): Short title taken from the first message
  - `updatedAt` (string (date-time)): Last change of the conversation row
- `status` (AgentStatus, required)
  - `canUse` (boolean, required): The caller can start the planning agent on the item now
  - `enabled` (boolean, required): The project switched the agent on
  - `models` (array of AgentModel, required): The tenant's usable models (bring your own key)
    - `credentialId` (string): Id of the tenant credential (bring your own key)
    - `credentialName` (string): Name of the credential as the tenant set it
    - `label` (string): Display name of the model
    - `model` (string): Model id
    - `provider` (string): Provider of the credential
  - `budget` (object): The tenant's agent token budget of the month (missing when it could not be read)
    - `capReached` (boolean): The cap is reached; no new run starts
    - `capTokens` (integer): The tenant's monthly token cap
    - `usedTokens` (integer): Tokens used this month
  - `reason` (string): Why `canUse` is false (one of `disabled`, `no_credentials`, `cap_reached`, `unavailable`)

Example 200 answer:

```json
{
  "conversations": [
    {
      "createdAt": "2026-11-17T14:02:00Z",
      "credentialId": "6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b01",
      "id": "7d8e9f0a-1b2c-4d3e-8f4a-6b7c8d9e0f01",
      "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c06",
      "lastActivity": "2026-11-17T14:06:00Z",
      "model": "claude-sonnet-4-5",
      "ownerRef": "marie.wagner@muster-it.example",
      "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
      "title": "Akzeptanzkriterien für die Filterleiste",
      "updatedAt": "2026-11-17T14:06:00Z"
    }
  ],
  "status": {
    "budget": {
      "capReached": false,
      "capTokens": 5000000,
      "usedTokens": 1284000
    },
    "canUse": true,
    "enabled": true,
    "models": [
      {
        "credentialId": "6f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b01",
        "credentialName": "Anthropic Muster IT",
        "label": "Claude Sonnet 4.5",
        "model": "claude-sonnet-4-5",
        "provider": "anthropic"
      }
    ]
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/agent' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
