> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agenten

> Agenten programmatisch finden und ihre vollständige Konfiguration lesen — read-only Discovery über die Localmind API.

Ein **Agent** ist die Einheit, die Sie über die Localmind API ansprechen: Er bündelt System-Prompt, Modell, Tools und den Zugriff auf Wissensquellen. Im Chat referenzieren Sie einen Agent über seine UUID (`model = <agent_uuid>`). Diese Seite beschreibt, wie Sie Agenten **read-only** finden und ihre vollständige Konfiguration auslesen.

<Note>
  Zum **Auflisten** der Agenten, auf die Ihr Key Zugriff hat, gibt es zusätzlich den schlankeren OpenAI-kompatiblen Endpunkt `GET /v1/models` — er liefert nur `id` und `name`. Die hier beschriebenen Endpunkte liefern die **vollständige** Agent-Konfiguration. Siehe [OpenAI-kompatibel](/api-reference/OpenAI-Kompatibel).
</Note>

## `POST /v1/agents/search`

Paginierte Suche über die für Ihren Key zugänglichen Agenten. Antwortet im Pagination-Envelope; `items[]` enthält vollständige Agent-Objekte.

<ParamField header="Authorization" type="string" required>
  `Bearer sk-…` — Ihr persönlicher API-Key.
</ParamField>

<ParamField query="limit" type="integer">
  Anzahl der Einträge pro Seite.
</ParamField>

<ParamField query="page" type="integer">
  Seitennummer (1-basiert).
</ParamField>

<ParamField body="filters" type="object">
  Filter im Format `feld__operator` (z. B. `space_id__exact`). Filter können den Zugriff nur **eingrenzen**, nie erweitern. Siehe [Konventionen und Fehler](/api-reference/Konventionen-und-Fehler).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/agents/search?page=1&limit=10" \
    -H "Authorization: Bearer sk-…" \
    -H "Content-Type: application/json" \
    -d '{
      "filters": {}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "items": [
      {
        "id": "{agent_id}",
        "name": "Test-INT1",
        "description": "",
        "version": "1.0.0",
        "agent_type": "simple",
        "model": "<model-deployment>",
        "system_prompt": "Du bist ein hilfreicher Assistent.",
        "temperature": null,
        "max_tokens": 4096,
        "reasoning_config": null,
        "tool_attachments": [
          { "tool_id": "{id}", "config": null }
        ],
        "is_public": false,
        "show_citations": true,
        "save_to_inbox": false,
        "data_access_mode": "origin",
        "allowed_folder_ids": null,
        "organization_id": "{org_id}",
        "space_id": "{space_id}",
        "from_system": false,
        "conversation_count": 3,
        "created_at": "2026-06-13T10:33:54.125058Z",
        "updated_at": "2026-06-13T10:33:54.125058Z",
        "created_by": { "id": "{user_id}", "name": "Beispiel Nutzer", "avatar_url": null }
      }
    ],
    "total_items": 1,
    "total_pages": 1,
    "page": 1,
    "page_size": 10
  }
  ```
</ResponseExample>

## `GET /v1/agents/{agent_id}`

Liefert die vollständige Konfiguration eines einzelnen Agents.

<ParamField header="Authorization" type="string" required>
  `Bearer sk-…` — Ihr persönlicher API-Key.
</ParamField>

<ParamField path="agent_id" type="string" required>
  Die Agent-UUID (z. B. aus `GET /v1/models` oder `POST /v1/agents/search`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://<deine-instanz>-api.localmind.ai/v1/agents/{agent_id}" \
    -H "Authorization: Bearer sk-…"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": "{agent_id}",
    "name": "Test-INT1",
    "description": "",
    "version": "1.0.0",
    "agent_type": "simple",
    "model": "<model-deployment>",
    "system_prompt": "Du bist ein hilfreicher Assistent.",
    "temperature": null,
    "max_tokens": 4096,
    "reasoning_config": null,
    "tool_attachments": [
      { "tool_id": "{id}", "config": null }
    ],
    "is_public": false,
    "show_citations": true,
    "save_to_inbox": false,
    "data_access_mode": "origin",
    "allowed_folder_ids": null,
    "organization_id": "{org_id}",
    "space_id": "{space_id}",
    "from_system": false,
    "conversation_count": 3,
    "created_at": "2026-06-13T10:33:54.125058Z",
    "updated_at": "2026-06-13T10:33:54.125058Z",
    "created_by": { "id": "{user_id}", "name": "Beispiel Nutzer", "avatar_url": null },
    "last_edited_by": { "id": "{user_id}", "name": "Beispiel Nutzer", "avatar_url": null }
  }
  ```
</ResponseExample>

## Das Agent-Objekt

Beide Endpunkte liefern dasselbe Agent-Objekt mit den folgenden Feldern.

