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

# Perguntar ao agente

> A resposta chega em streaming, e não depende da conexão.

A resposta é `text/event-stream`: quatro eventos, cada `data:` um JSON (ver os esquemas
`AgentStreamAccepted`, `AgentStreamDelta`, `AgentStreamDone` e `AgentStreamError`). O
`EventSource` do browser só faz `GET`; leia o corpo do `fetch`:

```ts theme={null}
const res = await fetch(`/api/v1/clubs/${clubId}/classroom/agents/${publicId}/messages`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ id: crypto.randomUUID(), content, conversation_id }),
});

if (!res.headers.get("content-type")?.startsWith("text/event-stream")) {
  const { error } = await res.json(); // 403, 409, 429… — ver a tabela abaixo
  throw new Error(error.code);
}

const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";

for (;;) {
  const { value, done } = await reader.read();
  if (done) break;

  buffer += value;
  const events = buffer.split("\n\n");
  buffer = events.pop()!;

  for (const raw of events) {
    const event = raw.match(/^event: (.+)$/m)?.[1];
    const data = raw.match(/^data: (.+)$/m)?.[1];
    if (event && data) handle(event, JSON.parse(data));
  }
}
```

Gere o `id` antes de mostrar a pergunta na tela e reuse-o se precisar reenviar: é ele que
impede a pergunta de ser feita — e cobrada — duas vezes. Se a conexão cair no meio, a resposta
continua sendo gerada; leia-a em
[`GET .../conversations/{conversationId}`](/api-reference/agents/classroom-conversations-get).


## OpenAPI

````yaml POST /v1/clubs/{clubId}/classroom/agents/{publicId}/messages
openapi: 3.0.3
info:
  title: weve API
  description: >
    Contrato entre a API Go e o dashboard. **Este arquivo é a fonte de
    verdade**:

    os tipos e a interface de servidor em Go, e o client TypeScript, são todos

    gerados daqui (`make openapi`). Handler que divergir da interface não
    compila.


    A superfície interna (`/internal/*`) fica de fora de propósito: é acesso de

    máquina, protegido por segredo dedicado, e não é contrato de cliente.
  version: 0.2.0
servers:
  - url: https://api.weve.cx
    description: produção
  - url: http://localhost:8080
    description: desenvolvimento
security: []
tags:
  - name: health
  - name: session
  - name: account
  - name: clubs
  - name: members
  - name: webhooks
  - name: outgoing-webhooks
  - name: sales-platforms
  - name: catalog
  - name: content
  - name: classroom
  - name: community
  - name: mentorships
  - name: agents
  - name: lives
  - name: students
  - name: auth
  - name: campaigns
  - name: workflows
  - name: email
paths:
  /v1/clubs/{clubId}/classroom/agents/{publicId}/messages:
    parameters:
      - $ref: '#/components/parameters/OrgId'
      - $ref: '#/components/parameters/PublicId'
    post:
      tags:
        - agents
      summary: Pergunta ao agente, com a resposta em streaming
      description: >
        Sem `conversation_id`, abre uma conversa nova, com o título tirado da

        primeira linha da pergunta. O `id` da pergunta é gerado pelo CLIENTE (um

        uuid v4): repetir o envio com o mesmo `id` responde 409 `message_exists`

        em vez de perguntar e cobrar duas vezes.


        Tudo o que pode dar errado ANTES de gerar volta como JSON comum, com o

        status de sempre:


        | status | `code` | quando |

        | --- | --- | --- |

        | 403 | `not_entitled` | o aluno não tem acesso ao agente |

        | 409 | `message_exists` | o `id` já foi usado |

        | 409 | `generation_in_progress` | a conversa já está respondendo |

        | 422 | `invalid_image` | imagem que não é desta pessoa, ou não está
        pronta |

        | 429 | `daily_limit_reached` | o teto de perguntas em 24 horas |

        | 429 | `club_budget_exhausted` | o orçamento de IA do club no mês |

        | 501 | `not_configured` | o ambiente não tem o modelo configurado |


        Aceita a pergunta, a resposta é `text/event-stream`, com quatro eventos:


        - `accepted` (`AgentStreamAccepted`): a conversa, a pergunta gravada e a
          resposta nascendo `generating`, com o teto já contando esta pergunta;
        - `delta` (`AgentStreamDelta`): cada pedaço do texto;

        - `done` (`AgentStreamDone`): a resposta final, com as citações;

        - `error` (`AgentStreamError`): a geração falhou; a resposta vem
        `failed`,
          com o que chegou a ser escrito.

        A geração NÃO depende da conexão: fechar a aba no meio não interrompe

        nada, e a resposta aparece inteira em `GET .../conversations/{id}`.
      operationId: sendClassroomAgentMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentMessageCreate'
      responses:
        '200':
          description: >
            A resposta, em eventos. Cada `data:` é um JSON de um dos quatro

            formatos, conforme o `event:` — `accepted`, `delta`, `done` ou
            `error`.
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AgentStreamAccepted'
                  - $ref: '#/components/schemas/AgentStreamDelta'
                  - $ref: '#/components/schemas/AgentStreamDone'
                  - $ref: '#/components/schemas/AgentStreamError'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/NotConfigured'
      security:
        - studentSession: []
