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

# Mit Agent chatten

> Sende eine Nutzernachricht an einen Pharen Hub KI-Agenten per UUID und streame die Modellantwort über HTTP mit einem agents:run API-Key.

Sendet eine Nachricht an einen Agent. Der Endpunkt streamt die Modellantwort. API-Keys mussen Streaming explizit erlauben, wenn der Client Streaming anfordert.

<Note>
  Erforderlicher API-Key-Scope: `agents:run`.
</Note>

## Path-Parameter

<ParamField path="agent_uuid" type="string" required>
  UUID des Agents.
</ParamField>

## Body-Parameter

<ParamField body="message" type="string" required>
  Nachricht an den Agent. Maximale Lange: `32000` Zeichen.
</ParamField>

<ParamField body="conversation_uuid" type="string">
  UUID einer bestehenden Unterhaltung. Ohne Wert startet Pharen eine neue Unterhaltung.
</ParamField>

<ParamField body="model" type="string">
  Optionales Modell. Ohne Wert nutzt Pharen das Standardmodell des Agents.
</ParamField>

<ParamField body="enable_thinking" type="boolean">
  Aktiviert Reasoning, wenn das Modell es unterstutzt.
</ParamField>

<ParamField body="page_context" type="object">
  Optionaler JSON-Kontext der aufrufenden Seite.
</ParamField>

## Beispiel-Body

```json theme={null}
{
  "message": "Fasse die offenen Aufgaben in diesem Workspace zusammen.",
  "enable_thinking": true
}
```


## OpenAPI

````yaml openapi.json POST /api/agents/{agent_uuid}/chat/
openapi: 3.1.0
info:
  title: Pharen Hub API
  version: 1.0.0
  description: >-
    Scoped REST API for Pharen Hub workspaces, calendars, lists, docs,
    workflows, and agents.
servers:
  - url: '{baseUrl}'
    description: Pharen Hub API base URL
    variables:
      baseUrl:
        default: https://pharen.app
        description: >-
          The Pharen Hub API origin. Keep the default for production, or enter
          another environment such as http://localhost:8000.
security:
  - bearerAuth: []
tags:
  - name: Calendar
    description: Calendar source and event operations.
  - name: Lists
    description: Saved list data and metadata operations.
  - name: Docs
    description: Document and collection operations.
  - name: Workflows
    description: Workflow definition and execution operations.
  - name: Agents
    description: Agent catalog and chat operations.
paths:
  /api/agents/{agent_uuid}/chat/:
    post:
      tags:
        - Agents
      summary: Chat with agent
      description: >-
        Send a message to an agent and receive a response. Requires the
        `agents:run` scope.
      operationId: chatWithAgent
      parameters:
        - name: agent_uuid
          in: path
          required: true
          description: Agent UUID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentChatRequest'
            examples:
              message:
                summary: Ask an agent
                value:
                  message: Summarize the latest onboarding blockers.
                  conversation_id: conv_123
      responses:
        '200':
          description: Agent response returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentChatResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    AgentChatRequest:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Summarize the latest onboarding blockers.
        conversation_id:
          type: string
          description: Optional conversation identifier for continuing a thread.
        context:
          type: object
          additionalProperties: true
          description: Optional structured context for the agent.
    AgentChatResponse:
      type: object
      properties:
        message:
          type: string
        conversation_id:
          type: string
        run_id:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: forbidden
            message:
              type: string
              example: This API key does not have the required scope.
            details:
              type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: The request was malformed or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The request did not include a valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The API key is valid but does not have the required scope or workspace
        access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        The requested resource was not found or is outside the key's access
        target.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Paste your Pharen API key without the Bearer prefix.
      x-default: phk_your_api_key

````