<ResponseField name="id" type="string">
  Die Agent-UUID. Wird im Chat als `model` verwendet.
</ResponseField>

<ResponseField name="name" type="string">
  Anzeigename des Agents.
</ResponseField>

<ResponseField name="description" type="string">
  Freitext-Beschreibung (kann leer sein).
</ResponseField>

<ResponseField name="version" type="string">
  Versionskennung der Agent-Konfiguration, z. B. `"1.0.0"`.
</ResponseField>

<ResponseField name="agent_type" type="string">
  Typ des Agents, z. B. `"simple"`.
</ResponseField>

<ResponseField name="model" type="string">
  Das hinter dem Agent konfigurierte Sprachmodell (Deployment-Name, z. B. `"<model-deployment>"`). Dieser Wert wird am Agent konfiguriert (**Agent bearbeiten → Modell**) und ist **nicht** der Wert, den Sie im Chat als `model` senden — dort verwenden Sie immer die Agent-UUID (`id`).
</ResponseField>

<ResponseField name="system_prompt" type="string">
  Das System-Prompt, das das Verhalten des Agents bestimmt.
</ResponseField>

<ResponseField name="temperature" type="number | null">
  Voreingestellte Sampling-Temperatur, oder `null` für den Modell-Default. Im Chat überschreibbar.
</ResponseField>

<ResponseField name="max_tokens" type="integer | null">
  Voreingestellte maximale Token-Anzahl. Im Chat überschreibbar.
</ResponseField>

<ResponseField name="reasoning_config" type="object | null">
  Optionale Reasoning-Konfiguration des Agents.
</ResponseField>

<ResponseField name="tool_attachments" type="array">
  Die dem Agent zugeordneten Tools. Jeder Eintrag hat ein `tool_id` und ein optionales `config`. Diese Tools führt der Agent serverseitig aus.
</ResponseField>

<ResponseField name="is_public" type="boolean">
  Gibt an, ob der Agent öffentlich (innerhalb seiner Sichtbarkeit) bereitgestellt ist.
</ResponseField>

<ResponseField name="show_citations" type="boolean">
  Ob der Agent Quellenangaben zu seinen Antworten anzeigt.
</ResponseField>

<ResponseField name="save_to_inbox" type="boolean">
  Ob Ergebnisse des Agents in der Inbox abgelegt werden.
</ResponseField>

<ResponseField name="data_access_mode" type="string">
  Steuert, auf welche Daten der Agent zugreift, z. B. `"origin"`.
</ResponseField>

<ResponseField name="allowed_folder_ids" type="array | null">
  Schränkt den Wissenszugriff auf bestimmte Ordner ein, oder `null` für keine Einschränkung.
</ResponseField>

<ResponseField name="organization_id" type="string">
  Organisation, der der Agent gehört.
</ResponseField>

<ResponseField name="space_id" type="string">
  Der Space, in dem der Agent lebt.
</ResponseField>

<ResponseField name="conversation_count" type="integer">
  Anzahl der bisherigen Konversationen mit diesem Agent.
</ResponseField>

<ResponseField name="created_at" type="string">
  Erstellungszeitpunkt (ISO-8601).
</ResponseField>

<ResponseField name="created_by" type="object">
  Ersteller des Agents mit `id`, `name` und `avatar_url`. Das analoge Feld `last_edited_by` beschreibt den letzten Bearbeiter.
</ResponseField>

## Mehrstufige Chats

<Note>
  Eine persistente Conversation-API (`/v1/conversations/*`) ist derzeit **nicht** Teil der öffentlichen Dokumentation und folgt zu einem späteren Zeitpunkt. Für **mehrstufige Chats** nutzen Sie aktuell den **stateless** Endpunkt `POST /v1/chat/completions` und senden den bisherigen Verlauf bei jedem Aufruf im `messages`-Array mit. Ein vollständiges Beispiel finden Sie unter [Use Cases](/api-reference/Use-Cases).
</Note>

## Verwandte Seiten

<CardGroup cols={2}>
  <Card title="OpenAI-kompatibel" icon="plug" href="/api-reference/OpenAI-Kompatibel">
    Agenten per `GET /v1/models` auflisten und per Chat Completions ansprechen.
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/api-reference/Use-Cases">
    Mehrstufige Chats stateless umsetzen und weitere Rezepte.
  </Card>

  <Card title="Konventionen und Fehler" icon="list-checks" href="/api-reference/Konventionen-und-Fehler">
    Pagination, Filter-DSL und das Fehlermodell.
  </Card>

  <Card title="Authentifizierung und Rollen" icon="shield-check" href="/api-reference/Authentifizierung-und-Rollen">
    Welche Agenten Ihr Key sieht und wie der Zugriff verengt wird.
  </Card>
</CardGroup>