components:
  parameters:
    OrgId:
      name: clubId
      in: path
      required: true
      description: >
        Id público da organização — o mesmo que `GET /v1/me` devolve em

        `organization_id`.


        Na URL o recurso se chama **club**; no contrato e no domínio,
        organization.

        A divergência é deliberada: `clubs` é a palavra do produto, e a URL é o
        que

        as pessoas leem.


        É o identificador do provedor de autenticação, e é assim de propósito:

        o cliente precisa nomear a organização ao pedir o token, e o token é o

        que prova o escopo. Um id só nosso obrigaria a traduzir um no outro

        antes de ter um token — e a tradução exigiria uma chamada escopada, que

        é justamente a que ainda não dá para fazer.


        O uuid interno da organização não aparece no contrato: ele é o que as

        chaves estrangeiras do domínio referenciam, e continua sendo nosso.
      schema:
        type: string
        format: uuid
    PublicId:
      name: publicId
      in: path
      required: true
      description: A chave curta da URL do classroom.
      schema:
        type: string
        minLength: 1
        maxLength: 32
  schemas:
    AgentMessageCreate:
      type: object
      required:
        - id
        - content
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Gerado pelo cliente. Repetido, responde 409 `message_exists`.
        conversation_id:
          type: string
          format: uuid
          description: Ausente abre uma conversa nova.
        content:
          type: string
          minLength: 1
          maxLength: 8000
        image_ids:
          type: array
          maxItems: 2
          items:
            type: string
            format: uuid
          description: Imagens enviadas por `POST .../classroom/agent-images`.
    AgentStreamAccepted:
      type: object
      required:
        - conversation
        - question
        - answer
        - limits
      description: O evento `accepted`.
      properties:
        conversation:
          $ref: '#/components/schemas/AgentConversation'
        question:
          $ref: '#/components/schemas/AgentMessage'
        answer:
          $ref: '#/components/schemas/AgentMessage'
        limits:
          $ref: '#/components/schemas/AgentLimits'
    AgentStreamDelta:
      type: object
      required:
        - text
      description: O evento `delta`.
      properties:
        text:
          type: string
    AgentStreamDone:
      type: object
      required:
        - answer
      description: O evento `done`.
      properties:
        answer:
          $ref: '#/components/schemas/AgentMessage'
    AgentStreamError:
      type: object
      required:
        - error
        - answer
      description: O evento `error`.
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
        answer:
          $ref: '#/components/schemas/AgentMessage'
    AgentConversation:
      type: object
      required:
        - id
        - title
        - last_message_at
        - created_at
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        last_message_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    AgentMessage:
      type: object
      required:
        - id
        - role
        - content
        - status
        - images
        - citations
        - created_at
      properties:
        id:
          type: string
          format: uuid
        role:
          $ref: '#/components/schemas/AgentMessageRole'
        content:
          type: string
          description: Markdown, na resposta; texto cru, na pergunta.
        status:
          $ref: '#/components/schemas/AgentMessageStatus'
        error_code:
          type: string
        reply_to:
          type: string
          format: uuid
        images:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        citations:
          type: array
          items:
            $ref: '#/components/schemas/AgentCitation'
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    AgentLimits:
      type: object
      required:
        - daily_limit
        - used
        - remaining
        - club_budget_exhausted
      properties:
        daily_limit:
          type: integer
        used:
          type: integer
          description: >-
            Perguntas feitas nas últimas 24 horas, inclusive as de conversas
            apagadas.
        remaining:
          type: integer
        resets_at:
          type: string
          format: date-time
          description: Quando a pergunta mais antiga da janela sai dela e devolve um lugar.
        club_budget_exhausted:
          type: boolean
          description: >-
            O orçamento de IA do club no mês acabou; ninguém pergunta até virar
            o mês.
    ErrorEnvelope:
      type: object
      description: >-
        Envelope único de erro da API. O `code` é o contrato com o cliente — a
        `message` é diagnóstico, e pode mudar.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
            message:
              type: string
    AgentMessageRole:
      type: string
      enum:
        - user
        - assistant
      x-enum-varnames:
        - AgentMessageUser
        - AgentMessageAssistant
    AgentMessageStatus:
      type: string
      enum:
        - generating
        - complete
        - truncated
        - refused
        - failed
      x-enum-varnames:
        - AgentMessageGenerating
        - AgentMessageComplete
        - AgentMessageTruncated
        - AgentMessageRefused
        - AgentMessageFailed
      description: |
        Só a resposta tem ciclo. `truncated` é a resposta que bateu no teto de
        tamanho; `refused`, a que o modelo recusou.
    Media:
      type: object
      required:
        - id
        - kind
        - title
        - provider
        - status
        - visibility
        - archived
        - created_at
      properties:
        id:
          type: string
          format: uuid
        kind:
          $ref: '#/components/schemas/MediaKind'
        title:
          type: string
        file_name:
          type: string
        mime:
          type: string
        size_bytes:
          type: integer
          format: int64
        provider:
          $ref: '#/components/schemas/MediaProvider'
        external_id:
          description: |
            O id no provedor de FORA (o vídeo do YouTube, a URL colada). Para o
            que hospedamos, o id não vai na resposta: o que a tela precisa é o
            `preview_url` assinado.
          type: string
        status:
          $ref: '#/components/schemas/MediaStatus'
        visibility:
          $ref: '#/components/schemas/MediaVisibility'
        error:
          type: string
        duration_seconds:
          type: integer
        width:
          type: integer
        height:
          type: integer
        preview_url:
          description: |
            Endereço assinado e de prazo curto, para a tela do admin ver o que é
            este arquivo. Não é guardado em lugar nenhum — expira.
          type: string
        thumbnail_url:
          description: A miniatura, assinada pelo mesmo prazo curto.
          type: string
        folder_id:
          type: string
          format: uuid
        archived:
          type: boolean
        created_at:
          type: string
          format: date-time
    AgentCitation:
      type: object
      required:
        - media_id
        - media_title
        - cited_text
      properties:
        media_id:
          type: string
          format: uuid
        media_title:
          type: string
        page_from:
          type: integer
        page_to:
          type: integer
        cited_text:
          type: string
    MediaKind:
      description: Rótulo de tela — o ícone e o filtro. Nada de acesso lê isto.
      type: string
      enum:
        - video
        - audio
        - image
        - document
    MediaProvider:
      description: |
        Onde o bit mora. `bunny_stream` é o vídeo que hospedamos e `r2` o
        arquivo; `youtube`, `vimeo` e `external` são referências a algo de fora,
        que a biblioteca guarda para a aula ter um caminho só.
      type: string
      enum:
        - bunny_stream
        - r2
        - youtube
        - vimeo
        - external
    MediaStatus:
      description: |
        `uploading` enquanto o arquivo não chegou, `processing` enquanto o
        provedor transcodifica, `ready` quando dá para entregar, `failed`
        quando o provedor desistiu (e aí `error` diz por quê).
      type: string
      enum:
        - uploading
        - processing
        - ready
        - failed
    MediaVisibility:
      description: |
        `private` é o padrão, e continua sendo depois de qualquer dúvida:
        publicar é escolha explícita.

        A diferença é de BUCKET, não de um sinalizador na hora de entregar —
        objeto privado não tem endereço público, então nenhum erro de código
        consegue publicá-lo. Privado é entregue por endereço assinado e de
        prazo curto; público, por um endereço estável que o CDN cacheia.

        Público existe para o que precisa ser visto por quem ainda não comprou
        e sobreviver a um cache: a capa do curso na vitrine, a marca do club, o
        trailer. Uma URL assinada não serve para isso — ela muda a cada
        resposta, então o CDN nunca acerta, a prévia de link do WhatsApp busca
        a imagem dias depois e a capa dentro de um e-mail vence.
      type: string
      enum:
        - private
        - public
  responses:
    BadRequest:
      description: Requisição malformada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Sessão ausente, expirada ou revogada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: >
        A sessão é válida, mas não age nesta organização. É a mesma resposta
        para

        uma organização que não existe — distinguir as duas deixaria enumerar

        organizações alheias.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Conflict:
      description: >-
        Conflito com o estado atual. O `code` diz qual; a descrição da operação
        lista os possíveis.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    UnprocessableEntity:
      description: Campos obrigatórios ausentes ou inválidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TooManyRequests:
      description: Teto por IP atingido
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: >-
        Falha inesperada. O corpo nunca traz o erro real — ele fica no log e no
        rastreamento.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotConfigured:
      description: |
        O ambiente não tem o que a operação precisa (`not_configured`): o
        provedor de autenticação nas rotas de sessão, o e-mail nas que
        enviam link, a chave de cifra nos webhooks.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    studentSession:
      type: http
      scheme: bearer
      description: |
        Token OPACO de sessão de aluno, emitido por `/v1/auth/sign-in` e
        verificado contra a nossa tabela — não é JWT e não se lê nada dele.

        A ida ao banco não é custo novo: toda requisição autenticada já resolve
        o dono da sessão. Em troca, encerrar uma sessão vale no mesmo instante,
        sem lista de bloqueio nem janela de tolerância.

        O classroom o guarda em cookie **host-only**: um cookie de domínio o
        mandaria para os subdomínios dos outros clubs.

````

## Related topics

- [Agentes](/essentials/agents.md)
- [Limites de uso](/essentials/rate-limits.md)
- [Onde a mídia é usada](/api-reference/media/usage.md)
- [Acesso ao classroom](/api-reference/clubs/classroom-session.md)
- [Reagir ao post](/api-reference/community/post-reaction-add.md)