# Arquivos (/docs/api-reference/artifact-service) O `artifact-service` guarda arquivos enviados à plataforma, como anexos do chat. Cada arquivo é um **artifact**. Um **attachment** liga um artifact a um recurso, como uma conversa. Anexar arquivos exige os scopes `artifacts:read` e `artifacts:write`. ## Enviando um arquivo [#enviando-um-arquivo] O envio acontece em três etapas: 1. Peça uma URL assinada com `POST .../artifacts/presign-upload`. 2. Envie o arquivo direto ao storage, na URL recebida. 3. Confirme o envio com `POST .../artifacts/{artifact_id}/confirm`. # confirm (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/confirm) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download-url (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/download-url) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/download) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {artifact_id} (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # public-download (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/public-download) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # signed-download (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/signed-download) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # presign-upload (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/presign-upload) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # bind (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/attachments/bind) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {binding_id} (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/attachments/binding-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # attachments (/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/attachments) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Assistentes (/docs/api-reference/assistants-service) O `assistants-service` guarda a configuração de cada agente: modelo, instruções, coleções e ferramentas disponíveis. Ele também publica versões do agente. Para conversar com um agente, use o serviço de [Conversas](/docs/api-reference/conversation-service). Ele chama o agente por você e guarda o histórico. ## Listagens [#listagens] A listagem de agentes retorna um envelope paginado: | Campo | Tipo | Descrição | | ------------- | ----------------- | ------------------------------------ | | `items` | `object[]` | Agentes da página. | | `limit` | `integer` | Tamanho da página pedido. | | `offset` | `integer` | Posição inicial da página. | | `total` | `integer \| null` | Total de agentes, quando disponível. | | `has_more` | `boolean` | Indica se há outra página. | | `next_offset` | `integer \| null` | `offset` da próxima página. | # fixed (/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/assistant-id/fixed) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {assistant_id} (/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/assistant-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # publish (/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/assistant-id/publish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # assistants (/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limit (/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/plan-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Autenticação (/docs/api-reference/authentication) Toda chamada à API envia uma credencial no header `Authorization`, no formato `Bearer `. A plataforma aceita três tipos, e a escolha define em nome de quem a chamada acontece. ```bash curl https:///api/v1/me \ -H "Authorization: Bearer " ``` ## Tipos de credencial [#tipos-de-credencial] | Credencial | Formato | Age como | Use para | | --------------------------- | ------------------------------ | ---------------- | ----------------------------------------------------------------- | | Token de usuário | JWT emitido pelo login | O usuário logado | Admin, Chat e ferramentas internas com sessão de usuário. | | Personal Access Token (PAT) | `aumo_pat__` | O dono da chave | Scripts e integrações que agem em nome de uma pessoa. | | Chave de projeto | `aumo_pk__` | A própria chave | Integrações de um workspace que não devem depender de uma pessoa. | ### Personal Access Token [#personal-access-token] Um PAT age como o usuário que o criou. Ele nunca tem mais permissão que o papel atual do dono, e fica limitado à organização, aos workspaces permitidos, aos scopes concedidos e à data de expiração. Se o dono perde acesso ou muda de papel, o PAT acompanha. O consumo de tokens e as cotas contam para o usuário dono da chave. ### Chave de projeto [#chave-de-projeto] Uma chave de projeto pertence a um único workspace e não tem dono nem papel. Os scopes concedidos na criação são toda a sua autorização. Por isso ela continua válida depois que a pessoa que a criou sai da organização. Ela só deixa de valer quando é revogada ou expira. Uso e cota são atribuídos à própria chave. Uma chave de projeto só enxerga as conversas que ela mesma criou. ## Criando uma chave [#criando-uma-chave] Chaves são criadas por workspace, no `platform-core`. O valor completo aparece **uma única vez**, na resposta de criação. Guarde-o num cofre de segredos. | Método | Rota | Ação | | -------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | `POST` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys` | Cria um PAT. | | `GET` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys` | Lista os PATs. | | `DELETE` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys/{api_key_id}` | Revoga um PAT. | | `POST` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys` | Cria uma chave de projeto. | | `GET` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys` | Lista as chaves de projeto ativas. Use `include_revoked=true` para ver as revogadas. | | `DELETE` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys/{project_key_id}` | Revoga uma chave de projeto. | Só é possível conceder a uma chave de projeto os scopes que você mesmo tem no workspace. Emitir e revogar chaves de projeto exige ser dono do projeto ou admin da organização. Para trocar uma chave, crie a nova, atualize a integração e só depois revogue a anterior. ## Scopes [#scopes] Cada endpoint exige um scope, indicado na página do endpoint como **Scope**. Os scopes seguem o padrão `:`. | Para | Scopes necessários | | -------------------------- | ------------------------------------------------------- | | Conversar com um agente | `conversations:write`, `assistants:read`, `models:read` | | Anexar arquivos no chat | `artifacts:read`, `artifacts:write` | | Publicar um agente | `assistants:publish` | | Chamar modelos diretamente | `models:read` | | Executar um workflow | `workflow_run:write` | Chamar um agente executa o modelo como o chamador. Por isso uma chave que conversa com agentes precisa também de `models:read`. Nenhuma chave pode carregar scopes de gestão de chaves. Uma chave não cria nem revoga outras chaves. # Convenções (/docs/api-reference/conventions) Todos os serviços seguem as mesmas regras de URL, erro, paginação e rastreamento. Esta página descreve essas regras uma vez, e as páginas de endpoint só registram o que foge delas. ## URL e escopo [#url-e-escopo] Todas as rotas são servidas pelo mesmo host, atrás de um gateway que encaminha cada caminho para o serviço dono. Você não precisa saber qual serviço responde. A maior parte das rotas é escopada por organização e workspace: ```text https:///api/v1/org/{org_id}/workspaces/{workspace_id}/ ``` * **`org_id`**: identificador da organização. * **`workspace_id`**: identificador do workspace dentro da organização. Use [`GET /api/v1/me`](/docs/api-reference/platform-core/me) para descobrir as organizações e workspaces a que sua credencial tem acesso. ## Erros [#erros] Respostas de erro usam um envelope comum: ```json { "error_type": "PERMISSION_DENIED", "message": "User is not allowed to access this resource", "timestamp": "2026-06-18T12:00:00Z", "correlation_id": "corr_3f2a9c1e8b7d4e6fa0b1c2d3e4f5a6b7" } ``` | Campo | Tipo | Descrição | | ---------------- | -------- | ------------------------------------------------------------------------------------------------- | | `error_type` | `string` | Código estável em maiúsculas, como `VALIDATION_ERROR` ou `NOT_FOUND`. Use-o na lógica do cliente. | | `message` | `string` | Resumo legível. Pode mudar entre versões. | | `timestamp` | `string` | Momento do erro, em ISO 8601 UTC. | | `correlation_id` | `string` | Identificador da requisição. Envie-o ao suporte. | ### Limite de plano [#limite-de-plano] Atingir um limite do plano retorna `409` com `error_type` `PLAN_LIMIT_EXCEEDED` e um campo adicional `limit`: ```json { "error_type": "PLAN_LIMIT_EXCEEDED", "message": "Limite do plano FOUNDATION atingido para Usuários por Projeto Privado: 30 de 30.", "timestamp": "2026-08-21T12:00:00Z", "correlation_id": "corr_3f2a9c1e8b7d4e6fa0b1c2d3e4f5a6b7", "limit": { "limit_key": "users_per_private_workspace", "label": "Usuários por Projeto Privado", "plan": "FOUNDATION", "limit": 30, "current": 30, "requested": 1, "source": "plan", "scope_id": "" } } ``` * **`source`**: `plan` quando o teto vem do plano, `override` quando foi ajustado para a organização. * **`unit`**: presente só em limites que não são contagem, como `GB`. Nesse caso `limit`, `current` e `requested` podem ser fracionários. ## Paginação [#paginação] Listagens aceitam `limit` e `offset` como query string. O valor máximo de `limit` é `200` em todos os serviços. Um `limit` acima de `200` retorna `422 VALIDATION_ERROR`. A API não corta o valor silenciosamente. ## Correlation ID [#correlation-id] Envie `X-Correlation-ID` para rastrear uma requisição de ponta a ponta. Se você não enviar, o gateway gera um no formato `corr_`. O mesmo valor volta no corpo de qualquer erro e acompanha a requisição por todos os serviços internos. Registre-o nos logs do seu cliente. ## Idempotência [#idempotência] Comandos com efeito colateral aceitam o header `Idempotency-Key`. Exemplos: enviar mensagem, criar run de workflow, confirmar upload, copiar workflow e disparar agendamento. * **Mesma chave, mesmo comando**: retorna o mesmo resultado, sem repetir o efeito. * **Mesma chave, comando diferente**: retorna `409 IDEMPOTENCY_CONFLICT`. Gere uma chave única, como um UUID, por operação lógica e reutilize-a nas novas tentativas dessa operação. # Conversas (/docs/api-reference/conversation-service) O `conversation-service` guarda as conversas com agentes e as mensagens de cada uma. Quando você envia uma mensagem, ele chama o agente, grava a resposta e devolve o par pergunta e resposta. Uma **conversa** sempre pertence a um agente (`assistant_id`). Uma **mensagem** tem um `role` (`user` ou `assistant`) e um `status` que vai de `pending` a `completed` ou `failed`. ## Enviando mensagens [#enviando-mensagens] Há duas formas de enviar uma mensagem, com o mesmo corpo: * **[`POST .../messages`](/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages)**: espera o agente terminar e retorna a mensagem do usuário e a resposta, nessa ordem. * **[`POST .../messages/stream`](/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/stream)**: retorna um fluxo `text/event-stream` com a resposta aos pedaços. As duas aceitam `Idempotency-Key`. A credencial precisa de `conversations:write`, `assistants:read` e `models:read`. ## Eventos do streaming [#eventos-do-streaming] Cada evento tem um nome em `event:` e um JSON em `data:`, cujo campo `type` repete o nome. | Evento | Quando chega | Conteúdo | | --------------------- | --------------------------------------------- | ------------------------------------------------------------ | | `started` | Primeiro evento do fluxo. | `correlation_id` da requisição. | | `message` | Ao criar a mensagem do usuário e a do agente. | `message`: a mensagem completa. | | `chunk` | A cada pedaço de texto gerado. | `message_id` e `content`, o trecho novo. Concatene na ordem. | | `docs_used` | Quando o agente consulta uma coleção. | `message_id` e a consulta usada. | | `tool_response` | Quando uma ferramenta devolve resultado. | `message_id` e `tool_response`. | | `mcp_progress` | Durante uma ferramenta MCP demorada. | `message_id`, `message` e `progress`. | | `attachment_warnings` | Quando um anexo não pôde ser usado. | `message_id` e `warnings`. | | `done` | Resposta concluída. | `message`: a resposta final do agente. | | `error` | Falha durante o fluxo. | `status_code` e `data` com `error_code` e `message`. | | `heartbeat` | Depois de `done`, antes de fechar. | Nada além de `type`. | Depois que o fluxo começa, o status HTTP já é `200`, então falhas chegam como evento `error`. Os `error_code` possíveis são `NOT_FOUND`, `INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN` e `INTERNAL_ERROR`. Se o cliente desconectar no meio do fluxo, a plataforma ainda grava a resposta do agente no estado em que parou. # {artifact_id} (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/attachments/artifact-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # attachments (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/attachments) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {conversation_id} (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # last-message (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/last-message) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # mcp-elicitation (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/mcp-elicitation) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # messages (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # rating (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/message-id/rating) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stop (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/message-id/stop) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stream (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/stream) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stop (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/stop) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # title (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/title) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # conversations (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-message-count (/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/user-message-count) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Uso e feedback (/docs/api-reference/governance-telemetry) O `governance-telemetry` registra o consumo da plataforma: chamadas a modelos, tokens usados e eventos de uso. Ele também guarda as avaliações de respostas e as pesquisas de NPS, e define as cotas de tokens. ## Organização e workspace [#organização-e-workspace] A maior parte das rotas existe em dois níveis, com o mesmo formato: * **Organização**: `/api/v1/org/{org_id}/...` soma o uso de todos os workspaces. * **Workspace**: `/api/v1/org/{org_id}/workspaces/{workspace_id}/...` restringe ao workspace. Avaliações de respostas (`feedback-records`) e NPS existem só no nível de workspace. # dashboard (/docs/api-reference/governance-telemetry/org-org-id/dashboard) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # model-invocations (/docs/api-reference/governance-telemetry/org-org-id/model-invocations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # breakdown (/docs/api-reference/governance-telemetry/org-org-id/model-usage/breakdown) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # series (/docs/api-reference/governance-telemetry/org-org-id/model-usage/series) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # summary (/docs/api-reference/governance-telemetry/org-org-id/model-usage/summary) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # timeseries (/docs/api-reference/governance-telemetry/org-org-id/model-usage/timeseries) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-usage (/docs/api-reference/governance-telemetry/org-org-id/quota-usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/token-usage/provider-provider-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {grant_id} (/docs/api-reference/governance-telemetry/org-org-id/token-usage/quota-grants/grant-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-grants (/docs/api-reference/governance-telemetry/org-org-id/token-usage/quota-grants) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/token-usage/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quota (/docs/api-reference/governance-telemetry/org-org-id/token-usage/user-quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quotas (/docs/api-reference/governance-telemetry/org-org-id/token-usage/user-quotas) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/token-usage/user-user-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # traces (/docs/api-reference/governance-telemetry/org-org-id/traces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {trace_id} (/docs/api-reference/governance-telemetry/org-org-id/traces/trace-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/docs/api-reference/governance-telemetry/org-org-id/usage-logs/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage-logs (/docs/api-reference/governance-telemetry/org-org-id/usage-logs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {log_id} (/docs/api-reference/governance-telemetry/org-org-id/usage-logs/log-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # dashboard (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/dashboard) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {feedback_id} (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records/feedback-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # feedback-records (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # latest (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records/nps/latest) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # model-invocations (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-invocations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # breakdown (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/breakdown) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # series (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/series) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # summary (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/summary) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # timeseries (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/timeseries) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # ranking (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/nps/ranking) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # report (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/nps/report) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-usage (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/quota-usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/project-key-project-key-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # project-key-quota (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/project-key-quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # project-key-quotas (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/project-key-quotas) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/provider-provider-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {grant_id} (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/quota-grants/grant-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-grants (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/quota-grants) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quota (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/user-quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quotas (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/user-quotas) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/user-user-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # traces (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/traces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {trace_id} (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/traces/trace-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage-events (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-logs/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage-logs (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-logs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {log_id} (/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-logs/log-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # API Reference (/docs/api-reference) A API da AUMO é a mesma que o Admin e o Chat usam. Todas as rotas passam por um único gateway e cada recurso pertence a um serviço, que dá nome às seções desta referência. Quase toda rota vive dentro de uma organização e de um workspace: `/api/v1/org/{org_id}/workspaces/{workspace_id}/...`. Antes de chamar qualquer endpoint, leia [Autenticação](/docs/api-reference/authentication) e [Convenções](/docs/api-reference/conventions). ## Primeiros passos [#primeiros-passos] Escolher entre token de usuário, Personal Access Token e chave de projeto. Formato de erro, paginação, correlation id e idempotência, comuns a todos os serviços. ## Como ler esta referência [#como-ler-esta-referência] Cada serviço lista suas rotas na barra lateral como uma árvore de arquivos, a partir de `/api/v1`. Cada segmento do caminho é um item: * **Página**: o caminho tem operações. Todos os métodos daquele caminho ficam na mesma página, com playground, parâmetros, corpo, respostas e exemplos de código. * **Pasta**: o caminho tem sub-rotas. Quando ele também tem operações, a pasta abre a própria página. * **Prefixo agrupado**: segmentos sem operação próprias, como `org/{org_id}/workspaces/{workspace_id}`, aparecem juntos num item só. ## Serviços [#serviços] Usuário atual, organizações, workspaces, membros, chaves, modelos e servidores MCP. Criar, configurar e publicar agentes. Abrir conversas com um agente e trocar mensagens, com ou sem streaming. Gerenciar workflows, publicar versões e executar runs. Chamar modelos de linguagem por uma interface compatível com OpenAI. Coleções de conhecimento, documentos e status de indexação. Credenciais, conectores, sincronização e upload de documentos. Recuperar os trechos mais relevantes de uma coleção para uma pergunta. Enviar, baixar e anexar arquivos a conversas. Executar workflows e sincronizações em horários definidos. Consumo de tokens, cotas, logs de uso, avaliações e NPS. # Catálogo (/docs/api-reference/knowledge-catalog) O `knowledge-catalog` guarda as **coleções** de conhecimento e os **documentos** de cada uma. Ele acompanha o estado de cada documento, do envio até ficar pronto para busca. Conectores e upload de arquivos ficam em [Ingestão](/docs/api-reference/knowledge-ingestion). A busca por trechos fica em [Busca (RAG)](/docs/api-reference/retrieval-rag). ## Acompanhando a indexação [#acompanhando-a-indexação] Para saber quando uma coleção está pronta, consulte `GET .../knowledge-collections/{collection_id}/status`. Ele devolve só contagens por status, sem listar documentos, e é indicado para polling. Para receber as mudanças assim que acontecem, use o streaming em `.../knowledge-collections/{collection_id}/events`. # delete-file (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/delete-file) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # content (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/download-file/content) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download-file (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/download-file) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # search-files (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/search-files) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # semantic-search (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/semantic-search) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # update-file (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/update-file) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # document-stats (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/document-stats) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # search (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/documents/search) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {collection_id} (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # status (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/status) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # knowledge-collections (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limit (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/plan-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # storage-limit (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/storage-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {document_id} (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-documents/document-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # refresh (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-documents/document-id/refresh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # knowledge-documents (/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-documents) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # callback (/docs/api-reference/knowledge-ingestion/connectors-oauth/callback) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Ingestão (/docs/api-reference/knowledge-ingestion) O `knowledge-ingestion` traz conteúdo de fora para as coleções. Ele guarda as credenciais de acesso às fontes, sincroniza os conectores e recebe uploads. Cada **conector** pertence a uma coleção: a criação exige `collection_id`. Cada sincronização gera um **sync run**, com métricas de progresso. ## Credenciais e OAuth [#credenciais-e-oauth] Credenciais pertencem à organização, não ao workspace, e por isso ficam em `/api/v1/org/{org_id}/credentials`. Conectores com OAuth começam a autorização em `.../connectors/oauth/{provider}/start`. # start (/docs/api-reference/knowledge-ingestion/org-org-id/connectors-oauth/provider/start) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # readiness (/docs/api-reference/knowledge-ingestion/org-org-id/connectors-oauth/readiness) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {credential_id} (/docs/api-reference/knowledge-ingestion/org-org-id/credentials/credential-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # credentials (/docs/api-reference/knowledge-ingestion/org-org-id/credentials) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {connector_id} (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # sync-runs (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id/sync-runs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # cancel (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id/sync-runs/sync-run-id/cancel) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # items (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id/sync-runs/sync-run-id/items) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # items (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/google-drive/items) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # shared-drives (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/google-drive/shared-drives) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # connectors (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # reprocess (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-documents-document-id/reprocess) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # confirm (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-uploads/confirm) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download-url (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-uploads/download-url) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # presign (/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-uploads/presign) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Modelos (/docs/api-reference/model-gateway) O `model-gateway` é a porta única para modelos de linguagem. Ele recebe chamadas no formato da API da OpenAI, encaminha ao provedor configurado e registra consumo e cotas. Os modelos disponíveis são os habilitados no workspace. Liste-os com `GET .../workspaces/{workspace_id}/models`, servido pela [Plataforma](/docs/api-reference/platform-core). Inferência exige o scope `models:read`. ## Cotas [#cotas] Cada chamada passa pelos limites de consumo da organização, do workspace, do provedor e do usuário. Uma chamada com Personal Access Token conta para o dono da chave. Para uma integração automatizada, crie um PAT exclusivo, limitado aos workspaces necessários. Veja [Autenticação](/docs/api-reference/authentication). # speech (/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/audio/speech) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # transcriptions (/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/audio/transcriptions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # completions (/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/chat/completions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # reconcile (/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/quota/reconcile) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # responses (/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/responses) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stop (/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/responses/response-id/stop) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Plataforma (/docs/api-reference/platform-core) O `platform-core` é o serviço de controle da plataforma. Ele guarda quem é o usuário, a que organizações e workspaces tem acesso e o que pode fazer em cada um. Também é dono do catálogo de provedores e modelos, das chaves de API, das variáveis do workspace e da configuração de servidores MCP. Agentes, workflows, conversas e conhecimento ficam em serviços próprios. ## Descobrindo `org_id` e `workspace_id` [#descobrindo-org_id-e-workspace_id] Quase toda rota pede uma organização e um workspace. Chame [`GET /api/v1/me`](/docs/api-reference/platform-core/me) com a sua credencial: a resposta lista as organizações e os workspaces a que ela tem acesso, com o papel e os scopes em cada um. ## Chaves de API [#chaves-de-api] As rotas `api-keys` e `project-keys` do workspace criam e revogam Personal Access Tokens e chaves de projeto. Veja [Autenticação](/docs/api-reference/authentication) para escolher entre elas. # avatar (/docs/api-reference/platform-core/me/avatar) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # me (/docs/api-reference/platform-core/me) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {entry_id} (/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # installations (/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id/installations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # unfilled-configuration-keys (/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id/unfilled-configuration-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workspaces (/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id/workspaces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # integration-registry (/docs/api-reference/platform-core/org-org-id/integration-registry) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # rescan (/docs/api-reference/platform-core/org-org-id/mcp-servers-server-id-runtime/rescan) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # import (/docs/api-reference/platform-core/org-org-id/members/import) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # members (/docs/api-reference/platform-core/org-org-id/members) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {member_user_id} (/docs/api-reference/platform-core/org-org-id/members/member-user-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # org-providers (/docs/api-reference/platform-core/org-org-id/org-providers) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # catalog (/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id/catalog) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # deactivate (/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id/deactivate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {provider_resource_id} (/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # reactivate (/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id/reactivate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limits (/docs/api-reference/platform-core/org-org-id/plan-limits) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage (/docs/api-reference/platform-core/org-org-id/plan-limits/limit-key/usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # aumo-assistant (/docs/api-reference/platform-core/org-org-id/settings/aumo-assistant) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # autocurator (/docs/api-reference/platform-core/org-org-id/settings/autocurator) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {key} (/docs/api-reference/platform-core/org-org-id/settings/key) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # config (/docs/api-reference/platform-core/org-org-id/superagents-provider-resource-id/config) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # status (/docs/api-reference/platform-core/org-org-id/terms-of-service/status) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # accept (/docs/api-reference/platform-core/org-org-id/terms-of-service/tos-id/accept) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # all (/docs/api-reference/platform-core/org-org-id/workspaces/all) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workspaces (/docs/api-reference/platform-core/org-org-id/workspaces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {collection} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/admin-collections/collection) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {resource_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/admin-collections/collection/resource-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {api_key_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/api-keys/api-key-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # api-keys (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/api-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {credential_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/email-credentials/credential-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # email-credentials (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/email-credentials) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {workspace_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # install (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/integration-registry-entry-id/install) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # integration-tools (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/integration-tools) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {integration_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/integration-tools/integration-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # kv (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/kv) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {kv_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/kv/kv-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # unfilled-configuration-keys (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-registry-entry-id/unfilled-configuration-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # validate-security (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-registry-entry-id/validate-security) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # available (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/available) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # install (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/install) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # auth (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/auth) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # start (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/auth/start) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # connect (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/connect) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # dependents (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/dependents) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # prompts (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/prompts) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # resources (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/resources) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # runtime (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/runtime) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # logs (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/runtime/logs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # start (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/runtime/start) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # security-override (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/security-override) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # call (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/tools/call) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # tools (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/tools) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # import (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/members/import) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # members (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/members) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {member_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/members/member-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # models (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # disable (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models/model-id/disable) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # enable (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models/model-id/enable) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {model_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models/model-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # provision (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/org-providers/aumo/provision) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # sync (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/org-providers/provider-resource-id-models/sync) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/plan-limits-limit-key/usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # project-keys (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/project-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {project_key_id} (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/project-keys/project-key-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # catalog (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/providers/catalog) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # providers (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/providers) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # credentials (/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/providers/provider-id/credentials) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Busca (RAG) (/docs/api-reference/retrieval-rag) O `retrieval-rag` divide os documentos em trechos, gera embeddings e guarda tudo num índice vetorial. Na consulta, ele devolve os trechos mais próximos da pergunta, com reranking. Os agentes usam esta busca automaticamente quando têm coleções. Chame `POST .../retrieve` diretamente quando quiser os trechos sem passar por um agente. ## Indexação [#indexação] A indexação de documentos é feita pela [Ingestão](/docs/api-reference/knowledge-ingestion) e não é exposta para clientes externos. # retrieve (/docs/api-reference/retrieval-rag/org-org-id-workspaces-workspace-id/retrieve) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Agendamentos (/docs/api-reference/scheduler-service) O `scheduler-service` guarda os **agendamentos** e dispara cada execução no horário certo. Cada disparo é um **trigger**, com tentativas automáticas em caso de falha. ## Agendamentos de workflow [#agendamentos-de-workflow] Um agendamento de workflow executa sempre a versão publicada, em nome de quem o criou. Se essa pessoa perder acesso ao workflow, o agendamento deixa de rodar. Para agendar um workflow, você também pode usar `POST .../workflows/{workflow_id}/schedule` em [Workflows](/docs/api-reference/workflows-service). # schedules (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # cancel (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/cancel) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {schedule_id} (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # pause (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/pause) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # resume (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/resume) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # trigger-now (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/trigger-now) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # triggers (/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/triggers) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Workflows (/docs/api-reference/workflows-service) O `workflows-service` guarda a definição de cada workflow, as versões publicadas e o histórico de alterações. Ele também executa os workflows: cada execução é um **run**. O workflow que você edita e a versão publicada são coisas separadas. Publicar cria uma versão nova; editar o workflow depois disso não altera o que já foi publicado. ## Qual versão é executada [#qual-versão-é-executada] Um run precisa de uma versão publicada. Sem ela, a chamada retorna `409`. * **Workflow publicado**: executa a última versão publicada. * **Publicado com edições pendentes**: executa a versão publicada. As edições só entram depois de publicar de novo. * **Rascunho do dono**: com `allow_draft_run: true`, o dono do workflow executa a definição em edição, mesmo sem versão publicada. ## Esperando o resultado [#esperando-o-resultado] Por padrão, [`POST .../workflows/{workflow_id}/runs`](/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/runs) retorna na hora, com o run em `pending`. Com `wait=true`, a chamada espera o run chegar a `completed`, `failed` ou `cancelled`, por até `wait_timeout` segundos (padrão `30`, máximo `300`). Se o tempo acabar antes, a resposta traz o run no estado em que estava. Continue consultando `GET .../runs/{run_id}`. # runs (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # cancel (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id/cancel) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {run_id} (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stream (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id/stream) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workflow-tool-contracts (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflow-tool-contracts) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # import (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/import) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workflows (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limit (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/plan-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # versions (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/published/versions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # copy (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/copy) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # compare (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/diffs/compare) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {diff_id} (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/diffs/diff-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # diffs (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/diffs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {workflow_id} (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # mcp-auth-preflight (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/mcp-auth-preflight) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # publish (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/publish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # republish (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/republish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # revert (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/revert) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # runs (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/runs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stream (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/runs/stream) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # schedule (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/schedule) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # tool-contract (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/tool-contract) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # unpublish (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/unpublish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # validate (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/validate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # versions (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/versions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {version_id} (/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/versions/version-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Membros (/docs/user-guide/admin/members) Participar da plataforma tem dois níveis. **Organização › Membros** é a porta de entrada da empresa; **Workspace › Membros** decide quem participa de cada time. Os dois se somam, e é comum alguém ser Usuário na organização e Proprietário em um workspace. ## Membros da organização [#membros-da-organização] A tela abre para **Superadmin**, **Admin** e, em leitura, **Auditor**. Quatro colunas, **Nome**, **Email**, **Papel** e **Ações**, com busca por nome ou e-mail. Para convidar, clique em **+ Membro**. Na janela **Convidar um Novo Membro**, informe o e-mail, escolha o papel e clique em **Adicionar**: * **Superadmin**: acesso total à organização. * **Admin**: permissões amplas sobre a organização, sem alcançar provedores, credenciais e configurações gerais. * **Auditor**: somente leitura nos menus da organização. * **Usuário**: nenhuma permissão na organização. É o papel de quem só usa o Chat. **Superadmin** e **Admin** dividem o mesmo limite de vagas da organização, e o contador aparece ao lado de cada um na lista de papéis. Quando o limite acaba, os dois ficam desabilitados no convite. Até a pessoa entrar pela primeira vez, a coluna **Nome** mostra o próprio e-mail. O convite vale para a empresa, não para um workspace. Alguém convidado como Usuário entra e ainda não participa de nada, e verá as áreas de Workspace e Chat desabilitadas até ser adicionado a um. Adicionar como Usuário e depois incluir nos workspaces certos é o caminho normal para a maioria das pessoas. Papel de organização é para quem administra a empresa, não para quem usa a plataforma. ## Membros do workspace [#membros-do-workspace] A tela é acessível ao **Proprietário**; **Auditor** a vê em leitura. Só é possível adicionar pessoas que já pertencem à organização. Quem ainda não foi convidado precisa passar antes pela tela da organização. Os papéis de workspace são: * **Proprietário**: acesso total, incluindo Integrações, Chaves de API e excluir o workspace. * **Curador**: cria Coleções, Agentes, Workflows, MCPs e Variáveis, e lê Painel, Conversas, Avaliações e Quotas. * **Editor**: mesmo poder de criação do Curador, sem as telas de acompanhamento e configuração. * **Auditor**: só leitura na maior parte do workspace. * **Usuário**: sem telas de administração. Conversa no Chat. ## Quem não aparece na lista [#quem-não-aparece-na-lista] Papéis de organização de nível Superadmin, Admin e Auditor alcançam qualquer workspace **sem constar na lista de membros dele**. Se alguém edita coisas em um workspace e você não o encontra em Membros, é por esse caminho. ## Alterar e remover [#alterar-e-remover] O menu de ações permite trocar o papel e remover a pessoa, em ambas as telas. A diferença está no alcance: remover alguém do **workspace** tira o acesso àquele time, e a pessoa continua na empresa. Remover da **organização** tira o acesso a tudo, incluindo todos os workspaces de que participava. Trocar o papel vale imediatamente, no próximo carregamento da tela da pessoa. ## Exportar [#exportar] A tela da organização tem dois botões de ícone ao lado de **+ Membro**. **Importar membros** convida várias pessoas de uma vez a partir de um arquivo. **Exportar membros** baixa a lista em CSV ou JSON, o caminho prático para conferência de acesso e auditoria periódica. ## Próximos passos [#próximos-passos] * Entenda a soma dos dois níveis em [Papéis e permissões](/docs/user-guide/concepts/roles). * Veja o que cada time recebe da empresa em [Workspaces](/docs/user-guide/admin/workspaces). # Automações de IA (/docs/user-guide/admin/org-settings/ai-automations) Alguns recursos da plataforma chamam um modelo sozinhos, sem que ninguém peça. A aba **Automações de IA** é onde você escolhe qual modelo cada um deles usa. Todos consomem tokens como qualquer outra chamada. ## As automações [#as-automações] * **Auto Curador**: organiza e categoriza automaticamente os dados do workspace. * **Busca Semântica**: aprimora a busca nos conteúdos da organização. * **Renomear Chats**: gera o título das conversas a partir do conteúdo. O prompt usado é editável. * **Workspace Pessoal do Admin**: modelo dos recursos automáticos do workspace administrativo. * **Sugestão de Código**: sugere código em Workflows e automações. Cada uma tem seu próprio seletor de modelo. Nada obriga que sejam o mesmo. ## Escolhendo o modelo [#escolhendo-o-modelo] Essas tarefas são curtas, repetitivas e de baixa exigência, como resumir uma conversa em uma frase ou categorizar um documento. Modelos grandes não melhoram muito o resultado e multiplicam o custo. O critério prático é o inverso do de um Agente: aqui, comece pelo modelo mais barato disponível e só suba se a qualidade atrapalhar. O consumo dessas automações aparece na Observabilidade **sem estar atrelado a um Agente**. Um custo que ninguém consegue explicar, distribuído ao longo do dia, costuma vir daqui, em especial do Renomear Chats, que dispara a cada conversa nova. ## O prompt do Renomear Chats [#o-prompt-do-renomear-chats] É a única automação com prompt editável. O padrão pede um resumo curto em uma frase. Ajustá-lo muda o título de todas as conversas novas da organização. Títulos longos demais quebram no menu lateral do Chat, então vale manter a instrução de brevidade. ## Próximos passos [#próximos-passos] * Acompanhe o custo dessas chamadas em [Observabilidade](/docs/user-guide/monitoring/observability). * Configure o agente de apoio da plataforma em [Agente de chat](/docs/user-guide/admin/org-settings/chat-agent). # Agente de chat (/docs/user-guide/admin/org-settings/chat-agent) O **Agente de Chat** é o assistente de apoio da própria plataforma. Ele responde dúvidas de quem está usando a AUMO, sem que a pessoa precise sair da tela. É diferente dos Agentes que você cria nos workspaces: ele não usa as Coleções da sua organização e não aparece no seletor de Agentes do Chat. ## Ativar [#ativar] A aba traz a chave de ativação e o seletor de modelo. Enquanto estiver desativado, o atalho não aparece para ninguém na organização. Apenas modelos **AUMO com capacidade de visão** podem ser usados aqui. Modelos de outros provedores, e modelos AUMO sem visão, não constam na lista de escolha. ## Captura de tela [#captura-de-tela] A opção **Permitir captura de tela** define se o agente pode enxergar a tela de quem pede ajuda. Com ela ligada, a pessoa consegue perguntar sobre o que está vendo sem descrever a tela. É também a razão de o modelo precisar de capacidade de visão. Uma captura de tela carrega o que estiver visível no momento, incluindo dados de clientes abertos em uma Coleção ou em uma conversa. Avalie isso antes de ligar a opção em organizações que tratam dados sensíveis. ## Consumo [#consumo] As conversas com o Agente de Chat consomem tokens do provedor AUMO e aparecem na Observabilidade como as demais chamadas. Como as capturas de tela são enviadas como imagem, o consumo por mensagem é maior que o de uma pergunta em texto. ## Próximos passos [#próximos-passos] * Veja os demais recursos automáticos em [Automações de IA](/docs/user-guide/admin/org-settings/ai-automations). * Entenda o provedor que sustenta este recurso em [O provedor AUMO](/docs/user-guide/models/providers/aumo). # Guardrails (/docs/user-guide/admin/org-settings/guardrails) **Guardrails** filtram o que trafega entre as pessoas e os modelos de IA, para manter as respostas alinhadas às políticas da organização. Eles valem para a organização inteira e não dependem de cada Agente estar configurado corretamente. É o controle que sobrevive a um prompt mal escrito. ## As duas direções [#as-duas-direções] Um guardrail age em um de dois pontos do percurso: * **Na ida**: bloqueia ou mascara informação sensível antes que ela chegue ao modelo. É o que impede um CPF colado no chat de sair da organização. * **Na volta**: filtra o que o modelo devolveu, antes de exibir à pessoa. A lista na tela mostra o conjunto ativo, com o **tipo** de cada regra. ## Por que na organização e não no Agente [#por-que-na-organização-e-não-no-agente] Um Agente é criado por quem constrói no workspace, com o prompt que quiser. Confiar a proteção de dados a esse prompt significa confiar em cada pessoa que cria um Agente. Guardrails ficam acima disso. Um Agente novo nasce coberto pelas regras da organização sem que ninguém precise lembrar de configurá-las. Guardrails atuam sobre o conteúdo das mensagens, não sobre o que um MCP faz. Uma ferramenta que envia dados a um sistema externo não passa por este filtro. ## Efeito no dia a dia [#efeito-no-dia-a-dia] Regras apertadas demais recortam respostas legítimas, e a pessoa no Chat vê o resultado já filtrado, sem explicação do que foi removido. Quando alguém relata uma resposta incompleta sem causa aparente, esta tela é um dos lugares a conferir, junto do estado dos documentos na Coleção. ## Próximos passos [#próximos-passos] * Limite o alcance dos conectores em [Domínios de conhecimento](/docs/user-guide/knowledge/allowed-domains). * Veja o que mais ocupa esta tela em [Configurações](/docs/user-guide/admin/org-settings). # Visão geral (/docs/user-guide/admin/org-settings) **Configurações** reúne os ajustes que valem para a organização inteira, distribuídos em seis abas. A tela exige o papel **Superadmin**; nem Admin nem Auditor a alcançam. ## Identidade [#identidade] A aba **Geral** guarda o que identifica a organização: * **Nome**: como ela aparece no seletor de organização e no topo da tela. * **Slug**: o identificador que entra na URL de todas as páginas, no formato `/organization/`. * **Logo**: a imagem exibida no alto da barra de áreas. Trocar o slug altera o endereço de todas as páginas da organização. Links salvos e favoritos apontando para o slug antigo deixam de funcionar. A aba também dá acesso rápido a Workspaces e Membros, que têm telas próprias na barra lateral. ## Informações [#informações] A última aba mostra, em leitura, os dados de identificação e do plano contratado. É onde conferir o que está vigente antes de falar com a AUMO sobre limites ou recursos. ## As demais abas [#as-demais-abas] Filtrar o que trafega entre as pessoas e os modelos. Limitar quais domínios externos os conectores podem alcançar. Escolher o modelo de cada recurso automático da plataforma. Ativar o agente de apoio que atende dentro da plataforma. O **Scanner de Segurança MCP** também mora nesta tela, mas é documentado junto do registro de servidores, em [Scanner de segurança](/docs/user-guide/tools/mcp/security). # Ajustes do workspace (/docs/user-guide/admin/workspace-settings) **Configurações › Geral** é a tela curta do workspace: identidade, visibilidade e a zona de exclusão. Ela é acessível ao **Proprietário**; **Auditor** a vê em leitura. ## Identidade [#identidade] * **Nome do Workspace**: editável pelo ícone ao lado do valor. É como o workspace aparece no seletor e na lista da organização. * **Criado em**: a data de criação, em leitura. Trocar o nome não altera o identificador do workspace na URL. Links existentes continuam funcionando. ## Visibilidade [#visibilidade] A chave de **Visibilidade** alterna o workspace entre público e restrito dentro da organização. Público significa visível para quem não é membro, não acessível por qualquer um. Permissão continua sendo decidida pelo papel: quem não é membro e não tem papel de organização de nível Superadmin, Admin ou Auditor não entra. Visibilidade é descoberta, não controle de acesso. Para restringir de fato quem alcança o workspace, o que vale é a lista de [Membros](/docs/user-guide/admin/members) e os papéis de organização. ## Deleção de workspace [#deleção-de-workspace] A seção de exclusão fica recolhida e destacada em vermelho, ao pé da tela. Excluir um workspace remove o acesso a tudo que vive dentro dele: Coleções, Agentes, Workflows, Variáveis e o histórico de conversas. A exclusão não é reversível pela interface. Workspaces excluídos continuam aparecendo na lista da organização com o selo **Workspace deletado**, mas o conteúdo não volta. Antes de excluir, confira duas coisas. Se algum Agente daquele workspace está em uso por pessoas de outros times, e se há Coleções que valha a pena recriar em outro lugar, porque não existe exportação entre workspaces. ## Próximos passos [#próximos-passos] * Controle quem participa em [Membros](/docs/user-guide/admin/members). * Entenda o que o workspace recebe da empresa em [Workspaces](/docs/user-guide/admin/workspaces). # Workspaces (/docs/user-guide/admin/workspaces) **Workspaces** é a lista de todos os workspaces da organização e o ponto de onde se controla o que cada um recebe. É aqui que o catálogo da empresa vira recurso disponível para um time. Um modelo cadastrado em Provedores só chega a um Agente depois de passar por esta tela. ## A lista [#a-lista] Cada card traz o nome do workspace, o seu papel nele e há quanto tempo foi criado. Workspaces removidos continuam visíveis com o selo **Workspace deletado**. O filtro no topo divide a lista por relação: * **Todos**: tudo o que você enxerga na organização. * **Meus Workspaces**: aqueles de que você é membro. * **Outros Workspaces**: aqueles que você alcança pelo papel de organização, sem ser membro. * **Auditáveis**: disponível para o papel Auditor. ## Criar um workspace [#criar-um-workspace] Clique em **+ Workspace**, informe o **Nome do Workspace** e clique em **Criar Workspace**. Só **Superadmin** e **Admin** criam workspaces, e o contador no topo da lista mostra quantos a organização ainda pode criar. Ao criar, você é levado direto para o **Painel** do novo workspace. Um workspace recém-criado nasce vazio: sem modelos habilitados, sem MCPs, sem Integrações. Ele não consegue criar Agentes até receber ao menos um modelo. ## O que atribuir a um workspace [#o-que-atribuir-a-um-workspace] Ao abrir um workspace nesta tela, você encontra as abas que controlam o que ele recebe do catálogo: * **Modelos**: quais modelos, dentre os dos provedores da organização, ficam disponíveis ali. * **SuperAgentes**: quais agentes externos o time pode usar. * **MCP**: quais servidores do registro ficam instaláveis. * **Credenciais**: as credenciais de e-mail, com o remetente que os Workflows daquele workspace usam para enviar mensagens. Cada uma aponta para uma credencial **SMTP** cadastrada em [Credenciais](/docs/user-guide/tools/credentials). * **Integrações**: quais integrações cadastradas ficam disponíveis. A aba **Configurações** reúne os demais ajustes do workspace. Atribuir um modelo aqui é o passo que costuma ser esquecido. Um workspace sem modelo não deixa criar Agente, e a mensagem na tela de criação não explica que a causa está nesta página. ## Visibilidade [#visibilidade] Cada workspace tem uma configuração de visibilidade, que define se ele aparece para quem não é membro. Ela é alterada no menu de ações do workspace. Isso não substitui permissão: papéis de organização de nível Superadmin, Admin e Auditor continuam alcançando qualquer workspace. ## Próximos passos [#próximos-passos] * Cadastre os provedores que alimentam a lista de modelos em [Provedores](/docs/user-guide/models/providers). * Registre os servidores instaláveis em [MCPs](/docs/user-guide/tools/mcp). * Entenda a divisão entre catálogo e instalação em [Organizações e Workspaces](/docs/user-guide/concepts/organizations-workspaces). # Criar um agente (/docs/user-guide/agents/create) O formulário de **Criar agente** é uma página única com seções recolhíveis. Você preenche de cima para baixo e só abre o que for usar. Antes de começar, confirme que o workspace tem ao menos um modelo habilitado em **Configurações › Modelos**. Sem isso o campo **Modelo** fica vazio e o formulário não salva. Para abrir o formulário, vá em **Workspace › Agentes**, clique em **+ Agente** e escolha **Criar do zero**. A outra opção, **Criar de um template** (Beta), parte de um agente pronto do Marketplace. ## Dados básicos [#dados-básicos] Quatro campos, dos quais dois são obrigatórios: * **Nome**: como o Agente aparece no seletor do Chat. * **Modelo**: qual modelo ele usa. Dentre os habilitados no workspace. * **Logo do agente**: opcional, ajuda a distinguir visualmente na lista. * **Descrição**: opcional, mas é o que a pessoa lê para decidir se é este o Agente que ela quer. Nome e descrição são a interface do Agente para quem não o construiu. Descreva o trabalho dele, como "dúvidas sobre a política de despesas", e não a tecnologia. ## Prompt de resposta ao usuário [#prompt-de-resposta-ao-usuário] A seção já vem preenchida com um texto padrão que funciona. O editor tem prévia lado a lado e acesso a uma **Biblioteca de Prompts**. O que colocar aqui está em [Escrever o prompt](/docs/user-guide/agents/prompt). ## Coleções [#coleções] Adicione as Coleções que este Agente deve consultar. É esta associação, e nada mais, que liga a busca no conhecimento. Com ao menos uma Coleção, aparecem abaixo as **configurações de busca e contexto**. Sem nenhuma, o Agente responde apenas com modelo, ferramentas e prompt, e o rodapé do formulário diz isso explicitamente. Não existe uma chave de "ativar RAG". A presença de Coleções é a chave. ## MCPs e Integrações [#mcps-e-integrações] Marque as ferramentas que este Agente pode acionar, entre as instaladas no workspace. A seção de MCPs traz o **máximo de iterações**: quantas vezes, em uma única resposta, o Agente pode chamar ferramentas antes de concluir. É o que evita um laço quando uma ferramenta devolve algo inesperado. Instalar um MCP no workspace não o entrega ao Agente. Ele precisa ser marcado aqui. ## Sandbox [#sandbox] Dá ao Agente um ambiente persistente para executar comandos e trabalhar com arquivos. Vem **Desativado**; ligue em **Habilitar sandbox?** só se o trabalho do Agente exigir isso. ## Sub-agentes [#sub-agentes] Permite expor este Agente como ferramenta e selecionar outros Agentes como apoio. Serve para dividir responsabilidades, como um Agente que sabe de RH e outro do catálogo de produtos, em vez de inchar um prompt só. O Agente principal continua sendo quem fala com a pessoa. ## Opções avançadas [#opções-avançadas] * **Temperatura**: quanto o modelo varia entre respostas. Valores baixos deixam as respostas mais previsíveis e repetíveis. * **Máximo de tokens por resposta**: o corte de tamanho. Respostas truncadas no meio de uma frase costumam ser este campo. Para o primeiro Agente, os padrões servem. ## Salvar [#salvar] No rodapé, o botão é **Salvar rascunho**. Marcando **Publicar ao salvar**, ele vira **Salvar e publicar**. Depois de salvar, você volta para a lista de Agentes. A diferença está em [Publicar e manter](/docs/user-guide/agents/publish). ## Próximos passos [#próximos-passos] * Escreva instruções que se sustentem em [Escrever o prompt](/docs/user-guide/agents/prompt). * Prepare o conhecimento antes de publicar em [Coleções](/docs/user-guide/knowledge). # Visão geral (/docs/user-guide/agents) Um **Agente** é a unidade com que as pessoas conversam no Chat. Ele reúne um modelo, instruções em texto e o acesso às Coleções e ferramentas deste workspace. Criar e editar Agentes exige papel de **Proprietário**, **Curador** ou **Editor**. ## A lista [#a-lista] A tela mostra os Agentes em grade ou tabela, com busca por nome. Cada card traz o nome, a descrição, o ícone do provedor do modelo e quando foi alterado pela última vez. O botão **+ Agente** abre o formulário de criação. Ele também dá acesso à criação a partir de um modelo pronto, quando o workspace tem templates disponíveis. ## O que define um Agente [#o-que-define-um-agente] O formulário é uma página só, dividida em seções que você abre conforme precisa: * **Dados básicos**: nome, modelo, logo e descrição. * **Prompt de resposta ao usuário**: as instruções permanentes. * **Coleções**: o conhecimento que ele consulta. * **MCPs**, **Integrações** e **Sub-agentes**: as ferramentas e apoios que ele pode acionar. * **Opções avançadas**: temperatura e máximo de tokens por resposta. Só nome, modelo e prompt são obrigatórios. Percorrer o formulário seção a seção. O que colocar nas instruções e o que deixar de fora. Rascunho, publicação e o que muda para quem já usava. # Escrever o prompt (/docs/user-guide/agents/prompt) O **Prompt de resposta ao usuário** são as instruções permanentes do Agente. Elas entram em toda mensagem, antes do histórico e dos trechos recuperados das Coleções. O editor tem formatação, prévia lado a lado e uma **Biblioteca de Prompts** com textos reaproveitáveis. ## O que o prompt decide [#o-que-o-prompt-decide] Instruções permanentes são boas para quatro coisas: * **Papel**: quem o Agente é e para quem responde. * **Escopo**: o que está dentro e o que está fora do assunto dele. * **Formato**: tamanho, estrutura e idioma das respostas. * **Comportamento na dúvida**: o que fazer quando a resposta não está no material. O texto padrão do formulário já cobre formato e comportamento na dúvida. Costuma valer acrescentar papel e escopo, que são específicos do seu caso. ## O que não colocar [#o-que-não-colocar] * **Conhecimento**: fatos, tabelas e políticas pertencem a uma Coleção, não ao prompt. Conteúdo no prompt é pago em toda mensagem e não pode ser atualizado sem reeditar o Agente. * **Segredos**: chaves e senhas nunca vão no prompt. Acesso a sistemas é feito por Credenciais e ferramentas. * **Regras que já são guardrails**: filtros de dado sensível valem para a organização inteira e não dependem de cada Agente lembrar deles. Colar uma política inteira no prompt é o erro mais caro que dá para cometer aqui. Cada mensagem trocada passa a custar aquele texto todo, em todas as conversas, para sempre. ## Escrevendo para um Agente com Coleções [#escrevendo-para-um-agente-com-coleções] Quando o Agente tem conhecimento associado, o prompt deve dizer o que fazer com ele. Duas instruções que resolvem a maioria dos casos: responder a partir do material recuperado, e dizer que não sabe quando o material não cobre a pergunta. Sem a segunda, o modelo tende a completar a lacuna com o que aprendeu no treino, o que produz respostas plausíveis e erradas. ## Ajustando depois [#ajustando-depois] A forma mais rápida de avaliar um prompt é conversar com o Agente sobre casos reais, não sobre casos ideais. Perguntas ambíguas e fora de escopo revelam mais que perguntas bem formuladas. Mude uma coisa por vez. Reescrever o prompt inteiro entre dois testes torna impossível saber o que melhorou. ## Próximos passos [#próximos-passos] * Ligue o conhecimento que o prompt referencia em [Coleções](/docs/user-guide/knowledge). * Coloque o Agente na mão das pessoas em [Publicar e manter](/docs/user-guide/agents/publish). # Publicar e manter (/docs/user-guide/agents/publish) Todo Agente tem dois estados. **Rascunho** existe só no Admin; **publicado** aparece no seletor de Agentes do Chat, para as pessoas do workspace. A escolha é feita no rodapé do formulário, na opção **Publicar ao salvar**. ## Rascunho [#rascunho] Um Agente salvo sem publicar consta na lista de **Agentes** do Admin e não aparece para ninguém no Chat. É onde você deixa um Agente enquanto ainda ajusta o prompt, espera a indexação de uma Coleção terminar, ou aguarda a aprovação de quem responde pelo conteúdo. ## Publicar [#publicar] Marcar **Publicar ao salvar** e salvar coloca o Agente no ar. Ele passa a constar no seletor do Chat para todas as pessoas com acesso ao workspace. Antes de publicar, três conferências que evitam a maior parte dos problemas: 1. Os documentos das Coleções associadas estão em **Ativo**. 2. O modelo escolhido continua habilitado em **Configurações › Modelos**. 3. Uma pergunta real foi testada e a resposta bate com o documento de origem. ## Editar um agente publicado [#editar-um-agente-publicado] Editar e salvar um Agente já publicado atualiza o que está no ar. Não há versão paralela: a alteração vale na conversa seguinte de todo mundo. Não existe rascunho de um Agente já publicado. Salvar uma alteração parcial em um Agente em uso coloca essa alteração em produção imediatamente. Para mudanças grandes, o caminho seguro é duplicar o Agente, ajustar a cópia como rascunho e só então substituir. ## Conversas existentes [#conversas-existentes] Alterar um Agente não reescreve o passado. Conversas antigas continuam no histórico como foram, com as respostas que o Agente deu na época. Trocar o modelo, o prompt ou as Coleções afeta apenas as mensagens seguintes, inclusive dentro de uma conversa já aberta. ## Remover [#remover] Remover um Agente o tira do seletor do Chat. O histórico das conversas permanece em **Registros › Conversas**, mas não é possível seguir conversando. ## Próximos passos [#próximos-passos] * Acompanhe o uso em [Conversas](/docs/user-guide/monitoring/conversations) e [Avaliação das respostas](/docs/user-guide/monitoring/feedback). * Confira o consumo do Agente em [Painel](/docs/user-guide/monitoring/dashboard). # SuperAgentes (/docs/user-guide/agents/super-agents) Um **SuperAgente** é um agente que já existe fora da AUMO. A organização registra o endereço do serviço, e a plataforma passa a oferecê-lo aos workspaces como se fosse um Agente próprio. Ele não tem prompt, modelo nem coleções para você configurar: tudo isso pertence a quem mantém o serviço do outro lado. ## Quando usar [#quando-usar] Um SuperAgente cabe quando o agente já foi construído em outro lugar e você quer apenas disponibilizá-lo dentro da plataforma: um atendimento que roda em outro sistema, uma pesquisa especializada, uma automação comercial. Se o agente ainda vai ser construído, o caminho é [criar um Agente](/docs/user-guide/agents/create) dentro de um workspace. ## Registrar na organização [#registrar-na-organização] Em **Organização › SuperAgentes**, disponível para **Superadmin** e **Admin**: 1. Clique em **+ SuperAgente**. 2. Informe o **Nome do SuperAgente**, como ele aparecerá para as pessoas. 3. Informe a **URL do endpoint** e a **Chave de acesso**. 4. Clique em **Validar acesso**. A tela de cadastro é pensada para SuperAgentes contratados da Aumo: a URL e a chave de acesso são enviadas pela Aumo depois da contratação, e o painel ao lado traz o caminho para falar com a Aumo. A plataforma registra a URL como endpoint e define `responses` como a API suportada. O serviço do outro lado precisa responder no contrato da Responses API. ## Liberar para um workspace [#liberar-para-um-workspace] Depois de criado, o SuperAgente entra no catálogo da organização e ainda não aparece em nenhum workspace. A liberação acontece em **Organização › Workspaces**: abra o workspace desejado e use a seção de SuperAgentes para associar os que aquele time pode usar. ## No workspace [#no-workspace] **Workspace › SuperAgentes** lista o que a organização liberou para aquele time. Não há o que criar ali, porque a tela só mostra o que está disponível. Uma lista vazia significa que nenhum SuperAgente foi registrado na organização, ou que este workspace não foi associado a nenhum. Nos dois casos o caminho é falar com quem tem papel de Admin ou Superadmin. ## No Chat [#no-chat] Agentes e SuperAgentes aparecem no mesmo seletor, com nome e descrição, sem distinção visual. A distinção importa quando algo dá errado. Um Agente com resposta ruim se ajusta no prompt ou nas Coleções. Um SuperAgente com resposta ruim exige falar com quem mantém o serviço externo. ## Manutenção [#manutenção] Editar um SuperAgente altera nome e endpoint. Trocar a URL redireciona todas as conversas futuras para o novo endereço, em todos os workspaces em que ele estiver associado. Remover um SuperAgente o tira do catálogo e das associações. As conversas antigas continuam no histórico, mas não é possível seguir conversando. ## Consumo [#consumo] O consumo de um SuperAgente aparece na Observabilidade do workspace como qualquer outra chamada, mas o modelo por trás dele é decidido do lado externo. Isso significa que as Quotas por provedor podem não capturar esse consumo da mesma forma que capturam o de um Agente comum. ## Próximos passos [#próximos-passos] * Entenda a diferença conceitual em [Agentes e SuperAgentes](/docs/user-guide/concepts/agents). * Veja o que mais a organização distribui aos times em [Workspaces](/docs/user-guide/admin/workspaces). # Escolher o agente (/docs/user-guide/chat/agents) Cada conversa acontece com um Agente. O seletor fica no alto da tela, ao lado do nome do Agente atual, e lista o que está publicado no workspace. Agentes e SuperAgentes aparecem juntos, sem distinção visual. A diferença entre eles é de construção, não de uso. ## Trocar de agente [#trocar-de-agente] Abra o seletor e use **Filtrar agentes** quando a lista for longa. A escolha vale para a conversa em andamento. Nomes e descrições vêm de quem construiu o Agente. Quando estão vagos, o painel de informações costuma esclarecer melhor do que o nome. ## O painel de informações [#o-painel-de-informações] O botão **Informações do chat**, no cabeçalho, abre um painel lateral com duas abas no topo: **Agente** e **Chat**. Dentro de **Agente**, três abas mostram como ele está montado: * **Geral**: descrição, modelo, provedor em uso e quando o Agente foi criado. * **Coleções**: quais bases de conhecimento ele consulta, com o detalhe de cada uma. * **MCPs**: quais ferramentas ele pode acionar. É a forma mais rápida de responder "por que este agente não sabe disso" antes de abrir um chamado: se a aba **Coleções** está vazia, ele não consulta documento nenhum. ## O que o agente alcança [#o-que-o-agente-alcança] Um Agente só enxerga o que foi ligado a ele no Admin. Nada do que você escreve na conversa muda isso. Se a resposta que você precisa depende de um documento que não está em nenhuma Coleção daquele Agente, não há como pedir que ele o consulte. O caminho é falar com quem administra o workspace. A aba **Coleções** mostra também os conectores de cada base. Uma Coleção alimentada por conector pode estar desatualizada se a sincronização falhou, mesmo aparecendo ligada aqui. ## Quando a lista está vazia [#quando-a-lista-está-vazia] Nenhum Agente no seletor significa que o workspace não tem Agente **publicado**. Rascunhos existem só no Admin e não aparecem aqui. Confirme também o workspace selecionado no alto da barra lateral: cada workspace tem os seus Agentes. ## Próximos passos [#próximos-passos] * Entenda a diferença entre os dois tipos em [Agentes e SuperAgentes](/docs/user-guide/concepts/agents). * Veja como o Agente usa as Coleções em [Referências e fontes](/docs/user-guide/chat/sources). # Chaves de API (/docs/user-guide/chat/api-keys) **Chaves de API**, chamadas de chaves de projeto na plataforma, autenticam aplicações e integrações que chamam a AUMO sem uma pessoa na frente. A tela é exclusiva do **Proprietário** do workspace. Nenhum outro papel a alcança, nem em leitura. ## Por que só o Proprietário [#por-que-só-o-proprietário] Emitir uma chave é conceder acesso programático ao workspace, sem login e sem a barreira de uma sessão. A restrição é deliberada e não acompanha os demais papéis de construção: Curador e Editor criam Agentes e Coleções, mas não emitem credenciais. ## Criar uma chave [#criar-uma-chave] Clique em **+ Chave de projeto** e preencha a janela **Nova chave de projeto**: * **Nome**: o que aparece na listagem e nos relatórios de consumo. Descreva o sistema que vai usar a chave. * **Expiração**: 30 dias por padrão, com opções de 7, 60 e 90 dias, data personalizada ou sem expiração. * **Escopos**: para cada recurso, **Nenhum**, **Leitura** ou **Leitura e escrita**, entre outros níveis. Você só concede escopos que você mesmo tem no workspace. Para conversar com um agente, a própria janela indica o mínimo: **Conversas** em leitura e escrita, **Agente** e **Modelos** em leitura. Clique em **Gerar chave**. A chave aparece em um cartão no topo da lista, com a opção de copiar. O valor da chave é exibido uma única vez, no momento da criação. Guarde-o antes de fechar a tela; não há como recuperá-lo depois, apenas revogar e emitir outra. ## A lista [#a-lista] A busca filtra por nome, prefixo ou escopo. O prefixo é a parte visível da chave, suficiente para identificar qual credencial está em uso sem expor o valor. O botão **Mostrar revogadas** traz também as chaves já invalidadas, que somem da lista por padrão. ## Revogar [#revogar] Revogar invalida a chave imediatamente. Tudo que a usava para de autenticar, e a falha aparece no sistema chamador, não aqui. Uma chave revogada permanece no registro, para que o consumo passado continue atribuível. ## Consumo e quotas [#consumo-e-quotas] Chaves de projeto consomem do workspace como qualquer outra chamada, e têm aba própria em **Quotas**. Vale usá-la: uma integração em laço consome sem pausa e sem ninguém olhando, o que é exatamente o caso que um teto por chave evita. ## Próximos passos [#próximos-passos] * Limite o consumo por chave em [Quotas](/docs/user-guide/models/quotas). * Acompanhe as chamadas em [Observabilidade](/docs/user-guide/monitoring/observability). # Anexos e prompts (/docs/user-guide/chat/attachments) O botão **+**, à esquerda do campo de mensagem, reúne tudo que se pode acrescentar a uma mensagem além do texto. São três caminhos: anexar arquivos, anexar imagens e inserir um prompt pronto. ## Enviar arquivos [#enviar-arquivos] **Enviar arquivos** anexa documentos à mensagem. O Agente os lê no contexto daquela conversa. Isso é diferente de uma Coleção. Um arquivo anexado vale para a conversa em que foi enviado; uma Coleção vale para todas as conversas de todos os Agentes ligados a ela. Use anexo para o documento pontual: o contrato que chegou agora, a planilha desta análise. Use Coleção para o que a empresa consulta sempre. ## Enviar imagens [#enviar-imagens] **Enviar imagens** só funciona quando o modelo do Agente tem capacidade de visão. Quando não tem, a opção aparece desabilitada com o aviso de que aquele Agente não suporta anexos de imagem. Trocar para um Agente com modelo de visão é a única saída: a capacidade vem do modelo, não de uma configuração da conversa. ## Biblioteca de prompts [#biblioteca-de-prompts] **Biblioteca de prompts** abre a coleção de textos prontos, com busca por título, tag ou conteúdo. Selecionar um insere o texto no campo de mensagem, onde você pode editá-lo antes de enviar. Serve para padronizar pedidos recorrentes, como um formato de resumo ou um checklist de revisão, sem depender de cada pessoa lembrar da formulação certa. ## Recursos de MCP [#recursos-de-mcp] Quando o Agente tem MCPs com prompts e resources publicados, é possível navegá-los e anexá-los à mensagem. Os itens escolhidos aparecem como marcadores acima do campo, com ação de remover. Um marcador de prompt ou recurso anexado vale só para a mensagem que está sendo escrita. Ele não fica ligado à conversa. ## Ditar a mensagem [#ditar-a-mensagem] O botão de microfone, à direita do campo, transcreve fala em texto. O resultado vai para o campo de mensagem, onde pode ser corrigido antes do envio. ## Próximos passos [#próximos-passos] * Entenda quando o conteúdo deveria estar em uma base em [Coleções e conhecimento](/docs/user-guide/concepts/knowledge). * Veja o que o Agente consulta por conta própria em [Escolher o agente](/docs/user-guide/chat/agents). # Conversas (/docs/user-guide/chat/conversations) Uma conversa é uma sequência de mensagens com um Agente. Ela guarda o contexto: o Agente enxerga o que já foi dito ao responder a mensagem seguinte. Suas conversas são suas. Outras pessoas do workspace não veem o que você perguntou, embora quem administra o workspace alcance o histórico em **Registros › Conversas**. ## Começar [#começar] A tela inicial traz uma saudação e o campo de mensagem ao centro. Digite e envie. A conversa é criada na primeira mensagem. Quando o Agente selecionado tem Coleções associadas, aparecem sugestões de pergunta acima do campo. Sem base de conhecimento ligada, as sugestões não aparecem, e isso é comportamento esperado, não falha. O botão de **Novo Chat**, ao lado da busca na barra lateral, começa uma conversa em branco a qualquer momento. ## O histórico [#o-histórico] A barra lateral lista as conversas agrupadas por recência: **Fixados**, **Hoje**, **Ontem**, **Últimos 7 dias**, **Último mês** e **Antigos**. O campo **Pesquisar chat** filtra por conteúdo. O título de cada conversa é gerado automaticamente a partir das primeiras mensagens. ## Organizar [#organizar] O menu de cada conversa traz as ações de manutenção: * **Renomear**: substitui o título gerado automaticamente por um seu. * **Fixar**: move a conversa para o grupo **Fixados**, no topo. * **Excluir**: remove a conversa da sua lista, com confirmação. Excluir uma conversa a tira da sua barra lateral, mas o registro permanece acessível a quem administra o workspace, em **Registros › Conversas**. A exclusão é de organização, não de privacidade. ## Avaliar uma resposta [#avaliar-uma-resposta] Cada resposta do Agente traz ações ao passar o cursor. Duas delas alimentam a qualidade da plataforma: * **Resposta satisfatória** e **Resposta insatisfatória** registram a avaliação. * Ao marcar como insatisfatória, abre-se um modal com opções rápidas e um campo livre. Essas avaliações aparecem para quem administra o workspace em **Registros › Avaliação das Respostas**. É o canal mais direto para melhorar um Agente que erra. As demais ações da mensagem incluem editar a sua própria mensagem, copiar e ouvir a resposta em áudio. ## Compartilhar [#compartilhar] A ação **Compartilhar chat**, no cabeçalho, abre um painel com uma chave e um link. Enquanto a chave **Membros do workspace com o link** estiver desligada, ninguém mais consegue abrir a conversa. Ao ligá-la, qualquer membro do workspace que tenha o link passa a conseguir. O compartilhamento é de leitura e não invade a lista dos outros: * A conversa **não** aparece na barra lateral de quem recebeu o link. * Só você continua podendo escrever nela. * Quem não é membro do workspace não abre, mesmo com o link. Ainda assim, a conversa vai inteira, incluindo o que você colou nela ao longo do caminho. ## Próximos passos [#próximos-passos] * Escolha com quem conversar em [Escolher o agente](/docs/user-guide/chat/agents). * Confira a origem das respostas em [Referências e fontes](/docs/user-guide/chat/sources). # Visão geral (/docs/user-guide/chat) O **Chat** é o lado da plataforma que não exige acesso administrativo. Quem participa de um workspace conversa com os Agentes publicados nele e executa os Workflows disponíveis. Ele divide a barra de áreas com o Admin e usa o mesmo login. Trocar de um para o outro não pede autenticação de novo. ## As duas áreas [#as-duas-áreas] A barra de áreas traz dois destinos deste módulo, e a diferença entre eles é o formato da interação. * **Chat**: conversa aberta com um Agente, mensagem a mensagem. * **Agentes**: execução de Workflows publicados, por formulário, com um resultado no fim. O nome da segunda área confunde: ela lista **Workflows**, não os Agentes de conversa. Estes são escolhidos pelo seletor dentro da própria tela de Chat. ## Conversar [#conversar] Iniciar, retomar, renomear e compartilhar conversas. O seletor de agentes e o painel que mostra como cada um está configurado. Enviar arquivos e imagens, e reaproveitar prompts da biblioteca. De onde veio a resposta e como conferir o trecho de origem. ## Executar [#executar] Preencher o formulário de um workflow publicado e acompanhar o resultado. # Referências e fontes (/docs/user-guide/chat/sources) Quando o Agente responde com base em Coleções, a resposta traz um bloco de **Referências** ao final, apontando os documentos usados. É o que separa uma resposta verificável de uma resposta plausível. Conferir a referência leva alguns segundos e resolve a maior parte das dúvidas sobre confiabilidade. ## Abrir um fragmento [#abrir-um-fragmento] Clicar em uma referência abre o painel **Fragmentos do documento**, com os trechos daquele documento que a busca considerou relevantes para a sua pergunta. O painel mostra o nome do arquivo, quantos fragmentos foram encontrados e uma pontuação de relevância. A pontuação é do mecanismo de busca, não uma avaliação de correção: um fragmento com nota alta é o mais parecido com a pergunta, não necessariamente o que contém a resposta certa. ## Como ler o resultado [#como-ler-o-resultado] Três situações, e o que cada uma indica: * **A resposta cita um trecho que confere**: o caminho funcionou de ponta a ponta. * **A resposta cita um trecho que não sustenta o que foi dito**: o modelo extrapolou. Vale registrar como resposta insatisfatória. * **Não há bloco de Referências**: o Agente respondeu sem consultar documento nenhum. ## Quando não há referências [#quando-não-há-referências] A ausência do bloco tem três causas possíveis, em ordem de frequência: 1. **O Agente não tem Coleções associadas.** Confirme na aba **Coleções** do painel de informações. 2. **Os documentos ainda não estão prontos.** Documentos em extração ou indexação não participam das respostas. 3. **A busca não encontrou nada relevante.** A pergunta usa termos que não aparecem nos documentos. Um Agente sem Coleções responde assim mesmo, usando o que o modelo aprendeu no treino. A resposta parece igual, só não tem referências. É o caso em que mais vale conferir antes de agir. ## Fazer a busca encontrar [#fazer-a-busca-encontrar] A busca compara o conteúdo da pergunta com o conteúdo dos documentos, não com títulos ou nomes de arquivo. Perguntar usando os termos que aparecem dentro do documento funciona melhor do que citar o nome dele. "Qual o prazo de reembolso de despesas de viagem" encontra mais que "o que diz a política de despesas". ## Próximos passos [#próximos-passos] * Entenda o mecanismo por trás disso em [Coleções e conhecimento](/docs/user-guide/concepts/knowledge). * Registre uma resposta sem apoio em [Conversas](/docs/user-guide/chat/conversations). # Executar workflows (/docs/user-guide/chat/workflows) A área **Agentes**, na barra de áreas, lista os Workflows publicados no workspace e permite executá-los. Diferente do Chat, aqui não há conversa. Você preenche um formulário, executa e recebe um resultado. O nome da área é enganoso: ela lista **Workflows**, não os Agentes de conversa. Estes são escolhidos pelo seletor dentro da tela de Chat. ## A lista [#a-lista] A tela mostra os Workflows disponíveis, com busca por nome e a descrição de cada um. A barra lateral traz os que você já executou e as execuções recentes. Na primeira visita ela aparece vazia, com o aviso de que os itens aparecem depois da primeira execução. ## Executar [#executar] Abrir um Workflow mostra o formulário de entrada, montado a partir do que quem construiu declarou no nó de Entrada. Os campos e suas descrições vêm de lá. Preencha os campos em **Entradas do usuário** e clique no botão de executar (▶), no canto do cartão. Campos obrigatórios não preenchidos travam o botão. ## Acompanhar [#acompanhar] Durante a execução, a tela mostra o andamento por etapas. Workflows com várias etapas levam mais tempo que uma mensagem de chat, e isso é esperado. Ao final, o resultado aparece conforme o que o nó de Saída define: texto, estrutura de dados ou arquivo para download. ## Quando algo dá errado [#quando-algo-dá-errado] Uma execução que falha para na etapa problemática e indica onde parou. Do seu lado há pouco a corrigir: o formulário é a única entrada que você controla. Vale conferir se os valores informados estão no formato esperado e, se o erro persistir, levar o caso a quem mantém o Workflow, com o identificador da execução. ## Versões [#versões] Uma execução usa a versão publicada do Workflow no momento em que roda. A barra lateral marca as execuções feitas com uma versão anterior. Ao comparar dois resultados diferentes para a mesma entrada, essa marca costuma ser a explicação. ## Próximos passos [#próximos-passos] * Entenda quando um Workflow é a ferramenta certa em [Workflows](/docs/user-guide/concepts/workflows). * Para quem constrói, o caminho está em [Montar no canvas](/docs/user-guide/workflows/build). # Agentes e SuperAgentes (/docs/user-guide/concepts/agents) Um **Agente** é a unidade com que as pessoas conversam no Chat. Ele reúne um modelo de IA, instruções em texto e o acesso ao conhecimento e às ferramentas do workspace. Agentes pertencem a um workspace e são criados no Admin. Nada no Chat cria um Agente. ## Do que um Agente é feito [#do-que-um-agente-é-feito] O formulário de criação organiza o Agente em seções, e cada uma responde a uma pergunta diferente: * **Dados básicos**: nome, modelo, logo e descrição. Nome e descrição são o que a pessoa lê na hora de escolher o Agente. * **Prompt de resposta ao usuário**: as instruções permanentes. Define tom, formato e limites do que ele deve responder. * **Coleções**: o conhecimento que ele consulta antes de responder. * **MCPs** e **Integrações**: as ferramentas que ele pode acionar. * **Sub-agentes**: outros Agentes que ele chama como apoio. * **Opções avançadas**: temperatura e máximo de tokens por resposta. Só nome, modelo e prompt são obrigatórios. Um Agente sem coleções e sem ferramentas é válido: ele responde com o modelo e o prompt, como um chat comum. ## Rascunho e publicado [#rascunho-e-publicado] Todo Agente tem dois estados. **Rascunho** existe só no Admin; **publicado** aparece no seletor de Agentes do Chat, para as pessoas do workspace. Você escolhe entre eles ao salvar, na opção **Publicar ao salvar**. Um Agente criado e não publicado some da vista de quem usa a plataforma, o que é útil enquanto você ainda está ajustando o prompt. ## Como o Agente responde [#como-o-agente-responde] A cada mensagem, o Agente monta a resposta nesta ordem: 1. Se tem Coleções associadas, busca os trechos relevantes nelas. 2. Se tem MCPs ou Integrações, decide se precisa acionar alguma ferramenta, respeitando o limite de iterações configurado. 3. Junta tudo ao prompt e ao histórico da conversa e pede a resposta ao modelo. Sem Coleções associadas, o passo 1 não acontece, e a plataforma nem consulta o mecanismo de busca. É a associação de Coleções que liga o RAG, não uma chave separada. ## Sub-agentes [#sub-agentes] Um Agente pode expor a si mesmo como ferramenta e chamar outros Agentes como apoio. O Agente principal continua sendo quem fala com a pessoa; os sub-agentes trabalham por trás. Isso serve para dividir responsabilidades, como um Agente que sabe da política de RH e outro que sabe do catálogo de produtos, em vez de inchar um prompt só. ## SuperAgentes [#superagentes] Um **SuperAgente** é um agente que já existe fora da AUMO e que a organização registra por URL. A plataforma o trata como um endpoint compatível com a Responses API. As diferenças que importam: * **Onde nasce**: o Agente é construído dentro da AUMO; o SuperAgente é registrado apontando para um sistema externo. * **Quem registra**: SuperAgentes entram no catálogo da Organização e depois são liberados para cada workspace. * **O que você configura**: no SuperAgente você informa nome e endpoint. Prompt, modelo e conhecimento são responsabilidade de quem mantém o serviço do outro lado. Para quem usa o Chat, os dois aparecem lado a lado no seletor. A diferença é de construção e governança, não de experiência. ## Próximos passos [#próximos-passos] * Entenda o conhecimento que alimenta o Agente em [Coleções e conhecimento](/docs/user-guide/concepts/knowledge). * Veja de onde vêm os modelos disponíveis em [Provedores e modelos](/docs/user-guide/concepts/models). * Monte um Agente do zero em [Seu primeiro agente](/docs/user-guide/get-started/first-agent). # Coleções e conhecimento (/docs/user-guide/concepts/knowledge) Uma **Coleção** é um conjunto de documentos que um Agente pode consultar antes de responder. É o mecanismo pelo qual a plataforma responde com o conteúdo da sua empresa, e não só com o que o modelo aprendeu no treino. Coleções pertencem a um workspace e não são compartilhadas entre workspaces. ## Do que uma Coleção é feita [#do-que-uma-coleção-é-feita] Uma Coleção reúne fontes de dois tipos, nas abas **Arquivos** e **Conectores**: * **Arquivos**: documentos que você envia, em PDF, DOCX, TXT e formatos equivalentes. Ficam parados até alguém substituí-los. * **Conectores**: fontes externas que a plataforma sincroniza, como um site indexado ou um repositório de documentos. Voltam a buscar conteúdo de tempos em tempos. Até a versão 3 existiam duas telas, **Fontes de Conhecimento** e **Coleções**. A v4 unificou as duas: arquivos e conectores agora são adicionados direto na Coleção. ## O ciclo de vida de um documento [#o-ciclo-de-vida-de-um-documento] Todo documento passa pelos mesmos estados até ficar utilizável, e a aba **Arquivos** mostra o estado de cada um: 1. **Em fila**: o arquivo chegou e espera processamento. 2. **Extraindo**: a plataforma está transformando o arquivo em texto. 3. **Indexando**: o texto está sendo quebrado em trechos e preparado para a busca. 4. **Extraído**: o documento está disponível para as respostas. Apesar do nome, **Extraído** é o estado final: ele vem depois de **Indexando**, não logo após a extração. Os dois estados de erro são **Extração falhou** e **Indexação falhou**. Nenhum dos dois se recupera sozinho, e um documento nesses estados não participa das respostas. Só documentos em **Extraído** são consultados. Um Agente ligado a uma Coleção cujos arquivos ainda estão indexando responde como se a Coleção estivesse vazia. ## O que acontece a cada pergunta [#o-que-acontece-a-cada-pergunta] Quando um Agente com Coleções recebe uma mensagem, a plataforma: 1. Converte a pergunta em uma representação numérica e busca os trechos mais próximos dentro das Coleções associadas àquele Agente. 2. Entrega os trechos encontrados ao modelo, junto do prompt e do histórico. 3. Pede a resposta, agora com esse material à vista. Esse desenho é o que a indústria chama de **RAG**, geração aumentada por recuperação. A consequência prática é que a qualidade da resposta depende mais do conteúdo indexado do que do modelo escolhido. ## Limites que valem conhecer [#limites-que-valem-conhecer] * **A busca é por conteúdo, não por título.** Perguntar pelo nome do arquivo raramente encontra o arquivo. Use os termos que aparecem dentro dele. * **Coleção vazia significa "sem conhecimento", nunca "busque em tudo".** Um Agente sem Coleções não varre o workspace; ele apenas não busca. * **PDFs digitalizados dependem de extração de texto** e demoram mais. Quando o original é uma imagem sem texto selecionável, a extração pode falhar. * **O escopo é o workspace.** Levar uma Coleção para outro workspace significa recriá-la ali. ## Próximos passos [#próximos-passos] * Veja como a Coleção se liga a quem responde em [Agentes e SuperAgentes](/docs/user-guide/concepts/agents). * Crie a sua primeira Coleção em [Seu primeiro agente](/docs/user-guide/get-started/first-agent). # Provedores e modelos (/docs/user-guide/concepts/models) Um **Provedor** é a conta de um serviço de modelos de IA: AUMO, OpenAI, Bedrock e equivalentes. Um **Modelo** é uma opção concreta dentro de um provedor, escolhível no formulário de um Agente. Os dois vivem em níveis diferentes de propósito: o Provedor é da Organização, o Modelo é habilitado por Workspace. ## Provedores [#provedores] Provedores ficam em **Organização › Provedores** e são o ponto onde as credenciais de IA da empresa são guardadas. Cadastrar um provedor é o que dá à plataforma o direito de chamar aquele serviço. Só o papel **Superadmin** abre essa tela. Isso é deliberado: é onde o segredo mora. O provedor **AUMO** é o caso especial. Em vez de você trazer a sua conta, a AUMO fornece o acesso, com aprovação e cotas negociadas entre a sua organização e a plataforma. ## Modelos [#modelos] Modelos ficam em **Workspace › Configurações › Modelos**. É ali que se decide quais opções, entre tudo o que os provedores da organização oferecem, aparecem para quem cria Agentes naquele workspace. Cada modelo carrega os dados que determinam seu comportamento e seu custo: * **Janela de contexto**: quanto texto cabe em uma chamada, somando prompt, histórico e trechos recuperados. * **Máximo de tokens de saída**: o teto de uma resposta. * **Preço de entrada e de saída**: o custo por token, usado para calcular consumo e cotas. Um workspace sem nenhum modelo habilitado não deixa criar Agente: o campo **Modelo** é obrigatório e ficaria vazio. ## O caminho até uma resposta [#o-caminho-até-uma-resposta] A cadeia completa tem quatro elos, e vale saber onde cada um quebra: 1. A Organização cadastra o **Provedor**, com a credencial. 2. O Workspace habilita os **Modelos** daquele provedor que quer oferecer. 3. O Agente escolhe **um** desses modelos. 4. Cada mensagem no Chat consome tokens daquele modelo, contabilizados no workspace. Se um modelo some da lista de um Agente que já existia, quase sempre o elo rompido é o 2: alguém o desabilitou no workspace. ## Escolhendo um modelo [#escolhendo-um-modelo] Três critérios costumam bastar: * **Tamanho do contexto**: Agentes com muitas Coleções ou conversas longas precisam de janelas maiores. * **Custo**: modelos maiores cobram mais por token, e o Painel mostra o efeito disso no fim do mês. * **Comportamento**: prompts iguais rendem respostas diferentes entre modelos. Vale testar o mesmo Agente em dois antes de publicar. Começar pelo modelo mais barato que resolve a tarefa é o caminho mais previsível. Trocar depois é editar um campo. ## Próximos passos [#próximos-passos] * Veja como o consumo desses modelos é limitado em [Quotas e consumo](/docs/user-guide/concepts/quotas). * Entenda onde o modelo entra na montagem da resposta em [Agentes e SuperAgentes](/docs/user-guide/concepts/agents). # Organizações e Workspaces (/docs/user-guide/concepts/organizations-workspaces) Toda configuração da AUMO pertence a um de dois níveis. A **Organização** representa a empresa; o **Workspace** representa um time, produto ou projeto dentro dela. Saber em qual nível uma coisa mora explica três perguntas que aparecem o tempo todo: quem pode alterá-la, quem a enxerga e onde o consumo dela é contabilizado. ## Organização [#organização] Uma **Organização** é o limite externo da sua empresa na plataforma. Ela guarda o catálogo do que é permitido usar e as regras que valem para todo mundo. Pertencem à Organização: * **Provedores** e **Credenciais**: as contas de modelos de IA e os segredos de acesso a sistemas externos. * **SuperAgentes**: os agentes externos registrados para a empresa. * **MCPs** e **Integrações**: o registro do que os workspaces podem instalar. * **Membros** e **Quotas**: quem entra na empresa e quanto ela pode gastar. Uma pessoa pode participar de mais de uma Organização, com papel diferente em cada. Trocar de Organização troca o contexto inteiro. ## Workspace [#workspace] Um **Workspace** é onde o trabalho acontece. Ele consome o catálogo da Organização e monta coisas próprias em cima dele. Pertencem ao Workspace: * **Coleções**: os documentos que alimentam as respostas. * **Agentes** e **Workflows**: o que as pessoas usam no Chat. * **MCPs** e **Integrações** instaladas: as ferramentas efetivamente ligadas. * **Modelos**, **Variáveis**, **Membros**, **Quotas** e **Chaves de API**. Workspaces não enxergam um ao outro. Uma Coleção de um workspace não aparece para o Agente de outro, mesmo dentro da mesma Organização. Até a versão 3 os workspaces se chamavam **Projetos**. O nome mudou em toda a plataforma na v4; o conceito é o mesmo. ## Catálogo e instalação [#catálogo-e-instalação] Provedores de IA, MCPs, Integrações e SuperAgentes existem nos dois níveis, e isso é proposital. São dois passos diferentes: 1. A Organização **registra** o item uma vez: a conta do provedor, o servidor MCP, a URL do SuperAgente. É aqui que segredos e aprovação vivem. 2. O Workspace **instala** o que vai usar daquele catálogo, com nome e configuração próprios. O mesmo item do registro pode ser instalado várias vezes no mesmo workspace, desde que cada instalação tenha um nome diferente. A configuração pertence à instalação, não ao registro. Esse desenho existe para que uma credencial fique guardada em um lugar só, enquanto cada time decide o que ligar. Um workspace nunca cria uma conta de provedor por conta própria. ## Onde isso aparece na prática [#onde-isso-aparece-na-prática] Três consequências que valem lembrar: * **Permissão**: o seu papel na Organização e o seu papel em cada Workspace são independentes. Você pode ser Admin da empresa e não ser membro de um workspace específico. * **Consumo**: o gasto de tokens é atribuído ao workspace que fez a chamada, e sobe para a Organização no total. * **Isolamento**: mover conhecimento entre workspaces significa recriar a Coleção, não compartilhá-la. ## Próximos passos [#próximos-passos] * Veja quem pode fazer o quê em cada nível em [Papéis e permissões](/docs/user-guide/concepts/roles). * Entenda como o catálogo de modelos desce até o workspace em [Provedores e modelos](/docs/user-guide/concepts/models). # Quotas e consumo (/docs/user-guide/concepts/quotas) Toda chamada a um modelo de IA consome **tokens**, e todo token tem preço. As **Quotas** são os tetos mensais que a plataforma aplica sobre esse consumo. Sem quota configurada, um escopo não tem limite. Quotas existem para que um experimento mal calibrado não consuma o orçamento do mês inteiro. ## Os escopos [#os-escopos] O mesmo consumo é contado em mais de um nível ao mesmo tempo, e cada um pode ter o seu teto: * **Organização**: o total da empresa. * **Workspace**: o total de um time ou projeto. * **Usuário**: quanto uma pessoa pode consumir dentro do workspace. * **Chave de projeto**: quanto uma integração programática pode consumir. Também é possível limitar **por provedor**, quando um deles é mais caro que os outros e merece teto próprio. A cota de Organização tem **prioridade** sobre a de Workspace. Esgotado o teto da empresa, nenhum workspace continua, por mais folga que tenha no próprio limite. Os tetos são definidos em **custo** ou em **tokens**, e valem para o mês corrente. A virada do mês zera o consumo acumulado. Campo em branco significa "sem limite"; um limite igual a **zero** bloqueia todas as requisições daquele escopo. ## O que acontece ao estourar [#o-que-acontece-ao-estourar] Quando o consumo passa do teto, a chamada é recusada e quem está no Chat recebe um aviso de cota excedida. A plataforma não degrada a resposta nem troca de modelo: ela bloqueia. O bloqueio vale para o escopo que estourou. Um usuário que atingiu o próprio limite para de conseguir usar, enquanto o resto do workspace continua. ## Liberações temporárias [#liberações-temporárias] Subir a política de quota resolve o problema do dia e raramente volta a descer. Para o caso pontual existe a **liberação temporária**. Ela funciona assim: * Acrescenta um teto extra ao limite vigente, por um prazo definido, com motivo registrado. * Expira sozinha. Não existe rotina para desfazer: a plataforma deixa de considerar liberações vencidas. * Ao expirar, o escopo volta ao teto da política e volta a bloquear, se o consumo do mês já tiver passado dele. A liberação leva até cerca de 30 segundos para valer, porque o consumo é lido de um cache. O mesmo vale ao revogar uma liberação antes do prazo. ## Onde ver o consumo [#onde-ver-o-consumo] Três telas respondem a perguntas diferentes: * **Workspace › Painel**: o resumo do workspace, com tokens consumidos, custo total e uso por Agente. * **Quotas**, na Organização ou no Workspace: limites, uso do mês e a projeção até o fim dele. * **Observabilidade**: o detalhe por modelo, com filtros e traces de cada execução. A projeção da tela de Quotas é o sinal mais útil no meio do mês: ela indica se o ritmo atual estoura o teto antes da virada. ## Próximos passos [#próximos-passos] * Entenda de onde vem o preço por token em [Provedores e modelos](/docs/user-guide/concepts/models). * Veja quem pode alterar quotas em [Papéis e permissões](/docs/user-guide/concepts/roles). # Papéis e permissões (/docs/user-guide/concepts/roles) Cada pessoa tem um papel na **Organização** e um papel em cada **Workspace** de que participa. Os dois são independentes e se somam. É essa combinação que decide o que aparece na barra lateral e o que a plataforma aceita quando você clica em salvar. ## Papéis de organização [#papéis-de-organização] * **Superadmin**: acesso total. É o único papel que abre **Provedores**, **Credenciais** e **Configurações › Geral**. * **Admin**: administra a organização: workspaces, membros, quotas, SuperAgentes, MCPs e Integrações. Não alcança Provedores, Credenciais nem Configurações › Geral, e não cadastra MCPs novos no registro. * **Auditor**: só leitura, e apenas em Workspaces, Membros, Quotas, Observabilidade e SuperAgentes. * **Usuário**: sem acesso às telas de Organização. É o papel de quem só usa o Chat. A distância entre Superadmin e Admin é deliberada: o que guarda segredo, conta de provedor e credencial, fica com um papel só. ## Papéis de workspace [#papéis-de-workspace] * **Proprietário**: acesso total ao workspace, incluindo Integrações, Chaves de API e excluir o workspace. * **Curador**: constrói e acompanha. Cria Coleções, Agentes, SuperAgentes, Workflows, MCPs e Variáveis, e lê Painel, Conversas, Avaliação das Respostas, Observabilidade e Quotas. * **Editor**: só constrói. Mesmo poder de criação do Curador, sem nenhuma das telas de acompanhamento e configuração. * **Auditor**: só leitura, na maior parte do workspace. * **Usuário**: sem acesso às telas de administração. Conversa no Chat. | Área do workspace | Proprietário | Curador | Editor | Auditor | | ----------------------------------------------------------- | ------------ | ---------- | ---------- | ---------- | | Coleções, Agentes, SuperAgentes, Workflows, MCPs, Variáveis | Edita | Edita | Edita | Lê | | Painel, Observabilidade, Quotas | Lê | Lê | Sem acesso | Lê | | Conversas, Avaliação das Respostas | Lê | Lê | Sem acesso | Lê | | Modelos, Membros, Geral | Edita | Sem acesso | Sem acesso | Lê | | Integrações, Chaves de API | Edita | Sem acesso | Sem acesso | Sem acesso | ## Como os dois se combinam [#como-os-dois-se-combinam] A plataforma resolve o acesso a um workspace nesta ordem: 1. Se você é membro do workspace, vale o seu papel de workspace. 2. Se não é, mas é Superadmin, Admin ou Auditor da organização, vale o papel de organização. 3. Se nenhum dos dois se aplica, o workspace não abre. Por isso um Admin da organização entra em um workspace onde nunca foi adicionado, enquanto um Editor de outro workspace não entra. A barra lateral esconde o que o seu papel não permite, mas a decisão real é do backend: cada serviço reconfere a permissão a cada chamada. Digitar a URL de uma página escondida não dá acesso a ela. ## Quando o acesso não é o esperado [#quando-o-acesso-não-é-o-esperado] * **Você vê o workspace mas não edita nada**: você chegou pelo papel de organização, não como membro. Peça para ser adicionado ao workspace. * **Você é Admin e não abre Provedores ou Credenciais**: isso é por desenho, e não se resolve por workspace. Esses dois exigem Superadmin. * **Você é Curador e não vê Modelos nem Membros**: também por desenho. Essas duas ficam com o Proprietário. * **A área de Workspace está desabilitada**: você não participa de nenhum workspace naquela organização. ## Próximos passos [#próximos-passos] * Entenda o que pertence a cada nível em [Organizações e Workspaces](/docs/user-guide/concepts/organizations-workspaces). * Seu papel na organização aparece no menu de usuário, em **Configurações**, junto do nome dela. # MCPs e Integrações (/docs/user-guide/concepts/tools) Coleções dão ao Agente o que **ler**. Ferramentas dão a ele o que **fazer**: consultar um sistema, abrir um chamado, buscar um dado que muda a cada minuto. A AUMO oferece dois caminhos para isso, **MCPs** e **Integrações**. Os dois seguem o mesmo desenho de catálogo na Organização e instalação no Workspace. ## MCPs [#mcps] **MCP** é um protocolo aberto para expor ferramentas a modelos de IA. Um servidor MCP publica um conjunto de ferramentas, e o Agente decide quando chamá-las. O caminho é em dois passos: * **Organização › MCPs** é o registro. Ali a empresa cadastra os servidores permitidos, a partir do Docker Hub, do GitHub ou de um endereço próprio. * **Workspace › MCPs** é a instalação. Cada workspace escolhe, entre os do registro, quais quer ligar, e dá a cada instalação um nome e uma configuração. O mesmo servidor do registro pode ser instalado várias vezes no mesmo workspace, desde que cada instalação tenha nome diferente. Isso permite, por exemplo, duas conexões ao mesmo sistema apontando para ambientes distintos. A configuração e o funcionamento pertencem à **instalação**, não ao registro. Alterar uma instalação não afeta as outras nem o item registrado na Organização. ## Integrações [#integrações] **Integrações** são conexões prontas a serviços conhecidos, mantidas pela plataforma. Você não descreve o protocolo: escolhe o serviço de uma lista e informa o acesso. Seguem a mesma divisão. Em **Organização › Integrações**, as abas **Disponíveis** e **Instaladas** mostram o catálogo conhecido e o que a empresa já cadastrou. Em **Workspace › Integrações**, cada workspace liga as que vai usar. No workspace, a tela de Integrações é acessível apenas ao **Proprietário**. ## MCP ou Integração [#mcp-ou-integração] A escolha costuma ser direta: * **Use uma Integração** quando o serviço já está na lista. É menos configuração e a manutenção é da plataforma. * **Use um MCP** quando o sistema é interno, específico do seu negócio, ou quando você precisa controlar exatamente quais ferramentas são expostas. Não é uma decisão exclusiva: um mesmo Agente pode ter MCPs e Integrações ao mesmo tempo. ## Como o Agente usa a ferramenta [#como-o-agente-usa-a-ferramenta] No formulário do Agente, as seções **MCPs** e **Integrações** listam o que está instalado no workspace. Você marca o que aquele Agente pode acionar. A seção de MCPs traz também o **máximo de iterações**: quantas vezes, em uma única resposta, o Agente pode chamar ferramentas antes de ter que concluir. É o que impede um Agente de ficar em laço quando uma ferramenta devolve algo inesperado. Um Agente só alcança o que foi instalado no workspace dele e marcado no formulário dele. Instalar um MCP no workspace não o entrega automaticamente a todos os Agentes. ## Credenciais [#credenciais] Acessos a sistemas externos ficam em **Organização › Credenciais**, guardados uma vez e reaproveitados pelas instalações. Como Provedores, a tela é restrita ao **Superadmin**. Isso mantém o segredo em um lugar só, enquanto cada workspace decide o que ligar sem nunca ver o valor guardado. ## Próximos passos [#próximos-passos] * Veja onde as ferramentas entram na resposta em [Agentes e SuperAgentes](/docs/user-guide/concepts/agents). * Ferramentas também aparecem como nós em [Workflows](/docs/user-guide/concepts/workflows). # Workflows (/docs/user-guide/concepts/workflows) Um **Workflow** é uma sequência de etapas montada em um canvas, ligando nós que recebem dados, processam e devolvem um resultado. Onde o Agente conversa, o Workflow executa. Quem usa preenche um formulário de entrada e recebe uma saída, sem diálogo no meio. ## Agente ou Workflow [#agente-ou-workflow] A pergunta que separa os dois é se o caminho é conhecido de antemão: * **Agente**: a pessoa faz perguntas abertas e o modelo decide o que fazer a cada mensagem. Bom para dúvidas, apoio e pesquisa. * **Workflow**: você sabe as etapas e a ordem delas. Bom para processar um documento, extrair campos, consultar um sistema e gerar um arquivo. Um Workflow é mais previsível e mais fácil de auditar. Um Agente cobre casos que você não antecipou. ## Os nós [#os-nós] O canvas oferece os nós agrupados por finalidade: * **Entrada e Saída**: os dois extremos do fluxo. A Entrada define os campos do formulário que a pessoa preenche; a Saída define o que ela recebe. * **LLM**: chama um modelo de IA com um prompt montado a partir do que veio antes. * **Documentos**: Extrator de arquivos, Extrator de CPF, Banco de dados vetorial e Gerador de arquivos. * **Lógica**: Condição, Iteração e Agregação, para desvios, repetição sobre listas e escolha entre resultados. * **Integração**: Requisição HTTP, Envio de Email e Integração, para falar com sistemas de fora. * **Código**: Executor de código, para transformações que nenhum nó pronto cobre. O nó **Banco de dados vetorial** é o que dá acesso às Coleções dentro de um Workflow, e ele exige pelo menos uma Coleção configurada. ## Rascunho, publicação e execuções [#rascunho-publicação-e-execuções] Como os Agentes, Workflows têm rascunho e versão publicada. Só a publicada fica disponível para execução por outras pessoas. Cada execução vira um **run** com registro próprio: entrada, saída, etapas percorridas e erros. É por ali que se investiga um resultado estranho, etapa por etapa, em vez de adivinhar. ## Onde as pessoas executam [#onde-as-pessoas-executam] Workflows publicados aparecem na área **Agentes** do módulo Chat, no ícone logo abaixo do Chat na barra de áreas. Quem abre um workflow ali vê o formulário definido pelo nó de Entrada, executa e acompanha o resultado. Não é preciso acesso ao Admin para isso. O nome da área confunde: **Agentes**, no Chat, lista Workflows publicados, não os Agentes de conversa. Os Agentes de conversa são escolhidos pelo seletor dentro da própria tela de Chat. ## Próximos passos [#próximos-passos] * Entenda as Coleções que o nó vetorial consulta em [Coleções e conhecimento](/docs/user-guide/concepts/knowledge). * Veja as ferramentas que os nós de integração alcançam em [MCPs e Integrações](/docs/user-guide/concepts/tools). # Acesso e login (/docs/user-guide/get-started/access) A AUMO usa login único (SSO): você não cria uma senha na plataforma, e sim entra com a conta que a sua empresa já usa. O mesmo login vale para o Admin e para o Chat. Ao final desta página você terá entrado na plataforma, entendido onde caiu e sabido o que fazer quando uma área aparece vazia ou bloqueada. ## Onde a plataforma fica [#onde-a-plataforma-fica] A AUMO é entregue em um endereço próprio da sua organização, fornecido pela equipe AUMO. Nesse mesmo endereço convivem os dois módulos: * **Chat**: na raiz do endereço. É onde as pessoas conversam com os Agentes. * **Admin**: no caminho `/admin`. É onde Agentes, Coleções e Workflows são configurados. Você não precisa decorar os dois endereços. Depois de entrar, a barra de áreas leva de um para o outro sem novo login. ## Entrando [#entrando] Ao abrir a plataforma deslogado, você é enviado direto para a tela de login do provedor de identidade da sua empresa. Depois de autenticar, o navegador volta para a AUMO já dentro da sua organização. Na primeira vez que você entra em uma organização, a plataforma pede aceite dos **Termos de Uso** daquela organização. A tela bloqueia o restante da plataforma até você aceitar, e o aceite vale por organização: se você participa de mais de uma, cada uma pede o seu. Se o login falhar com um aviso em vez de te levar adiante, é quase sempre porque a conta autenticada não pertence a nenhuma organização da AUMO. Use a ação de trocar de conta na própria tela e entre com o e-mail corporativo correto. ## Onde você cai depois do login [#onde-você-cai-depois-do-login] A plataforma não tem uma tela inicial única. O destino depende do que você pode ver: * **Com permissões de organização**: você cai na primeira página de Organização que o seu papel abre, normalmente Provedores ou Workspaces. * **Só com permissões de workspace**: você cai na primeira página do workspace que o seu papel abre, normalmente o Painel. * **Sem nenhuma das duas**: você cai no Chat, que é a área disponível para qualquer pessoa com acesso a um workspace. A plataforma lembra a última organização e o último workspace que você visitou e volta para eles na próxima vez, inclusive quando você pula entre Admin e Chat. ## Trocando de organização [#trocando-de-organização] O seletor de organização fica no topo da tela. Ele lista as organizações de que você participa e tem busca quando são muitas. Trocar de organização troca todo o contexto: workspaces, Agentes, Coleções e permissões passam a ser os daquela organização. Seu papel também muda: você pode ser Admin em uma e Usuário em outra. ## Quando uma área aparece bloqueada [#quando-uma-área-aparece-bloqueada] Dois casos são comuns e não são erro: * **Você não participa de nenhum workspace da organização**: as áreas de Workspace e de Chat ficam desabilitadas. Peça a um administrador para te adicionar a um workspace. * **Você chegou pelo papel de organização, sem permissão no workspace atual**: a área de Workspace continua clicável, mas abre o seletor de workspaces em vez da página. Escolha um workspace em que você tenha acesso. ## Próximos passos [#próximos-passos] * Entenda as áreas e a barra lateral em [Navegando na plataforma](/docs/user-guide/get-started/navigation). * Coloque a plataforma para funcionar seguindo [Seu primeiro agente](/docs/user-guide/get-started/first-agent). # Seu primeiro agente (/docs/user-guide/get-started/first-agent) Este tutorial monta o caminho completo da plataforma em um workspace: você cria uma **Coleção** com alguns documentos, cria um **Agente** apoiado nela e conversa com ele no Chat. Ao final você terá um agente publicado que responde com base nos seus arquivos, e terá visto onde cada etapa mora no Admin. ## Pré-requisitos [#pré-requisitos] * Acesso a um workspace com papel de **Proprietário**, **Curador** ou **Editor**. Auditor e Usuário só leem. * Pelo menos um modelo habilitado no workspace, em **Configurações › Modelos**. Sem modelo, o formulário do agente não deixa salvar. * Dois ou três arquivos de teste com conteúdo real. PDF, DOCX ou TXT servem. Textos curtos funcionam melhor para conferir a resposta. ### Crie a coleção [#crie-a-coleção] Na área **Workspace**, abra **Coleções** e clique em **+ Coleção**. Preencha o **Nome** e, se quiser, a **Descrição**. A descrição não muda a busca. Ela existe para que outra pessoa entenda o que há ali dentro seis meses depois. Abra **Adicionar arquivos** e selecione os seus documentos. O contador ao lado da seção mostra quantos arquivos estão prontos para subir. Clique em **Criar**. ### Espere a indexação terminar [#espere-a-indexação-terminar] A coleção abre na aba **Arquivos**, com uma linha por documento e o estado de cada um. Os documentos passam por **Em fila**, **Extraindo** e **Indexando** até chegar em **Extraído**. Só documentos em **Extraído** são usados nas respostas. O tempo depende do tamanho e do tipo do arquivo; PDFs digitalizados demoram mais porque passam por extração de texto. ![Aba Arquivos da coleção com os três documentos no estado Extraído](/img/tutorials/colecao/10-indexado.png) Um documento em **Extração falhou** ou **Indexação falhou** não entra nas respostas e não se recupera sozinho. Remova o arquivo e envie de novo, de preferência em um formato com texto selecionável. ### Crie o agente [#crie-o-agente] Abra **Agentes** no mesmo workspace, clique em **+ Agente** e escolha **Criar do zero**. Em **Dados básicos**, preencha o **Nome**, escolha o **Modelo** e escreva uma **Descrição**. O nome e a descrição são o que as pessoas veem na hora de escolher o agente no Chat, então descreva o trabalho dele, não a tecnologia. Em **Prompt de resposta ao usuário**, ajuste as instruções. O campo já vem com um texto padrão que funciona; para o primeiro agente, acrescente uma frase dizendo de onde ele deve tirar as respostas. O passo a passo abaixo cobre também as duas etapas seguintes: ligar a coleção e publicar. ### Ligue a coleção ao agente [#ligue-a-coleção-ao-agente] Ainda no formulário, abra a seção **Coleções** e adicione a coleção que você criou. É essa associação que liga o RAG. Não existe uma chave separada de "ativar busca". Com pelo menos uma coleção, as **Configurações de busca e contexto** aparecem logo abaixo. Sem nenhuma, o agente responde só com o modelo, as ferramentas e o prompt. As seções **MCPs**, **Sandbox**, **Integrações**, **Sub-agentes** e **Opções avançadas** podem ficar como estão neste primeiro agente. ### Publique [#publique] No rodapé do formulário, marque **Publicar ao salvar** e clique em **Salvar e publicar**. Sem a marcação, o botão é **Salvar rascunho** e o agente fica como rascunho: ele aparece na lista de **Agentes** do Admin, mas não no Chat. Publicar é o que o torna visível para as pessoas do workspace. ### Converse com ele [#converse-com-ele] Vá para a área **Chat** e confira, no alto da tela, se o workspace é o mesmo e se o agente selecionado é o que você acabou de publicar. O seletor de agente fica ao lado do nome do workspace. Faça uma pergunta cuja resposta esteja nos documentos que você subiu. Compare a resposta com o arquivo de origem: é assim que você descobre se a coleção certa está ligada e se o prompt está pedindo o comportamento que você quer. ## Quando a resposta não vem dos seus documentos [#quando-a-resposta-não-vem-dos-seus-documentos] Três causas cobrem quase todos os casos: * **Nenhum documento está em Extraído**: volte à coleção e confira o estado de cada arquivo. * **A coleção não está associada ao agente**: abra o agente e verifique a seção Coleções. * **A pergunta não casa com o texto**: a busca é por conteúdo, não por título. Pergunte usando os termos que aparecem dentro do documento. ## Próximos passos [#próximos-passos] * Acompanhe o uso do agente em **Registros › Conversas** e **Registros › Avaliação das Respostas**, no mesmo workspace. * Conheça o resto da barra lateral, e o que muda entre Organização e Workspace, em [Navegando na plataforma](/docs/user-guide/get-started/navigation). * Se alguma área aparecer bloqueada durante o tutorial, os casos comuns estão em [Acesso e login](/docs/user-guide/get-started/access). # Navegando na plataforma (/docs/user-guide/get-started/navigation) A plataforma tem duas barras à esquerda. A estreita, colada na borda, escolhe a **área**. A larga, ao lado, lista as páginas daquela área. Entender essa divisão resolve a maior parte das dúvidas de "onde fica tal coisa". Quase tudo que você procura está em uma das duas áreas administrativas, Organização ou Workspace, e a diferença entre elas é o alcance da configuração. ## As áreas [#as-áreas] A barra estreita mostra sempre os mesmos destinos, na mesma ordem, com o logo da organização no topo. Clicar no logo volta para a home da organização. * **Organização**: o que vale para a empresa inteira: provedores de IA, credenciais, membros, cotas e a lista de workspaces. * **Workspace**: o que pertence a um time ou projeto: Coleções, Agentes, Workflows, MCPs e as configurações daquele workspace. * **Chat**: a conversa com os Agentes, no dia a dia. * **Agentes**: a execução dos Workflows publicados. Você preenche um formulário de entrada e recebe o resultado, em vez de conversar. Organização e Workspace vivem no módulo Admin; Chat e Agentes, no módulo Chat. Você navega entre eles pela mesma barra, sem novo login. ## Organização e Workspace: qual usar [#organização-e-workspace-qual-usar] A regra é o alcance. Uma configuração de Organização atinge todos os workspaces; uma de Workspace para nas fronteiras dele. Algumas capacidades existem nos dois níveis, e isso é intencional: a Organização mantém o catálogo aprovado e o Workspace escolhe o que usar dele. Provedores de IA, MCPs e Integrações funcionam assim. ## A barra lateral da Organização [#a-barra-lateral-da-organização] As páginas do topo tratam do catálogo e da operação da organização: * **Provedores**: provedores de modelos de IA disponíveis para os workspaces. * **SuperAgentes**: agentes externos, registrados por URL, que a organização libera para os workspaces. * **Workspaces**: criação e gestão dos workspaces, incluindo o que cada um recebe. * **MCPs** e **Integrações**: o registro de servidores MCP e de integrações que os workspaces podem instalar. * **Credenciais**: segredos de acesso a sistemas externos, guardados uma vez e reaproveitados. * **Observabilidade**: consumo, uso por modelo e rastreamento das execuções. O grupo **Configurações** fecha a área com **Geral**, **Membros** e **Quotas**. ## A barra lateral do Workspace [#a-barra-lateral-do-workspace] No topo dela fica o seletor de workspace: é por ali que você troca de projeto sem sair da página em que está. As páginas seguintes são as que você usa para construir: * **Painel**: o resumo de uso do workspace. * **Coleções**: os documentos e conectores que alimentam as respostas dos Agentes. * **MCPs** e **Integrações**: as ferramentas instaladas neste workspace. * **Agentes** e **SuperAgentes**: os agentes que aparecem no Chat. * **Workflows**: fluxos automatizados montados em um canvas. * **Variáveis**: valores nomeados reaproveitados por Agentes e Workflows. * **Marketplace**: a biblioteca de templates de prompts, agentes e workflows. Depois vêm dois grupos. **Registros** guarda o que já aconteceu: **Conversas**, **Avaliação das Respostas** e **Observabilidade**. **Configurações** guarda os ajustes do workspace: **Geral**, **Guardrails**, **Modelos**, **Quotas**, **Membros** e **Chaves de API**. Em **Guardrails** ficam as regras que bloqueiam ou anonimizam dados sensíveis antes que cheguem à IA. ## A barra superior [#a-barra-superior] No alto da tela ficam duas coisas. À esquerda, um caminho de navegação. À direita, os controles que não pertencem a nenhuma área: o atalho para esta documentação, o botão do **assistente da plataforma** e o botão com o nome da organização. O assistente abre um painel lateral de conversa que ajuda a construir, analisar e gerenciar os workspaces sem sair da página. O botão com o nome da organização abre o seletor de organização e, junto dele, o seu menu. **Aparência** troca o tema e **Idioma** troca o idioma da interface. **Configurações** mostra o seu perfil: nome, e-mail, organização e papel. No rodapé do menu ficam a Política de Privacidade e os Termos de Uso. Papéis administrativos podem ver mais um botão na barra, **Logs**, que abre os traces de execução. ## Por que você vê menos itens [#por-que-você-vê-menos-itens] A barra lateral mostra apenas o que o seu papel permite. Duas pessoas no mesmo workspace podem ver listas diferentes, e isso não é erro de carregamento. Os papéis de organização são Superadmin, Admin, Auditor e Usuário. Os de workspace são Proprietário, Curador, Editor, Auditor e Usuário. Papéis de organização enxergam os workspaces da organização mesmo sem serem membros deles. A barra lateral é a porta, não a tranca: cada serviço reconfere as permissões a cada chamada. Um item escondido não vira acessível pela URL. ## Próximos passos [#próximos-passos] * Monte o primeiro fluxo completo em [Seu primeiro agente](/docs/user-guide/get-started/first-agent). * Se uma área aparecer bloqueada, veja os casos comuns em [Acesso e login](/docs/user-guide/get-started/access). # Conectar um sistema ao agente (/docs/user-guide/guides/connect-system) Coleções resolvem conhecimento estável, como políticas, manuais e catálogos. Elas não resolvem o que muda a cada minuto: o status de um pedido, o saldo de um estoque, o chamado aberto ontem. Para isso o Agente precisa de uma **ferramenta**: algo que ele aciona na hora da pergunta. Este guia decide qual caminho usar e monta a ligação. ## Coleção ou ferramenta [#coleção-ou-ferramenta] A pergunta é se o dado tem validade. * **Coleção**: o conteúdo vale por semanas ou meses. Indexar é mais barato e mais rápido na resposta. * **Ferramenta**: o dado precisa ser o de agora. Cada pergunta dispara uma consulta real ao sistema. Um mesmo Agente pode ter os dois: a política de trocas na Coleção, o status do pedido pela ferramenta. ## Integração ou MCP [#integração-ou-mcp] Escolhido o caminho da ferramenta, há dois jeitos: * **Integração**, quando o serviço está no catálogo que a plataforma já conhece. Menos configuração, manutenção da plataforma. * **MCP**, quando o sistema é interno ou específico do seu negócio, ou quando você precisa controlar exatamente quais ferramentas ficam expostas. ## O caminho, ponta a ponta [#o-caminho-ponta-a-ponta] Os dois seguem a mesma sequência de três telas, em papéis diferentes: 1. **Na organização**, alguém com papel de Superadmin ou Admin cadastra o servidor MCP ou a integração no catálogo, com a credencial de acesso. 2. **Na gestão de workspaces**, o item é associado ao workspace que vai usá-lo. 3. **No workspace**, ele é instalado, com nome e configuração próprios. A etapa 2 é a que trava mais gente. Um servidor cadastrado e um workspace sem nada em "Disponíveis" quase sempre significa que a associação não foi feita. ## Entregar ao agente [#entregar-ao-agente] Instalar no workspace ainda não entrega nada. No formulário do Agente, marque o item na seção **MCPs** ou **Integrações**. Na seção de MCPs, ajuste também o **máximo de iterações**: quantas vezes o Agente pode acionar ferramentas em uma resposta. O padrão serve para a maioria; suba apenas se o Agente estiver concluindo antes de terminar o trabalho. ## Escrever o prompt com ferramenta [#escrever-o-prompt-com-ferramenta] Instruções permanentes precisam dizer **quando** usar a ferramenta. Sem isso, o modelo tende a responder de memória em vez de consultar. ```text Para qualquer pergunta sobre status, prazo ou valor de um pedido, consulte o sistema antes de responder. Nunca estime esses dados. ``` ## Quando a ferramenta não é acionada [#quando-a-ferramenta-não-é-acionada] Em ordem de frequência: * **Não está marcada no formulário do Agente.** Instalação no workspace não é entrega. * **O prompt não instrui a usá-la**, e o modelo respondeu sem consultar. * **O limite de iterações foi atingido** antes de completar as chamadas. * **O servidor está fora do ar.** A falha aparece nos traces, em Observabilidade. Os traces são o modo de distinguir os dois primeiros casos dos dois últimos: eles mostram se a chamada chegou a acontecer. ## Segurança [#segurança] Um MCP dá ao Agente a capacidade de **agir** em sistemas reais, não só de ler. Antes de liberar um servidor para os times, confira o resultado da análise automática em [Scanner de segurança](/docs/user-guide/tools/mcp/security). ## Próximos passos [#próximos-passos] * Registre o servidor em [MCPs](/docs/user-guide/tools/mcp). * Ou use uma conexão pronta em [Integrações](/docs/user-guide/tools/integrations). # Extrair dados de documentos em lote (/docs/user-guide/guides/document-extraction) Quando a tarefa é sempre a mesma, como ler contratos e extrair partes, valores e prazos, um Workflow entrega mais que um Agente. O caminho é fixo, o resultado é estruturado e cada execução fica registrada. Este guia monta o fluxo de extração em lote, do upload ao resultado. ## Pré-requisitos [#pré-requisitos] * Papel de **Proprietário**, **Curador** ou **Editor** no workspace. * Um modelo habilitado, de preferência barato, já que a tarefa é repetitiva. * Alguns arquivos de exemplo que representem a variação real dos documentos. ## O desenho do fluxo [#o-desenho-do-fluxo] ### Entrada: receba a lista de arquivos [#entrada-receba-a-lista-de-arquivos] No nó de **Entrada**, declare uma variável que recebe os arquivos. Ela vira o campo do formulário que quem executa preenche. Dê a ela um nome legível: quem executa lê esse rótulo na tela. ### Extrator de arquivos: converta em texto [#extrator-de-arquivos-converta-em-texto] Ligue um nó **Extrator de arquivos** à Entrada. Ele transforma os binários em texto e devolve uma lista, acessível como `{{ extrator_arquivos.contents }}`. Sem este nó, os arquivos não chegam ao modelo de forma aproveitável. ### Iteração: repita por documento [#iteração-repita-por-documento] Adicione um nó de **Iteração** e aponte a entrada dele para a lista de textos extraídos. Dentro do laço, o nó **Início da iteração** fornece `item`, o texto de um documento, e `index`. ### LLM: extraia os campos [#llm-extraia-os-campos] Dentro da Iteração, ligue um nó **LLM** ao Início da iteração. No prompt, peça os campos e **exija o formato**. ```text Extraia os campos abaixo do contrato e responda apenas com JSON válido, sem texto antes ou depois. Campos: partes, valor_total, data_inicio, data_fim, prazo_rescisao. Use null quando o campo não estiver no documento. Contrato: {{ inicio_da_iteracao.item }} ``` A instrução de formato não é opcional. Sem ela, o modelo devolve texto corrido e nada depois consegue tratar a saída de forma confiável. ### Saída da iteração: colete os resultados [#saída-da-iteração-colete-os-resultados] Em **Variáveis de saída** do nó de Iteração, declare o nome da lista que sai do laço, por exemplo `contratos_extraidos`, e aponte a variável de origem para a resposta do nó LLM interno. ### Saída: devolva o resultado [#saída-devolva-o-resultado] Ligue a lista ao nó de **Saída**. Para um resultado consumível por outro sistema, declare campos separados; para leitura humana, um campo só com o consolidado basta. Se quem executa precisa de um arquivo, acrescente um nó **Gerador de arquivos** antes da Saída. ## Antes de publicar [#antes-de-publicar] Execute a partir do estúdio com dois ou três documentos reais, incluindo um caso atípico. O registro da execução mostra o que cada nó recebeu e devolveu, etapa a etapa. O ponto de falha mais comum é o nó LLM devolvendo formato inconsistente em documentos fora do padrão. Isso se resolve no prompt, não no nó seguinte. ## O custo [#o-custo] Um nó LLM dentro de uma Iteração executa **uma vez por item**. Cem documentos são cem chamadas. Antes de liberar para o time, estime o custo de um lote típico em **Observabilidade** e, se for relevante, defina um teto em **Quotas**. ## Publicar [#publicar] Publique o Workflow. Ele passa a aparecer na área **Agentes** do módulo Chat, onde as pessoas executam sem precisar de acesso ao Admin. ## Próximos passos [#próximos-passos] * Escolha o nó certo para cada etapa em [Catálogo de nós](/docs/user-guide/workflows/nodes). * Investigue uma execução que saiu errada em [Execuções](/docs/user-guide/workflows/runs). # Colocar um agente na mão do time (/docs/user-guide/guides/rollout) Publicar um Agente é um clique. Colocá-lo em uso por um time envolve três coisas que a tela de publicação não menciona: quem consegue acessá-lo, quanto ele vai custar e como você saberá se está funcionando. Este guia cobre essas três. ## Antes de publicar [#antes-de-publicar] Uma conferência curta evita a maior parte dos problemas do primeiro dia: * **Os documentos estão Ativos.** Coleções em indexação fazem o Agente responder como se estivesse vazio. * **O modelo continua habilitado** no workspace. Um modelo retirado quebra o Agente sem aviso. * **Uma pergunta real foi testada**, e a referência citada sustenta a resposta. ## Quem vai conseguir usar [#quem-vai-conseguir-usar] Conversar no Chat exige apenas ser **membro do workspace**. Nenhum papel administrativo é necessário, e **Usuário** basta. O caminho para incluir alguém tem dois passos, em telas diferentes: 1. A pessoa precisa pertencer à **organização**. Se ainda não pertence, alguém com papel de Admin a convida. 2. A pessoa precisa ser adicionada ao **workspace**, pelo Proprietário dele. Um sintoma comum no primeiro dia: alguém entra e não vê Agente nenhum. Quase sempre é o passo 2 faltando, ou o Agente ter ficado como rascunho. ## Estimar e limitar o custo [#estimar-e-limitar-o-custo] Antes de abrir para muita gente, vale ter uma noção de ordem de grandeza. Deixe o Agente rodar com um grupo pequeno por alguns dias e observe em **Observabilidade** o consumo por modelo, e em **Painel** o uso por Agente. A partir daí: * Defina um teto de **Workspace** com folga sobre o pico observado, não sobre a média. * Considere um teto por **Usuário**, que é o que protege contra um caso isolado consumindo o mês inteiro. Começar apertado gera bloqueio no primeiro dia de uso intenso, e a correção acaba virando uma política permanentemente alta. ## Comunicar o que ele faz [#comunicar-o-que-ele-faz] O **nome** e a **descrição** do Agente são a única instrução que a maioria das pessoas vai ler. Elas aparecem no seletor do Chat. Descreva o trabalho e o limite: "Dúvidas sobre políticas de RH: férias, despesas e benefícios" diz mais que "Assistente de RH", e reduz perguntas fora de escopo. ## As primeiras semanas [#as-primeiras-semanas] Três telas, em ordem de utilidade: * **Registros › Avaliação das Respostas**: onde os problemas aparecem primeiro. Volume baixo é normal; as pessoas avaliam pouco, e quase sempre quando algo deu errado. * **Registros › Conversas**: o que as pessoas de fato perguntam. Costuma render a segunda versão do prompt e uma lista de documentos que faltavam. * **Painel**: se o uso se sustenta depois da novidade passar. ## Mudar um agente em uso [#mudar-um-agente-em-uso] Não existe rascunho de um Agente já publicado. Salvar uma alteração coloca essa alteração em produção na conversa seguinte de todo mundo. Para mudanças grandes, duplique o Agente, ajuste a cópia como rascunho e só então substitua. ## Próximos passos [#próximos-passos] * Ajuste as instruções a partir do que você leu em [Escrever o prompt](/docs/user-guide/agents/prompt). * Configure os tetos em [Definir limites](/docs/user-guide/models/quotas/limits). # Agente de suporte com base própria (/docs/user-guide/guides/support-agent) É o caso de uso mais comum da plataforma: um Agente que responde dúvidas recorrentes de política de despesas, processo de férias ou catálogo de produtos, a partir dos documentos que a empresa já tem. Este guia vai além do [primeiro agente](/docs/user-guide/get-started/first-agent): trata do que faz a diferença entre um agente que demonstra bem e um que aguenta uso real. ## Pré-requisitos [#pré-requisitos] * Papel de **Proprietário**, **Curador** ou **Editor** no workspace. * Ao menos um modelo habilitado em **Configurações › Modelos**. * Os documentos que sustentam as respostas, em formato com texto selecionável. ## Recortar as coleções [#recortar-as-coleções] ### Separe por assunto, não por origem [#separe-por-assunto-não-por-origem] Uma Coleção por tema, como "Políticas de RH" ou "Catálogo de produtos", funciona melhor que uma Coleção única com tudo. O recorte por assunto deixa a busca mais precisa e permite tirar um conjunto de circulação sem afetar o resto. ### Descarte o que está desatualizado [#descarte-o-que-está-desatualizado] Documentos contraditórios são o modo mais comum de um Agente dar respostas erradas com aparência de certas. Duas versões da mesma política, ambas indexadas, e o Agente cita a antiga. Antes de subir, confirme qual é a versão vigente de cada documento. ### Espere a indexação [#espere-a-indexação] Confira em **Coleções › Arquivos** que todos os documentos chegaram ao estado **Ativo**. Documentos em processamento não participam das respostas, e não há aviso disso na tela do Agente. ## Escrever o prompt [#escrever-o-prompt] O texto padrão do formulário cobre tom e formato. Para um agente de suporte, acrescente três coisas: * **O papel e o público**: quem ele atende e sobre o que responde. * **A ordem de prioridade**: responder a partir dos documentos recuperados, não do conhecimento geral do modelo. * **O comportamento na lacuna**: dizer que não encontrou, e indicar a quem recorrer. A terceira é a que mais economiza retrabalho. Sem ela, o modelo completa a lacuna com o que aprendeu no treino, e a resposta sai plausível, sem referências e errada. ## Testar antes de publicar [#testar-antes-de-publicar] Teste com perguntas reais, não com as que você escreveria. Três categorias que revelam problemas: * **Perguntas ambíguas**, que podem se referir a dois documentos. * **Perguntas fora de escopo**, para conferir se ele recusa em vez de inventar. * **Perguntas cuja resposta mudou** recentemente, para checar se a versão certa está indexada. Em cada resposta, abra o bloco de **Referências** e confira se o trecho citado sustenta o que foi dito. ## Publicar e acompanhar [#publicar-e-acompanhar] Marque **Publicar ao salvar**. O Agente passa a aparecer no seletor do Chat para o workspace. Nas primeiras semanas, duas telas respondem se ele está servindo: * **Registros › Conversas** mostra o que as pessoas de fato perguntam, que raramente é o que se imaginou. * **Registros › Avaliação das Respostas** concentra os casos que deram errado. A leitura dessas duas costuma render a segunda versão do prompt e uma lista de documentos que faltavam. ## Próximos passos [#próximos-passos] * Ajuste o texto de instruções em [Escrever o prompt](/docs/user-guide/agents/prompt). * Limite o custo do agente em [Quotas](/docs/user-guide/models/quotas). # Guia do Usuário (/docs/user-guide) A AUMO é uma plataforma de IA corporativa: você conecta os documentos e sistemas da sua empresa, cria agentes que respondem a partir deles e coloca esses agentes na mão das pessoas pelo Chat. Admin e Chat compartilham o mesmo login e a mesma barra de navegação. O que muda é a área em que você está. **Organização** trata do que vale para a empresa inteira. **Workspace**, do que pertence a um time ou projeto. **Chat** e **Agentes** são o uso do dia a dia. ## Comece por aqui [#comece-por-aqui] Entrar na plataforma e escolher a organização e o workspace certos. Entender as áreas, a barra lateral e por que você vê menos itens que outra pessoa. Criar uma coleção, publicar um agente e conversar com ele em cerca de 15 minutos. # Domínios de conhecimento (/docs/user-guide/knowledge/allowed-domains) A aba **Fontes de Conhecimento** controla quais domínios externos os conectores das Coleções podem acessar, serviço por serviço. Um domínio fora da lista é recusado no momento de configurar o conector, no workspace. ## Os serviços cobertos [#os-serviços-cobertos] * **Atlassian**: domínios permitidos para Confluence e Jira. * **SharePoint**: domínios permitidos. * **OneDrive**: domínios permitidos. Cada um tem a própria lista. Liberar um domínio na Atlassian não o libera no SharePoint. ## Por que a lista existe [#por-que-a-lista-existe] Sem ela, qualquer pessoa com permissão para criar Coleções no workspace poderia indexar um site arbitrário usando a infraestrutura e as credenciais da organização. A lista inverte o padrão: nada é alcançável até que alguém com papel de **Superadmin** autorize aquele domínio explicitamente. ## Adicionar um domínio [#adicionar-um-domínio] Abra a configuração do serviço correspondente e acrescente o domínio à lista de permitidos. Vale conferir o domínio exato que o serviço usa. Uma instância Atlassian em `empresa.atlassian.net` não é alcançada por uma entrada `atlassian.net`, e o erro só aparece quando alguém tenta configurar o conector. Quando um conector falha ao ser criado com erro de domínio, a causa está aqui, e não nas permissões do workspace nem na credencial do serviço. ## Próximos passos [#próximos-passos] * Entenda o que os conectores alimentam em [Coleções e conhecimento](/docs/user-guide/concepts/knowledge). * Veja as demais abas em [Configurações](/docs/user-guide/admin/org-settings). # Confluence (/docs/user-guide/knowledge/connectors/confluence) O conector do **Confluence** traz páginas dos espaços da sua instância Atlassian para a Coleção. É um dos conectores de maior retorno, porque o Confluence costuma concentrar exatamente o tipo de conteúdo que um Agente de suporte precisa: políticas, procedimentos e decisões registradas. ## Pré-requisitos [#pré-requisitos] 1. As credenciais OAuth do Confluence cadastradas na organização, em **Credenciais**. 2. O domínio da instância liberado em **Configurações › Fontes de Conhecimento**. ## Configurar [#configurar] O formulário pede a instância Atlassian e os espaços a sincronizar. A plataforma lê a lista de sites disponíveis a partir da credencial autorizada. Quando a credencial dá acesso a mais de uma instância, a seleção precisa apontar para uma delas de forma explícita. Páginas de rascunho e espaços pessoais entram na sincronização se estiverem no recorte selecionado. Como o Confluence costuma acumular versões antigas em espaços de arquivo, vale conferir o recorte antes de ligar o agendamento. ## Conteúdo desatualizado [#conteúdo-desatualizado] O risco típico do Confluence é ter duas páginas sobre o mesmo assunto, uma vigente e uma antiga, ambas indexadas. O Agente encontra as duas e pode citar a errada. Restringir a sincronização aos espaços mantidos, e excluir os de arquivo, resolve mais do que ajustar o prompt do Agente depois. ## Próximos passos [#próximos-passos] * Configure o conector irmão em [Jira](/docs/user-guide/knowledge/connectors/jira). * Veja os demais conectores em [Visão geral](/docs/user-guide/knowledge/connectors). # Google Drive (/docs/user-guide/knowledge/connectors/google-drive) O conector do **Google Drive** traz documentos de pastas do Drive para a Coleção, com sincronização periódica. A plataforma tem duas variantes: a conexão pela conta de quem configura e a conexão por conta de serviço, que acessa em nome da organização. ## Escolher a variante [#escolher-a-variante] * **Conta pessoal**: o conector enxerga o que aquela conta enxerga. Simples de configurar, mas o acesso morre se a pessoa sair da empresa. * **Conta de serviço**: o acesso pertence à organização e sobrevive a trocas de time. Exige configuração do lado do Google Workspace. Para conteúdo que um time inteiro depende, a segunda evita o conector quebrar sem aviso meses depois. ## Configurar [#configurar] O fluxo pede a autorização no Google e, depois dela, a seleção das pastas ou arquivos a sincronizar. A plataforma oferece também o seletor do Google, que exige as chaves `VITE_GOOGLE_CLIENT_ID`, `VITE_GOOGLE_PICKER_API_KEY` e `VITE_GOOGLE_APP_ID` configuradas no ambiente. Sem elas, a seleção é feita pelo caminho alternativo. Permissão revogada no Google derruba a sincronização sem alterar o que já foi indexado. Os documentos antigos continuam respondendo, agora desatualizados, e a falha aparece só no conector. ## Formatos [#formatos] Documentos nativos do Google (Docs, Sheets, Slides) e arquivos comuns depositados no Drive são processados pelo mesmo caminho de extração dos arquivos enviados à mão. Arquivos digitalizados sem camada de texto dependem de extração por reconhecimento e podem falhar. ## Próximos passos [#próximos-passos] * Acompanhe o processamento em [Indexação](/docs/user-guide/knowledge/indexing). * Veja os demais conectores em [Visão geral](/docs/user-guide/knowledge/connectors). # Visão geral (/docs/user-guide/knowledge/connectors) Um **conector** liga uma Coleção a uma fonte externa e traz o conteúdo dela periodicamente. Onde um arquivo enviado fica parado até alguém substituí-lo, um conector volta a buscar. Eles ficam na aba **Conectores** da Coleção, ao lado de Arquivos. ## Quando usar [#quando-usar] Conectores compensam quando a fonte muda com frequência e alguém teria que reenviar arquivos manualmente: uma base de conhecimento em Confluence, um repositório de documentos, um site público que vira referência. Para um conjunto estável de documentos que muda uma vez por ano, o envio manual é mais simples e não depende de credencial nem de domínio liberado. ## Adicionar um conector [#adicionar-um-conector] Na Coleção, clique em **+ Fonte** e escolha **Criar conector**. A outra opção, **Enviar Arquivos**, sobe arquivos avulsos. Escolha o tipo e clique em **Próximo**. O formulário muda conforme o tipo. O **Indexador** pede **Nome**, **URL** e **Tipo de extração**; ao seguir links internos, ele também pergunta se deve **Usar links de sites exteriores** e qual a **Profundidade de extração**. Um conector de repositório pede o espaço e a credencial de acesso. Em **Tipo da tarefa** você define quando a sincronização roda: **Executar imediatamente**, **Executar rotineiramente** ou **Executar na data selecionada**. Domínios externos precisam estar liberados na organização. Um conector Atlassian, SharePoint ou OneDrive apontando para um domínio fora da lista é recusado na criação. A lista fica em **Organização › Configurações › Fontes de Conhecimento**. ## Sincronizações [#sincronizações] Cada execução de um conector é uma **sincronização**, com estado próprio. Sincronizações em fila, em execução ou falhas aparecem como pendências no conector. Uma falha de sincronização não invalida o que já foi indexado: o conteúdo trazido antes continua respondendo. O que para é a atualização. ## Quando a sincronização falha [#quando-a-sincronização-falha] As causas mais comuns são externas à plataforma: * **Credencial expirada** na fonte de origem. * **Permissão revogada** para a conta usada pelo conector. * **Domínio não liberado** na configuração da organização. O erro aparece no conector, não nos documentos. Um documento indexado por uma sincronização anterior continua com estado **Extraído** mesmo que a sincronização seguinte tenha falhado. ## Próximos passos [#próximos-passos] * Confira o estado dos documentos trazidos em [Indexação](/docs/user-guide/knowledge/indexing). * Veja quem libera os domínios em [Domínios de conhecimento](/docs/user-guide/knowledge/allowed-domains). ## Os conectores disponíveis [#os-conectores-disponíveis] Rastrear páginas públicas. O único que não exige credencial. Pastas e arquivos do Drive, por conta pessoal ou de serviço. Bibliotecas de documentos do Microsoft 365. Pastas pessoais e compartilhadas do Microsoft 365. Espaços e páginas da instância Atlassian. Issues e projetos, para perguntas sobre histórico. # Indexador de site (/docs/user-guide/knowledge/connectors/indexer) O **Indexador** percorre URLs públicas e traz o texto das páginas para a Coleção. É o conector que não depende de credencial: se a página abre no navegador sem login, ele alcança. Internamente a plataforma o identifica como `web_scraper`. ## Quando usar [#quando-usar] Serve para conteúdo que já está publicado e é a fonte de verdade: documentação pública, central de ajuda, páginas de produto, políticas em site institucional. Não serve para conteúdo atrás de login, nem para páginas que montam o texto por JavaScript depois do carregamento. ## Configurar [#configurar] O formulário pede a lista de URLs a percorrer e o tipo de extração aplicado ao conteúdo encontrado. A descrição do conector, quando você não preenche, recebe o valor padrão `Indexador`. Vale substituir por algo que diga qual site é, porque a lista de conectores mostra esse texto. ## Agendamento [#agendamento] Como os demais conectores, ele aceita agendamento. A frequência define de quanto em quanto tempo as URLs são percorridas de novo. Páginas que mudam pouco não justificam sincronização diária: cada execução reprocessa o conteúdo e consome tempo de indexação. O Indexador não respeita paywall nem sessão. Uma URL que exige login devolve a página de login, e é esse texto que acaba indexado na Coleção. ## Próximos passos [#próximos-passos] * Confira o estado dos documentos trazidos em [Indexação](/docs/user-guide/knowledge/indexing). * Veja os demais conectores em [Visão geral](/docs/user-guide/knowledge/connectors). # Jira (/docs/user-guide/knowledge/connectors/jira) O conector do **Jira** traz o conteúdo de issues para a Coleção: título, descrição e o que estiver registrado nos campos de texto. Ele compartilha a autenticação Atlassian com o conector do Confluence, e a configuração pode reaproveitar a credencial já cadastrada. ## Pré-requisitos [#pré-requisitos] 1. As credenciais OAuth do Jira cadastradas na organização, em **Credenciais**. 2. O domínio da instância liberado em **Configurações › Fontes de Conhecimento**. Quando a organização já usa Confluence, o formulário permite apontar para a credencial do Confluence em vez de exigir uma nova autorização. ## Configurar [#configurar] O formulário pede a instância e o recorte de projetos a sincronizar. ## Quando o Jira ajuda, e quando atrapalha [#quando-o-jira-ajuda-e-quando-atrapalha] Issues são um bom acervo para perguntas sobre histórico: por que uma decisão foi tomada, se um problema já apareceu antes, qual foi a solução aplicada. Issues também carregam discussão em andamento, hipóteses descartadas e opinião individual. Indexar um projeto inteiro faz o Agente tratar tudo isso como fato, e ele passa a responder com coisas que ninguém decidiu. Um recorte por projeto resolvido, ou por tipo de issue, costuma render melhor que o backlog completo. ## Próximos passos [#próximos-passos] * Configure o conector irmão em [Confluence](/docs/user-guide/knowledge/connectors/confluence). * Veja os demais conectores em [Visão geral](/docs/user-guide/knowledge/connectors). # OneDrive (/docs/user-guide/knowledge/connectors/onedrive) O conector do **OneDrive** traz arquivos das pastas pessoais ou compartilhadas do Microsoft 365 para a Coleção. Ele compartilha a base de autenticação com o conector do SharePoint, mas aponta para o armazenamento individual em vez das bibliotecas de site. ## Pré-requisitos [#pré-requisitos] Como no SharePoint, dois itens precisam existir antes: 1. As credenciais OAuth do OneDrive cadastradas na organização, em **Credenciais**. 2. O domínio liberado em **Configurações › Fontes de Conhecimento**. ## Configurar [#configurar] Após a autorização, selecione as pastas a sincronizar. O conector enxerga o que a conta autorizada enxerga, incluindo o que foi compartilhado com ela. ## OneDrive ou SharePoint [#onedrive-ou-sharepoint] A escolha acompanha onde o conteúdo de fato mora: * **OneDrive** para material que pertence a uma pessoa ou a um pequeno grupo. * **SharePoint** para documentação oficial de um time, em biblioteca de site. Conteúdo em OneDrive pessoal costuma sair da empresa junto com a pessoa. Para conhecimento que o time depende, mover para uma biblioteca do SharePoint antes de indexar evita perder a fonte depois. ## Próximos passos [#próximos-passos] * Compare com a alternativa em [SharePoint](/docs/user-guide/knowledge/connectors/sharepoint). * Veja os demais conectores em [Visão geral](/docs/user-guide/knowledge/connectors). # SharePoint (/docs/user-guide/knowledge/connectors/sharepoint) O conector do **SharePoint** traz documentos das bibliotecas da sua organização no Microsoft 365 para a Coleção. É o caminho para empresas cuja documentação interna vive no SharePoint e não em arquivos soltos. ## Pré-requisitos [#pré-requisitos] Dois itens precisam estar prontos antes, e nenhum deles é configurado nesta tela: 1. As credenciais OAuth do SharePoint cadastradas na organização, em **Credenciais**. 2. O domínio da sua instância liberado em **Configurações › Fontes de Conhecimento**. O domínio precisa bater exatamente. Uma instância em `empresa.sharepoint.com` não é alcançada por uma entrada `sharepoint.com`, e o erro só aparece ao tentar criar o conector. ## Configurar [#configurar] Depois da autorização, você seleciona o site e as bibliotecas de documentos a sincronizar. A permissão do conector é a da conta autorizada. Bibliotecas restritas a outros grupos não aparecem na seleção, e isso não é falha da plataforma. ## Permissões e o que fica visível [#permissões-e-o-que-fica-visível] O conector não reproduz as permissões do SharePoint dentro da Coleção. Tudo que ele indexa fica disponível para qualquer Agente ligado àquela Coleção, e portanto para qualquer pessoa do workspace que converse com ele. Se parte do conteúdo é restrita, o recorte precisa ser feito na seleção das bibliotecas, não depois. ## Próximos passos [#próximos-passos] * Libere o domínio em [Domínios de conhecimento](/docs/user-guide/knowledge/allowed-domains). * Veja os demais conectores em [Visão geral](/docs/user-guide/knowledge/connectors). # Criar uma coleção (/docs/user-guide/knowledge/create) O formulário de **Nova Coleção** é curto de propósito: nome, descrição e as fontes iniciais. Tudo o mais é ajustado depois, na Coleção já criada. Você precisa do papel **Proprietário**, **Curador** ou **Editor**. ## Passo a passo [#passo-a-passo] ### Abra o formulário [#abra-o-formulário] Em **Workspace › Coleções**, clique em **+ Coleção**. ### Nomeie a coleção [#nomeie-a-coleção] O **Nome** é obrigatório. Ele é o que aparece na lista e na hora de associar a Coleção a um Agente, então descreva o assunto, não a origem dos arquivos. A **Descrição** é opcional e não influencia a busca. Ela existe para que outra pessoa entenda o que há ali dentro seis meses depois. ### Adicione arquivos [#adicione-arquivos] Abra **Adicionar arquivos** e selecione os documentos. O contador ao lado da seção mostra quantos estão prontos para subir. Essa etapa é opcional. Uma Coleção pode nascer vazia e receber arquivos depois. ### Adicione conectores [#adicione-conectores] Abra **Adicionar conectores** se quiser que a Coleção busque conteúdo de uma fonte externa, em vez de depender de envio manual. ### Crie [#crie] Clique em **Criar**. A Coleção abre já na aba **Arquivos**, com o processamento dos documentos em andamento. Criar a Coleção não a torna utilizável na hora. Os documentos passam por extração e indexação, e só respondem quando chegam ao estado **Extraído**. ## Escolhendo o recorte [#escolhendo-o-recorte] A pergunta que define quantas Coleções criar é quem vai consultar o quê. Uma Coleção por assunto, com Agentes diferentes consultando as que interessam a cada um, costuma funcionar melhor do que uma Coleção única com tudo dentro. A busca fica mais precisa e fica mais fácil tirar um conjunto de circulação sem afetar o resto. ## Próximos passos [#próximos-passos] * Acompanhe o processamento em [Indexação](/docs/user-guide/knowledge/indexing). * Associe a Coleção a quem responde em [Criar um agente](/docs/user-guide/agents/create). # Arquivos (/docs/user-guide/knowledge/files) A aba **Arquivos** lista os documentos enviados manualmente a uma Coleção, com o estado de cada um. É a aba que abre por padrão ao entrar em uma Coleção, e onde se resolve a maior parte dos problemas de "o agente não sabe dessa informação". ## Enviar documentos [#enviar-documentos] Use **Enviar arquivos** na coleção vazia, ou **+ Fonte** na barra superior quando já houver conteúdo. Formatos com texto selecionável, como PDF nativo, DOCX e TXT, são os mais previsíveis. PDFs digitalizados funcionam, mas dependem de extração de texto e demoram mais. ## Ler a lista [#ler-a-lista] Cada linha traz o documento, a origem e o estado. A busca filtra por nome, e o ícone de filtro restringe por estado. A coluna de origem distingue o que foi enviado à mão do que veio de um conector: documentos manuais aparecem como **Upload**, os demais mostram a URL ou o identificador da fonte. ## Substituir um documento [#substituir-um-documento] Não há edição de conteúdo. Para atualizar um documento, remova a versão antiga e envie a nova. Fazer só o envio da nova, sem remover a antiga, deixa as duas indexadas. O Agente passa a encontrar trechos das duas versões e pode responder com a desatualizada. Esse é o modo mais comum de um Agente dar respostas contraditórias: duas versões do mesmo documento vivas na mesma Coleção. ## Remover [#remover] Remover um documento o tira das respostas futuras. Conversas anteriores que o citaram continuam no histórico como estão. A remoção não é imediata em todos os casos. O documento sai do índice de busca, o que pode levar alguns instantes em coleções grandes. ## Quando um arquivo não aparece [#quando-um-arquivo-não-aparece] * **Ele está em processamento**: confira o estado na própria lista. * **Ele falhou**: os estados de erro estão descritos em [Indexação](/docs/user-guide/knowledge/indexing). * **Ele veio de um conector**: documentos sincronizados ficam na aba **Conectores**, não aqui. ## Próximos passos [#próximos-passos] * Entenda os estados de processamento em [Indexação](/docs/user-guide/knowledge/indexing). * Automatize a entrada de conteúdo em [Conectores](/docs/user-guide/knowledge/connectors). # Visão geral (/docs/user-guide/knowledge) Uma **Coleção** reúne os documentos que um Agente consulta antes de responder. É o que faz a plataforma responder com o conteúdo da sua empresa, e não só com o que o modelo aprendeu no treino. Coleções pertencem a este workspace e não são visíveis para nenhum outro. ## A lista [#a-lista] A tela mostra as Coleções em grade ou tabela, com busca por nome. A visão em tabela traz o número de **Documentos**, a **Descrição** e a data de criação. Criar e editar Coleções exige papel de **Proprietário**, **Curador** ou **Editor**. Auditor vê a lista sem alterá-la. ## Como uma Coleção é usada [#como-uma-coleção-é-usada] A Coleção sozinha não faz nada. Ela passa a valer quando alguém a associa a um Agente, na seção **Coleções** do formulário daquele Agente. Um Agente pode consultar várias Coleções; uma Coleção pode atender vários Agentes. Nada é exclusivo. O formulário, os arquivos iniciais e os conectores. Enviar, substituir e remover documentos de uma coleção. Sincronizar fontes externas em vez de subir arquivos à mão. Os estados de um documento e o que fazer quando um falha. # Indexação (/docs/user-guide/knowledge/indexing) Entre enviar um documento e ele aparecer em uma resposta há um processamento em etapas. Cada documento carrega o estado da etapa em que está. Só documentos **Ativos** participam das respostas. Todos os outros estados são intermediários ou de erro. ## Os estados [#os-estados] | Estado | O que está acontecendo | | ------------------ | ---------------------------------------------------------------- | | `Em fila` | O arquivo chegou e aguarda processamento. | | `Extraindo` | O conteúdo está sendo transformado em texto. | | `Indexando` | O texto está sendo quebrado em trechos e preparado para a busca. | | `Ativo` | O documento está disponível para as respostas. | | `Extração falhou` | Não foi possível obter texto do arquivo. | | `Indexação falhou` | O texto foi obtido, mas não entrou no índice de busca. | O tempo total depende do tamanho e do tipo do arquivo. PDFs digitalizados demoram mais porque a extração precisa reconhecer o texto na imagem. Nenhum dos dois estados de erro se recupera sozinho. Um documento parado neles fica invisível para os Agentes indefinidamente, sem nenhum aviso na tela do Agente. ## Quando a extração falha [#quando-a-extração-falha] **Extração falhou** quase sempre significa que o arquivo não tem texto recuperável: * Um PDF que é apenas a imagem de uma página digitalizada, sem camada de texto. * Um arquivo corrompido ou protegido por senha. * Um formato que a plataforma não processa. A saída é converter o arquivo para um formato com texto selecionável e enviá-lo de novo. Reenviar o mesmo arquivo produz a mesma falha. ## Quando a indexação falha [#quando-a-indexação-falha] **Indexação falhou** é mais raro e não depende do formato: o texto foi obtido, mas não entrou no índice. Remova o documento e envie de novo. Se a falha se repetir com o mesmo arquivo, o conteúdo tem alguma particularidade que vale reportar ao suporte, com o documento em mãos. ## O efeito de um documento parado [#o-efeito-de-um-documento-parado] Um Agente associado a uma Coleção cujos documentos ainda estão processando responde como se a Coleção estivesse vazia. Não há aviso, nem no Admin nem no Chat. Por isso, ao publicar um Agente logo depois de criar a Coleção, vale voltar a esta aba e confirmar que os documentos chegaram a **Ativo** antes de avisar as pessoas. ## Próximos passos [#próximos-passos] * Gerencie os documentos em [Arquivos](/docs/user-guide/knowledge/files). * Entenda como os trechos indexados viram resposta em [Coleções e conhecimento](/docs/user-guide/concepts/knowledge). # O provedor AUMO (/docs/user-guide/models/providers/aumo) O provedor **AUMO** é o único que não depende de você trazer uma conta. Em vez de cadastrar a credencial de um serviço externo, a organização solicita o acesso e a AUMO o fornece. Para quem usa a plataforma, o resultado é idêntico: ele aparece na lista de Provedores como qualquer outro, e seus modelos são atribuídos aos workspaces da mesma forma. ## Como o acesso é concedido [#como-o-acesso-é-concedido] O fluxo tem duas pontas e não se completa só do seu lado: 1. A sua organização solicita o provedor AUMO. 2. A solicitação fica **pendente** até alguém do lado da AUMO aprová-la. 3. Na aprovação, são definidas as cotas e quais modelos ficam habilitados. 4. A organização sincroniza o provedor, e os modelos aprovados passam a aparecer. Enquanto a solicitação estiver pendente, o provedor não serve chamadas. Não há o que ajustar na sua ponta nesse intervalo. ## Cotas negociadas [#cotas-negociadas] Diferente de uma conta própria, onde o teto é o do seu contrato com o fornecedor, o provedor AUMO vem com limites definidos no momento da aprovação. Esses limites são independentes das **Quotas** que você configura na plataforma. As suas quotas repartem o consumo entre workspaces e pessoas; o limite negociado é o teto externo, acima de tudo isso. Uma recusa por cota pode vir, portanto, de duas origens: do seu próprio teto na plataforma ou do limite acordado com a AUMO. ## Modelos habilitados [#modelos-habilitados] A lista de modelos que o provedor AUMO oferece é definida na aprovação, não por você. Se um modelo esperado não aparece na hora de atribuir a um workspace, o caminho é falar com a AUMO, não procurar uma configuração na plataforma. Alguns recursos internos exigem modelos AUMO específicos. O **Agente de Chat** da plataforma, por exemplo, só aceita modelos AUMO com capacidade de visão. ## Próximos passos [#próximos-passos] * Cadastre contas próprias de outros serviços em [Cadastrar um provedor](/docs/user-guide/models/providers/register). * Reparta o consumo entre os times em [Quotas](/docs/user-guide/models/quotas). # Visão geral (/docs/user-guide/models/providers) Um **Provedor** é a conta de um serviço de modelos de IA: AUMO, OpenAI, Bedrock e equivalentes. Sem ao menos um provedor cadastrado, nenhum workspace habilita modelos e nenhum Agente responde. A tela exige o papel **Superadmin**. Admin e Auditor não a alcançam, por ser onde as credenciais de IA ficam guardadas. ## A lista [#a-lista] Cada linha mostra o provedor, o ícone do serviço e a data de criação. O menu de ações de cada linha permite editar e remover. Um provedor cadastrado ainda não está disponível para ninguém: é cada workspace que habilita os modelos dele, em **Configurações › Modelos**. ## Onde continuar [#onde-continuar] Conectar uma conta própria de OpenAI, Bedrock ou equivalente. O caso em que o acesso vem da plataforma, com aprovação e cotas negociadas. Os quatro campos que definem o comportamento e o custo de um modelo. # Metadados de modelo (/docs/user-guide/models/providers/metadata) Ao cadastrar um modelo que a plataforma não conhece de antemão, você informa quatro valores. Dois governam o que cabe em uma chamada; dois governam quanto ela custa. Modelos do catálogo já vêm com esses valores preenchidos. Você só os informa manualmente ao adicionar um modelo próprio ou uma variante nova. ## Os campos [#os-campos] | Campo | Unidade | O que determina | | ------------------- | ------------- | ------------------------------------------------------------------------------- | | `Max Input Tokens` | tokens | Tamanho da janela de contexto, somando prompt, histórico e trechos recuperados. | | `Max Output Tokens` | tokens | Teto de uma única resposta. | | `Custo por Input` | USD por token | Preço de cada token enviado ao modelo. | | `Custo por Output` | USD por token | Preço de cada token devolvido pelo modelo. | Os dois campos de custo são informados por token, não por milhar. Um modelo que cobra US$ 0,15 por milhão de tokens de entrada tem `Custo por Input` igual a `0,00000015`. ## O efeito de cada um [#o-efeito-de-cada-um] **Max Input Tokens** é o limite prático de quanto conhecimento cabe em uma resposta. Um Agente com muitas Coleções associadas e conversas longas esbarra nele antes de qualquer outra coisa. **Max Output Tokens** corta a resposta quando ela cresce demais. Respostas truncadas no meio de uma frase costumam ser este campo, não o modelo. Os dois campos de custo não mudam nada no comportamento. Eles alimentam o cálculo de consumo e o enforcement de quotas. Um preço errado aqui produz relatórios e cotas errados em toda a organização, sem nenhum aviso. O consumo continua sendo contabilizado; só o valor fica incorreto. Para menos, atrasa o bloqueio; para mais, bloqueia cedo demais. ## Onde esses valores aparecem depois [#onde-esses-valores-aparecem-depois] * **Observabilidade** usa os custos para converter tokens em dinheiro. * **Quotas** usa os mesmos custos para decidir quando bloquear um escopo. * O formulário do Agente usa `Max Output Tokens` como teto do campo de mesmo nome, em Opções avançadas. ## Próximos passos [#próximos-passos] * Veja o consumo calculado a partir desses valores em [Observabilidade](/docs/user-guide/monitoring/observability). * Entenda como escolher entre modelos em [Provedores e modelos](/docs/user-guide/concepts/models). # Cadastrar um provedor (/docs/user-guide/models/providers/register) Cadastrar um provedor é o que dá à plataforma o direito de chamar aquele serviço de IA. É o primeiro elo da cadeia que termina em um Agente respondendo no Chat. Você precisa do papel **Superadmin** e da credencial de acesso do serviço em mãos. ## Passo a passo [#passo-a-passo] ### Abra o formulário [#abra-o-formulário] Em **Organização › Provedores**, clique em **+ Provedor**. ### Escolha o serviço [#escolha-o-serviço] Selecione o provedor na lista de serviços suportados. A escolha determina quais campos de credencial o formulário pede em seguida. ### Informe a credencial [#informe-a-credencial] Os campos dependem do serviço. Para a maioria, como a Anthropic, basta a **Chave de API**, e o provedor aparece na lista com o nome do serviço. **Provedor Customizado** é a exceção: além da **API Key**, ele pede **Nome do provedor**, **Base URL** e as **APIs suportadas**. A credencial é o segredo de acesso ao serviço. Depois de salvo, o valor não é exibido de volta. ### Crie [#crie] Se quiser, abra **Modelos disponíveis** para conferir os modelos que vêm com o provedor, com janela de contexto, custo e capacidades de cada um. Clique em **Criar**. O provedor entra no catálogo da organização e você volta para a lista de Provedores. ## Depois de cadastrar [#depois-de-cadastrar] O provedor ainda não chega a ninguém. Faltam dois passos, em telas diferentes: 1. Em **Organização › Workspaces**, abra cada workspace e use **Gerenciar Modelos** para atribuir os modelos daquele provedor. 2. Em **Workspace › Configurações › Modelos**, confirme que os modelos aparecem para quem cria Agentes. Esquecer o passo 1 é o erro mais comum. O workspace fica sem modelo, o formulário de criação de Agente não deixa salvar, e a mensagem na tela não menciona que a causa está na gestão de workspaces. ## Modelos desconhecidos [#modelos-desconhecidos] Se o modelo que você quer usar não constar no catálogo da plataforma, você o cadastra informando manualmente os quatro campos que determinam comportamento e custo. Eles estão descritos em [Metadados de modelo](/docs/user-guide/models/providers/metadata). ## Próximos passos [#próximos-passos] * Distribua os modelos aos times em [Workspaces](/docs/user-guide/admin/workspaces). * Limite quanto cada provedor pode consumir em [Quotas](/docs/user-guide/models/quotas). # Liberações temporárias (/docs/user-guide/models/quotas/grants) Uma **liberação temporária** acrescenta teto a um escopo por um prazo, com motivo registrado, e expira sozinha. Ela existe para o caso em que alguém estourou a cota e precisa continuar hoje. Subir a política resolveria também, mas a política não tem prazo e raramente volta a descer. ## Como funciona [#como-funciona] * O valor liberado **soma** ao teto vigente, em vez de substituí-lo. * A liberação vale até a data de expiração que você definir. * Não há rotina de reversão: a plataforma apenas deixa de considerar liberações vencidas. * Ao expirar, o escopo volta ao teto da política e volta a bloquear, se o consumo do mês já tiver passado dele. ## Criar uma liberação [#criar-uma-liberação] Na seção **Liberações temporárias** do escopo, clique em **+ Nova liberação**. Na janela **Nova liberação temporária**, informe **Tokens a mais**, **Custo a mais (USD)** ou ambos, o prazo em **Expira em**, com atalhos para **24 horas**, **7 dias** e **Fim do mês**, e o **Motivo**. Clique em **Liberar**. O motivo não é burocracia: como a liberação some sozinha, ele é o único registro de por que aquele escopo passou do teto naquele mês. A liberação leva até cerca de 30 segundos para valer, porque o consumo é lido de um cache. Quem está bloqueado precisa tentar de novo depois desse intervalo, não na hora. ## Revogar antes do prazo [#revogar-antes-do-prazo] O menu de ações da liberação permite revogá-la. O teto extra deixa de valer no mesmo intervalo de cerca de 30 segundos. Se o consumo do mês já tiver passado do limite da política, o escopo volta a bloquear imediatamente após a revogação. ## Quando usar cada coisa [#quando-usar-cada-coisa] * **Liberação temporária**: um pico pontual, uma demanda de fim de trimestre, um teste que estourou. O normal volta sozinho. * **Alterar a política**: o consumo mudou de patamar de forma duradoura, e o teto antigo não reflete mais o uso real. Liberações repetidas no mesmo escopo, mês após mês, são o sinal de que a política é que está errada. ## Próximos passos [#próximos-passos] * Ajuste a política em [Definir limites](/docs/user-guide/models/quotas/limits). * Confirme o consumo que motivou a liberação em [Observabilidade](/docs/user-guide/monitoring/observability). # Visão geral (/docs/user-guide/models/quotas) **Quotas** define os tetos mensais de consumo de modelos de IA. Sem teto configurado, um escopo consome sem limite. A mesma tela existe em dois lugares, **Organização › Quotas** e **Workspace › Quotas**, com escopos diferentes e comportamento idêntico. ## Os escopos [#os-escopos] As duas abas do topo escolhem entre **Organização** e **Workspace**. Dentro de cada uma há recortes: * **Geral**: o teto total daquele escopo. * **Provedores**: um teto por provedor, para quando um deles é mais caro que os outros. * **Usuários**: quanto cada pessoa pode consumir. * **Chaves de projeto**: só no escopo de workspace, para integrações programáticas. A aba de Chaves de projeto existe porque uma integração consome de forma diferente de uma pessoa: sem pausa, e frequentemente sem ninguém olhando. A cota de Organização tem **prioridade** sobre a de Workspace. Esgotado o teto da empresa, nenhum workspace continua, por mais folga que tenha no próprio limite. ## Quem altera [#quem-altera] Na organização, a tela abre para **Superadmin**, **Admin** e, em leitura, **Auditor**. No workspace, para **Proprietário**, **Curador** e **Auditor**, mas só o Proprietário salva alterações. ## Exceções por pessoa e por chave [#exceções-por-pessoa-e-por-chave] Nas abas de Usuários e Chaves de projeto é possível criar **exceções** para casos individuais, além do teto padrão. Uma exceção sobrepõe o teto padrão daquele escopo para aquela pessoa ou chave. Diferente de uma liberação temporária, ela não expira sozinha. O menu de ações permite editá-la, liberar temporariamente ou removê-la. ## O que acontece ao estourar [#o-que-acontece-ao-estourar] A chamada é recusada e quem está no Chat recebe um aviso de cota excedida. A plataforma não troca de modelo nem degrada a resposta. O bloqueio vale só para o escopo que estourou. Uma pessoa que atingiu o próprio limite para de conseguir usar, enquanto o resto do workspace continua. Os tetos valem para o mês corrente. A virada do mês zera o consumo acumulado e desbloqueia automaticamente. ## Nesta seção [#nesta-seção] Configurar tetos em tokens ou custo e ler a projeção do mês. Destravar um escopo por um prazo, sem mexer na política. # Definir limites (/docs/user-guide/models/quotas/limits) Um limite é definido em **tokens**, em **custo** ou nos dois. Quando há os dois, o que for atingido primeiro bloqueia. Você precisa do papel **Superadmin** ou **Admin**. Auditor vê os números, mas não salva. ## Configurar [#configurar] Em **Limites e uso mensal**, preencha **Tokens**, **Custo (USD)** ou ambos, e clique em **Salvar limites**. O botão **Remover** desfaz o teto. O passo a passo abaixo define o teto da organização inteira, em **Organização › Quotas**: Duas convenções que é fácil inverter por engano: * **Campo em branco** significa sem limite. * **Limite igual a zero** bloqueia todas as requisições daquele escopo. Abaixo do formulário, **Tokens usados** e **Custo usado** mostram o consumo real do mês. É esse número, e não uma estimativa, que o bloqueio usa. ## Ler a projeção do mês [#ler-a-projeção-do-mês] O gráfico **Projeção do mês** estende o consumo diário recente até o fim do mês corrente, por regressão linear. O painel ao lado traz quatro números: | Indicador | O que responde | | ------------------------ | ---------------------------------------------- | | `Consumido no mês` | Quanto já foi gasto até agora. | | `Previsto no fechamento` | Onde o mês termina, mantido o ritmo atual. | | `Estouro do limite` | Quando o teto seria atingido, se for atingido. | | `Ritmo projetado` | Consumo médio por dia na janela recente. | É o sinal mais útil no meio do mês: ele diz se o ritmo atual estoura o teto antes da virada, enquanto ainda dá tempo de agir. A projeção é uma reta sobre o consumo recente. Ela não sabe de sazonalidade, nem do Agente que você publicou ontem. Trate-a como alerta, não como previsão. ## Escolher um valor inicial [#escolher-um-valor-inicial] Um caminho previsível, quando não há histórico: 1. Deixe o escopo sem limite por um ciclo e acompanhe o consumo real em **Observabilidade**. 2. Defina o teto com folga sobre o pico observado, não sobre a média. 3. Ajuste na virada do mês seguinte, agora com dois pontos de comparação. Começar apertado gera bloqueio no primeiro dia de uso intenso, e a correção acaba virando uma política permanentemente alta. ## Próximos passos [#próximos-passos] * Destrave um caso pontual sem mexer na política em [Liberações temporárias](/docs/user-guide/models/quotas/grants). * Veja o consumo detalhado por modelo em [Observabilidade](/docs/user-guide/monitoring/observability). # Modelos do workspace (/docs/user-guide/models/workspace-models) **Modelos** define quais opções, entre tudo o que os provedores da organização oferecem, aparecem no formulário de um Agente deste workspace. A tela é acessível ao **Proprietário**; **Auditor** a vê em leitura. Curador e Editor não a alcançam, embora sejam quem mais cria Agentes. ## A lista [#a-lista] Os modelos habilitados, com busca por nome e o provedor de origem de cada um. A lista não é o catálogo da organização: é o recorte que este workspace recebeu. Modelos existentes na organização mas não atribuídos a este workspace não aparecem. ## De onde vem a lista [#de-onde-vem-a-lista] A cadeia tem três elos, em telas diferentes: 1. **Organização › Provedores**: a conta do serviço é cadastrada. 2. **Organização › Workspaces › Gerenciar Modelos**: os modelos são atribuídos a este workspace. 3. **Workspace › Configurações › Modelos**: esta tela, onde se confirma o que ficou disponível. Um workspace sem nenhum modelo não deixa criar Agente. O campo **Modelo** do formulário é obrigatório e fica vazio, sem que a mensagem de erro aponte para o elo 2 da cadeia. ## Quando um modelo some [#quando-um-modelo-some] Se um Agente que funcionava para de listar seu modelo, o elo rompido é quase sempre o 2: alguém retirou aquele modelo deste workspace na gestão de workspaces da organização. O Agente continua salvo com o modelo antigo, mas não roda. Editá-lo exige escolher um modelo ainda disponível. ## Escolher entre os disponíveis [#escolher-entre-os-disponíveis] Três critérios costumam bastar: * **Janela de contexto**: Agentes com muitas Coleções ou conversas longas precisam de janelas maiores. * **Custo**: modelos maiores cobram mais por token, e o efeito aparece no Painel no fim do mês. * **Comportamento**: o mesmo prompt rende respostas diferentes entre modelos. Vale testar antes de publicar. ## Próximos passos [#próximos-passos] * Entenda os metadados que definem cada modelo em [Metadados de modelo](/docs/user-guide/models/providers/metadata). * Limite o consumo por modelo em [Quotas](/docs/user-guide/models/quotas). # Conversas registradas (/docs/user-guide/monitoring/conversations) **Conversas** guarda o histórico das trocas entre as pessoas e os Agentes do workspace. É o registro bruto do uso, mensagem a mensagem. A tela abre para **Proprietário**, **Curador** e **Auditor**. Editor não a alcança. ## A lista [#a-lista] Seis colunas: **Data de criação**, **Assunto**, **Usuário**, **Aplicativo**, **Agente** e **Ações**. O **Assunto** é gerado automaticamente a partir do conteúdo, pela automação de Renomear Chats da organização. O **Aplicativo** distingue de onde a conversa veio, quando o workspace é acessado por mais de um canal. ## Abrir uma conversa [#abrir-uma-conversa] Abrir uma linha mostra a troca completa. Há ações para copiar uma mensagem específica ou a conversa inteira, o que é o caminho prático para levar um caso a quem vai ajustar o Agente. ## Para que serve na prática [#para-que-serve-na-prática] Três usos que justificam a tela: * **Entender o que as pessoas de fato perguntam**, que raramente é o que se imaginou ao escrever o prompt. * **Investigar um caso relatado**, com a conversa real em vez da lembrança de quem relatou. * **Auditar**, quando é preciso demonstrar o que foi respondido e com base em quê. ## Privacidade [#privacidade] O conteúdo aqui é o que as pessoas escreveram, incluindo o que colaram no chat. Papéis com acesso a esta tela enxergam tudo isso. Guardrails filtram o que chega ao modelo, não o que fica registrado. Um dado sensível colado por alguém no chat aparece nesta tela mesmo quando foi mascarado antes de ir ao modelo. ## Conversas de agentes removidos [#conversas-de-agentes-removidos] Remover um Agente não apaga o histórico. As conversas continuam listadas, com o nome do Agente que as atendeu, mas não é possível seguir conversando. ## Próximos passos [#próximos-passos] * Veja o que as pessoas avaliaram em [Avaliação das respostas](/docs/user-guide/monitoring/feedback). * Ajuste o Agente a partir do que você leu em [Escrever o prompt](/docs/user-guide/agents/prompt). # Painel (/docs/user-guide/monitoring/dashboard) O **Painel** é a primeira tela do workspace e responde a uma pergunta ampla: este workspace está sendo usado, e a que custo. Ele abre para **Proprietário**, **Curador** e **Auditor**. Editor não o alcança. ## Uso de tokens [#uso-de-tokens] No topo, dois números do período: **Tokens consumidos** e **Custo total**. O custo vem dos preços cadastrados no provedor de cada modelo. Um preço mal cadastrado aparece aqui antes de aparecer em qualquer outro lugar. ## Os contadores [#os-contadores] Uma grade de números absolutos sobre o que existe no workspace: membros, coleções, agentes, workflows, MCPs, conversas e modelos. Eles servem para conferência rápida, não para tendência. Um contador de conversas alto com uso de agentes baixo, por exemplo, indica conversas curtas ou abandonadas. O contador de **Fontes de conhecimento** é herança da estrutura anterior à v4, quando fontes e coleções eram telas separadas. Hoje ambas vivem em Coleções. ## Uso de agentes [#uso-de-agentes] O gráfico distribui as mensagens por Agente ao longo do período, com a lista de totais ao lado. Clicar em um Agente na legenda o oculta do gráfico. É o melhor sinal de adoção que a plataforma dá: mostra quais Agentes as pessoas realmente usam, e quais foram publicados e esquecidos. ## Feedbacks, usuários ativos e acessos [#feedbacks-usuários-ativos-e-acessos] Na base da tela, três recortes de atividade: * **Feedbacks**: o saldo das avaliações dadas às respostas no período. * **Usuários ativos**: quantas pessoas usaram, em recorte diário, semanal ou mensal. * **Acessos à plataforma**: o volume de entradas no período. Usuários ativos e acessos respondem a perguntas diferentes. Muitos acessos com poucos usuários ativos significa que poucas pessoas voltam muitas vezes. ## Painel ou Observabilidade [#painel-ou-observabilidade] O Painel resume a atividade do workspace. A Observabilidade detalha o consumo por modelo e dá acesso aos traces. Use o Painel para saber se algo mudou; a Observabilidade para descobrir o quê. ## Próximos passos [#próximos-passos] * Detalhe o consumo em [Observabilidade](/docs/user-guide/monitoring/observability). * Leia as avaliações por trás do saldo em [Avaliação das respostas](/docs/user-guide/monitoring/feedback). # Avaliação das respostas (/docs/user-guide/monitoring/feedback) **Avaliação das Respostas** reúne o retorno que as pessoas deram às respostas dos Agentes no Chat. É o sinal de qualidade mais direto da plataforma: não mede uso, mede se o que foi respondido serviu. A tela abre para **Proprietário**, **Curador** e **Auditor**. ## A lista [#a-lista] Cinco colunas: **Data**, **Agente**, **Avaliador**, **Avaliação** e **Ações**. A coluna **Agente** é a que transforma a tela em ferramenta. Ordenar ou filtrar por ela mostra rapidamente qual Agente concentra as avaliações negativas. ## Como usar o retorno negativo [#como-usar-o-retorno-negativo] Uma avaliação negativa raramente diz o que houve. O caminho é ir da avaliação para a conversa e ler a troca inteira. As causas mais comuns, em ordem de frequência: * **O conhecimento não estava lá**: o documento não foi enviado, ou não chegou a **Ativo** na Coleção. * **A resposta veio do modelo, não do material**: o prompt não instrui a dizer que não sabe. * **A pergunta estava fora do escopo do Agente**: o problema é de expectativa, e se resolve no nome e na descrição. ## O saldo no Painel [#o-saldo-no-painel] O Painel resume estas avaliações em um saldo do período. O número sozinho diz pouco; a leitura útil está aqui, caso a caso. Volume baixo de avaliações é o normal. As pessoas avaliam pouco, e quase sempre quando algo deu errado. Um Agente sem avaliações não é um Agente aprovado. ## Próximos passos [#próximos-passos] * Leia a conversa completa por trás de uma avaliação em [Conversas](/docs/user-guide/monitoring/conversations). * Confira se o conhecimento estava disponível em [Indexação](/docs/user-guide/knowledge/indexing). # Observabilidade (/docs/user-guide/monitoring/observability) **Observabilidade** responde a duas perguntas diferentes: quanto foi consumido, e o que aconteceu em uma execução específica. A tela existe nos dois escopos, com os mesmos recursos. A da **Organização** soma todos os workspaces; a do **Workspace** cobre apenas um. Ela substituiu a antiga página de Logs de Uso na versão 4. ## Uso de modelos [#uso-de-modelos] A primeira aba resume o período escolhido em três números: **Tokens**, **Custo** e **Requisições**. Abaixo deles, o gráfico **Consumo por modelo** distribui esse total ao longo do tempo. O seletor ao lado alterna a métrica entre tokens e custo e permite agrupar por outra dimensão. A legenda à direita lista os modelos por consumo. Clicar em um deles o oculta do gráfico, o que ajuda quando um modelo dominante achata a escala dos demais. ## A tabela de modelos [#a-tabela-de-modelos] Sob o gráfico, uma linha por modelo: | Coluna | Para que serve | | ------------- | --------------------------------------------------------- | | `Requisições` | Quantas chamadas foram feitas àquele modelo. | | `Tokens` | Volume total consumido. | | `Custo` | Valor correspondente, calculado pelos preços do provedor. | | `% do total` | Participação do modelo no consumo do período. | A combinação de poucas requisições com muitos tokens costuma indicar prompts longos ou Agentes com muitas Coleções associadas. ## Período e exportação [#período-e-exportação] O seletor **Escolha o período** define a janela de todos os números da tela. O botão de atualizar recarrega sem trocar o período. **Exportar** baixa os dados da visão atual, para análise fora da plataforma. ## Traces [#traces] A segunda aba lista as execuções com **Root trace**, **Status**, **Duração** e **Custo**. Os filtros restringem por identificador de recurso, aplicação e usuário. Um trace percorre a execução inteira: a chamada ao modelo, a busca nas Coleções quando houve, e cada acionamento de ferramenta. É a forma de responder ao que a tela de Conversas não responde: por que a resposta demorou, se o MCP foi de fato chamado, quanto aquela mensagem custou. Papéis administrativos têm um atalho na barra superior para a ferramenta de traces detalhados, fora da plataforma. ## Qual escopo usar [#qual-escopo-usar] Use a da **Organização** para entender custo e tendência da empresa; a do **Workspace** para investigar o comportamento de um time. Quem tem papel de organização alcança as duas; quem só tem papel de workspace vê apenas a sua. ## Próximos passos [#próximos-passos] * Transforme o que você observou em limite, em [Quotas](/docs/user-guide/models/quotas). * Veja o resumo de atividade do time em [Painel](/docs/user-guide/monitoring/dashboard). # Credenciais (/docs/user-guide/tools/credentials) **Credenciais** é onde ficam os acessos que provedores e integrações usam para falar com sistemas de fora. Cada segredo é cadastrado uma vez e reaproveitado por quem precisar dele. A tela exige o papel **Superadmin**, pela mesma razão que Provedores: é onde o segredo mora. ## Por que existe [#por-que-existe] Sem esta tela, cada integração de cada workspace pediria o seu próprio segredo, e a mesma senha acabaria copiada em dezenas de lugares. Com ela, o desenho fica claro: a Organização guarda o segredo; o Workspace escolhe o que ligar, sem nunca ver o valor guardado. Rotacionar um acesso vira uma edição em um lugar só. ## Cadastrar uma credencial [#cadastrar-uma-credencial] 1. Clique em **+ Credencial**. 2. Escolha o tipo, conforme o sistema que ela vai acessar, e clique em **Próximo**. 3. Informe os campos que aquele tipo exige. 4. Clique em **Criar**. Os tipos se dividem em dois grupos: * **SMTP** e **Google Drive**: você informa tudo no próprio formulário. No SMTP, nome, servidor, porta, criptografia, usuário e senha; no Google Drive, o tipo de autenticação (**Pessoal** ou **Organizacional**), os domínios permitidos e o arquivo JSON da conta de serviço. * **Jira**, **Confluence**, **SharePoint** e **OneDrive**: o formulário pede só nome e descrição. Ao clicar em **Criar**, você é levado à tela de consentimento da Atlassian ou da Microsoft, e a credencial só é criada quando o login volta para a AUMO. Antes, os domínios daquele serviço precisam estar configurados em [Domínios de conhecimento](/docs/user-guide/knowledge/allowed-domains); sem isso, a plataforma avisa e não segue. A credencial passa a estar disponível para as integrações, conectores e provedores da organização. O passo a passo abaixo usa uma credencial SMTP: Depois de salvo, o valor de um segredo não é exibido de volta. Ao rotacionar um acesso, você substitui o valor; não há como conferir o anterior pela interface. ## Editar e remover [#editar-e-remover] **Editar** permite trocar o valor de uma credencial sem refazer as associações que dependem dela. É o caminho para rotação de senha ou renovação de token. **Remover** apaga a credencial. Tudo que dependia dela para de funcionar, e a falha aparece no momento do uso, não no da remoção. Confira as associações antes. ## Credenciais de e-mail [#credenciais-de-e-mail] O servidor usado pelo nó de envio de e-mail dos Workflows é cadastrado aqui, como credencial do tipo **SMTP**. Cada workspace então escolhe o seu remetente: em **Organização › Workspaces**, abra o workspace e, na aba **Credenciais**, crie uma credencial de e-mail com nome, endereço de remetente e a credencial SMTP que ela usa. Isso permite que cada time envie a partir do próprio remetente, reaproveitando o mesmo servidor. ## Próximos passos [#próximos-passos] * Ligue credenciais às conexões cadastradas em [Integrações](/docs/user-guide/tools/integrations). * Entenda onde elas entram na cadeia em [MCPs e Integrações](/docs/user-guide/concepts/tools). # DuckDuckGo (/docs/user-guide/tools/integrations/duckduckgo) A integração do **DuckDuckGo** permite que um Agente ou Workflow pesquise na web durante a resposta. É a ferramenta certa quando a pergunta depende de informação pública e atual, fora do que está indexado nas Coleções. ## A ferramenta [#a-ferramenta] | Ferramenta | O que faz | | ------------------- | ---------------------------------------- | | `DuckDuckGo Search` | Pesquisa na web e devolve os resultados. | ## Campos [#campos] * **Pesquisa**: o termo a buscar. Aceita texto longo e costuma vir de uma variável do fluxo ou da pergunta do usuário. * **Remover HTML**: quando ativo, limpa a marcação do conteúdo retornado. Vem ligado por padrão, e manter assim reduz o ruído que chega ao modelo. ## Quando usar [#quando-usar] Busca na web amplia muito o alcance do Agente, e junto com isso a chance de ele responder com algo que não passou por nenhuma curadoria. Resultados da web não são fonte controlada. Em Agentes que respondem sobre política interna ou dados de cliente, a busca aberta tende a atrapalhar mais do que ajuda: o modelo mistura o conteúdo da empresa com o que achou na internet. Para esses casos, o prompt precisa ser explícito quanto a quando pesquisar e quando ficar restrito às Coleções. ## Próximos passos [#próximos-passos] * Ligue a integração ao workspace em [Visão geral](/docs/user-guide/tools/integrations). * Use a ferramenta dentro de um fluxo em [Integração](/docs/user-guide/workflows/nodes/integration). # GitHub (/docs/user-guide/tools/integrations/github) A integração do **GitHub** consulta repositórios públicos: metadados, o commit mais recente e detalhes de um pull request. O escopo é público. Repositórios privados não são alcançados por esta integração. ## As ferramentas [#as-ferramentas] | Ferramenta | O que faz | | ----------------- | ------------------------------------------------- | | `Repository Info` | Recupera metadados de um repositório público. | | `Latest Commit` | Recupera o commit mais recente de um repositório. | | `Pull Request` | Busca detalhes de um pull request público. | Cada ferramenta é marcada separadamente no formulário do Agente. Um Agente que só precisa checar a última versão publicada não precisa de acesso a pull requests. ## Casos de uso [#casos-de-uso] A combinação que mais rende é um Agente de suporte técnico que consulta o estado real do repositório em vez de responder de memória. Qual a versão atual, o que entrou no último commit, se determinada mudança já foi aceita. Em Workflows, `Latest Commit` serve como gatilho de verificação: o fluxo compara o commit atual com o registrado e decide se segue. ## Limites [#limites] Como a consulta é pública e sem credencial, ela está sujeita aos limites de taxa que o GitHub aplica a chamadas anônimas. Fluxos que consultam em laço podem ser recusados por excesso de requisições. ## Próximos passos [#próximos-passos] * Ligue a integração ao workspace em [Visão geral](/docs/user-guide/tools/integrations). * Para repositórios privados, o caminho é um [MCP](/docs/user-guide/tools/mcp). # Visão geral (/docs/user-guide/tools/integrations) **Integrações** são conexões a serviços que a plataforma já sabe conversar. Diferente dos MCPs, você não descreve o protocolo: escolhe o serviço de uma lista e informa o acesso. Como os MCPs, elas seguem o caminho de catálogo na organização e ligação no workspace. ## Cadastrar na organização [#cadastrar-na-organização] **Organização › Integrações** abre para **Superadmin** e **Admin**, com duas abas: * **Disponíveis**: o catálogo de integrações que a plataforma conhece e que ainda não foram cadastradas. * **Instaladas**: as que a organização já cadastrou e pode distribuir aos workspaces. Para cadastrar, abra **Disponíveis** e clique em **Instalar** no card do serviço. Não há formulário nesta etapa: a integração passa direto para **Instaladas**. O acesso que ela exige é informado depois, quando cada workspace a instala. Quando a aba **Disponíveis** aparece vazia, todas as integrações conhecidas já foram cadastradas neste registro. ## Associar a um workspace [#associar-a-um-workspace] A associação é feita em **Organização › Workspaces**: abra o workspace e, na aba **Integrações**, ligue a chave do card. O estado passa de **Inativo** para **Ativo**. Associar e desassociar são ações reversíveis. ## Ligar no workspace [#ligar-no-workspace] **Workspace › Integrações** tem as mesmas duas abas, **Instaladas** e **Disponíveis**, aplicadas ao que a organização associou a este workspace. Esta tela é acessível apenas ao **Proprietário** do workspace. Nenhum outro papel a alcança, nem em leitura. Um Curador que esteja montando um Agente vê a integração na lista do formulário, mas não consegue ligá-la. A ligação precisa ser feita por quem tem o papel. Ao instalar no workspace, a janela pede nome, descrição e as credenciais que a integração exige. Integrações que dependem de autorização no serviço de origem abrem o fluxo de consentimento nesse momento. ## Entregar a um agente [#entregar-a-um-agente] Ligar no workspace não entrega a integração a nenhum Agente. Cada Agente marca o que pode acionar na seção **Integrações** do próprio formulário. Workflows também alcançam integrações, pelo nó **Integração** do canvas. ## Nome e descrição [#nome-e-descrição] O menu de ações do registro da organização permite editar o nome e a descrição de uma integração cadastrada. Vale usar isso quando a mesma integração é cadastrada mais de uma vez, apontando para ambientes diferentes: o nome padrão do catálogo não distingue uma da outra. ## Remover [#remover] Desligar uma integração no workspace interrompe o acesso dos Agentes e Workflows que dependiam dela. A falha aparece no momento do uso, não no da remoção. ## Próximos passos [#próximos-passos] * Guarde os acessos que elas usam em [Credenciais](/docs/user-guide/tools/credentials). * Compare com o caminho dos servidores de ferramentas em [MCPs](/docs/user-guide/tools/mcp). ## O catálogo atual [#o-catálogo-atual] Busca na web pública, com uma ferramenta de pesquisa. Metadados, commits e pull requests de repositórios públicos. Pesquisa de vídeos, tendências, categorias e canais. # YouTube (/docs/user-guide/tools/integrations/youtube) A integração do **YouTube** usa a YouTube Data API para pesquisar vídeos e recuperar informação sobre eles, sobre canais e sobre o que está em alta. É a integração com mais ferramentas do catálogo, e vale marcar no Agente apenas as que ele de fato usa. ## As ferramentas [#as-ferramentas] | Ferramenta | O que faz | | ------------------ | -------------------------------------------------------------------------- | | `Search Vídeos` | Pesquisa vídeos com filtros por canal, data, duração, idioma e relevância. | | `Trending Vídeos` | Lista os vídeos mais populares por região ou categoria. | | `Video Details` | Recupera os detalhes completos de um vídeo pelo ID. | | `Video Categories` | Lista as categorias de vídeo disponíveis por região. | | `Channel Info` | Recupera informações de um canal por ID ou username. | ## Como as ferramentas se encadeiam [#como-as-ferramentas-se-encadeiam] O uso típico passa por duas chamadas: `Search Vídeos` devolve os identificadores, e `Video Details` busca o detalhe de um deles. Um Agente com as duas marcadas faz esse encadeamento sozinho, desde que o limite de iterações permita mais de uma chamada por resposta. ## Casos de uso [#casos-de-uso] Monitoramento de marca e pesquisa de conteúdo são os dois casos diretos: o que foi publicado sobre um tema, qual canal cobre determinado assunto, o que está em alta numa região. ## Limites [#limites] A YouTube Data API trabalha com cota diária de consumo. Fluxos que pesquisam em laço, ou Agentes muito usados, podem esgotar a cota antes do fim do dia, e as chamadas passam a falhar até a virada. ## Próximos passos [#próximos-passos] * Ligue a integração ao workspace em [Visão geral](/docs/user-guide/tools/integrations). * Ajuste o limite de chamadas por resposta em [Criar um agente](/docs/user-guide/agents/create). # Visão geral (/docs/user-guide/tools/mcp) **MCP** é um protocolo aberto para expor ferramentas a modelos de IA. Um servidor MCP publica um conjunto de ferramentas, e o Agente decide quando chamá-las. Ligar um MCP acontece em dois passos, em telas diferentes: a organização **registra** o servidor no catálogo, e cada workspace **instala** o que vai usar. Esta página cobre os dois. ## O registro da organização [#o-registro-da-organização] **Organização › MCPs** é o catálogo dos servidores aprovados pela empresa. Nenhum workspace instala um MCP que não tenha passado por aqui. A tela abre para **Superadmin** e **Admin**, mas cadastrar servidores novos é privilégio do Superadmin. Ela tem três abas: * **Instalados**: os servidores já registrados na organização. * **Docker Hub**: catálogo público de MCPs distribuídos como imagem. * **GitHub**: catálogo público de MCPs distribuídos como repositório. Os dois catálogos públicos servem para descobrir e registrar sem sair da plataforma. O passo a passo está em [Registrar um servidor](/docs/user-guide/tools/mcp/register). ## Liberar para um workspace [#liberar-para-um-workspace] Registrar não entrega o servidor a ninguém. A liberação é feita em **Organização › Workspaces**, na seção de MCPs de cada workspace. É o passo que costuma ser esquecido: um servidor no registro e nenhum workspace conseguindo instalá-lo quase sempre significa que essa associação não foi feita. ## Instalar no workspace [#instalar-no-workspace] **Workspace › MCPs** é onde o servidor é efetivamente ligado. Instalar e configurar exige papel de **Proprietário**, **Curador** ou **Editor**. A tela tem duas abas: * **Instalados**: os servidores já ligados neste workspace, com a configuração de cada um. * **Disponíveis**: o que a organização liberou e ainda não foi instalado aqui. Ao instalar, você dá ao servidor um nome e a configuração que este workspace precisa. O mesmo servidor do registro pode ser instalado **várias vezes** no mesmo workspace, desde que cada instalação tenha nome diferente. É assim que se aponta para dois ambientes do mesmo sistema. A configuração e o funcionamento pertencem à **instalação**, não ao registro. Alterar uma instalação não afeta as outras nem o item registrado na organização. ## Entregar a um agente [#entregar-a-um-agente] Instalar no workspace ainda não basta. Cada Agente precisa marcar o MCP na seção **MCPs** do próprio formulário. Lá também fica o **máximo de iterações**, que limita quantas vezes aquele Agente pode acionar ferramentas em uma única resposta. É o que evita um laço quando uma ferramenta devolve algo inesperado. ## Remover [#remover] Remover uma **instalação** interrompe o uso naquele workspace. Agentes que a tinham marcada param de acionar aquelas ferramentas e passam a responder sem elas, sem erro visível para quem conversa. Remover o servidor do **registro** da organização não desfaz o que os workspaces já instalaram, porque a configuração pertence à instalação. Para interromper o uso de vez, é preciso remover nos dois lugares. ## Quando uma ferramenta não é acionada [#quando-uma-ferramenta-não-é-acionada] * **O MCP não está marcado no Agente**: instalação no workspace não é entrega ao Agente. * **O limite de iterações foi atingido**: o Agente concluiu a resposta antes de completar as chamadas. * **O servidor está fora do ar**: a falha aparece nos traces, em Observabilidade. ## Nesta seção [#nesta-seção] Pelos catálogos públicos ou colando uma configuração JSON. As camadas de validação e o que o selo de verificado significa. # Registrar um servidor (/docs/user-guide/tools/mcp/register) Há dois caminhos para registrar um servidor MCP, e a escolha depende de onde ele está publicado. Os dois exigem o papel **Superadmin** e terminam no mesmo lugar: o servidor passa a constar na aba **Instalados** do registro. ## Os dois caminhos [#os-dois-caminhos] Use quando o servidor está publicado no Docker Hub ou no GitHub. 1. Abra a aba **Docker Hub** ou **GitHub**. 2. Busque o servidor pelo nome. 3. Clique em **Instalar** no card. 4. Confira a janela e clique em **Instalar**. A plataforma preenche descrição, versão e repositório a partir dos metadados publicados. A janela também lista as **Variáveis de Ambiente** do servidor, como tokens de acesso; elas são opcionais nesta etapa. Use para servidores internos, que não estão em catálogo público. 1. Clique em **+ MCPs**. 2. Na janela **Importar MCPs**, cole uma configuração JSON válida. 3. Clique em **Importar MCPs**. É o caminho para um MCP desenvolvido pela sua própria equipe, ou para um fornecedor que entrega a configuração em vez de publicar em catálogo. ## Depois de registrar [#depois-de-registrar] O servidor entra no registro, mas nenhum workspace o alcança ainda. A liberação é feita em **Organização › Workspaces**, na seção de MCPs de cada workspace. Depois de liberado, ele aparece em **Workspace › MCPs**, na aba **Disponíveis**, para que o time o instale com nome e configuração próprios. O mesmo servidor do registro pode ser instalado várias vezes no mesmo workspace, desde que cada instalação tenha nome diferente. É assim que se aponta para dois ambientes do mesmo sistema. ## Antes de registrar [#antes-de-registrar] Um MCP dá ao Agente a capacidade de **agir** em sistemas externos, não só de ler. Registrar um servidor de origem desconhecida expõe a organização ao que aquele código fizer. Confira o resultado da análise automática antes de liberar o servidor para os times. Veja [Scanner de segurança](/docs/user-guide/tools/mcp/security). ## Próximos passos [#próximos-passos] * Libere o servidor para os times em [Workspaces](/docs/user-guide/admin/workspaces). * Compare com o caminho das Integrações em [MCPs e Integrações](/docs/user-guide/concepts/tools). # Scanner de segurança (/docs/user-guide/tools/mcp/security) O **Scanner de Segurança MCP** analisa os servidores registrados na organização antes que eles cheguem aos workspaces. Ele existe porque um MCP não é conteúdo passivo: é código que o Agente pode acionar contra sistemas reais. Registrar um servidor é uma decisão de segurança, não de catálogo. ## Onde fica cada coisa [#onde-fica-cada-coisa] A configuração e o resultado moram em telas diferentes: * **Configurações › Geral** define quais camadas de validação o scanner aplica na organização. * **MCPs** exibe o resultado. Cada servidor traz a ação **Ver segurança**, que abre a análise daquele item. Um servidor aprovado ganha um selo de **verificado** na listagem, visível sem abrir o detalhe. ## Como ler o resultado [#como-ler-o-resultado] O selo responde a uma pergunta só: o servidor passou pelas camadas configuradas. Ele não afirma que o servidor é seguro para o seu caso de uso. Duas coisas que o scanner não sabe: * **O que o servidor faz com os dados** que o Agente enviar a ele. * **Se as ferramentas expostas são apropriadas** para as pessoas daquele workspace. O selo é condição necessária, não suficiente. Um servidor verificado de um fornecedor desconhecido continua sendo um fornecedor desconhecido com acesso de escrita aos seus sistemas. ## Ajustar as camadas [#ajustar-as-camadas] Em **Configurações › Geral**, a seção **Scanner de Segurança MCP** lista as camadas disponíveis e permite ativar ou desativar cada uma. Afrouxar as camadas faz mais servidores passarem; apertá-las pode reprovar servidores que já estavam em uso. A alteração vale para toda a organização, e só o **Superadmin** a faz. ## Próximos passos [#próximos-passos] * Registre servidores em [Registrar um servidor](/docs/user-guide/tools/mcp/register). * Veja as demais seções da tela em [Configurações](/docs/user-guide/admin/org-settings). # Variáveis (/docs/user-guide/tools/variables) **Variáveis** guarda valores nomeados que as configurações do workspace consomem: um endereço de ambiente, um identificador de sistema, um parâmetro que muda entre homologação e produção. Em vez de repetir o mesmo valor em vários lugares, você o nomeia uma vez e referencia o nome. ## A lista [#a-lista] A tabela traz o **Tipo** (pública ou secreta), a **Variável**, o **Valor** e quando foi **Atualizada em**. A busca filtra por nome. O valor tem ações de revelar e de copiar. Copiar é útil quando ele é longo ou precisa ser conferido contra outro sistema. ## Criar uma variável [#criar-uma-variável] Clique em **+ Variável** e informe o **Nome da variável** e o **Valor**. O nome segue a convenção de variável de ambiente, em maiúsculas com underscore, como `DATABASE_URL` ou `API_BASE_URL`. A **Visibilidade da variável** é **Pública**, quando o valor pode ser exibido de novo, ou **Secreta**, quando ele fica oculto depois de salvar. Visibilidade mascarada esconde o valor na tela, não o transforma em segredo gerenciado. Credenciais de acesso a sistemas pertencem a **Organização › Credenciais**, que é onde o segredo é de fato protegido. ## Quem pode alterar [#quem-pode-alterar] **Proprietário**, **Curador** e **Editor** criam e alteram variáveis. **Auditor** apenas lê. Apagar uma variável é privilégio do **Proprietário**. Curador e Editor conseguem criar e editar, mas não remover, o que evita que um valor em uso desapareça por engano. ## Efeito de alterar um valor [#efeito-de-alterar-um-valor] Alterar uma variável muda o valor para todo mundo que a referencia, na próxima execução. Não há versão nem histórico. Antes de mudar um valor em uso, vale conferir onde ele é referenciado: não existe uma tela que liste os consumidores de uma variável. ## Próximos passos [#próximos-passos] * Guarde segredos de acesso em [Credenciais](/docs/user-guide/tools/credentials). * Veja onde valores nomeados entram na automação em [Workflows](/docs/user-guide/workflows). # Montar no canvas (/docs/user-guide/workflows/build) O canvas é onde o Workflow toma forma. Você adiciona nós, liga a saída de um à entrada de outro e configura cada um no painel lateral. Todo fluxo executável começa em um nó de **Entrada** e termina em um de **Saída**. ## Adicionar e ligar nós [#adicionar-e-ligar-nós] O botão de adicionar abre a paleta, com os nós agrupados por finalidade e busca por nome. Nós também podem ser arrastados diretamente para o canvas. Cada nó tem conectores de entrada e de saída. Arrastar de um conector de saída até um de entrada cria a ligação e define a ordem de execução. Clicar em um nó abre o painel lateral com a configuração dele. É onde se escolhe o modelo de um nó LLM, as Coleções de um nó vetorial, a URL de uma requisição HTTP. ## Entrada e saída [#entrada-e-saída] O nó de **Entrada** define o formulário que a pessoa preenche ao executar. Cada campo declarado aqui vira um campo daquele formulário. O nó de **Saída** define o que a pessoa recebe no fim. O que não passar por ele fica no registro da execução, mas não é exibido como resultado. Vale desenhar o formulário de entrada pensando em quem executa, não em quem construiu. Nomes de campo como `input_1` chegam assim à tela do usuário. ## Referenciar o que veio antes [#referenciar-o-que-veio-antes] Os nós consomem o que os anteriores produziram. Um nó LLM monta o prompt a partir das saídas anteriores; um nó de condição avalia esses mesmos valores. Como a ligação define a ordem, um nó só alcança o que está upstream dele. Nós em ramos paralelos não enxergam um ao outro até serem reunidos por um nó de agregação. ## Rascunho e publicação [#rascunho-e-publicação] Como os Agentes, Workflows têm rascunho e versão publicada. Só a publicada fica disponível para execução por outras pessoas, na área **Agentes** do Chat. Editar e republicar substitui a versão em uso. Execuções já registradas permanecem como estão. ## Testar antes de publicar [#testar-antes-de-publicar] Execute o fluxo a partir do próprio estúdio antes de publicar, com uma entrada real. O registro da execução mostra o que cada nó recebeu e devolveu, o que é a forma mais rápida de achar um nó mal configurado. Um fluxo que falha sempre no mesmo nó quase nunca é problema de ligação: é configuração daquele nó, visível no painel lateral. ## Próximos passos [#próximos-passos] * Escolha os nós certos em [Catálogo de nós](/docs/user-guide/workflows/nodes). * Investigue o resultado em [Execuções](/docs/user-guide/workflows/runs). # Visão geral (/docs/user-guide/workflows) Um **Workflow** é uma sequência de etapas montada em um canvas. Onde o Agente conversa, o Workflow executa: quem usa preenche um formulário e recebe um resultado. Criar e editar Workflows exige papel de **Proprietário**, **Curador** ou **Editor**. ## A lista [#a-lista] A tela lista os Workflows do workspace com busca por nome. Cada item abre o canvas de edição. A tela é chamada de **Estúdio de IA** em versões anteriores da plataforma e na barra lateral aparece como **Workflows**. ## Quando escolher um Workflow [#quando-escolher-um-workflow] A pergunta que separa Workflow de Agente é se o caminho é conhecido de antemão. * **Workflow**: você sabe as etapas e a ordem. Processar um documento, extrair campos, consultar um sistema, gerar um arquivo. * **Agente**: a pessoa faz perguntas abertas e o modelo decide o que fazer a cada mensagem. Um Workflow é mais previsível e mais fácil de auditar, porque cada execução fica registrada etapa a etapa. ## Onde as pessoas executam [#onde-as-pessoas-executam] Workflows publicados aparecem na área **Agentes** do módulo Chat, não no Admin. Quem executa não precisa de acesso administrativo ao workspace. Adicionar nós, ligar saídas a entradas e publicar. O que cada nó faz e quando usá-lo. Acompanhar e investigar os runs registrados. # Código (/docs/user-guide/workflows/nodes/code) O nó **Executor de código** roda um script dentro do fluxo. Serve para transformar dados, calcular valores derivados e aplicar regras de negócio que os nós padrão não cobrem. É a saída para o caso específico, não o caminho padrão. ## Variáveis de entrada [#variáveis-de-entrada] Antes do código, você declara quais dados ele recebe. Cada entrada tem duas partes: * **Nome do campo**: como a variável se chama dentro do script, por exemplo `texto` ou `numero1`. * **Valor**: de onde o dado vem, como `{{ entrada.mensagem }}`. Os nomes declarados aqui viram os argumentos da função principal. ## O código [#o-código] O editor aceita **Python** ou **Node.js**. O script precisa expor uma função `main`, cujos parâmetros correspondem às variáveis de entrada declaradas. ```python def main(arg1, arg2): resultado = arg1 + arg2 return {"soma": resultado} ``` O que a função retorna vira a saída do nó, acessível pelos nós seguintes. ## Quando não usar [#quando-não-usar] Um fluxo cujo trabalho todo acontece dentro de um nó de código perde o que o canvas oferece: a leitura etapa a etapa no registro da execução. Se o script faz três coisas distintas, separá-las em nós próprios torna a investigação muito mais direta. O registro passa a mostrar qual etapa falhou, em vez de apontar para um bloco único. Antes de escrever código, confira se há nó pronto. Extrair CPF, consultar Coleções, chamar uma API e montar um arquivo já têm nós dedicados, com tratamento de erro próprio. ## Próximos passos [#próximos-passos] * Veja o catálogo completo em [Visão geral](/docs/user-guide/workflows/nodes). * Confira a saída do script em [Execuções](/docs/user-guide/workflows/runs). # Extrator de CPF (/docs/user-guide/workflows/nodes/documents/cpf-extractor) O **Extrator de CPF** localiza números de CPF e CNPJ dentro de um texto já processado, valida cada um e devolve os que passaram. Diferente de uma busca por padrão, ele aplica os algoritmos de dígito verificador e trata conflitos de detecção. ## Validação, não só detecção [#validação-não-só-detecção] Uma expressão regular encontra qualquer sequência com o formato de CPF, incluindo números inventados e trechos de outros identificadores que casam por acaso. Este nó aplica o cálculo do dígito verificador e descarta o que não fecha. O resultado é uma lista de identificadores que existem de fato como números válidos. Validar o dígito confirma que o número é bem formado, não que ele pertence a alguém ou que está correto no contexto do documento. ## Uso típico [#uso-típico] O encadeamento comum tem três nós: **Extrator de arquivos** converte o documento em texto, este nó recupera os identificadores, e um nó de **Requisição HTTP** consulta cada um em um sistema interno. A saída é uma lista, acessível por índice quando o fluxo espera um único valor, como `{{ extrator_cpf.cpfs[0] }}`. ## Dados pessoais [#dados-pessoais] CPF e CNPJ são dados pessoais, e o que este nó extrai circula pelo resto do fluxo e fica registrado na execução. Vale conferir quem tem acesso aos registros de execução daquele workspace antes de montar um fluxo que trata documentos com esse tipo de informação. ## Próximos passos [#próximos-passos] * Converta o documento antes em [Extrator de arquivos](/docs/user-guide/workflows/nodes/documents/file-extractor). * Consulte um sistema com o resultado em [Integração](/docs/user-guide/workflows/nodes/integration). # Extrator de arquivos (/docs/user-guide/workflows/nodes/documents/file-extractor) O **Extrator de arquivos** transforma documentos brutos em texto puro. PDFs, planilhas e imagens entram como binário e saem como conteúdo que um modelo consegue ler. É o primeiro nó de praticamente todo fluxo que processa documentos. ## Por que ele é necessário [#por-que-ele-é-necessário] Um arquivo que chega pela Entrada é uma referência a um binário. Ligar essa referência direto a um nó LLM não entrega o conteúdo: o modelo recebe o ponteiro, não o texto. O extrator resolve essa ponte, e nada depois dele precisa saber o formato original. ## A saída [#a-saída] O nó devolve uma lista de textos extraídos, acessível como `{{ extrator_arquivos.contents }}`. É uma lista porque a Entrada pode receber vários arquivos. Para processar um a um, ligue essa lista a um nó de **Iteração**. ## Formatos [#formatos] Arquivos com texto selecionável saem limpos e rápidos. Documentos digitalizados dependem de reconhecimento de texto, demoram mais e podem falhar quando a digitalização tem baixa qualidade. Um PDF que contém apenas a imagem de uma página escaneada pode devolver texto vazio sem erro explícito. O fluxo segue com conteúdo em branco, e o nó LLM seguinte responde a partir de nada. Vale tratar esse caso com um nó de **Condição** logo depois, checando se o texto extraído veio vazio. ## Próximos passos [#próximos-passos] * Processe cada documento separadamente com [Lógica](/docs/user-guide/workflows/nodes/logic). * Extraia identificadores do texto em [Extrator de CPF](/docs/user-guide/workflows/nodes/documents/cpf-extractor). # Gerador de arquivos (/docs/user-guide/workflows/nodes/documents/file-generator) O **Gerador de arquivos** transforma o que o fluxo montou em um documento para download, em Markdown, DOCX ou PDF. É o nó de fechamento de fluxos que produzem relatório, parecer ou resumo consolidado. ## Os formatos [#os-formatos] * **Markdown**: saída direta do texto, útil quando outro sistema vai consumir. * **DOCX**: documento editável, para quando alguém ainda vai revisar e ajustar. * **PDF**: documento final, renderizado a partir de HTML. ## Imagens [#imagens] PDFs são renderizados de HTML, e as fontes de imagem permitidas são restritas por segurança. Aceitam-se imagens embutidas como `data:`, o bucket HTTPS configurado pela plataforma e o CDN oficial. URLs locais, HTTP simples e origens externas arbitrárias são bloqueadas. Uma imagem de origem bloqueada não derruba a execução. O arquivo é gerado sem ela, e o problema só aparece quando alguém abre o documento. ## Onde o arquivo fica [#onde-o-arquivo-fica] O resultado é persistido pela plataforma e entregue a quem executou o fluxo, conforme o que o nó de **Saída** declarar. Arquivos gerados por execuções antigas continuam acessíveis pelo registro daquela execução. ## Próximos passos [#próximos-passos] * Declare o resultado em [Saída](/docs/user-guide/workflows/nodes/io/output). * Monte o conteúdo do documento em [LLM](/docs/user-guide/workflows/nodes/llm). # Visão geral (/docs/user-guide/workflows/nodes/documents) Quatro nós tratam de documentos: dois que trazem conteúdo para dentro do fluxo, um especializado em identificadores e um que produz arquivos no fim. ## O que cada nó faz [#o-que-cada-nó-faz] * **Extrator de arquivos**: converte arquivos recebidos na Entrada em texto puro. Primeiro nó de quase todo fluxo documental. * **Extrator de CPF**: localiza, valida e extrai CPF e CNPJ de dentro de um texto já processado. * **Banco de dados vetorial**: busca nas Coleções do workspace e devolve os trechos relevantes. É o que habilita RAG no canvas. * **Gerador de arquivos**: produz Markdown, DOCX ou PDF a partir do que o fluxo montou. ## O encadeamento comum [#o-encadeamento-comum] Fluxos documentais quase sempre seguem a mesma ordem: o Extrator de arquivos converte, um nó de Lógica repete por item, o nó LLM interpreta e o Gerador de arquivos fecha. O Banco de dados vetorial entra em fluxos que respondem perguntas, não nos que processam arquivos recebidos. Transformar PDFs, planilhas e imagens em texto utilizável. Recuperar identificadores válidos de dentro do texto. Consultar as Coleções e escolher quantos trechos trazer. Fechar o fluxo com um documento para download. # Banco de dados vetorial (/docs/user-guide/workflows/nodes/documents/vector-db) O **Banco de dados vetorial** faz busca semântica nas Coleções do workspace e devolve os trechos mais próximos da consulta. É o nó que habilita RAG dentro de um Workflow, equivalente a associar Coleções a um Agente. ## Configurar [#configurar] A configuração tem três partes, e cada uma responde a uma pergunta diferente: * **Coleções**: onde procurar. Uma ou várias, entre as do workspace. * **Texto de busca**: o que procurar. Normalmente a pergunta vinda da Entrada, mas o campo aceita consulta composta, como `{{ entrada.pergunta }} no contexto de {{ entrada.categoria }}`. * **Número de chunks**: quanto trazer, por um controle deslizante. ## Quantos chunks trazer [#quantos-chunks-trazer] | Faixa | Quando usar | | ------ | -------------------------------------------------------------------------- | | 3 a 5 | Perguntas objetivas. Equilibra contexto e custo. | | 5 a 10 | Resumos amplos e pesquisas. Mais contexto, mais tokens no nó LLM seguinte. | Subir o número não melhora sempre: trechos pouco relevantes diluem o contexto e aumentam a chance de o modelo se apoiar no material errado. Este nó exige ao menos uma Coleção configurada. Lista vazia não significa "buscar em tudo". Significa que o nó não tem onde procurar, e ele devolve vazio. ## O que ele devolve [#o-que-ele-devolve] A saída é `chunks`: uma lista com os textos encontrados, o score de similaridade e os metadados de origem. Ele não redige resposta. Quem transforma os trechos em texto é o nó **LLM** que vem depois, recebendo `chunks` no prompt. ## Quando não devolve nada [#quando-não-devolve-nada] Três causas, em ordem de frequência: os documentos da Coleção não chegaram ao estado **Ativo**, a Coleção configurada está vazia, ou o texto de busca não tem relação com o conteúdo indexado. O registro da execução mostra o que o nó devolveu, o que distingue o terceiro caso dos dois primeiros. ## Próximos passos [#próximos-passos] * Redija a resposta em [LLM](/docs/user-guide/workflows/nodes/llm). * Confira o estado dos documentos em [Indexação](/docs/user-guide/knowledge/indexing). # Visão geral (/docs/user-guide/workflows/nodes) Os **nós** são as peças do canvas. Cada um recebe dados, faz uma coisa e entrega um resultado ao próximo. A paleta os agrupa por finalidade, e é essa divisão que as páginas seguintes seguem. ## Referenciar o que veio antes [#referenciar-o-que-veio-antes] Todo nó consome o que os anteriores produziram, através de variáveis no formato `{{ no.campo }}`. ```text {{ entrada.pergunta_usuario }} {{ extrator_arquivos.contents }} {{ llm.classificacao }} ``` Nos campos que aceitam variáveis, a tecla `/` abre o menu de seleção, o que evita errar o nome do nó ou do campo. Um nó só alcança o que está **acima** dele no fluxo. Ramos paralelos não enxergam um ao outro até serem reunidos por um nó de Agregação. ## Os grupos [#os-grupos] Os dois extremos obrigatórios: o formulário que a pessoa preenche e o resultado que ela recebe. Chamar um modelo de IA com um prompt montado a partir do fluxo. Extrair texto de arquivos, consultar Coleções e gerar documentos. Desviar, repetir sobre listas e escolher entre resultados. Falar com sistemas de fora por HTTP, e-mail ou integração instalada. Rodar Python ou Node.js para o que nenhum nó pronto cobre. # Envio de e-mail (/docs/user-guide/workflows/nodes/integration/email) O nó de **Envio de Email** despacha mensagens por SMTP durante a execução. Serve para notificar alguém ou entregar um relatório que o fluxo gerou. Ele não configura remetente. Apenas lista as credenciais já cadastradas para o workspace. ## Pré-requisitos [#pré-requisitos] A configuração acontece fora do canvas, em dois níveis: 1. A organização precisa ter uma credencial SMTP cadastrada. 2. Um administrador cria a credencial de e-mail para aquele workspace, em **Organização › Workspaces › Credenciais de Email**. Sem credencial disponível, o nó falha na **execução**, não na montagem. O canvas aceita o fluxo, a publicação funciona, e o erro só aparece quando alguém executa. ## Destinatários [#destinatários] Três campos, cada um aceitando vários endereços: | Campo | Comportamento | | ----- | --------------------------------------- | | `TO` | Destinatários principais. | | `CC` | Recebem cópia visível aos demais. | | `BCC` | Recebem cópia sem que os outros saibam. | Os endereços aceitam variáveis, o que permite enviar para quem o fluxo determinou em vez de uma lista fixa. ## Conteúdo [#conteúdo] * **Assunto**: o título da mensagem. * **Corpo (texto)**: a versão em texto puro. * **Corpo HTML**: a versão formatada, com links e tabelas. Preencher os dois cobre clientes de e-mail que bloqueiam HTML. ## Anexos [#anexos] Arquivos são anexados pela **URL pública** do arquivo. Um documento produzido pelo nó **Gerador de arquivos** pode ser anexado dessa forma. ## Próximos passos [#próximos-passos] * Produza o documento a ser enviado em [Gerador de arquivos](/docs/user-guide/workflows/nodes/documents/file-generator). * Veja onde a credencial é criada em [Workspaces](/docs/user-guide/admin/workspaces). # Requisição HTTP (/docs/user-guide/workflows/nodes/integration/http) O nó de **Requisição HTTP** é um cliente de API completo dentro do canvas. Serve para buscar dado em tempo real ou enviar informação a um sistema externo. É a saída para sistemas que não têm MCP nem integração pronta. ## Método e URL [#método-e-url] Os métodos disponíveis são `GET`, `POST`, `PUT`, `DELETE` e `PATCH`. A URL aceita variáveis, o que permite montar o endereço a partir do fluxo: ```text https://api.loja.com/pedidos/{{ entrada.numero_pedido }} ``` ## Cabeçalhos [#cabeçalhos] Pares chave-valor, usados sobretudo para autenticação: | Chave | Valor | | --------------- | -------------------------------- | | `Authorization` | `Bearer {{ entrada.token_api }}` | Um token digitado direto no valor fica salvo na definição do fluxo, visível para quem abrir o canvas. Prefira passá-lo por uma [Variável](/docs/user-guide/tools/variables) do workspace, ou usar uma Integração, que guarda o acesso fora do desenho. ## Corpo [#corpo] Para `POST` e `PUT`, o corpo é o JSON enviado, montado com variáveis dos nós anteriores: ```json { "cliente": "{{ extrator_cpf.cpfs[0] }}", "motivo": "{{ llm.classificacao }}" } ``` ## Configurações avançadas [#configurações-avançadas] * **Timeout**: tempo máximo de espera pela resposta, em segundos, com padrão de 360. * **Content-Type** e **Accept**: o formato dos dados, normalmente `application/json`. Um endpoint lento que estoura o timeout falha a execução inteira. Para serviços conhecidamente demorados, vale subir o valor antes de publicar. ## Próximos passos [#próximos-passos] * Guarde credenciais fora do desenho em [Variáveis](/docs/user-guide/tools/variables). * Para serviços conhecidos, compare com [Integração](/docs/user-guide/workflows/nodes/integration/tool). # Visão geral (/docs/user-guide/workflows/nodes/integration) Três nós falam com sistemas externos. A diferença entre eles é quanta configuração você precisa fazer à mão. ## O que cada nó faz [#o-que-cada-nó-faz] * **Requisição HTTP**: um cliente de API completo. Método, URL, cabeçalhos e corpo, montados por você. * **Envio de e-mail**: despacha mensagens por SMTP usando uma credencial já cadastrada para o workspace. * **Integração**: aciona uma das conexões prontas ligadas ao workspace, com as ferramentas que ela expõe. ## Qual escolher [#qual-escolher] Para serviços que a plataforma já conhece, a **Integração** exige menos configuração e mantém o acesso fora do desenho do fluxo. Para sistemas internos ou sem integração pronta, a **Requisição HTTP** é o caminho, com o cuidado de não deixar credenciais escritas no nó. ## Falhas na execução, não na montagem [#falhas-na-execução-não-na-montagem] Os três dependem de configuração feita fora do canvas: credencial SMTP, integração ligada ao workspace, endpoint no ar. O canvas aceita o fluxo mesmo assim. O erro aparece quando alguém executa, e o registro da execução aponta o nó. Chamar qualquer endpoint, com método, cabeçalhos e corpo. Destinatários, conteúdo, anexos e o pré-requisito de credencial. Acionar DuckDuckGo, GitHub ou YouTube a partir do fluxo. # Integração (/docs/user-guide/workflows/nodes/integration/tool) O nó de **Integração** aciona uma das conexões prontas já ligadas ao workspace, usando as ferramentas que ela expõe. É a alternativa de menor configuração à Requisição HTTP. ## Integração ou HTTP [#integração-ou-http] A escolha é direta: * **Integração**, quando o serviço está no catálogo da plataforma. Ela já sabe conversar com aquele sistema, e o acesso fica guardado fora do desenho do fluxo. * **Requisição HTTP**, quando o serviço não tem integração pronta. Você monta método, URL, cabeçalho e corpo. ## Pré-requisitos [#pré-requisitos] A integração precisa estar cadastrada na organização e ligada ao workspace antes de aparecer aqui. Uma lista vazia no nó significa que nenhuma integração foi ligada naquele workspace, e a solução está em **Workspace › Integrações**, acessível ao Proprietário. ## Escolher a ferramenta [#escolher-a-ferramenta] Uma integração expõe uma ou mais ferramentas, e o nó aciona uma delas por vez. O YouTube, por exemplo, expõe cinco ferramentas distintas. Os campos do painel mudam conforme a ferramenta escolhida, e todos aceitam variáveis dos nós anteriores. ## O catálogo atual [#o-catálogo-atual] A plataforma oferece hoje DuckDuckGo, GitHub e YouTube. O detalhe de cada uma, com as ferramentas e os campos, está em [Integrações](/docs/user-guide/tools/integrations). ## Próximos passos [#próximos-passos] * Ligue uma integração ao workspace em [Integrações](/docs/user-guide/tools/integrations). * Para sistemas internos, compare com [MCPs](/docs/user-guide/tools/mcp). # Visão geral (/docs/user-guide/workflows/nodes/io) Todo Workflow começa em um nó de **Entrada** e termina em pelo menos um de **Saída**. Juntos eles definem a interface do fluxo: o que a pessoa preenche e o que ela recebe. Um fluxo sem nó de Saída executa por completo e não entrega nada. ## O que cada nó faz [#o-que-cada-nó-faz] * **Entrada**: declara as variáveis que o fluxo recebe. Cada uma vira um campo do formulário de execução. * **Saída**: declara a estrutura do resultado devolvido a quem executou ou ao sistema que chamou pela API. * **Início da iteração**: aparece sozinho dentro de um nó de Iteração e representa o item corrente do laço. ## Como os dados atravessam [#como-os-dados-atravessam] As variáveis da Entrada ficam disponíveis para todos os nós seguintes, no formato `{{ entrada.nome_da_variavel }}`. O que não passar pelo nó de Saída continua registrado na execução, mas não aparece como resultado. Declarar as variáveis e montar o formulário de execução. Definir os campos do resultado, e quando usar mais de uma saída. As variáveis `item` e `index` dentro de um laço. # Entrada (/docs/user-guide/workflows/nodes/io/input) O nó de **Entrada** é a porta do fluxo. Ele declara as variáveis que o Workflow precisa receber para começar, e cada variável declarada vira um campo do formulário de execução. Todo fluxo tem exatamente um nó de Entrada, e ele não pode ser removido. ## Declarar variáveis [#declarar-variáveis] No painel lateral você adiciona uma variável por informação que o fluxo precisa. Cada uma tem nome, tipo e descrição. No canvas, o nó exibe a lista de variáveis configuradas, o que dá para conferir o contrato do fluxo sem abrir o painel. O nome e a descrição chegam à tela de quem executa. `numero_pedido` com a descrição "Número do pedido, sem pontuação" produz um formulário utilizável; `input_1` sem descrição, não. ## Usar nos nós seguintes [#usar-nos-nós-seguintes] As variáveis ficam disponíveis para todos os nós do fluxo, no formato `{{ entrada.nome_da_variavel }}`. ```text Analise a solicitação do cliente {{ entrada.nome_cliente }} sobre o pedido {{ entrada.numero_pedido }}. ``` Nos campos que aceitam variáveis, a tecla `/` abre o menu de seleção. ## Arquivos [#arquivos] Quando o fluxo processa documentos, a Entrada recebe o arquivo e o entrega ao nó **Extrator de arquivos**, que o converte em texto. Ligar a Entrada direto a um nó LLM sem passar pelo extrator não funciona: o modelo recebe a referência do binário, não o conteúdo. ## Próximos passos [#próximos-passos] * Defina o que o fluxo devolve em [Saída](/docs/user-guide/workflows/nodes/io/output). * Converta arquivos em texto em [Documentos](/docs/user-guide/workflows/nodes/documents). # Início da iteração (/docs/user-guide/workflows/nodes/io/iteration-start) O **Início da iteração** é o único nó que você não adiciona. Ele aparece automaticamente dentro de um nó de **Iteração** e marca onde o sub-fluxo começa. No canvas ele é o pequeno nó destacado dentro do bloco maior da Iteração. ## O que ele fornece [#o-que-ele-fornece] Ele representa o item que está sendo processado naquela volta do laço, e expõe duas variáveis aos nós internos: | Variável | Conteúdo | | -------- | --------------------------------------------- | | `item` | O item atual da lista recebida pela Iteração. | | `index` | A posição do item, começando em zero. | ```text Resuma o contrato abaixo em até três frases. {{ inicio_da_iteracao.item }} ``` ## Ligar a lógica interna [#ligar-a-lógica-interna] Para montar o sub-fluxo, clique no conector à direita do nó de início e adicione o próximo nó. O que você ligar ali executa uma vez por item. Um nó LLM dentro do laço executa uma vez por item. Uma lista de 200 elementos são 200 chamadas ao modelo, com o custo correspondente. ## Fora do laço [#fora-do-laço] As variáveis `item` e `index` só existem dentro da Iteração. Nós posicionados depois do bloco não as alcançam. Para levar resultado para fora, use as **Variáveis de saída** do nó de Iteração, que agrupam os resultados individuais em uma nova lista. ## Próximos passos [#próximos-passos] * Entenda o laço completo em [Lógica](/docs/user-guide/workflows/nodes/logic). * Veja os dois extremos do fluxo em [Entrada](/docs/user-guide/workflows/nodes/io/input). # Saída (/docs/user-guide/workflows/nodes/io/output) O nó de **Saída** define a resposta que volta para quem executou, ou para o sistema que chamou o fluxo pela API. Um fluxo sem nó de Saída executa por completo e não entrega resultado nenhum. ## Declarar os campos [#declarar-os-campos] No canvas, o nó exibe as chaves que serão retornadas. O formato acompanha o propósito do fluxo: * **Um campo de texto** atende um fluxo conversacional, com uma resposta só. Um campo `resposta` costuma bastar. * **Vários campos** servem a uma automação de dados. Um fluxo de extração pode devolver `resumo`, `status` e `dados_extraidos` separados. Campos separados são o que permite a outro sistema consumir o resultado sem precisar interpretar texto corrido. ## O que não passa pela saída [#o-que-não-passa-pela-saída] Tudo que o fluxo produziu fica registrado na execução, etapa a etapa, mesmo o que não foi declarado aqui. Ao investigar um resultado incompleto, o registro da execução mostra o que cada nó devolveu. Um dado que existe lá mas não aparece no resultado é um campo faltando neste nó, não um nó que falhou. ## Mais de uma saída [#mais-de-uma-saída] Um fluxo com bifurcações pode ter um nó de Saída por ramo. Cada caminho entrega o seu resultado, e apenas o ramo efetivamente percorrido devolve algo. A alternativa é reunir os ramos em um nó de **Agregação** antes de uma Saída única, o que mantém o contrato do fluxo estável. ## Próximos passos [#próximos-passos] * Veja de onde vêm os dados em [Entrada](/docs/user-guide/workflows/nodes/io/input). * Reúna ramos antes da saída em [Lógica](/docs/user-guide/workflows/nodes/logic). # LLM (/docs/user-guide/workflows/nodes/llm) O nó **LLM** é onde o fluxo usa um modelo de IA. Ele processa linguagem natural: classifica, resume, extrai informação de texto solto e gera conteúdo. É o nó mais caro do canvas, porque cada execução consome tokens. ## Escolher o modelo [#escolher-o-modelo] O painel lateral lista os modelos habilitados no workspace, em **Configurações › Modelos**. Um workspace sem modelos habilitados não permite configurar este nó. Nós LLM diferentes no mesmo fluxo podem usar modelos diferentes. É comum usar um modelo barato para classificar e um melhor para redigir o texto final. ## Escrever o prompt [#escrever-o-prompt] O prompt é montado com as variáveis dos nós anteriores, no formato `{{ no.campo }}`. A tecla `/` abre o menu de variáveis disponíveis naquele ponto do fluxo. ```text Classifique a solicitação abaixo em uma das categorias: reembolso, troca, dúvida. Responda apenas com a categoria, sem explicação. Solicitação: {{ entrada.mensagem_cliente }} ``` Se o nó seguinte consome a saída deste, seja explícito quanto ao formato. Um prompt que não restringe a resposta devolve texto livre, e o nó de Condição ou de Código que vem depois não consegue tratá-lo. ## Combinar com conhecimento [#combinar-com-conhecimento] Um nó LLM sozinho responde com o que o modelo sabe. Para responder a partir dos documentos da empresa, coloque um nó de **Banco de dados vetorial** antes dele e injete os trechos recuperados no prompt. Esse par, busca seguida de prompt, é o que implementa RAG dentro de um Workflow. O equivalente em um Agente é associar Coleções a ele. ## Custo [#custo] O consumo deste nó aparece na Observabilidade do workspace, atribuído ao modelo escolhido. Fluxos com nó LLM dentro de uma Iteração multiplicam o custo pelo tamanho da lista. Uma lista de 200 itens são 200 chamadas. ## Próximos passos [#próximos-passos] * Recupere conhecimento antes do prompt em [Documentos](/docs/user-guide/workflows/nodes/documents). * Repita a mesma lógica sobre uma lista em [Lógica](/docs/user-guide/workflows/nodes/logic). # Agregação (/docs/user-guide/workflows/nodes/logic/aggregation) O nó de **Agregação** unifica variáveis de ramos diferentes em uma saída única. Ele não concatena nem soma. Avalia as fontes em ordem e devolve o **primeiro valor válido** que encontrar. ## Como funciona [#como-funciona] 1. Você informa uma lista de fontes em ordem de prioridade. 2. O nó testa a primeira, depois a segunda, e assim por diante. 3. Ao encontrar um valor válido, para e devolve aquele resultado. 4. Fonte vazia faz o fluxo seguir para a próxima automaticamente. É o comportamento de um encadeamento de alternativas, e não o de uma junção. Para combinar conteúdo de várias fontes em um texto só, o caminho é um nó LLM recebendo todas elas no prompt. ## Uso típico [#uso-típico] O lugar natural deste nó é depois de uma **Condição**. Cada ramo produz o seu resultado, apenas um deles executou, e a Agregação recolhe o que de fato foi preenchido. Isso mantém o contrato do fluxo estável: independente do caminho seguido, o nó de Saída recebe sempre a mesma variável. ## Saída não estruturada [#saída-não-estruturada] Devolve um valor único: a primeira fonte válida da lista. ```json { "config": { "assign_variables": [ "{{primary.result}}", "{{secondary.result}}", "{{fallback.value}}" ] } } ``` O resultado é o conteúdo da primeira dessas três que tiver valor. ## Saída estruturada [#saída-estruturada] Devolve um conjunto de campos fixos. Você declara os campos em `output_schema`, e cada fonte passa a ser um objeto com esses campos. ```json { "config": { "assign_variables": [ { "result": "{{branch1.result}}", "status": "{{branch1.status}}" }, { "result": "{{branch2.result}}", "status": "{{branch2.status}}" } ], "output_schema": ["result", "status"] } } ``` ## No painel lateral [#no-painel-lateral] **Adicionar** inclui novas fontes de entrada. A ordem da lista é a ordem de prioridade, e a primeira é a mais importante. A chave de saída estruturada fica no mesmo painel, e ativá-la troca o formato das fontes de valor simples para objeto. ## Próximos passos [#próximos-passos] * Veja o nó que abre os ramos em [Condição](/docs/user-guide/workflows/nodes/logic/condition). * Declare o resultado final em [Saída](/docs/user-guide/workflows/nodes/io/output). # Condição (/docs/user-guide/workflows/nodes/logic/condition) O nó de **Condição** avalia os dados que recebeu e direciona a execução para um caminho. É o único nó com **múltiplas saídas** no canvas, uma por ramo. Ele resolve o caso "se o cliente pediu reembolso, vá por aqui; se não, vá por ali". ## Como a avaliação acontece [#como-a-avaliação-acontece] 1. O nó avalia os grupos de condição de cima para baixo. 2. O **primeiro** grupo verdadeiro determina o caminho seguido. 3. A avaliação para ali. Os demais ramos não executam. A ordem dos grupos decide o resultado. Uma condição ampla colocada no topo captura casos que uma condição específica mais abaixo nunca chegará a avaliar. Na prática, isso significa escrever as condições mais restritivas primeiro e deixar a mais genérica por último. ## Montar os ramos [#montar-os-ramos] Cada saída do nó no canvas corresponde a um grupo de condição. Ligue cada uma ao trecho de fluxo que deve rodar naquele caso. Ramos paralelos não enxergam um ao outro. Para reunir os resultados depois, use um nó de **Agregação**. ## O caso padrão [#o-caso-padrão] Vale sempre ter um ramo para o que não casou com nenhuma condição. Sem ele, uma entrada inesperada faz o fluxo terminar sem passar por nenhum caminho, e o resultado sai vazio sem erro aparente. ## Próximos passos [#próximos-passos] * Reúna os ramos em [Agregação](/docs/user-guide/workflows/nodes/logic/aggregation). * Veja qual ramo foi seguido em [Execuções](/docs/user-guide/workflows/runs). # Visão geral (/docs/user-guide/workflows/nodes/logic) Três nós controlam o percurso. Eles são o que separa um fluxo linear de um fluxo que trata casos diferentes. ## O que cada nó faz [#o-que-cada-nó-faz] * **Condição**: avalia grupos de condição de cima para baixo e segue pelo primeiro verdadeiro. Único nó com múltiplas saídas no canvas. * **Iteração**: cria um sub-fluxo e executa os nós internos uma vez por item de uma lista. * **Agregação**: avalia fontes em ordem e devolve o primeiro valor válido. ## Como eles se combinam [#como-eles-se-combinam] Condição abre ramos, Agregação os fecha. Esse par mantém o contrato do fluxo estável: independente do caminho seguido, o nó de Saída recebe sempre a mesma variável. Iteração é independente dos outros dois e costuma aparecer logo depois de um nó que devolve lista, como o Extrator de arquivos. ## O custo de repetir [#o-custo-de-repetir] Cada nó dentro de uma Iteração executa uma vez por item. Um nó LLM sobre uma lista de 200 elementos são 200 chamadas ao modelo. Bifurcar o fluxo, e por que a ordem dos grupos decide o resultado. Repetir um trecho sobre cada item e coletar os resultados. Escolher o primeiro valor válido, em modo simples ou estruturado. # Iteração (/docs/user-guide/workflows/nodes/logic/iteration) O nó de **Iteração** processa listas item a item, aplicando a mesma lógica a cada um. Diferente dos outros nós, ele cria um **sub-fluxo**: no canvas ele aparece como um bloco maior, com nós desenhados dentro dele. ## O ciclo [#o-ciclo] 1. **Entrada**: recebe uma variável do tipo lista, como `{{ extrator_arquivos.contents }}`. 2. **Processamento**: executa os nós internos uma vez por item. 3. **Saída**: agrupa os resultados individuais em uma nova lista. A entrada precisa ser uma lista. Apontar para um valor único faz o nó falhar na execução. ## Dentro do laço [#dentro-do-laço] O nó **Início da iteração** aparece automaticamente dentro do bloco e fornece `item` e `index` aos nós internos. Um encadeamento típico liga o Início da iteração a um nó LLM, cujo prompt usa `{{ inicio_da_iteracao.item }}`. ## Variáveis de saída [#variáveis-de-saída] É aqui que você declara o que sai do laço, com dois campos: * **Nome da saída**: o nome da nova lista, por exemplo `resumos`. * **Variável de origem**: qual dado do sub-fluxo alimenta cada posição, normalmente a resposta do nó LLM interno. Sem declarar variáveis de saída, o laço executa e nada atravessa para os nós seguintes. Cada nó dentro do laço executa uma vez por item. Um nó LLM sobre uma lista de 200 elementos são 200 chamadas ao modelo. Estime o custo antes de liberar o fluxo para o time. ## Próximos passos [#próximos-passos] * Entenda o nó interno em [Início da iteração](/docs/user-guide/workflows/nodes/io/iteration-start). * Veja um fluxo completo de lote em [Extrair dados de documentos em lote](/docs/user-guide/guides/document-extraction). # Execuções (/docs/user-guide/workflows/runs) Cada execução de um Workflow gera um **run** com registro próprio: a entrada recebida, as etapas percorridas, o que cada nó devolveu e o resultado final. É a diferença prática entre Workflow e Agente na hora de investigar. Um Agente dá uma resposta; um Workflow deixa o rastro de como chegou nela. ## O que um run registra [#o-que-um-run-registra] * **Entrada**: os valores que a pessoa preencheu no formulário. * **Etapas intermediárias**: o que cada nó recebeu e produziu, na ordem de execução. * **Saída**: o resultado exibido a quem executou. * **Erros**: em qual nó a execução parou, quando parou. ## Investigar um resultado errado [#investigar-um-resultado-errado] O rastro torna a investigação mecânica. Percorra os nós de trás para frente até achar o primeiro cuja saída já está errada. O problema está naquele nó ou na entrada que ele recebeu. Os dois casos mais comuns: * **O nó vetorial não devolveu nada**: as Coleções configuradas nele estão vazias, ou os documentos não chegaram a **Ativo**. * **O nó LLM devolveu algo fora do formato esperado**: o prompt do nó não é explícito quanto ao formato, e o nó seguinte não consegue consumir a saída. ## Quando a execução falha [#quando-a-execução-falha] Uma falha para o fluxo no nó problemático e registra o erro ali. Os nós seguintes não executam. Falhas em nós de integração costumam ser externas: credencial expirada, endpoint fora do ar, domínio não liberado. Falhas em nós de lógica ou código costumam ser de configuração. Um nó de Envio de Email falha na execução, e não na montagem, quando o workspace não tem credencial SMTP configurada. O canvas aceita o fluxo; o run é que acusa. ## Versão executada [#versão-executada] Um run guarda a versão do Workflow que estava publicada no momento da execução. Isso importa ao investigar um caso antigo: o fluxo pode ter sido alterado desde então, e o que você vê no canvas hoje não é necessariamente o que rodou. ## Próximos passos [#próximos-passos] * Ajuste o fluxo em [Montar no canvas](/docs/user-guide/workflows/build). * Veja o consumo de modelos dessas execuções em [Observabilidade](/docs/user-guide/monitoring/observability). # Novidades (/docs/whats-new) Cada release traz novos recursos, correções e otimizações nos módulos **Admin**, **Workflows** e **Chat**. As versões aparecem da mais recente para a mais antiga. ## v4.0.0: Unificação da Plataforma [#v400-unificação-da-plataforma] 24 de agosto de 2026 Atualização com foco em unificar a experiência entre **Admin** e **Chat**, simplificar os fluxos de criação de agentes e coleções, melhorar a visibilidade de uso da plataforma e uma leva de ajustes visuais gerais. ### Destaques [#destaques] * **Login e navegação unificados**: Admin e Chat agora compartilham o mesmo login e uma única barra de navegação, com as abas dos dois módulos acessíveis lado a lado. * **Observabilidade**: A página de "Logs de Uso" deu lugar à página de **Observabilidade**, com melhor visualização das informações de uso (como uso por modelo), filtros mais específicos e a inclusão de traces para rastreamento detalhado das execuções. * **Quotas**: Novo controle de cotas de uso de provedores de IA, configurável em nível de organização, workspace e usuário. * **Coleções simplificadas**: Fontes de Conhecimento e Coleções foram unificadas: agora existe apenas Coleções, onde arquivos e conectores são adicionados diretamente, com um formulário mais simples. * **Novo formulário de criação de agentes**: Agora em uma única página, organizada em seções (accordion), muito mais fácil de preencher e revisar. ### Admin [#admin] * Menu de troca de organização e o dialog de configurações/usuário aprimorados. * Nova tela de **API Keys** nas configurações de usuário. * Ajustes visuais gerais: alinhamentos, padronização de cores, troca de ícones e maior consistência entre as telas. * "Projetos" agora são chamados de **Workspaces** em toda a plataforma. * Melhor exibição de blocos de código. ### Chat [#chat] * Visual atualizado para seguir o mesmo padrão do Admin. * Campo de mensagem inicial agora centralizado na tela, expandindo conforme o texto digitado; sugestões de mensagens passam a aparecer apenas quando há uma base de conhecimento (RAG) vinculada. * Sidebar informativa do chat aprimorada. ### Correções de bugs [#correções-de-bugs] * Correção de vários bugs gerais e ajustes visuais menores em diversas telas. *** ## v3.3.0: Superagentes e Integrações Nativas [#v330-superagentes-e-integrações-nativas] 07 de julho de 2026 Release com avanços importantes em **Superagentes**, **integrações nativas**, **segurança de MCPs** e diversas melhorias de experiência no **Chat**, nos **Workflows** e no **Admin**. ### Destaques [#destaques-1] * **Superagentes**: Nova capacidade de cadastrar e configurar **Superagentes**, com interface dedicada tanto para configuração quanto para uso no chat, orquestrando múltiplos agentes/fluxos. * **Integrações Nativas**: A plataforma passa a oferecer integrações nativas (ex.: **Jira**, **GitHub**, **DuckDuckGo**), utilizáveis tanto em Agentes quanto em nós dedicados dentro dos Workflows. * **Segurança de MCPs (MCP Scanner)**: Introdução de uma camada de proteção para servidores MCP, com verificação de segurança baseada em regras estáticas e avaliação semântica, incluindo status de segurança (`VERIFIED`, `UNVERIFIED`, `UNSAFE`) e revalidação sob demanda. ### Superagentes e Agentes [#superagentes-e-agentes] * Cadastro e configuração de **Superagentes** na organização e projeto. * Interface de front-end para configuração e uso do superagente. * Favoritar/fixar agentes por usuário no chat. * Correção na seleção de sub-agentes que listava o próprio agente. ### Integrações [#integrações] * Novas integrações nativas: **Jira**, **GitHub** e **DuckDuckGo**. * Interface para uso de integrações na criação/edição de agentes. * Novos **nós de integração** nos workflows. ### MCPs e Segurança [#mcps-e-segurança] * **MCP Scanner:** configuração via org settings (YARA + LLM as Judge), status de segurança e botão de revalidação no registro de MCPs. * Suporte a **Resources**, **Prompts**, **Progress** e **Elicitation** no cliente MCP. * Suporte a **MCP App** no chat. * Correções de segurança. ### Estúdio de IA (Workflows) [#estúdio-de-ia-workflows] * **Versionamento e ciclo de vida de workflows:** publicação, despublicação, republicação e listagem de versões. * Indicação de status do workflow (rascunho, publicado ou com mudanças pendentes) dentro do estúdio. * Execução da **última versão publicada** do workflow no chat/agentes. * **Cancelamento** de execuções de workflow, com botão de cancelamento. * Novo botão de **sugestão de código** no nó de execução. * Nó de **criação de arquivos/artefatos** (PDF, Word, Markdown) para envio por e-mail. * Correções nos nós de HTTP (timeout e query parameters via variáveis), executor de código e nó de agregação. ### RAG e Conhecimento [#rag-e-conhecimento] * **Busca semântica híbrida** aplicada à busca de arquivos nas coleções. * Possibilidade de editar context length, custo e outras configurações para modelos de provedores customizados. * Correções em conectores (associação/desassociação, status, Google Drive) e extração de arquivos. ### Provedores e Modelos [#provedores-e-modelos] * Suporte ao provedor **Vertex AI**. * Suporte completo a **provedores customizados** e à **Responses API**. ### Chat [#chat-1] * Paginação e otimização de carregamento do histórico de mensagens de um chat (incluindo chats longos e com muitas imagens). * Fixar chats mais usados pelo usuário e melhor ordenação de chats antigos. * Pré-preenchimento de mensagem no chat por meio de URL customizada. * Correções de scroll, flicker antes do streaming, edição de mensagens e troca de branch. ### Admin e Governança [#admin-e-governança] * Configuração de **cotas de uso** (tokens e custo real) para projetos. * Links para documentação nas páginas do admin para facilitar o uso. * Correções na importação/exportação de membros (CSV, roles). ### Segurança [#segurança] * Correções de segurança advindas de pentests. *** ## v3.2.0: Customization [#v320-customization] 8 de junho de 2026 Release com melhorias nos módulos **Admin**, **Estúdio de IA (Workflows)**, **Chat**, **Templates**, **MCPs** e **Governança**. A versão traz cadastro nativo de **provedores customizados**, evolução do suporte a **MCPs remotos**, criação de assistentes a partir de templates, biblioteca de prompts reutilizáveis, tour guiado de onboarding e novos controles de segurança, isolamento e cotas. ### Destaques [#destaques-2] * **Provedores Customizados**: Cadastro nativo de provedores de IA customizados, com configuração de `base_url`, `api_key` e sincronização dos modelos disponíveis diretamente com o catálogo do provedor. * **Evolução dos MCPs**: Ampliação do suporte ao protocolo MCP, incluindo **Resources**, **Prompts**, registry OAuth de tools e melhor compatibilidade com MCPs remotos. * **Templates de Assistentes e Biblioteca de Prompts**: Criação de assistentes a partir de templates, hints de configuração e biblioteca de prompts reutilizáveis. * **Customizações Visuais**: Adicionamos a funcionalidade de administradores da organização determinarem o schema de cores do chat para todos os usuários da organização, permitindo a criação de uma identidade visual alinhada com a empresa. * **Governança, Segurança e Cotas**: Melhorias de autenticação, isolamento por organização e controle de cotas de uso por tokens e custo em nível de projeto. ### Admin [#admin-1] * **Provedores customizados:** Cadastro de provedores de IA customizados. * **Cotas de uso:** Configuração de cotas por tokens e custo mensal. * **Dashboards de projeto:** Métricas mais claras e amigáveis. * **Gráficos:** Ajustes nos gráficos de assistentes, usuários, feedbacks e uso. * **Melhorias visuais:** Ajustes em modais, modo escuro, headers, filtros e cards. ### Estúdio de IA (Workflows) [#estúdio-de-ia-workflows-1] * **Editor visual de Markdown:** Novo editor para prompts e instruções. * **Markdown:** Melhorias na edição e visualização. * **Provedores desabilitados:** Melhor tratamento para workflows que dependem de provedores desabilitados. * **Validação:** Validação aprimorada com hints para templates e dependências. ### Templates e Prompts [#templates-e-prompts] * Criação de assistentes a partir de templates. * Hints para indicar modelos, MCPs, coleções e credenciais necessárias. * Nova biblioteca de prompts reutilizáveis. * Botão para copiar prompts diretamente na plataforma. ### MCPs e Integrações [#mcps-e-integrações] * Suporte a **Resources** no cliente MCP. * Suporte a **Prompts** no cliente MCP. * Melhorias no registry OAuth de tools e compatibilidade com MCPs remotos. ### Chat [#chat-2] * Melhorias gerais de interface. * Suporte a **assistente global**. * Persistência do último assistente usado por workspace/organização. * Suporte a **projetos públicos** no chat. * Melhorias para abrir botões em nova aba. ### Onboarding [#onboarding] * Implementação inicial de tour guiado. ### Governança e Segurança [#governança-e-segurança] * Ajustes derivados de validações internas de segurança e pentest. * Melhorias de autenticação, isolamento por organização e controle de cotas. #### Correções de bugs [#correções-de-bugs-1] * Correções em workflows, assistentes, templates e MCPs. * Correções visuais no Admin e Chat. * Correções em exportação CSV, filtros e modais. * Correções em providers, modelos Azure e Bedrock. * Correções de falhas no chat causadas por tools inválidas ou ausentes. * Correções no onboarding e no comportamento de projetos públicos. *** ## v3.1.0: Templates [#v310-templates] 23 de abril de 2026 Release com melhorias no **Admin**, no **Estúdio de IA (Workflows)** e no **Chat**: templates centralizados de workflows, suporte ao provedor **Anthropic**, novo sistema de **roles** e otimizações no **RAG** (busca híbrida). ### Destaques [#destaques-3] * **Sub-agentes**: Nova funcionalidade que permite montar estruturas de multi-agentes, onde um agente orquestrador pode chamar sub-agentes e assistentes. * **Sistema de Templates Centralizado**: Infraestrutura dedicada ao gerenciamento de templates de workflows, permitindo reutilizar fluxos criados pela equipe AUMO para o seu caso de uso. * **Novo Provedor Anthropic**: Suporte completo ao provedor Anthropic, ampliando as opções de modelos na plataforma. * **Melhorias de Performance e Estabilidade**: Otimizações significativas no sistema de busca (RAG). ### Admin [#admin-2] * **Configuração de sub agentes:** Assistentes e fluxos de IA podem ser habilitados como sub agentes e ficam disponíveis como MCPs para outros assistentes e fluxos. * **Gestão de roles:** Novo sistema de permissões com roles orientadas a projeto (Auditor, Proprietário, Curador, Editor, Usuário). * **Configuração do Assistente AUMO:** Opção em nível de organização para habilitar ou desabilitar o chat lateral no painel de administração com dúvidas sobre o uso da plataforma. * **Desabilitação de provedores:** Desativar provedores de IA sem excluí-los, removendo a API key do banco de dados. * **Logo em workflows:** Logo personalizada nos workflows do Estúdio de IA. * **Parâmetros avançados:** Controles de temperatura e `max_tokens` nas configurações avançadas dos assistentes. * **Redirecionamento inteligente:** Ao abrir **Chat** no admin, o usuário vai para o projeto correto em vez do último projeto visitado. * **Link direto para o chat:** Botão para abrir o chat correspondente a partir do assistente. * **Invalidação de cache:** Melhorias no cache da logo da organização. * **Atualização do JSON de modelos:** Remoção de modelos depreciados ou inacessíveis dos provedores Fireworks AI, Bedrock, OpenAI e AUMO. * **Termos de uso:** Ciência e aceite tácito dos Termos de Uso com registro técnico para validade jurídica. #### Correções de bugs (Admin) [#correções-de-bugs-admin] * Scroll no modal de adição de arquivos em coleções. * Adição de usuários ao workspace. * Modais em telas pequenas (notebooks). * Ícones de assistentes que sumiam. ### Estúdio de IA (Workflows) [#estúdio-de-ia-workflows-2] * **Sistema de templates:** Criar fluxo a partir de template disponibilizado pela equipe AUMO. * **Correção de conflitos:** Edição simultânea de workflows sem conflito incorreto. * **Agendamento:** Correção no agendamento de workflows. * **Validação:** Validações adicionais, inclusive de tipos. * **Publicação:** Sistema de publicação de workflows e assistentes. ### Chat [#chat-3] * **Busca híbrida:** Migração no Qdrant para busca híbrida no RAG, melhorando desempenho. * **Botão de parar mensagem:** Interromper o streaming da resposta do assistente. * **Abrir em nova aba:** Botões do chat e do admin com clique do meio ou botão direito para abrir em nova aba. * **Edição de mensagens:** Editar mensagens já enviadas para gerar nova resposta. #### Correções e performance (Chat) [#correções-e-performance-chat] * Correções de bugs visuais. * Cursor pointer nos ícones da sidebar do chat. * Menos re-renderizações desnecessárias no chat. *** ## v3.0.0: Governance [#v300-governance] 11 de fevereiro de 2026 Release focada em **governança corporativa de MCPs**, **Guardrails Customizados** e **novos nós de automação** no Estúdio de IA. Agora, apenas Admins e Superadmins de Organização podem autorizar quais MCPs estarão disponíveis para uso nos projetos, garantindo conformidade e controle centralizado. A funcionalidade de Guardrails foi ampliada para permitir a customização dos tipos de informações que não devem ser enviadas para os modelos de IA, com opções de anonimização e bloqueio. Também foram adicionados novos nós de **Email** e **Execução de Código** (Python e Node.js) nos Workflows, além de possibilidade de agendamento da execução dos fluxos, ampliando significativamente as possibilidades de automação. ### Destaques [#destaques-4] * **Governança Completa de MCPs**: Sistema robusto de governança ao nível de organização. MCPs com OAuth (Google) agora funcionam com autenticação completa. * **Guardrails Customizáveis**: Sistema de personalização dos guardrails a nível de organização. Passa ser possível escolher o comportamento da plataforma diante de diversos tipos de informações que possam aparecer no chat, como nomes, CPFs, dados de pagamento, e diversos outros. * **Novos Nós nos Workflows**: Nó de Email para envio automático e nó de Execução de Código em Python e Node.js. ### Admin [#admin-3] * **Sistema de paginação infinita:** Implementação de scroll infinito nas listagens de Assistentes, Coleções, Fontes de Conhecimento e MCPs, melhorando a performance e experiência de navegação. * **Customização da Exibição de Informações:** Todas as listagens agora abrem por padrão na visualização em cards, com opção de alternar para tabela. * **Filtros de modelos:** Adicionado filtro na seleção de modelos durante a criação de projetos e no menu "Modelos" do projeto. * **Melhorias na adição de membros:** Correção na listagem e busca de membros ao adicionar usuários ao workspace, com suporte a paginação para organizações grandes. * **Avisos de dependências:** Ao tentar deletar um MCP, o sistema agora informa quais workflows e assistentes estão utilizando-o. * **Assistentes órfãos:** Identificação visual de assistentes que utilizam modelos removidos do workspace. * **Correções de formulários:** Ajustes e correções no formulário de criação e edição de Coleções. * **Mensagens de erro aprimoradas:** Erros de login e outras operações agora apresentam mensagens mais informativas e direcionadas. * **Guardrails Customizáveis:** Nas configurações da organização, passa a ser possível detalhar o funcionamento do guardrails para cada tipo de dado. ### MCPs [#mcps] * **MCPs Gerenciados na Organização:** Os MCPs passam a ser gerenciados na organização. Apenas MCPs autorizados na organização podem ser adicionados em projetos, e apenas Admins e Superadmins de Organização podem determinar quais MCPs um projeto pode usar. * **Edição de MCPs:** Agora é possível editar configurações de servidores MCP após a criação na organização. * **Suporte de MCPs com OAuth:** MCPs com OAuth do Google passam a funcionar com autenticação. ### Estúdio de IA (Workflows) [#estúdio-de-ia-workflows-3] * **Cópia de workflows:** Possibilidade de copiar workflows entre projetos diferentes ou dentro do mesmo projeto. * **Importação por JSON:** Nova opção no botão "Novo Workflow" para criar workflows a partir de templates ou importar via JSON. * **Agendamento de Execução:** Implementação de execução agendada de workflows usando expressões CRON. * **Documentação integrada:** Adição de links para documentação de workflows diretamente na plataforma. * **Parâmetro de iterações de MCP:** Novo parâmetro no nó de LLM para controlar o número de iterações de chamadas de MCPs. * **Novo Nó de Email:** Adição de novo nó que envia um email de acordo com o fluxo. * **Novo Nó de Execução de Código:** Permite a execução de código em Python e Node.js. ### Chat [#chat-4] * **Formatação de Markdown aprimorada:** Melhoria significativa na renderização de Markdown, incluindo listas, títulos, código e tabelas com hiperlinks. * **Melhoria de Cores:** Inversão das cores da barra lateral e do fundo para melhorar a experiência. * **Scroll otimizado:** Ajustes no comportamento de scroll das mensagens para melhor experiência de leitura. * **Botão de nova execução para workflows:** Adição de botão para executar workflows novamente a partir de execuções anteriores. * **Tooltip de limite de arquivos:** Indicação visual dos limites de envio de arquivos. * **Ícones consistentes:** Correção de problemas com ícones de assistentes que desapareciam. * **Melhorias visuais e de UX:** Cursor pointer na sidebar e melhorias nos ícones da barra lateral. * **Alinhamento responsivo:** Correções de alinhamento para telas menores (notebooks). * **Novo Botão de Copiar Resultado de MCP:** Agora é possível copiar o resultado de uma chamada de MCP para a área de transferência. * **Correções de Bugs multi-chat:** Melhor experiência ao enviar mensagens em vários chats ao mesmo tempo. *** ## v2.6.0: Analytics [#v260-analytics] 19 de dezembro de 2025 Release com foco em **métricas e analytics**, trazendo uma nova tela de visualização de métricas para projetos e organizações. Também inclui novas configurações de sincronização de fontes de conhecimento, customização de logo da organização e verificação de credenciais de provedores na criação. ### Admin [#admin-4] * Correção de bugs e melhorias visuais. * **Fonte de conhecimento:** agora é possível configurar a sincronização em minutos, horas ou dias. * Customização da logo da organização. * **Alteração de permissões:** apenas ADMIN e SUPERADMIN da organização podem alterar os modelos disponíveis para os workspaces. * Limite de caracteres nos prompts durante a criação de assistentes para não exceder o limite dos modelos. * **Provedores:** verificação das credenciais na hora de criar um provedor; não é possível criar se a chave de API não for válida. * Nova tela para visualização de métricas dos projetos e organizações, com histórico das ações realizadas pelos usuários. * Ícone visual para o assistente agora pode ser definido pelo usuário. ### Estúdio de IA (Workflows) [#estúdio-de-ia-workflows-4] * Adição de campos de descrição nas entradas do fluxo. * Execução do fluxo de IA em tempo real com indicação visual da etapa atual. * Novo nó de iteração (loop). * Novo nó de chamada de API. * Reestruturação visual na edição dos fluxos de IA: as configurações dos nós passam a ficar em um menu na direita. ### Chat [#chat-5] * Envio de imagens no chat para modelos com visão. * Sugestões de mensagens iniciais no chat personalizadas de acordo com os documentos acessíveis. *** ## v2.5.0: Performance [#v250-performance] 10 de novembro de 2025 Release com foco em **performance e conectores**. Inclui criação automática de projeto pessoal, melhorias nos conectores SharePoint, Google Drive e OneDrive, suporte a arrastar-e-soltar em coleções, novo nó de IF nos Workflows e otimização de performance no Chat. ### Admin [#admin-5] * Correções de bugs. * Criação automática de projeto pessoal para Admin/Superadmin (com assistente padrão). * Exibição das permissões por perfil (role) no painel. * Melhorias na listagem de feedbacks. * **Conectores:** * **SharePoint:** suporte a múltiplas URLs e card atualizado com mais dados. * **Google Drive:** cards clicáveis com link/ícone de tipo, exibição de nome da pasta, opção de adicionar arquivos individuais. * **OneDrive:** suporte no backend e ajustes no front. * **Web:** limites e textos explicativos mais claros. * **Coleções:** baixar/visualizar conteúdo extraído e arrastar-e-soltar arquivos nas coleções. * **MCPs:** Disponibilização de lista de MCPs para instalação mais simples e fácil. * Exibição mais intuitiva da tag `{context}` no prompt durante a criação e edição de assistentes. * Menu de configurações da organização e projeto. * Exibição de detalhes dos modelos de IA durante a criação de assistentes. ### Estúdio de IA (Workflows) [#estúdio-de-ia-workflows-5] * Nó de IF e ajustes visuais/UX. * Nó de API REST. * Duplicar workflow e selecionar saídas de nós anteriores no Output Node. * Limpeza de layout (remoção da barra lateral). * Undo / Redo com `Ctrl+Z` e `Ctrl+Shift+Z`. * Suporte a execução assíncrona de workflows por API. ### Chat [#chat-6] * Correção de bugs específicos de certos modelos. * Mensagens de erro mais explicativas. * Novo componente de tabelas nas respostas. * Indicadores mais responsivos de "Pensando" e "Executando ferramenta". * Mensagens de erro mais claras e melhor formatação (quebra de linha após tools; suporte a `
` em markdown). * Drag-and-drop de arquivos no chat. * Tela de configurações do usuário. * Otimização de performance para listagem de assistentes e envio de mensagens. *** ## v2.4.0: Collaboration [#v240-collaboration] 29 de setembro de 2025 Release com foco em **colaboração e integrações**. Destaque para integração com SharePoint, suporte a MCPs no nó de LLM do Workflow, novos formulários para criação de provedores de IA, e exibição de resultados de ferramentas diretamente no chat. ### Admin [#admin-6] * Exemplo de como acessar a API de modelos. * Integração com o SharePoint. * MCPs no nó de LLM no Workflow do Estúdio de IA. * Novos formulários para criação de provedores de IA. * Visualizador de chats para administrador agora mostra chamadas de ferramentas e arquivos enviados. * O sistema agora lembra a última organização e projeto utilizados. * Novas telas de feedback ao criar credenciais da Atlassian e SharePoint. * Nova funcionalidade do RAG de retornar os documentos completos. * Correções de erros e melhorias gerais. ### Chat [#chat-7] * Resultados das ferramentas aparecem diretamente no chat. * Possibilidade de adicionar comentários ao dar feedback. * Botão para copiar mensagens do usuário. * O chat agora lembra a última organização e projeto utilizados. * Visualização de trechos específicos retornados pelo sistema de RAG. * Colar imagens e arquivos diretamente da área de transferência (`Ctrl+V`). * Telas para quando algo não for encontrado e para erros genéricos. * Correções de erros e melhorias gerais. *** ## v2.3.0: Integration [#v230-integration] 12 de setembro de 2025 Release com foco em **integração de MCPs e indexação de conteúdo**. Inclui configuração de MCPs diretamente no Estúdio de IA, cadastro de MCPs via JSON, indexador de sites com extração de múltiplas páginas e exibição de respostas de ferramentas no chat. ### Admin [#admin-7] * Centralização dos modelos no Admin (melhoria interna de organização). * Configuração de MCPs diretamente na página de Estúdio de IA, vinculados ao nó de LLM. * **Cadastro de MCPs via JSON:** possibilidade de adicionar múltiplos MCPs apenas copiando e colando o JSON. * **Indexador de sites:** opção para extrair páginas além da inicial, permitindo indexação de conteúdos mais completos. ### Chat [#chat-8] * Novas páginas de fallback para tratar cenários de erro. * Exibição de respostas de Tools: acesso às respostas retornadas pelas ferramentas vinculadas ao MCP que o modelo utilizou. * Exibição de MCPs associados a um assistente. *** ## v2.2.0: Intelligence [#v220-intelligence] 2 de setembro de 2025 Release com foco em **inteligência e automação**. Destaque para exibição em tempo real das tools/MCPs chamados pelos assistentes, nova página de execução de runs dos agentes de IA, e melhorias no painel administrativo incluindo novo provedor OCI (Oracle) e importação de membros via CSV/JSON. ### Chat [#chat-9] * Assistentes com mais conhecimentos sobre a plataforma e sobre o que podem e não podem fazer. * Nome do chat agora é definido quando o usuário envia a mensagem. * Exibição das tools/MCPs chamados pelos assistentes em tempo real. * Nova página de execução e visualização de runs dos agentes de IA (criados no Estúdio de IA). * Correção de bugs relacionados aos feedbacks das mensagens. ### Admin [#admin-8] * Sistema em compliance com o Google para autenticação do Google Picker (criação de fonte de conhecimento Drive). * Novo provedor suportado: **OCI (Oracle)**. * Possível editar nome e descrição de Coleções de Conhecimento. * Melhor visualização de Projetos em que o usuário tem role Basic. * Correção de bugs no formulário de edição e criação de MCPs. * Busca de membros de organização e projeto pela interface. * Melhoria de experiência de usuário na edição de assistentes e de agentes. * Importação de novos membros de organização e projeto por meio de arquivos `.CSV` ou `.JSON`. * Novo botão para exportar todos os feedbacks de um projeto. * Possibilidade de regerar a API Key e visualizá-la para integrações via APIs. *** ## v2.1.0: Connectivity [#v210-connectivity] 20 de julho de 2025 Release com foco em **conectividade e experiência do usuário**. Inclui melhorias no histórico de conversas, reestruturação visual do chat, novo nó Extrator de CPFs e CNPJs no Estúdio de IA, e diversas correções de bugs e melhorias visuais. ### Chat [#chat-10] * Toasts informativos em português. * Ajustes na interface que evitam alterações inesperadas no assistente e no projeto durante o envio de arquivos. * Correções de bugs visuais. * Prevenção de envio duplicado de arquivos. * Aprimoramento na gestão do histórico das conversas, permitindo busca rápida por chats anteriores, projetos e assistentes. * Reestruturação visual do esquema de cores do chat e de trechos de código nas respostas dos assistentes. * Nova funcionalidade de botão para copiar trechos de código, markdown, CSV, etc. na resposta do assistente. ### Admin [#admin-9] * Ajustes visuais nos gráficos de feedback, com cores alinhadas ao significado do feedback. * Correções na listagem de provedores. * Correções ao exibir o tipo de assistente (com ou sem RAG). * No Estúdio de IA, implementação de novas validações e verificações iniciais nos fluxos internos (nodes). * Novo nó no Estúdio de IA: **Extrator de CPFs e CNPJs**. * Na criação de conectores, nova possibilidade de escrever ou colar o ID de uma pasta do Drive em vez de escolhê-la pelo Google Picker. *** ## v2.0.0: Foundation [#v200-foundation] 18 de agosto de 2025 Release de base da plataforma com foco em **fundação e estabilidade**. Destaque para suporte a envio de diversos tipos de arquivos no chat e no Estúdio de IA, suporte completo a MCPs nos assistentes, novo provedor Oracle e diversas melhorias na qualidade de vida do Estúdio de IA. ### Chat [#chat-11] * Ajustes visuais no login e nas cores. * Correção de bugs relacionados aos cookies do navegador. * Suporte a envio de diversos tipos de arquivos no chat: áudios, imagens com texto, arquivos Office de versões diferentes, arquivos de código, entre outros. ### Admin [#admin-10] * Novo gráfico na tela do Painel de um projeto: Assistentes mais utilizados. * Suporte para novo provedor de IA: **Oracle**. * Nova funcionalidade de editar credencial. * Nova página na organização que lista informações básicas de todos os projetos, até mesmo os que o usuário ADMIN, SUPERADMIN ou CONTROLLER não faz parte. * Novo aviso ao usuário caso tente criar um projeto com um slug já existente (mesmo que deletado). * Suporte completo a MCPs nos assistentes: criar MCPs, associá-los aos assistentes e usá-los no chat. * Melhorias na qualidade de vida do Estúdio de IA: avisos de erros caso algo esteja configurado de maneira errada, indicando o que deve ser corrigido. * Saída de nós de extração de arquivos e de CPFs de um workflow no Estúdio de IA podem ser ligadas diretamente ao nó de saída. * Possibilidade de customizar o nome dos campos dos nós de entrada e de saída dos workflows no Estúdio de IA. * Suporte a envio de diversos tipos de arquivos no Estúdio de IA: áudios, imagens com texto, arquivos Office de versões diferentes, arquivos de código, entre outros. * Correções de bugs nas fontes de conhecimento do Jira e Confluence e nas tarefas rotineiras para atualização das coleções. # Files (/en/docs/api-reference/artifact-service) The `artifact-service` stores files uploaded to the platform, such as chat attachments. Each file is an **artifact**. An **attachment** links an artifact to a resource, such as a conversation. Attaching files requires the `artifacts:read` and `artifacts:write` scopes. ## Uploading a file [#uploading-a-file] Uploading happens in three steps: 1. Request a signed URL with `POST .../artifacts/presign-upload`. 2. Send the file straight to storage, at the URL you received. 3. Confirm the upload with `POST .../artifacts/{artifact_id}/confirm`. # confirm (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/confirm) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download-url (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/download-url) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/download) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {artifact_id} (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # public-download (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/public-download) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # signed-download (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/artifact-id/signed-download) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # presign-upload (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/artifacts/presign-upload) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # bind (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/attachments/bind) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {binding_id} (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/attachments/binding-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # attachments (/en/docs/api-reference/artifact-service/org-org-id-workspaces-workspace-id/attachments) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Assistants (/en/docs/api-reference/assistants-service) The `assistants-service` stores each agent's configuration: model, instructions, collections and available tools. It also publishes agent versions. To chat with an agent, use the [Conversations](/en/docs/api-reference/conversation-service) service. It calls the agent for you and keeps the history. ## Lists [#lists] The agent list returns a paginated envelope: | Field | Type | Description | | ------------- | ----------------- | --------------------------------------- | | `items` | `object[]` | The page's agents. | | `limit` | `integer` | The requested page size. | | `offset` | `integer` | The page's starting position. | | `total` | `integer \| null` | Total number of agents, when available. | | `has_more` | `boolean` | Whether there is another page. | | `next_offset` | `integer \| null` | The next page's `offset`. | # fixed (/en/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/assistant-id/fixed) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {assistant_id} (/en/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/assistant-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # publish (/en/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/assistant-id/publish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # assistants (/en/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limit (/en/docs/api-reference/assistants-service/org-org-id-workspaces-workspace-id/assistants/plan-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Authentication (/en/docs/api-reference/authentication) Every API call sends a credential in the `Authorization` header, in the `Bearer ` format. The platform accepts three types, and the choice defines on whose behalf the call is made. ```bash curl https:///api/v1/me \ -H "Authorization: Bearer " ``` ## Credential types [#credential-types] | Credential | Format | Acts as | Use it for | | --------------------------- | ---------------------------- | ------------------ | --------------------------------------------------------- | | User token | JWT issued at login | The signed-in user | Admin, Chat and internal tools with a user session. | | Personal Access Token (PAT) | `aumo_pat__` | The key's owner | Scripts and integrations that act on behalf of a person. | | Project key | `aumo_pk__` | The key itself | Workspace integrations that shouldn't depend on a person. | ### Personal Access Token [#personal-access-token] A PAT acts as the user who created it. It never has more permission than the owner's current role, and it is limited to the organization, the allowed workspaces, the granted scopes and the expiration date. If the owner loses access or changes role, the PAT follows. Token consumption and quotas count against the user who owns the key. ### Project key [#project-key] A project key belongs to a single workspace and has no owner or role. The scopes granted at creation are its entire authorization. That is why it stays valid after the person who created it leaves the organization. It only stops working when it is revoked or expires. Usage and quota are attributed to the key itself. A project key only sees the conversations it created itself. ## Creating a key [#creating-a-key] Keys are created per workspace, in `platform-core`. The full value appears **only once**, in the creation response. Store it in a secrets vault. | Method | Route | Action | | -------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | `POST` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys` | Creates a PAT. | | `GET` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys` | Lists the PATs. | | `DELETE` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys/{api_key_id}` | Revokes a PAT. | | `POST` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys` | Creates a project key. | | `GET` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys` | Lists the active project keys. Use `include_revoked=true` to see revoked ones. | | `DELETE` | `/api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys/{project_key_id}` | Revokes a project key. | You can only grant a project key the scopes you yourself have in the workspace. Issuing and revoking project keys requires being the project owner or an organization admin. To rotate a key, create the new one, update the integration and only then revoke the previous one. ## Scopes [#scopes] Each endpoint requires a scope, shown on the endpoint's page as **Scope**. Scopes follow the `:` pattern. | To | Required scopes | | -------------------- | ------------------------------------------------------- | | Chat with an agent | `conversations:write`, `assistants:read`, `models:read` | | Attach files in chat | `artifacts:read`, `artifacts:write` | | Publish an agent | `assistants:publish` | | Call models directly | `models:read` | | Run a workflow | `workflow_run:write` | Calling an agent runs the model as the caller. That is why a key that chats with agents also needs `models:read`. No key can carry key-management scopes. A key doesn't create or revoke other keys. # Conventions (/en/docs/api-reference/conventions) Every service follows the same rules for URLs, errors, pagination and tracing. This page describes those rules once, and endpoint pages only record what departs from them. ## URL and scope [#url-and-scope] Every route is served by the same host, behind a gateway that forwards each path to the service that owns it. You don't need to know which service answers. Most routes are scoped by organization and workspace: ```text https:///api/v1/org/{org_id}/workspaces/{workspace_id}/ ``` * **`org_id`**: the organization's identifier. * **`workspace_id`**: the workspace's identifier within the organization. Use [`GET /api/v1/me`](/en/docs/api-reference/platform-core/me) to find the organizations and workspaces your credential has access to. ## Errors [#errors] Error responses use a common envelope: ```json { "error_type": "PERMISSION_DENIED", "message": "User is not allowed to access this resource", "timestamp": "2026-06-18T12:00:00Z", "correlation_id": "corr_3f2a9c1e8b7d4e6fa0b1c2d3e4f5a6b7" } ``` | Field | Type | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------------- | | `error_type` | `string` | A stable uppercase code, such as `VALIDATION_ERROR` or `NOT_FOUND`. Use it in client logic. | | `message` | `string` | A readable summary. It may change between versions. | | `timestamp` | `string` | When the error happened, in ISO 8601 UTC. | | `correlation_id` | `string` | The request's identifier. Send it to support. | ### Plan limit [#plan-limit] Reaching a plan limit returns `409` with `error_type` `PLAN_LIMIT_EXCEEDED` and an additional `limit` field. The `message` and `label` come from the platform as they are, in Portuguese: ```json { "error_type": "PLAN_LIMIT_EXCEEDED", "message": "Limite do plano FOUNDATION atingido para Usuários por Projeto Privado: 30 de 30.", "timestamp": "2026-08-21T12:00:00Z", "correlation_id": "corr_3f2a9c1e8b7d4e6fa0b1c2d3e4f5a6b7", "limit": { "limit_key": "users_per_private_workspace", "label": "Usuários por Projeto Privado", "plan": "FOUNDATION", "limit": 30, "current": 30, "requested": 1, "source": "plan", "scope_id": "" } } ``` * **`source`**: `plan` when the ceiling comes from the plan, `override` when it was adjusted for the organization. * **`unit`**: present only on limits that aren't counts, such as `GB`. In that case `limit`, `current` and `requested` may be fractional. ## Pagination [#pagination] Lists accept `limit` and `offset` in the query string. The maximum value of `limit` is `200` in every service. A `limit` above `200` returns `422 VALIDATION_ERROR`. The API doesn't silently clamp the value. ## Correlation ID [#correlation-id] Send `X-Correlation-ID` to trace a request end to end. If you don't send one, the gateway generates one in the `corr_` format. The same value comes back in the body of any error and follows the request through every internal service. Record it in your client's logs. ## Idempotency [#idempotency] Commands with side effects accept the `Idempotency-Key` header. Examples: sending a message, creating a workflow run, confirming an upload, copying a workflow and triggering a schedule. * **Same key, same command**: returns the same result, without repeating the effect. * **Same key, different command**: returns `409 IDEMPOTENCY_CONFLICT`. Generate a unique key, such as a UUID, per logical operation and reuse it on retries of that operation. # Conversations (/en/docs/api-reference/conversation-service) The `conversation-service` stores conversations with agents and each one's messages. When you send a message, it calls the agent, saves the answer and returns the question-and-answer pair. A **conversation** always belongs to an agent (`assistant_id`). A **message** has a `role` (`user` or `assistant`) and a `status` that goes from `pending` to `completed` or `failed`. ## Sending messages [#sending-messages] There are two ways to send a message, with the same body: * **[`POST .../messages`](/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages)**: waits for the agent to finish and returns the user's message and the answer, in that order. * **[`POST .../messages/stream`](/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/stream)**: returns a `text/event-stream` with the answer in chunks. Both accept `Idempotency-Key`. The credential needs `conversations:write`, `assistants:read` and `models:read`. ## Streaming events [#streaming-events] Each event has a name in `event:` and a JSON in `data:`, whose `type` field repeats the name. | Event | When it arrives | Content | | --------------------- | ----------------------------------------------------- | ---------------------------------------------------------------- | | `started` | First event in the stream. | The request's `correlation_id`. | | `message` | When the user's and the agent's messages are created. | `message`: the full message. | | `chunk` | For each piece of generated text. | `message_id` and `content`, the new piece. Concatenate in order. | | `docs_used` | When the agent looks up a collection. | `message_id` and the query used. | | `tool_response` | When a tool returns a result. | `message_id` and `tool_response`. | | `mcp_progress` | During a long-running MCP tool. | `message_id`, `message` and `progress`. | | `attachment_warnings` | When an attachment couldn't be used. | `message_id` and `warnings`. | | `done` | Answer completed. | `message`: the agent's final answer. | | `error` | Failure during the stream. | `status_code` and `data` with `error_code` and `message`. | | `heartbeat` | After `done`, before closing. | Nothing beyond `type`. | Once the stream starts, the HTTP status is already `200`, so failures arrive as an `error` event. The possible `error_code` values are `NOT_FOUND`, `INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN` and `INTERNAL_ERROR`. If the client disconnects mid-stream, the platform still saves the agent's answer in the state where it stopped. # {artifact_id} (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/attachments/artifact-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # attachments (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/attachments) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {conversation_id} (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # last-message (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/last-message) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # mcp-elicitation (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/mcp-elicitation) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # messages (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # rating (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/message-id/rating) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stop (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/message-id/stop) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stream (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/messages/stream) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stop (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/stop) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # title (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/conversation-id/title) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # conversations (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-message-count (/en/docs/api-reference/conversation-service/org-org-id-workspaces-workspace-id/conversations/user-message-count) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Usage and feedback (/en/docs/api-reference/governance-telemetry) The `governance-telemetry` service records the platform's consumption: model calls, tokens used and usage events. It also stores answer ratings and NPS surveys, and defines token quotas. ## Organization and workspace [#organization-and-workspace] Most routes exist at two levels, with the same format: * **Organization**: `/api/v1/org/{org_id}/...` adds up usage across every workspace. * **Workspace**: `/api/v1/org/{org_id}/workspaces/{workspace_id}/...` restricts it to the workspace. Answer ratings (`feedback-records`) and NPS exist only at the workspace level. # dashboard (/en/docs/api-reference/governance-telemetry/org-org-id/dashboard) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # model-invocations (/en/docs/api-reference/governance-telemetry/org-org-id/model-invocations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # breakdown (/en/docs/api-reference/governance-telemetry/org-org-id/model-usage/breakdown) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # series (/en/docs/api-reference/governance-telemetry/org-org-id/model-usage/series) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # summary (/en/docs/api-reference/governance-telemetry/org-org-id/model-usage/summary) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # timeseries (/en/docs/api-reference/governance-telemetry/org-org-id/model-usage/timeseries) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-usage (/en/docs/api-reference/governance-telemetry/org-org-id/quota-usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/provider-provider-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {grant_id} (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/quota-grants/grant-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-grants (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/quota-grants) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quota (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/user-quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quotas (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/user-quotas) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/token-usage/user-user-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # traces (/en/docs/api-reference/governance-telemetry/org-org-id/traces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {trace_id} (/en/docs/api-reference/governance-telemetry/org-org-id/traces/trace-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/en/docs/api-reference/governance-telemetry/org-org-id/usage-logs/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage-logs (/en/docs/api-reference/governance-telemetry/org-org-id/usage-logs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {log_id} (/en/docs/api-reference/governance-telemetry/org-org-id/usage-logs/log-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # dashboard (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/dashboard) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {feedback_id} (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records/feedback-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # feedback-records (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # latest (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/feedback-records/nps/latest) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # model-invocations (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-invocations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # breakdown (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/breakdown) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # series (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/series) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # summary (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/summary) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # timeseries (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/model-usage/timeseries) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # ranking (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/nps/ranking) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # report (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/nps/report) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-usage (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/quota-usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/project-key-project-key-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # project-key-quota (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/project-key-quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # project-key-quotas (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/project-key-quotas) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/provider-provider-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {grant_id} (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/quota-grants/grant-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota-grants (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/quota-grants) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quota (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/user-quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # user-quotas (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/user-quotas) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # quota (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/token-usage/user-user-id/quota) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # traces (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/traces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {trace_id} (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/traces/trace-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage-events (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-logs/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage-logs (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-logs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {log_id} (/en/docs/api-reference/governance-telemetry/org-org-id/workspaces-workspace-id/usage-logs/log-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # API Reference (/en/docs/api-reference) The AUMO API is the same one Admin and Chat use. Every route goes through a single gateway, and each resource belongs to a service, which names the sections of this reference. Almost every route lives inside an organization and a workspace: `/api/v1/org/{org_id}/workspaces/{workspace_id}/...`. Before calling any endpoint, read [Authentication](/en/docs/api-reference/authentication) and [Conventions](/en/docs/api-reference/conventions). ## Get started [#get-started] Choose between a user token, a Personal Access Token and a project key. Error format, pagination, correlation id and idempotency, shared by every service. ## How to read this reference [#how-to-read-this-reference] Each service lists its routes in the sidebar as a file tree, starting from `/api/v1`. Each path segment is an item: * **Page**: the path has operations. Every method of that path is on the same page, with playground, parameters, body, responses and code samples. * **Folder**: the path has sub-routes. When it also has operations, the folder opens its own page. * **Grouped prefix**: segments without operations of their own, such as `org/{org_id}/workspaces/{workspace_id}`, appear together as a single item. ## Services [#services] Current user, organizations, workspaces, members, keys, models and MCP servers. Create, configure and publish agents. Open conversations with an agent and exchange messages, with or without streaming. Manage workflows, publish versions and execute runs. Call language models through an OpenAI-compatible interface. Knowledge collections, documents and indexing status. Credentials, connectors, syncing and document upload. Retrieve the most relevant passages from a collection for a question. Upload, download and attach files to conversations. Run workflows and syncs at set times. Token consumption, quotas, usage logs, ratings and NPS. # Catalog (/en/docs/api-reference/knowledge-catalog) The `knowledge-catalog` stores knowledge **collections** and each one's **documents**. It tracks each document's state, from upload until it is ready for search. Connectors and file upload live in [Ingestion](/en/docs/api-reference/knowledge-ingestion). Passage search lives in [Search (RAG)](/en/docs/api-reference/retrieval-rag). ## Tracking indexing [#tracking-indexing] To know when a collection is ready, query `GET .../knowledge-collections/{collection_id}/status`. It returns only counts per status, without listing documents, and is meant for polling. To receive changes as they happen, use the stream at `.../knowledge-collections/{collection_id}/events`. # delete-file (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/delete-file) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # content (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/download-file/content) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download-file (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/download-file) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # search-files (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/search-files) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # semantic-search (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/semantic-search) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # update-file (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/collections-files/update-file) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # document-stats (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/document-stats) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # search (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/documents/search) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {collection_id} (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # status (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/collection-id/status) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # knowledge-collections (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limit (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/plan-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # storage-limit (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-collections/storage-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {document_id} (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-documents/document-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # refresh (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-documents/document-id/refresh) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # knowledge-documents (/en/docs/api-reference/knowledge-catalog/org-org-id-workspaces-workspace-id/knowledge-documents) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # callback (/en/docs/api-reference/knowledge-ingestion/connectors-oauth/callback) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Ingestion (/en/docs/api-reference/knowledge-ingestion) The `knowledge-ingestion` service brings outside content into collections. It stores the access credentials for sources, syncs connectors and receives uploads. Each **connector** belongs to a collection: creating one requires `collection_id`. Each sync produces a **sync run**, with progress metrics. ## Credentials and OAuth [#credentials-and-oauth] Credentials belong to the organization, not the workspace, which is why they live at `/api/v1/org/{org_id}/credentials`. Connectors with OAuth start authorization at `.../connectors/oauth/{provider}/start`. # start (/en/docs/api-reference/knowledge-ingestion/org-org-id/connectors-oauth/provider/start) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # readiness (/en/docs/api-reference/knowledge-ingestion/org-org-id/connectors-oauth/readiness) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {credential_id} (/en/docs/api-reference/knowledge-ingestion/org-org-id/credentials/credential-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # credentials (/en/docs/api-reference/knowledge-ingestion/org-org-id/credentials) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {connector_id} (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # sync-runs (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id/sync-runs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # cancel (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id/sync-runs/sync-run-id/cancel) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # items (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/connector-id/sync-runs/sync-run-id/items) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # items (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/google-drive/items) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # shared-drives (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors/google-drive/shared-drives) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # connectors (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/connectors) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # reprocess (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-documents-document-id/reprocess) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # confirm (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-uploads/confirm) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # download-url (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-uploads/download-url) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # presign (/en/docs/api-reference/knowledge-ingestion/org-org-id/workspaces-workspace-id/knowledge-uploads/presign) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Models (/en/docs/api-reference/model-gateway) The `model-gateway` is the single gateway to language models. It receives calls in the OpenAI API format, forwards them to the configured provider and records consumption and quotas. The available models are the ones enabled in the workspace. List them with `GET .../workspaces/{workspace_id}/models`, served by [Platform](/en/docs/api-reference/platform-core). Inference requires the `models:read` scope. ## Quotas [#quotas] Each call goes through the consumption limits of the organization, the workspace, the provider and the user. A call with a Personal Access Token counts against the key's owner. For an automated integration, create a dedicated PAT, limited to the workspaces it needs. See [Authentication](/en/docs/api-reference/authentication). # speech (/en/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/audio/speech) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # transcriptions (/en/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/audio/transcriptions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # completions (/en/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/chat/completions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # reconcile (/en/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/quota/reconcile) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # responses (/en/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/responses) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stop (/en/docs/api-reference/model-gateway/org-org-id-workspaces-workspace-id/responses/response-id/stop) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Platform (/en/docs/api-reference/platform-core) The `platform-core` is the platform's control service. It keeps track of who the user is, which organizations and workspaces they can access and what they can do in each. It also owns the provider and model catalog, API keys, workspace variables and MCP server configuration. Agents, workflows, conversations and knowledge live in their own services. ## Finding `org_id` and `workspace_id` [#finding-org_id-and-workspace_id] Almost every route asks for an organization and a workspace. Call [`GET /api/v1/me`](/en/docs/api-reference/platform-core/me) with your credential: the response lists the organizations and workspaces it can access, with the role and scopes in each. ## API keys [#api-keys] The workspace's `api-keys` and `project-keys` routes create and revoke Personal Access Tokens and project keys. See [Authentication](/en/docs/api-reference/authentication) to choose between them. # avatar (/en/docs/api-reference/platform-core/me/avatar) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # me (/en/docs/api-reference/platform-core/me) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {entry_id} (/en/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # installations (/en/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id/installations) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # unfilled-configuration-keys (/en/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id/unfilled-configuration-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workspaces (/en/docs/api-reference/platform-core/org-org-id/integration-registry/entry-id/workspaces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # integration-registry (/en/docs/api-reference/platform-core/org-org-id/integration-registry) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # rescan (/en/docs/api-reference/platform-core/org-org-id/mcp-servers-server-id-runtime/rescan) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # import (/en/docs/api-reference/platform-core/org-org-id/members/import) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # members (/en/docs/api-reference/platform-core/org-org-id/members) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {member_user_id} (/en/docs/api-reference/platform-core/org-org-id/members/member-user-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # org-providers (/en/docs/api-reference/platform-core/org-org-id/org-providers) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # catalog (/en/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id/catalog) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # deactivate (/en/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id/deactivate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {provider_resource_id} (/en/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # reactivate (/en/docs/api-reference/platform-core/org-org-id/org-providers/provider-resource-id/reactivate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limits (/en/docs/api-reference/platform-core/org-org-id/plan-limits) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage (/en/docs/api-reference/platform-core/org-org-id/plan-limits/limit-key/usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # aumo-assistant (/en/docs/api-reference/platform-core/org-org-id/settings/aumo-assistant) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # autocurator (/en/docs/api-reference/platform-core/org-org-id/settings/autocurator) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {key} (/en/docs/api-reference/platform-core/org-org-id/settings/key) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # config (/en/docs/api-reference/platform-core/org-org-id/superagents-provider-resource-id/config) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # status (/en/docs/api-reference/platform-core/org-org-id/terms-of-service/status) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # accept (/en/docs/api-reference/platform-core/org-org-id/terms-of-service/tos-id/accept) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # all (/en/docs/api-reference/platform-core/org-org-id/workspaces/all) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workspaces (/en/docs/api-reference/platform-core/org-org-id/workspaces) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {collection} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/admin-collections/collection) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {resource_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/admin-collections/collection/resource-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {api_key_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/api-keys/api-key-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # api-keys (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/api-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {credential_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/email-credentials/credential-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # email-credentials (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/email-credentials) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {workspace_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # install (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/integration-registry-entry-id/install) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # integration-tools (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/integration-tools) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {integration_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/integration-tools/integration-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # kv (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/kv) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {kv_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/kv/kv-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # unfilled-configuration-keys (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-registry-entry-id/unfilled-configuration-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # validate-security (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-registry-entry-id/validate-security) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # available (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/available) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # install (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/install) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # auth (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/auth) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # start (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/auth/start) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # connect (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/connect) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # dependents (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/dependents) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # prompts (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/prompts) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # resources (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/resources) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # runtime (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/runtime) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # logs (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/runtime/logs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # start (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/runtime/start) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # security-override (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/security-override) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # call (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/tools/call) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # tools (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/mcp-servers/server-id/tools) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # import (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/members/import) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # members (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/members) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {member_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/members/member-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # models (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # disable (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models/model-id/disable) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # enable (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models/model-id/enable) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {model_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/models/model-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # provision (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/org-providers/aumo/provision) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # sync (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/org-providers/provider-resource-id-models/sync) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # usage (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/plan-limits-limit-key/usage) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # project-keys (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/project-keys) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {project_key_id} (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/project-keys/project-key-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # catalog (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/providers/catalog) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # providers (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/providers) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # credentials (/en/docs/api-reference/platform-core/org-org-id/workspaces/workspace-id/providers/provider-id/credentials) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Search (RAG) (/en/docs/api-reference/retrieval-rag) The `retrieval-rag` service splits documents into passages, generates embeddings and stores everything in a vector index. At query time, it returns the passages closest to the question, with reranking. Agents use this search automatically when they have collections. Call `POST .../retrieve` directly when you want the passages without going through an agent. ## Indexing [#indexing] Document indexing is done by [Ingestion](/en/docs/api-reference/knowledge-ingestion) and isn't exposed to external clients. # retrieve (/en/docs/api-reference/retrieval-rag/org-org-id-workspaces-workspace-id/retrieve) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Schedules (/en/docs/api-reference/scheduler-service) The `scheduler-service` stores **schedules** and triggers each run at the right time. Each firing is a **trigger**, with automatic retries on failure. ## Workflow schedules [#workflow-schedules] A workflow schedule always runs the published version, on behalf of whoever created it. If that person loses access to the workflow, the schedule stops running. To schedule a workflow, you can also use `POST .../workflows/{workflow_id}/schedule` in [Workflows](/en/docs/api-reference/workflows-service). # schedules (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # cancel (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/cancel) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {schedule_id} (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # pause (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/pause) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # resume (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/resume) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # trigger-now (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/trigger-now) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # triggers (/en/docs/api-reference/scheduler-service/org-org-id-workspaces-workspace-id/schedules/schedule-id/triggers) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Workflows (/en/docs/api-reference/workflows-service) The `workflows-service` stores each workflow's definition, the published versions and the change history. It also executes workflows: each execution is a **run**. The workflow you edit and the published version are separate things. Publishing creates a new version; editing the workflow afterwards doesn't change what was already published. ## Which version runs [#which-version-runs] A run needs a published version. Without one, the call returns `409`. * **Published workflow**: runs the latest published version. * **Published with pending edits**: runs the published version. The edits only take effect after publishing again. * **Owner's draft**: with `allow_draft_run: true`, the workflow's owner runs the definition being edited, even without a published version. ## Waiting for the result [#waiting-for-the-result] By default, [`POST .../workflows/{workflow_id}/runs`](/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/runs) returns right away, with the run in `pending`. With `wait=true`, the call waits for the run to reach `completed`, `failed` or `cancelled`, for up to `wait_timeout` seconds (default `30`, maximum `300`). If time runs out first, the response has the run in whatever state it was in. Keep querying `GET .../runs/{run_id}`. # runs (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # cancel (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id/cancel) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {run_id} (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stream (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/runs/run-id/stream) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workflow-tool-contracts (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflow-tool-contracts) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # import (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/import) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # workflows (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # plan-limit (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/plan-limit) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # versions (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/published/versions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # copy (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/copy) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # compare (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/diffs/compare) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {diff_id} (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/diffs/diff-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # diffs (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/diffs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # events (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/events) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # export (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/export) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {workflow_id} (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # mcp-auth-preflight (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/mcp-auth-preflight) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # publish (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/publish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # republish (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/republish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # revert (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/revert) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # runs (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/runs) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # stream (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/runs/stream) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # schedule (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/schedule) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # tool-contract (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/tool-contract) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # unpublish (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/unpublish) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # validate (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/validate) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # versions (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/versions) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # {version_id} (/en/docs/api-reference/workflows-service/org-org-id-workspaces-workspace-id/workflows/workflow-id/versions/version-id) {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} # Members (/en/docs/user-guide/admin/members) Belonging to the platform has two levels. **Organization › Members** is the company's front door; **Workspace › Members** decides who belongs to each team. The two add up, and it is common for someone to be a User in the organization and an Owner in a workspace. ## Organization members [#organization-members] The screen opens for **Superadmin**, **Admin** and, read-only, **Auditor**. Four columns, **Name**, **Email**, **Role** and **Actions**, with search by name or email. To invite someone, click **+ Member**. In the **Invite a New Member** window, enter the email, choose the role and click **Add**: * **Superadmin**: full access to the organization. * **Admin**: broad permissions over the organization, without reaching providers, credentials and general settings. * **Auditor**: read-only in the organization menus. * **User**: no permissions in the organization. This is the role for people who only use Chat. **Superadmin** and **Admin** share the same seat limit for the organization, and the counter shows next to each one in the role list. When the limit runs out, both are disabled in the invitation. Until the person signs in for the first time, the **Name** column shows their email. The invitation is for the company, not for a workspace. Someone invited as a User gets in but doesn't belong to anything yet, and will see the Workspace and Chat areas disabled until they are added to one. Adding someone as a User and then including them in the right workspaces is the normal path for most people. Organization roles are for people who run the company, not for people who use the platform. ## Workspace members [#workspace-members] The screen is accessible to the **Owner**; the **Auditor** sees it read-only. You can only add people who already belong to the organization. Anyone not yet invited has to go through the organization screen first. The workspace roles are: * **Owner**: full access, including Integrations, API keys and deleting the workspace. * **Curator**: creates Collections, Agents, Workflows, MCPs and Variables, and reads the Dashboard, Conversations, Feedback and Quotas. * **Editor**: the same creation power as the Curator, without the monitoring and settings screens. * **Auditor**: read-only across most of the workspace. * **User**: no administration screens. Chats in Chat. ## Who doesn't show up in the list [#who-doesnt-show-up-in-the-list] Superadmin, Admin and Auditor organization roles reach any workspace **without being on its member list**. If someone edits things in a workspace and you can't find them under Members, that is how. ## Change and remove [#change-and-remove] The action menu lets you change the role and remove the person, on both screens. The difference is in the reach: removing someone from the **workspace** takes away access to that team, and the person stays in the company. Removing them from the **organization** takes away access to everything, including every workspace they belonged to. A role change applies immediately, the next time the person's screen loads. ## Export [#export] The organization screen has two icon buttons next to **+ Member**. **Import members** invites several people at once from a file. **Export members** downloads the list as CSV or JSON, the practical path for access reviews and periodic audits. ## Next steps [#next-steps] * Understand how the two levels add up in [Roles and permissions](/en/docs/user-guide/concepts/roles). * See what each team receives from the company in [Workspaces](/en/docs/user-guide/admin/workspaces). # AI automations (/en/docs/user-guide/admin/org-settings/ai-automations) Some platform features call a model on their own, without anyone asking. The **AI automations** tab is where you choose which model each one uses. All of them consume tokens like any other call. ## The automations [#the-automations] * **Auto Curator**: automatically organizes and categorizes the workspace's data. * **Semantic Search**: improves search across the organization's content. * **Rename Chats**: generates conversation titles from their content. The prompt it uses is editable. * **Admin Personal Workspace**: the model for the administrative workspace's automatic features. * **Code Suggestion**: suggests code in Workflows and automations. Each has its own model selector. Nothing requires them to be the same. ## Choosing the model [#choosing-the-model] These tasks are short, repetitive and undemanding, such as summarizing a conversation in one sentence or categorizing a document. Large models don't improve the result much and multiply the cost. The practical criterion is the reverse of an Agent's: here, start with the cheapest available model and only move up if quality gets in the way. The consumption of these automations shows up in Observability **without being tied to an Agent**. A cost nobody can explain, spread throughout the day, usually comes from here, especially from Rename Chats, which fires on every new conversation. ## The Rename Chats prompt [#the-rename-chats-prompt] It is the only automation with an editable prompt. The default asks for a short one-sentence summary. Adjusting it changes the title of every new conversation in the organization. Titles that are too long break in the Chat sidebar, so keep the brevity instruction. ## Next steps [#next-steps] * Follow the cost of these calls in [Observability](/en/docs/user-guide/monitoring/observability). * Configure the platform's support agent in [Chat agent](/en/docs/user-guide/admin/org-settings/chat-agent). # Chat agent (/en/docs/user-guide/admin/org-settings/chat-agent) The **Chat Agent** is the platform's own support assistant. It answers questions from people using AUMO, without them having to leave the screen. It is different from the Agents you create in workspaces: it doesn't use your organization's Collections and doesn't show up in the Chat Agent selector. ## Turn it on [#turn-it-on] The tab has the activation switch and the model selector. While it is off, the shortcut doesn't show up for anyone in the organization. Only **AUMO models with vision capability** can be used here. Models from other providers, and AUMO models without vision, aren't in the list of choices. ## Screen capture [#screen-capture] The **Allow screen capture** option defines whether the agent can see the screen of the person asking for help. With it on, the person can ask about what they are seeing without describing the screen. It is also why the model needs vision capability. A screen capture carries whatever is visible at the moment, including customer data open in a Collection or a conversation. Weigh this before turning the option on in organizations that handle sensitive data. ## Consumption [#consumption] Conversations with the Chat Agent consume tokens from the AUMO provider and show up in Observability like other calls. Since screen captures are sent as images, the consumption per message is higher than for a text question. ## Next steps [#next-steps] * See the other automatic features in [AI automations](/en/docs/user-guide/admin/org-settings/ai-automations). * Understand the provider behind this feature in [The AUMO provider](/en/docs/user-guide/models/providers/aumo). # Guardrails (/en/docs/user-guide/admin/org-settings/guardrails) **Guardrails** filter what travels between people and AI models, to keep answers aligned with the organization's policies. They apply to the whole organization and don't depend on each Agent being configured correctly. It is the control that survives a badly written prompt. ## The two directions [#the-two-directions] A guardrail acts at one of two points along the way: * **On the way in**: blocks or masks sensitive information before it reaches the model. It is what keeps a CPF pasted into the chat from leaving the organization. * **On the way out**: filters what the model returned, before showing it to the person. The list on the screen shows the active set, with each rule's **type**. ## Why in the organization and not in the Agent [#why-in-the-organization-and-not-in-the-agent] An Agent is created by whoever builds in the workspace, with whatever prompt they want. Entrusting data protection to that prompt means trusting every person who creates an Agent. Guardrails sit above that. A new Agent is born covered by the organization's rules without anyone having to remember to configure them. Guardrails act on message content, not on what an MCP does. A tool that sends data to an external system doesn't go through this filter. ## Day-to-day effect [#day-to-day-effect] Rules that are too tight cut legitimate answers, and the person in Chat sees the already-filtered result, with no explanation of what was removed. When someone reports an incomplete answer with no apparent cause, this screen is one of the places to check, along with the state of the documents in the Collection. ## Next steps [#next-steps] * Limit the connectors' reach in [Knowledge domains](/en/docs/user-guide/knowledge/allowed-domains). * See what else is on this screen in [Settings](/en/docs/user-guide/admin/org-settings). # Overview (/en/docs/user-guide/admin/org-settings) **Settings** gathers the configuration that applies to the whole organization, spread across six tabs. The screen requires the **Superadmin** role; neither Admin nor Auditor can reach it. ## Identity [#identity] The **General** tab keeps what identifies the organization: * **Name**: how it shows up in the organization selector and at the top of the screen. * **Slug**: the identifier that goes into the URL of every page, in the `/organization/` format. * **Logo**: the image shown at the top of the area bar. Changing the slug changes the address of every page in the organization. Saved links and bookmarks pointing to the old slug stop working. The tab also gives quick access to Workspaces and Members, which have their own screens in the sidebar. ## Information [#information] The last tab shows, read-only, the identification data and the contracted plan. It is where to check what is in effect before talking to AUMO about limits or features. ## The other tabs [#the-other-tabs] Filter what travels between people and models. Limit which external domains connectors can reach. Choose the model for each of the platform's automatic features. Turn on the support agent that helps inside the platform. The **MCP Security Scanner** also lives on this screen, but it is documented alongside server registration, in [Security scanner](/en/docs/user-guide/tools/mcp/security). # Workspace settings (/en/docs/user-guide/admin/workspace-settings) **Settings › General** is the workspace's short screen: identity, visibility and the deletion zone. It is accessible to the **Owner**; the **Auditor** sees it read-only. ## Identity [#identity] * **Workspace name**: editable through the icon next to the value. It is how the workspace shows up in the selector and in the organization's list. * **Created at**: the creation date, read-only. Changing the name doesn't change the workspace's identifier in the URL. Existing links keep working. ## Visibility [#visibility] The **Visibility** switch toggles the workspace between public and restricted within the organization. Public means visible to non-members, not accessible to anyone. Permission is still decided by role: someone who isn't a member and doesn't have a Superadmin, Admin or Auditor organization role can't get in. Visibility is about discovery, not access control. To actually restrict who reaches the workspace, what counts is the [Members](/en/docs/user-guide/admin/members) list and the organization roles. ## Workspace deletion [#workspace-deletion] The deletion section is collapsed and highlighted in red, at the bottom of the screen. Deleting a workspace removes access to everything that lives inside it: Collections, Agents, Workflows, Variables and the conversation history. Deletion can't be undone through the interface. Deleted workspaces keep showing up in the organization's list with the **Workspace deleted** badge, but the content doesn't come back. Before deleting, check two things. Whether any Agent in that workspace is in use by people from other teams, and whether there are Collections worth recreating elsewhere, because there is no export between workspaces. ## Next steps [#next-steps] * Control who belongs in [Members](/en/docs/user-guide/admin/members). * Understand what the workspace receives from the company in [Workspaces](/en/docs/user-guide/admin/workspaces). # Workspaces (/en/docs/user-guide/admin/workspaces) **Workspaces** is the list of all of the organization's workspaces and the place where you control what each one receives. This is where the company's catalog becomes a resource available to a team. A model registered under Providers only reaches an Agent after going through this screen. ## The list [#the-list] Each card shows the workspace's name, your role in it and how long ago it was created. Removed workspaces stay visible with the **Workspace deleted** badge. The filter at the top splits the list by relationship: * **All**: everything you can see in the organization. * **My workspaces**: the ones you are a member of. * **Other workspaces**: the ones you reach through your organization role, without being a member. * **Auditable**: available to the Auditor role. ## Create a workspace [#create-a-workspace] Click **+ Workspace**, enter the **Workspace name** and click **Create Workspace**. Only **Superadmin** and **Admin** create workspaces, and the counter at the top of the list shows how many more the organization can create. Once created, you're taken straight to the new workspace's **Dashboard**. A newly created workspace starts empty: no enabled models, no MCPs, no Integrations. It can't create Agents until it receives at least one model. ## What to assign to a workspace [#what-to-assign-to-a-workspace] When you open a workspace on this screen, you find the tabs that control what it receives from the catalog: * **Models**: which models, out of the organization's providers', become available there. * **SuperAgents**: which external agents the team can use. * **MCP**: which registry servers become installable. * **Credentials**: the email credentials, with the sender that Workflows in that workspace use to send messages. Each one points to an **SMTP** credential registered in [Credentials](/en/docs/user-guide/tools/credentials). * **Integrations**: which registered integrations become available. The **Settings** tab holds the rest of the workspace's configuration. Assigning a model here is the step people tend to forget. A workspace without a model won't let you create an Agent, and the message on the creation screen doesn't explain that the cause is on this page. ## Visibility [#visibility] Each workspace has a visibility setting, which defines whether it shows up for non-members. It is changed in the workspace's action menu. This doesn't replace permission: Superadmin, Admin and Auditor organization roles still reach any workspace. ## Next steps [#next-steps] * Register the providers that feed the model list in [Providers](/en/docs/user-guide/models/providers). * Register the installable servers in [MCPs](/en/docs/user-guide/tools/mcp). * Understand the split between catalog and installation in [Organizations and Workspaces](/en/docs/user-guide/concepts/organizations-workspaces). # Create an agent (/en/docs/user-guide/agents/create) The **Create agent** form is a single page with collapsible sections. You fill it in from top to bottom and only open what you'll use. Before you start, confirm that the workspace has at least one model enabled under **Settings › Models**. Without one, the **Model** field stays empty and the form won't save. To open the form, go to **Workspace › Agents**, click **+ Agent** and choose **Create from scratch**. The other option, **Create from a template** (Beta), starts from a ready-made agent in the Marketplace. ## Basic data [#basic-data] Four fields, two of them required: * **Name**: how the Agent shows up in the Chat selector. * **Model**: which model it uses, out of those enabled in the workspace. * **Agent logo**: optional, helps tell it apart visually in the list. * **Description**: optional, but it is what people read to decide whether this is the Agent they want. The name and description are the Agent's interface for people who didn't build it. Describe its job, such as "questions about the expense policy", not the technology. ## User response prompt [#user-response-prompt] The section comes pre-filled with a default text that works. The editor has a side-by-side preview and access to a **Prompt Library**. What to put here is covered in [Write the prompt](/en/docs/user-guide/agents/prompt). ## Collections [#collections] Add the Collections this Agent should look up. This association, and nothing else, is what turns on knowledge search. With at least one Collection, the **search and context settings** appear below. With none, the Agent answers using only the model, tools and prompt, and the form footer says so explicitly. There is no "enable RAG" switch. The presence of Collections is the switch. ## MCPs and Integrations [#mcps-and-integrations] Check the tools this Agent can call, out of those installed in the workspace. The MCPs section has the **maximum iterations**: how many times, in a single answer, the Agent can call tools before wrapping up. This prevents a loop when a tool returns something unexpected. Installing an MCP in the workspace doesn't hand it to the Agent. It has to be checked here. ## Sandbox [#sandbox] Gives the Agent a persistent environment to run commands and work with files. It comes **Disabled**; turn on **Enable sandbox?** only if the Agent's job needs it. ## Sub-agents [#sub-agents] Lets you expose this Agent as a tool and select other Agents for support. It is useful for splitting responsibilities, such as one Agent that knows HR and another that knows the product catalog, instead of bloating a single prompt. The main Agent is still the one talking to the person. ## Advanced options [#advanced-options] * **Temperature**: how much the model varies between answers. Low values make answers more predictable and repeatable. * **Maximum tokens per answer**: the length cutoff. Answers cut off mid-sentence are usually this field. For your first Agent, the defaults are fine. ## Save [#save] In the footer, the button is **Save draft**. Checking **Publish on save** turns it into **Save and publish**. After saving, you go back to the Agents list. The difference is covered in [Publish and maintain](/en/docs/user-guide/agents/publish). ## Next steps [#next-steps] * Write instructions that hold up in [Write the prompt](/en/docs/user-guide/agents/prompt). * Prepare the knowledge before publishing in [Collections](/en/docs/user-guide/knowledge). # Overview (/en/docs/user-guide/agents) An **Agent** is the unit people talk to in Chat. It brings together a model, written instructions and access to this workspace's Collections and tools. Creating and editing Agents requires the **Owner**, **Curator** or **Editor** role. ## The list [#the-list] The screen shows Agents as a grid or a table, with search by name. Each card shows the name, the description, the model provider's icon and when it was last changed. The **+ Agent** button opens the creation form. It also gives access to creating from a ready-made template, when the workspace has templates available. ## What defines an Agent [#what-defines-an-agent] The form is a single page, split into sections you open as needed: * **Basic details**: name, model, logo and description. * **User response prompt**: the standing instructions. * **Collections**: the knowledge it looks up. * **MCPs**, **Integrations** and **Sub-agents**: the tools and helpers it can call. * **Advanced options**: temperature and maximum tokens per answer. Only the name, model and prompt are required. Go through the form section by section. What to put in the instructions and what to leave out. Draft, publishing and what changes for people already using it. # Write the prompt (/en/docs/user-guide/agents/prompt) The **User response prompt** is the Agent's standing instructions. They go into every message, before the history and the passages retrieved from Collections. The editor has formatting, a side-by-side preview and a **Prompt Library** with reusable texts. ## What the prompt decides [#what-the-prompt-decides] Standing instructions are good for four things: * **Role**: who the Agent is and whom it answers. * **Scope**: what is inside and what is outside its subject. * **Format**: the length, structure and language of answers. * **Behavior when unsure**: what to do when the answer isn't in the material. The form's default text already covers format and behavior when unsure. It is usually worth adding role and scope, which are specific to your case. ## What not to include [#what-not-to-include] * **Knowledge**: facts, tables and policies belong in a Collection, not in the prompt. Content in the prompt is paid for on every message and can't be updated without editing the Agent again. * **Secrets**: keys and passwords never go in the prompt. Access to systems is handled through Credentials and tools. * **Rules that are already guardrails**: sensitive-data filters apply to the whole organization and don't depend on each Agent remembering them. Pasting an entire policy into the prompt is the most expensive mistake you can make here. Every message exchanged then costs that whole text, in every conversation, forever. ## Writing for an Agent with Collections [#writing-for-an-agent-with-collections] When the Agent has knowledge attached, the prompt should say what to do with it. Two instructions handle most cases: answer from the retrieved material, and say it doesn't know when the material doesn't cover the question. Without the second, the model tends to fill the gap with what it learned in training, which produces plausible and wrong answers. ## Adjusting later [#adjusting-later] The fastest way to evaluate a prompt is to chat with the Agent about real cases, not ideal ones. Ambiguous and out-of-scope questions reveal more than well-phrased ones. Change one thing at a time. Rewriting the whole prompt between two tests makes it impossible to know what improved. ## Next steps [#next-steps] * Attach the knowledge the prompt refers to in [Collections](/en/docs/user-guide/knowledge). * Put the Agent in people's hands in [Publish and maintain](/en/docs/user-guide/agents/publish). # Publish and maintain (/en/docs/user-guide/agents/publish) Every Agent has two states. A **draft** exists only in Admin; a **published** Agent shows up in the Chat Agent selector for the people in the workspace. You make the choice in the form footer, with the **Publish on save** option. ## Draft [#draft] An Agent saved without publishing is listed under **Agents** in Admin and doesn't show up for anyone in Chat. It is where you keep an Agent while you are still tuning the prompt, waiting for a Collection to finish indexing, or waiting for approval from whoever owns the content. ## Publish [#publish] Checking **Publish on save** and saving puts the Agent live. It then shows up in the Chat selector for everyone with access to the workspace. Before publishing, three checks that prevent most problems: 1. The documents in the attached Collections are **Active**. 2. The chosen model is still enabled under **Settings › Models**. 3. A real question was tested and the answer matches the source document. ## Edit a published agent [#edit-a-published-agent] Editing and saving an already published Agent updates what is live. There is no parallel version: the change applies to everyone's next conversation. There is no draft of an already published Agent. Saving a partial change to an Agent in use puts that change into production immediately. For large changes, the safe path is to duplicate the Agent, adjust the copy as a draft and only then swap it in. ## Existing conversations [#existing-conversations] Changing an Agent doesn't rewrite the past. Old conversations stay in the history as they were, with the answers the Agent gave at the time. Changing the model, the prompt or the Collections only affects the following messages, including within a conversation that is already open. ## Remove [#remove] Removing an Agent takes it out of the Chat selector. The conversation history remains under **Logs › Conversations**, but you can't keep chatting. ## Next steps [#next-steps] * Follow usage in [Conversations](/en/docs/user-guide/monitoring/conversations) and [Response feedback](/en/docs/user-guide/monitoring/feedback). * Check the Agent's consumption in [Dashboard](/en/docs/user-guide/monitoring/dashboard). # SuperAgents (/en/docs/user-guide/agents/super-agents) A **SuperAgent** is an agent that already exists outside AUMO. The organization registers the service's address, and the platform then offers it to workspaces as if it were one of its own Agents. It has no prompt, model or collections for you to configure: all of that belongs to whoever runs the service on the other side. ## When to use one [#when-to-use-one] A SuperAgent fits when the agent has already been built elsewhere and you just want to make it available inside the platform: customer service running on another system, specialized research, a sales automation. If the agent is still to be built, the path is to [create an Agent](/en/docs/user-guide/agents/create) inside a workspace. ## Register it in the organization [#register-it-in-the-organization] Under **Organization › SuperAgents**, available to **Superadmin** and **Admin**: 1. Click **+ SuperAgent**. 2. Enter the **SuperAgent name**, as it will show to people. 3. Enter the **Endpoint URL** and the **Access key**. 4. Click **Validate access**. The registration screen is built for SuperAgents contracted from Aumo: Aumo sends the URL and access key once the SuperAgent is contracted, and the side panel shows how to get in touch with Aumo. The platform registers the URL as the endpoint and sets `responses` as the supported API. The service on the other side has to respond following the Responses API contract. ## Make it available to a workspace [#make-it-available-to-a-workspace] Once created, the SuperAgent goes into the organization's catalog and doesn't show up in any workspace yet. You make it available under **Organization › Workspaces**: open the desired workspace and use the SuperAgents section to associate the ones that team can use. ## In the workspace [#in-the-workspace] **Workspace › SuperAgents** lists what the organization made available to that team. There is nothing to create there, because the screen only shows what is available. An empty list means no SuperAgent was registered in the organization, or this workspace wasn't associated with any. In both cases, the way forward is to talk to someone with the Admin or Superadmin role. ## In Chat [#in-chat] Agents and SuperAgents show up in the same selector, with name and description, with no visual distinction. The distinction matters when something goes wrong. An Agent with a bad answer is adjusted in the prompt or the Collections. A SuperAgent with a bad answer requires talking to whoever maintains the external service. ## Maintenance [#maintenance] Editing a SuperAgent changes its name and endpoint. Changing the URL redirects all future conversations to the new address, in every workspace it is associated with. Removing a SuperAgent takes it out of the catalog and the associations. Old conversations stay in the history, but you can't keep chatting. ## Consumption [#consumption] A SuperAgent's consumption shows up in the workspace's Observability like any other call, but the model behind it is decided on the external side. This means per-provider Quotas may not capture that consumption the same way they capture a regular Agent's. ## Next steps [#next-steps] * Understand the conceptual difference in [Agents and SuperAgents](/en/docs/user-guide/concepts/agents). * See what else the organization distributes to teams in [Workspaces](/en/docs/user-guide/admin/workspaces). # Choose the agent (/en/docs/user-guide/chat/agents) Every conversation happens with an Agent. The selector sits at the top of the screen, next to the current Agent's name, and lists what is published in the workspace. Agents and SuperAgents show up together, with no visual distinction. The difference between them is in how they are built, not in how they are used. ## Switch agents [#switch-agents] Open the selector and use **Filter agents** when the list is long. The choice applies to the conversation in progress. Names and descriptions come from whoever built the Agent. When they are vague, the information panel usually explains better than the name. ## The information panel [#the-information-panel] The **Chat info** button, in the header, opens a side panel with two tabs at the top: **Agent** and **Chat**. Inside **Agent**, three tabs show how it is put together: * **General**: description, model, provider in use and when the Agent was created. * **Collections**: which knowledge bases it looks up, with each one's details. * **MCPs**: which tools it can call. It is the fastest way to answer "why doesn't this agent know this" before opening a ticket: if the **Collections** tab is empty, it doesn't look up any document. ## What the agent reaches [#what-the-agent-reaches] An Agent only sees what was attached to it in Admin. Nothing you write in the conversation changes that. If the answer you need depends on a document that isn't in any of that Agent's Collections, there is no way to ask it to look it up. The way forward is to talk to whoever administers the workspace. The **Collections** tab also shows each base's connectors. A Collection fed by a connector may be outdated if the sync failed, even if it shows as attached here. ## When the list is empty [#when-the-list-is-empty] No Agent in the selector means the workspace has no **published** Agent. Drafts exist only in Admin and don't show up here. Also check the workspace selected at the top of the sidebar: each workspace has its own Agents. ## Next steps [#next-steps] * Understand the difference between the two kinds in [Agents and SuperAgents](/en/docs/user-guide/concepts/agents). * See how the Agent uses Collections in [References and sources](/en/docs/user-guide/chat/sources). # API keys (/en/docs/user-guide/chat/api-keys) **API keys**, called project keys on the platform, authenticate applications and integrations that call AUMO without a person in front of it. The screen is exclusive to the workspace **Owner**. No other role reaches it, not even read-only. ## Why only the Owner [#why-only-the-owner] Issuing a key grants programmatic access to the workspace, without login and without the barrier of a session. The restriction is deliberate and doesn't extend to the other builder roles: Curator and Editor create Agents and Collections, but don't issue credentials. ## Create a key [#create-a-key] Click **+ Project key** and fill in the **New project key** window: * **Name**: what shows up in the list and in consumption reports. Describe the system that will use the key. * **Expiration**: 30 days by default, with options for 7, 60 and 90 days, a custom date or no expiration. * **Scopes**: for each resource, **None**, **Read** or **Read and write**, among other levels. You can only grant scopes you have yourself in the workspace. To chat with an agent, the window itself points out the minimum: **Conversations** with read and write, **Agent** and **Models** with read. Click **Generate key**. The key shows up on a card at the top of the list, with a copy option. The key's value is shown only once, at creation time. Store it before closing the screen; there is no way to retrieve it later, only to revoke it and issue another. ## The list [#the-list] Search filters by name, prefix or scope. The prefix is the visible part of the key, enough to identify which credential is in use without exposing the value. The **Show revoked** button also brings in keys that were already invalidated, which are hidden from the list by default. ## Revoke [#revoke] Revoking invalidates the key immediately. Everything that used it stops authenticating, and the failure shows up in the calling system, not here. A revoked key stays on record, so past consumption remains attributable. ## Consumption and quotas [#consumption-and-quotas] Project keys consume from the workspace like any other call, and have their own tab under **Quotas**. Use it: an integration stuck in a loop consumes nonstop with no one watching, which is exactly the case a per-key cap prevents. ## Next steps [#next-steps] * Cap consumption per key in [Quotas](/en/docs/user-guide/models/quotas). * Follow the calls in [Observability](/en/docs/user-guide/monitoring/observability). # Attachments and prompts (/en/docs/user-guide/chat/attachments) The **+** button, to the left of the message field, gathers everything you can add to a message besides text. There are three paths: attach files, attach images and insert a ready-made prompt. ## Upload files [#upload-files] **Upload files** attaches documents to the message. The Agent reads them in the context of that conversation. This is different from a Collection. An attached file applies to the conversation it was sent in; a Collection applies to every conversation of every Agent attached to it. Use an attachment for the one-off document: the contract that just arrived, the spreadsheet for this analysis. Use a Collection for what the company looks up all the time. ## Upload images [#upload-images] **Upload images** only works when the Agent's model has vision capability. When it doesn't, the option shows as disabled with a notice that the Agent doesn't support image attachments. Switching to an Agent with a vision model is the only way out: the capability comes from the model, not from a conversation setting. ## Prompt library [#prompt-library] **Prompt library** opens the collection of ready-made texts, with search by title, tag or content. Selecting one inserts the text into the message field, where you can edit it before sending. It helps standardize recurring requests, such as a summary format or a review checklist, without depending on each person remembering the right wording. ## MCP resources [#mcp-resources] When the Agent has MCPs with published prompts and resources, you can browse them and attach them to the message. The chosen items show up as chips above the field, with a remove action. An attached prompt or resource chip applies only to the message being written. It doesn't stay attached to the conversation. ## Dictate the message [#dictate-the-message] The microphone button, to the right of the field, transcribes speech into text. The result goes into the message field, where it can be corrected before sending. ## Next steps [#next-steps] * Understand when the content should be in a knowledge base in [Collections and knowledge](/en/docs/user-guide/concepts/knowledge). * See what the Agent looks up on its own in [Choose the agent](/en/docs/user-guide/chat/agents). # Conversations (/en/docs/user-guide/chat/conversations) A conversation is a sequence of messages with an Agent. It keeps the context: the Agent sees what has already been said when answering the next message. Your conversations are yours. Other people in the workspace don't see what you asked, although whoever administers the workspace can reach the history under **Logs › Conversations**. ## Start [#start] The home screen shows a greeting and the message field in the center. Type and send. The conversation is created with the first message. When the selected Agent has Collections attached, suggested questions appear above the field. With no knowledge base attached, the suggestions don't appear, and that is expected behavior, not a failure. The **New chat** button, next to the search box in the sidebar, starts a blank conversation at any time. ## The history [#the-history] The sidebar lists conversations grouped by recency: **Pinned**, **Today**, **Yesterday**, **Last 7 days**, **Last month** and **Older**. The **Search chats** field filters by content. Each conversation's title is generated automatically from its first messages. ## Organize [#organize] Each conversation's menu has the housekeeping actions: * **Rename**: replaces the automatically generated title with your own. * **Pin**: moves the conversation to the **Pinned** group, at the top. * **Delete**: removes the conversation from your list, with confirmation. Deleting a conversation takes it out of your sidebar, but the record remains accessible to whoever administers the workspace, under **Logs › Conversations**. Deletion is for organization, not privacy. ## Rate an answer [#rate-an-answer] Each Agent answer shows actions on hover. Two of them feed the platform's quality: * **Good response** and **Bad response** record the rating. * When you mark it as bad, a modal opens with quick options and a free-text field. These ratings show up for whoever administers the workspace under **Logs › Response feedback**. It is the most direct channel for improving an Agent that gets things wrong. The message's other actions include editing your own message, copying and listening to the answer as audio. ## Share [#share] The **Share chat** action, in the header, opens a panel with a switch and a link. While the **Workspace members with the link** switch is off, nobody else can open the conversation. When you turn it on, any workspace member who has the link can open it. Sharing is read-only and doesn't intrude on other people's lists: * The conversation does **not** show up in the sidebar of whoever received the link. * Only you can keep writing in it. * Anyone who isn't a workspace member can't open it, even with the link. Still, the whole conversation goes along, including whatever you pasted into it along the way. ## Next steps [#next-steps] * Choose whom to chat with in [Choose the agent](/en/docs/user-guide/chat/agents). * Check where answers come from in [References and sources](/en/docs/user-guide/chat/sources). # Overview (/en/docs/user-guide/chat) **Chat** is the side of the platform that doesn't require administrative access. Anyone in a workspace chats with the Agents published there and runs the available Workflows. It shares the area bar with Admin and uses the same login. Switching from one to the other doesn't ask you to authenticate again. ## The two areas [#the-two-areas] The area bar has two destinations in this module, and the difference between them is the shape of the interaction. * **Chat**: an open conversation with an Agent, message by message. * **Agents**: running published Workflows, through a form, with a result at the end. The second area's name is confusing: it lists **Workflows**, not conversational Agents. Those are picked from the selector inside the Chat screen itself. ## Chat [#chat] Start, resume, rename and share conversations. The agent selector and the panel that shows how each one is configured. Send files and images, and reuse prompts from the library. Where the answer came from and how to check the source passage. ## Run [#run] Fill in a published workflow's form and follow the result. # References and sources (/en/docs/user-guide/chat/sources) When the Agent answers from Collections, the answer ends with a **References** block pointing to the documents used. That is what separates a verifiable answer from a plausible one. Checking the reference takes a few seconds and settles most doubts about reliability. ## Open a fragment [#open-a-fragment] Clicking a reference opens the **Document fragments** panel, with the passages from that document that search considered relevant to your question. The panel shows the file name, how many fragments were found and a relevance score. The score comes from the search engine, not from an assessment of correctness: a high-scoring fragment is the one most similar to the question, not necessarily the one that contains the right answer. ## How to read the result [#how-to-read-the-result] Three situations, and what each one indicates: * **The answer cites a passage that checks out**: the path worked end to end. * **The answer cites a passage that doesn't support what was said**: the model extrapolated. Record it as a bad response. * **There is no References block**: the Agent answered without looking up any document. ## When there are no references [#when-there-are-no-references] The missing block has three possible causes, in order of frequency: 1. **The Agent has no Collections attached.** Confirm it on the **Collections** tab of the information panel. 2. **The documents aren't ready yet.** Documents being extracted or indexed don't take part in answers. 3. **Search found nothing relevant.** The question uses terms that don't appear in the documents. An Agent without Collections answers anyway, using what the model learned in training. The answer looks the same, it just has no references. This is the case where it's most worth checking before acting. ## Help search find it [#help-search-find-it] Search compares the content of the question with the content of the documents, not with titles or file names. Asking with the terms that appear inside the document works better than naming it. "What is the reimbursement deadline for travel expenses" finds more than "what does the expense policy say". ## Next steps [#next-steps] * Understand the mechanism behind this in [Collections and knowledge](/en/docs/user-guide/concepts/knowledge). * Record an unsupported answer in [Conversations](/en/docs/user-guide/chat/conversations). # Run workflows (/en/docs/user-guide/chat/workflows) The **Agents** area, in the area bar, lists the Workflows published in the workspace and lets you run them. Unlike Chat, there is no conversation here. You fill in a form, run it and get a result. The area's name is misleading: it lists **Workflows**, not conversational Agents. Those are picked from the selector inside the Chat screen. ## The list [#the-list] The screen shows the available Workflows, with search by name and each one's description. The sidebar shows the ones you have already run and the recent runs. On your first visit it is empty, with a notice that items appear after the first run. ## Run [#run] Opening a Workflow shows the input form, built from what its creator declared in the Input node. The fields and their descriptions come from there. Fill in the fields under **User inputs** and click the run button (▶) in the corner of the card. Required fields left empty disable the button. ## Follow [#follow] While it runs, the screen shows progress by step. Workflows with several steps take longer than a chat message, and that is expected. At the end, the result appears according to what the Output node defines: text, a data structure or a downloadable file. ## When something goes wrong [#when-something-goes-wrong] A run that fails stops at the problematic step and shows where it stopped. There is little to fix on your side: the form is the only input you control. Check that the values you entered are in the expected format and, if the error persists, take the case to whoever maintains the Workflow, with the run's identifier. ## Versions [#versions] A run uses the Workflow version that is published at the time it runs. The sidebar marks runs made with an earlier version. When you compare two different results for the same input, that mark is usually the explanation. ## Next steps [#next-steps] * Understand when a Workflow is the right tool in [Workflows](/en/docs/user-guide/concepts/workflows). * For builders, the path is in [Build on the canvas](/en/docs/user-guide/workflows/build). # Agents and SuperAgents (/en/docs/user-guide/concepts/agents) An **Agent** is the unit people talk to in Chat. It brings together an AI model, written instructions and access to the workspace's knowledge and tools. Agents belong to a workspace and are created in Admin. Nothing in Chat creates an Agent. ## What an Agent is made of [#what-an-agent-is-made-of] The creation form organizes the Agent into sections, and each one answers a different question: * **Basic details**: name, model, logo and description. The name and description are what people read when choosing the Agent. * **User response prompt**: the standing instructions. It defines the tone, format and limits of what the Agent should answer. * **Collections**: the knowledge it looks up before answering. * **MCPs** and **Integrations**: the tools it can call. * **Sub-agents**: other Agents it calls for support. * **Advanced options**: temperature and maximum tokens per answer. Only the name, model and prompt are required. An Agent with no collections and no tools is valid: it answers with the model and the prompt, like a plain chat. ## Draft and published [#draft-and-published] Every Agent has two states. A **draft** exists only in Admin; a **published** Agent shows up in the Chat Agent selector for the people in the workspace. You choose between them when you save, with the **Publish on save** option. An Agent that is created but not published stays out of sight of platform users, which is useful while you are still tuning the prompt. ## How the Agent answers [#how-the-agent-answers] For each message, the Agent builds its answer in this order: 1. If it has Collections attached, it searches them for relevant passages. 2. If it has MCPs or Integrations, it decides whether it needs to call a tool, within the configured iteration limit. 3. It combines everything with the prompt and the conversation history and asks the model for the answer. Without attached Collections, step 1 doesn't happen, and the platform doesn't even query the search engine. Attaching Collections is what turns on RAG, not a separate switch. ## Sub-agents [#sub-agents] An Agent can expose itself as a tool and call other Agents for support. The main Agent is still the one talking to the person; the sub-agents work behind the scenes. This is useful for splitting responsibilities, such as one Agent that knows the HR policy and another that knows the product catalog, instead of bloating a single prompt. ## SuperAgents [#superagents] A **SuperAgent** is an agent that already exists outside AUMO and that the organization registers by URL. The platform treats it as an endpoint compatible with the Responses API. The differences that matter: * **Where it comes from**: an Agent is built inside AUMO; a SuperAgent is registered by pointing to an external system. * **Who registers it**: SuperAgents go into the Organization catalog and are then made available to each workspace. * **What you configure**: for a SuperAgent you provide a name and an endpoint. The prompt, model and knowledge are the responsibility of whoever runs the service on the other side. For Chat users, both show up side by side in the selector. The difference is in how they are built and governed, not in the experience. ## Next steps [#next-steps] * Understand the knowledge that feeds the Agent in [Collections and knowledge](/en/docs/user-guide/concepts/knowledge). * See where the available models come from in [Providers and models](/en/docs/user-guide/concepts/models). * Build an Agent from scratch in [Your first agent](/en/docs/user-guide/get-started/first-agent). # Collections and knowledge (/en/docs/user-guide/concepts/knowledge) A **Collection** is a set of documents an Agent can look up before answering. It is how the platform answers with your company's content, not just with what the model learned in training. Collections belong to a workspace and are not shared between workspaces. ## What a Collection is made of [#what-a-collection-is-made-of] A Collection brings together two kinds of sources, on the **Files** and **Connectors** tabs: * **Files**: documents you upload, in PDF, DOCX, TXT and equivalent formats. They stay as they are until someone replaces them. * **Connectors**: external sources the platform syncs, such as an indexed website or a document repository. They fetch content again from time to time. Up to version 3 there were two screens, **Knowledge Sources** and **Collections**. v4 merged them: files and connectors are now added directly to the Collection. ## A document's lifecycle [#a-documents-lifecycle] Every document goes through the same states before it becomes usable, and the **Files** tab shows the state of each one: 1. **Queued**: the file has arrived and is waiting to be processed. 2. **Extracting**: the platform is turning the file into text. 3. **Indexing**: the text is being split into passages and prepared for search. 4. **Extracted**: the document is available for answers. Despite the name, **Extracted** is the final state: it comes after **Indexing**, not right after extraction. The two error states are **Extraction failed** and **Indexing failed**. Neither recovers on its own, and a document in either state doesn't take part in answers. Only **Extracted** documents are looked up. An Agent attached to a Collection whose files are still indexing answers as if the Collection were empty. ## What happens on each question [#what-happens-on-each-question] When an Agent with Collections receives a message, the platform: 1. Converts the question into a numeric representation and searches for the closest passages in the Collections attached to that Agent. 2. Hands the passages it found to the model, along with the prompt and the history. 3. Asks for the answer, now with that material in view. This design is what the industry calls **RAG**, retrieval-augmented generation. The practical consequence is that answer quality depends more on the indexed content than on the chosen model. ## Limits worth knowing [#limits-worth-knowing] * **Search is by content, not by title.** Asking for a file's name rarely finds the file. Use the terms that appear inside it. * **An empty Collection means "no knowledge", never "search everything".** An Agent without Collections doesn't scan the workspace; it just doesn't search. * **Scanned PDFs depend on text extraction** and take longer. When the original is an image without selectable text, extraction may fail. * **The scope is the workspace.** Taking a Collection to another workspace means recreating it there. ## Next steps [#next-steps] * See how the Collection connects to whoever answers in [Agents and SuperAgents](/en/docs/user-guide/concepts/agents). * Create your first Collection in [Your first agent](/en/docs/user-guide/get-started/first-agent). # Providers and models (/en/docs/user-guide/concepts/models) A **Provider** is an account with an AI model service: AUMO, OpenAI, Bedrock and the like. A **Model** is a concrete option within a provider, selectable in an Agent's form. The two live at different levels on purpose: the Provider belongs to the Organization, the Model is enabled per Workspace. ## Providers [#providers] Providers live under **Organization › Providers** and are where the company's AI credentials are stored. Registering a provider is what gives the platform the right to call that service. Only the **Superadmin** role opens that screen. This is deliberate: it is where the secret lives. The **AUMO** provider is the special case. Instead of bringing your own account, AUMO provides the access, with approval and quotas negotiated between your organization and the platform. ## Models [#models] Models live under **Workspace › Settings › Models**. That is where you decide which options, out of everything the organization's providers offer, show up for whoever creates Agents in that workspace. Each model carries the data that determines its behavior and its cost: * **Context window**: how much text fits in one call, adding up the prompt, history and retrieved passages. * **Maximum output tokens**: the ceiling for one answer. * **Input and output price**: the cost per token, used to calculate consumption and quotas. A workspace with no model enabled won't let you create an Agent: the **Model** field is required and would be empty. ## The path to an answer [#the-path-to-an-answer] The full chain has four links, and it is worth knowing where each one breaks: 1. The Organization registers the **Provider**, with the credential. 2. The Workspace enables the **Models** from that provider it wants to offer. 3. The Agent picks **one** of those models. 4. Each Chat message consumes tokens from that model, counted against the workspace. If a model disappears from the list of an existing Agent, the broken link is almost always number 2: someone disabled it in the workspace. ## Choosing a model [#choosing-a-model] Three criteria are usually enough: * **Context size**: Agents with many Collections or long conversations need larger windows. * **Cost**: larger models charge more per token, and the Dashboard shows the effect at the end of the month. * **Behavior**: the same prompt yields different answers across models. It is worth testing the same Agent on two before publishing. Starting with the cheapest model that handles the task is the most predictable path. Switching later means editing one field. ## Next steps [#next-steps] * See how the consumption of these models is capped in [Quotas and consumption](/en/docs/user-guide/concepts/quotas). * Understand where the model fits in building the answer in [Agents and SuperAgents](/en/docs/user-guide/concepts/agents). # Organizations and Workspaces (/en/docs/user-guide/concepts/organizations-workspaces) Every AUMO setting belongs to one of two levels. The **Organization** represents the company; the **Workspace** represents a team, product or project within it. Knowing which level something lives at answers three questions that come up all the time: who can change it, who can see it and where its consumption is counted. ## Organization [#organization] An **Organization** is your company's outer boundary on the platform. It keeps the catalog of what is allowed and the rules that apply to everyone. These belong to the Organization: * **Providers** and **Credentials**: the AI model accounts and the access secrets for external systems. * **SuperAgents**: the external agents registered for the company. * **MCPs** and **Integrations**: the registry of what workspaces can install. * **Members** and **Quotas**: who joins the company and how much it can spend. A person can belong to more than one Organization, with a different role in each. Switching Organizations switches the whole context. ## Workspace [#workspace] A **Workspace** is where the work happens. It consumes the Organization's catalog and builds its own things on top of it. These belong to the Workspace: * **Collections**: the documents that feed the answers. * **Agents** and **Workflows**: what people use in Chat. * Installed **MCPs** and **Integrations**: the tools actually turned on. * **Models**, **Variables**, **Members**, **Quotas** and **API keys**. Workspaces don't see each other. A Collection in one workspace doesn't show up for another workspace's Agent, even within the same Organization. Up to version 3, workspaces were called **Projects**. The name changed across the platform in v4; the concept is the same. ## Catalog and installation [#catalog-and-installation] AI providers, MCPs, Integrations and SuperAgents exist at both levels, and that is on purpose. They are two different steps: 1. The Organization **registers** the item once: the provider account, the MCP server, the SuperAgent URL. This is where secrets and approval live. 2. The Workspace **installs** what it will use from that catalog, with its own name and configuration. The same registry item can be installed several times in the same workspace, as long as each installation has a different name. The configuration belongs to the installation, not to the registry entry. This design exists so that a credential is stored in a single place, while each team decides what to turn on. A workspace never creates a provider account on its own. ## Where this shows up in practice [#where-this-shows-up-in-practice] Three consequences worth remembering: * **Permission**: your role in the Organization and your role in each Workspace are independent. You can be the company's Admin and not be a member of a specific workspace. * **Consumption**: token spending is attributed to the workspace that made the call, and rolls up to the Organization total. * **Isolation**: moving knowledge between workspaces means recreating the Collection, not sharing it. ## Next steps [#next-steps] * See who can do what at each level in [Roles and permissions](/en/docs/user-guide/concepts/roles). * Understand how the model catalog flows down to the workspace in [Providers and models](/en/docs/user-guide/concepts/models). # Quotas and consumption (/en/docs/user-guide/concepts/quotas) Every call to an AI model consumes **tokens**, and every token has a price. **Quotas** are the monthly caps the platform applies to that consumption. Without a quota configured, a scope has no limit. Quotas exist so that a poorly calibrated experiment doesn't eat the whole month's budget. ## The scopes [#the-scopes] The same consumption is counted at more than one level at once, and each one can have its own cap: * **Organization**: the company's total. * **Workspace**: a team's or project's total. * **User**: how much one person can consume within the workspace. * **Project key**: how much a programmatic integration can consume. You can also cap **per provider**, when one of them is more expensive than the others and deserves its own ceiling. The Organization quota takes **precedence** over the Workspace quota. Once the company's cap is used up, no workspace continues, however much headroom it has under its own limit. Caps are set in **cost** or in **tokens**, and apply to the current month. The turn of the month resets accumulated consumption. A blank field means "no limit"; a limit of **zero** blocks every request in that scope. ## What happens when a cap is exceeded [#what-happens-when-a-cap-is-exceeded] When consumption goes over the cap, the call is refused and whoever is in Chat gets a quota-exceeded warning. The platform doesn't degrade the answer or switch models: it blocks. The block applies to the scope that went over. A user who hit their own limit can no longer use the platform, while the rest of the workspace carries on. ## Temporary grants [#temporary-grants] Raising the quota policy fixes the problem of the day and rarely comes back down. For one-off cases there is the **temporary grant**. It works like this: * It adds an extra allowance on top of the current limit, for a set period, with a recorded reason. * It expires on its own. There is no routine to undo it: the platform simply stops counting expired grants. * When it expires, the scope goes back to the policy cap and blocks again if the month's consumption has already passed it. A grant takes up to about 30 seconds to take effect, because consumption is read from a cache. The same applies when you revoke a grant before it expires. ## Where to see consumption [#where-to-see-consumption] Three screens answer different questions: * **Workspace › Dashboard**: the workspace summary, with tokens consumed, total cost and usage per Agent. * **Quotas**, in the Organization or the Workspace: limits, usage for the month and the projection to the end of it. * **Observability**: the per-model detail, with filters and traces for each execution. The projection on the Quotas screen is the most useful signal mid-month: it shows whether the current pace will exceed the cap before the month turns. ## Next steps [#next-steps] * Understand where the per-token price comes from in [Providers and models](/en/docs/user-guide/concepts/models). * See who can change quotas in [Roles and permissions](/en/docs/user-guide/concepts/roles). # Roles and permissions (/en/docs/user-guide/concepts/roles) Each person has one role in the **Organization** and one role in each **Workspace** they belong to. The two are independent and add up. That combination decides what shows up in the sidebar and what the platform accepts when you click save. ## Organization roles [#organization-roles] * **Superadmin**: full access. It is the only role that opens **Providers**, **Credentials** and **Settings › General**. * **Admin**: runs the organization: workspaces, members, quotas, SuperAgents, MCPs and Integrations. It doesn't reach Providers, Credentials or Settings › General, and doesn't register new MCPs in the registry. * **Auditor**: read-only, and only in Workspaces, Members, Quotas, Observability and SuperAgents. * **User**: no access to Organization screens. This is the role for people who only use Chat. The gap between Superadmin and Admin is deliberate: what holds secrets, provider accounts and credentials, stays with a single role. ## Workspace roles [#workspace-roles] * **Owner**: full access to the workspace, including Integrations, API keys and deleting the workspace. * **Curator**: builds and monitors. Creates Collections, Agents, SuperAgents, Workflows, MCPs and Variables, and reads the Dashboard, Conversations, Response feedback, Observability and Quotas. * **Editor**: builds only. Same creation power as the Curator, without any of the monitoring and settings screens. * **Auditor**: read-only, across most of the workspace. * **User**: no access to the administration screens. Chats in Chat. | Workspace area | Owner | Curator | Editor | Auditor | | ------------------------------------------------------------ | ----- | --------- | --------- | --------- | | Collections, Agents, SuperAgents, Workflows, MCPs, Variables | Edits | Edits | Edits | Reads | | Dashboard, Observability, Quotas | Reads | Reads | No access | Reads | | Conversations, Response feedback | Reads | Reads | No access | Reads | | Models, Members, General | Edits | No access | No access | Reads | | Integrations, API keys | Edits | No access | No access | No access | ## How the two combine [#how-the-two-combine] The platform resolves access to a workspace in this order: 1. If you are a member of the workspace, your workspace role applies. 2. If you aren't, but you are a Superadmin, Admin or Auditor of the organization, your organization role applies. 3. If neither applies, the workspace doesn't open. That is why an organization Admin can enter a workspace they were never added to, while an Editor from another workspace can't. The sidebar hides what your role doesn't allow, but the real decision is made by the backend: every service rechecks the permission on every call. Typing the URL of a hidden page doesn't give you access to it. ## When access isn't what you expected [#when-access-isnt-what-you-expected] * **You see the workspace but can't edit anything**: you got in through your organization role, not as a member. Ask to be added to the workspace. * **You are an Admin and can't open Providers or Credentials**: this is by design, and can't be solved per workspace. Those two require Superadmin. * **You are a Curator and don't see Models or Members**: also by design. Those two stay with the Owner. * **The Workspace area is disabled**: you don't belong to any workspace in that organization. ## Next steps [#next-steps] * Understand what belongs to each level in [Organizations and Workspaces](/en/docs/user-guide/concepts/organizations-workspaces). * Your role in the organization shows up in the user menu, under **Settings**, next to its name. # MCPs and Integrations (/en/docs/user-guide/concepts/tools) Collections give the Agent something to **read**. Tools give it something to **do**: query a system, open a ticket, fetch data that changes by the minute. AUMO offers two paths for this, **MCPs** and **Integrations**. Both follow the same design: a catalog in the Organization and an installation in the Workspace. ## MCPs [#mcps] **MCP** is an open protocol for exposing tools to AI models. An MCP server publishes a set of tools, and the Agent decides when to call them. The path has two steps: * **Organization › MCPs** is the registry. That is where the company registers the allowed servers, from Docker Hub, from GitHub or from its own address. * **Workspace › MCPs** is the installation. Each workspace chooses which registry servers it wants to turn on, and gives each installation a name and a configuration. The same registry server can be installed several times in the same workspace, as long as each installation has a different name. This allows, for example, two connections to the same system pointing at different environments. Configuration and behavior belong to the **installation**, not to the registry entry. Changing one installation doesn't affect the others or the item registered in the Organization. ## Integrations [#integrations] **Integrations** are ready-made connections to well-known services, maintained by the platform. You don't describe the protocol: you pick the service from a list and provide the access. They follow the same split. Under **Organization › Integrations**, the **Available** and **Installed** tabs show the known catalog and what the company has already registered. Under **Workspace › Integrations**, each workspace turns on the ones it will use. In the workspace, the Integrations screen is accessible only to the **Owner**. ## MCP or Integration [#mcp-or-integration] The choice is usually straightforward: * **Use an Integration** when the service is already on the list. It means less configuration, and the platform handles maintenance. * **Use an MCP** when the system is internal, specific to your business, or when you need to control exactly which tools are exposed. It isn't an either-or decision: the same Agent can have MCPs and Integrations at the same time. ## How the Agent uses the tool [#how-the-agent-uses-the-tool] In the Agent form, the **MCPs** and **Integrations** sections list what is installed in the workspace. You check what that Agent can call. The MCPs section also has the **maximum iterations**: how many times, in a single answer, the Agent can call tools before it has to wrap up. This keeps an Agent from looping when a tool returns something unexpected. An Agent only reaches what was installed in its workspace and checked in its form. Installing an MCP in the workspace doesn't automatically hand it to every Agent. ## Credentials [#credentials] Access to external systems lives under **Organization › Credentials**, stored once and reused by installations. Like Providers, the screen is restricted to the **Superadmin**. This keeps the secret in a single place, while each workspace decides what to turn on without ever seeing the stored value. ## Next steps [#next-steps] * See where tools come into the answer in [Agents and SuperAgents](/en/docs/user-guide/concepts/agents). * Tools also show up as nodes in [Workflows](/en/docs/user-guide/concepts/workflows). # Workflows (/en/docs/user-guide/concepts/workflows) A **Workflow** is a sequence of steps built on a canvas, connecting nodes that receive data, process it and return a result. Where an Agent converses, a Workflow executes. The person using it fills in an input form and gets an output, with no dialogue in between. ## Agent or Workflow [#agent-or-workflow] The question that separates the two is whether the path is known in advance: * **Agent**: the person asks open questions and the model decides what to do on each message. Good for questions, support and research. * **Workflow**: you know the steps and their order. Good for processing a document, extracting fields, querying a system and generating a file. A Workflow is more predictable and easier to audit. An Agent covers cases you didn't anticipate. ## The nodes [#the-nodes] The canvas offers nodes grouped by purpose: * **Input and Output**: the two ends of the flow. Input defines the form fields the person fills in; Output defines what they get back. * **LLM**: calls an AI model with a prompt built from what came before. * **Documents**: File extractor, CPF extractor, Vector database and File generator. * **Logic**: Condition, Iteration and Aggregation, for branching, repeating over lists and choosing between results. * **Integration**: HTTP request, Send email and Integration, for talking to outside systems. * **Code**: Code executor, for transformations no ready-made node covers. The **Vector database** node is what gives a Workflow access to Collections, and it requires at least one configured Collection. ## Draft, publishing and runs [#draft-publishing-and-runs] Like Agents, Workflows have a draft and a published version. Only the published one is available for other people to run. Each execution becomes a **run** with its own record: input, output, steps taken and errors. That is where you investigate a strange result, step by step, instead of guessing. ## Where people run them [#where-people-run-them] Published Workflows show up in the **Agents** area of the Chat module, under the icon right below Chat in the area bar. Whoever opens a workflow there sees the form defined by the Input node, runs it and follows the result. No Admin access is needed for this. The area's name is confusing: **Agents**, in Chat, lists published Workflows, not conversational Agents. Conversational Agents are picked from the selector inside the Chat screen itself. ## Next steps [#next-steps] * Understand the Collections the vector node queries in [Collections and knowledge](/en/docs/user-guide/concepts/knowledge). * See the tools the integration nodes reach in [MCPs and Integrations](/en/docs/user-guide/concepts/tools). # Access and login (/en/docs/user-guide/get-started/access) AUMO uses single sign-on (SSO): you don't create a password on the platform, you sign in with the account your company already uses. The same login works for Admin and Chat. By the end of this page you will have signed in, understood where you landed, and know what to do when an area shows up empty or locked. ## Where the platform lives [#where-the-platform-lives] AUMO is delivered at an address dedicated to your organization, provided by the AUMO team. Both modules live at that same address: * **Chat**: at the root of the address. This is where people talk to Agents. * **Admin**: at the `/admin` path. This is where Agents, Collections and Workflows are configured. You don't need to memorize both addresses. Once you're signed in, the area bar takes you from one to the other without signing in again. ## Signing in [#signing-in] When you open the platform while signed out, you are sent straight to your company's identity provider login screen. After you authenticate, the browser returns to AUMO, already inside your organization. The first time you enter an organization, the platform asks you to accept that organization's **Terms of Use**. The screen blocks the rest of the platform until you accept, and acceptance is per organization: if you belong to more than one, each asks separately. If login fails with a warning instead of moving you forward, it is almost always because the authenticated account doesn't belong to any AUMO organization. Use the switch-account action on that screen and sign in with the correct corporate email. ## Where you land after login [#where-you-land-after-login] The platform has no single home screen. Where you land depends on what you can see: * **With organization permissions**: you land on the first Organization page your role opens, usually Providers or Workspaces. * **With workspace permissions only**: you land on the first workspace page your role opens, usually the Dashboard. * **With neither**: you land in Chat, the area available to anyone with access to a workspace. The platform remembers the last organization and workspace you visited and returns to them next time, including when you jump between Admin and Chat. ## Switching organizations [#switching-organizations] The organization selector sits at the top of the screen. It lists the organizations you belong to and has a search box when there are many. Switching organizations switches the whole context: workspaces, Agents, Collections and permissions become those of that organization. Your role changes too: you can be an Admin in one and a User in another. ## When an area shows up locked [#when-an-area-shows-up-locked] Two cases are common and are not errors: * **You don't belong to any workspace in the organization**: the Workspace and Chat areas are disabled. Ask an administrator to add you to a workspace. * **You got here through an organization role, without permission on the current workspace**: the Workspace area is still clickable, but it opens the workspace selector instead of the page. Pick a workspace you have access to. ## Next steps [#next-steps] * Learn the areas and the sidebar in [Navigating the platform](/en/docs/user-guide/get-started/navigation). * Put the platform to work by following [Your first agent](/en/docs/user-guide/get-started/first-agent). # Your first agent (/en/docs/user-guide/get-started/first-agent) This tutorial walks through the platform end to end in one workspace: you create a **Collection** with a few documents, create an **Agent** backed by it and chat with it in Chat. By the end you will have a published agent that answers from your files, and you will have seen where each step lives in Admin. ## Prerequisites [#prerequisites] * Access to a workspace with the **Owner**, **Curator** or **Editor** role. Auditor and User are read-only. * At least one model enabled in the workspace, under **Settings › Models**. Without a model, the agent form won't let you save. * Two or three test files with real content. PDF, DOCX or TXT will do. Short texts work best for checking the answer. ### Create the collection [#create-the-collection] In the **Workspace** area, open **Collections** and click **+ Collection**. Fill in the **Name** and, optionally, the **Description**. The description doesn't change search. It exists so someone else understands what's inside six months from now. Open **Add files** and select your documents. The counter next to the section shows how many files are ready to upload. Click **Create**. ### Wait for indexing to finish [#wait-for-indexing-to-finish] The collection opens on the **Files** tab, with one row per document and the state of each. Documents go through **Queued**, **Extracting** and **Indexing** until they reach **Extracted**. Only **Extracted** documents are used in answers. The time depends on the file's size and type; scanned PDFs take longer because they go through text extraction. ![The collection's Files tab with all three documents in the Extracted state](/img/tutorials/colecao/en/10-indexado.png) A document in **Extraction failed** or **Indexing failed** is not used in answers and doesn't recover on its own. Remove the file and upload it again, preferably in a format with selectable text. ### Create the agent [#create-the-agent] Open **Agents** in the same workspace, click **+ Agent** and choose **Create from scratch**. Under **Basic data**, fill in the **Name**, choose the **Model** and write a **Description**. The name and description are what people see when choosing the agent in Chat, so describe its job, not the technology. Under **User response prompt**, adjust the instructions. The field comes with a default text that works; for your first agent, add a sentence saying where it should take its answers from. The walkthrough below also covers the next two steps: attaching the collection and publishing. ### Attach the collection to the agent [#attach-the-collection-to-the-agent] Still in the form, open the **Collections** section and add the collection you created. This association is what turns on RAG. There is no separate "enable search" switch. With at least one collection, the **Search and context settings** appear right below. With none, the agent answers using only the model, the tools and the prompt. The **MCPs**, **Sandbox**, **Integrations**, **Sub-agents** and **Advanced options** sections can stay as they are for this first agent. ### Publish [#publish] In the form footer, check **Publish on save** and click **Save and publish**. Without that box, the button reads **Save draft** and the agent stays a draft: it shows up in the Admin **Agents** list, but not in Chat. Publishing is what makes it visible to the people in the workspace. ### Chat with it [#chat-with-it] Go to the **Chat** area and check, at the top of the screen, that the workspace is the same and that the selected agent is the one you just published. The agent selector sits next to the workspace name. Ask a question whose answer is in the documents you uploaded. Compare the answer with the source file: that is how you find out whether the right collection is attached and whether the prompt asks for the behavior you want. ## When the answer doesn't come from your documents [#when-the-answer-doesnt-come-from-your-documents] Three causes cover almost every case: * **No document is Extracted**: go back to the collection and check each file's state. * **The collection isn't attached to the agent**: open the agent and check the Collections section. * **The question doesn't match the text**: search is by content, not by title. Ask using the terms that appear inside the document. ## Next steps [#next-steps] * Follow the agent's usage under **Records › Conversations** and **Records › Response Ratings**, in the same workspace. * Get to know the rest of the sidebar, and what changes between Organization and Workspace, in [Navigating the platform](/en/docs/user-guide/get-started/navigation). * If an area showed up locked during the tutorial, the common cases are in [Access and login](/en/docs/user-guide/get-started/access). # Navigating the platform (/en/docs/user-guide/get-started/navigation) The platform has two bars on the left. The narrow one, against the edge, picks the **area**. The wide one, next to it, lists the pages of that area. Understanding this split answers most "where is that thing" questions. Almost everything you look for is in one of the two administrative areas, Organization or Workspace, and the difference between them is the scope of the setting. ## The areas [#the-areas] The narrow bar always shows the same destinations, in the same order, with the organization's logo at the top. Clicking the logo takes you back to the organization home. * **Organization**: what applies to the whole company: AI providers, credentials, members, quotas and the list of workspaces. * **Workspace**: what belongs to a team or project: Collections, Agents, Workflows, MCPs and that workspace's settings. * **Chat**: day-to-day conversation with Agents. * **Agents**: running published Workflows. You fill in an input form and get the result, instead of chatting. Organization and Workspace live in the Admin module; Chat and Agents, in the Chat module. You move between them through the same bar, without signing in again. ## Organization or Workspace: which one to use [#organization-or-workspace-which-one-to-use] The rule is scope. An Organization setting reaches every workspace; a Workspace setting stops at that workspace's boundaries. Some capabilities exist at both levels, and that is intentional: the Organization keeps the approved catalog and the Workspace picks what to use from it. AI providers, MCPs and Integrations work this way. ## The Organization sidebar [#the-organization-sidebar] The top pages handle the organization's catalog and operations: * **Providers**: AI model providers available to workspaces. * **SuperAgents**: external agents, registered by URL, that the organization makes available to workspaces. * **Workspaces**: creating and managing workspaces, including what each one receives. * **MCPs** and **Integrations**: the registry of MCP servers and integrations that workspaces can install. * **Credentials**: access secrets for external systems, stored once and reused. * **Observability**: consumption, usage per model and execution tracing. The **Settings** group closes the area with **General**, **Members** and **Quotas**. ## The Workspace sidebar [#the-workspace-sidebar] At its top is the workspace selector: that is how you switch projects without leaving the page you're on. The following pages are the ones you use to build: * **Dashboard**: the workspace's usage summary. * **Collections**: the documents and connectors that feed the Agents' answers. * **MCPs** and **Integrations**: the tools installed in this workspace. * **Agents** and **SuperAgents**: the agents that show up in Chat. * **Workflows**: automated flows built on a canvas. * **Variables**: named values reused by Agents and Workflows. * **Marketplace**: the library of prompt, agent and workflow templates. Then come two groups. **Records** keeps what has already happened: **Conversations**, **Response Ratings** and **Observability**. **Settings** keeps the workspace's configuration: **General**, **Guardrails**, **Models**, **Quotas**, **Members** and **API Keys**. **Guardrails** holds the rules that block or anonymize sensitive data before it reaches the AI. ## The top bar [#the-top-bar] Two things sit at the top of the screen. On the left, a breadcrumb. On the right, the controls that don't belong to any area: the shortcut to this documentation, the **platform assistant** button and the button with the organization's name. The assistant opens a side chat panel that helps you build, analyze and manage workspaces without leaving the page. The button with the organization's name opens the organization selector and, along with it, your menu. **Appearance** switches the theme and **Language** switches the interface language. **Settings** shows your profile: name, email, organization and role. The menu footer links to the Privacy Policy and the Terms of Use. Administrative roles may see one more button in the bar, **Logs**, which opens execution traces. ## Why you see fewer items [#why-you-see-fewer-items] The sidebar shows only what your role allows. Two people in the same workspace can see different lists, and that is not a loading error. The organization roles are Superadmin, Admin, Auditor and User. The workspace roles are Owner, Curator, Editor, Auditor and User. Organization roles see the organization's workspaces even without being members of them. The sidebar is the door, not the lock: every service rechecks permissions on every call. A hidden item doesn't become accessible through the URL. ## Next steps [#next-steps] * Build your first end-to-end flow in [Your first agent](/en/docs/user-guide/get-started/first-agent). * If an area shows up locked, see the common cases in [Access and login](/en/docs/user-guide/get-started/access). # Connect a system to the agent (/en/docs/user-guide/guides/connect-system) Collections handle stable knowledge, such as policies, manuals and catalogs. They don't handle what changes by the minute: an order's status, a stock balance, the ticket opened yesterday. For that the Agent needs a **tool**: something it calls at the moment of the question. This guide decides which path to take and sets up the connection. ## Collection or tool [#collection-or-tool] The question is whether the data has a shelf life. * **Collection**: the content is valid for weeks or months. Indexing is cheaper and faster at answer time. * **Tool**: the data has to be current. Each question triggers a real query to the system. The same Agent can have both: the returns policy in the Collection, the order status through the tool. ## Integration or MCP [#integration-or-mcp] Once you've chosen the tool path, there are two ways: * **Integration**, when the service is in the catalog the platform already knows. Less configuration, maintained by the platform. * **MCP**, when the system is internal or specific to your business, or when you need to control exactly which tools are exposed. ## The path, end to end [#the-path-end-to-end] Both follow the same three-screen sequence, handled by different roles: 1. **In the organization**, someone with the Superadmin or Admin role registers the MCP server or the integration in the catalog, with the access credential. 2. **In workspace management**, the item is associated with the workspace that will use it. 3. **In the workspace**, it is installed, with its own name and configuration. Step 2 is the one that trips up the most people. A registered server and a workspace with nothing under "Available" almost always means the association wasn't made. ## Hand it to the agent [#hand-it-to-the-agent] Installing in the workspace still doesn't hand anything over. In the Agent form, check the item in the **MCPs** or **Integrations** section. In the MCPs section, also adjust the **maximum iterations**: how many times the Agent can call tools in one answer. The default suits most cases; raise it only if the Agent is wrapping up before finishing the job. ## Write the prompt with the tool in mind [#write-the-prompt-with-the-tool-in-mind] Standing instructions need to say **when** to use the tool. Without that, the model tends to answer from memory instead of querying. ```text For any question about the status, deadline or amount of an order, query the system before answering. Never estimate this data. ``` ## When the tool isn't called [#when-the-tool-isnt-called] In order of frequency: * **It isn't checked in the Agent form.** Installing in the workspace isn't handing it over. * **The prompt doesn't tell it to use the tool**, and the model answered without querying. * **The iteration limit was reached** before the calls were completed. * **The server is down.** The failure shows up in the traces, under Observability. Traces are how you tell the first two cases from the last two: they show whether the call actually happened. ## Security [#security] An MCP gives the Agent the ability to **act** on real systems, not just read them. Before releasing a server to teams, check the result of the automatic analysis in [Security scanner](/en/docs/user-guide/tools/mcp/security). ## Next steps [#next-steps] * Register the server in [MCPs](/en/docs/user-guide/tools/mcp). * Or use a ready-made connection in [Integrations](/en/docs/user-guide/tools/integrations). # Extract data from documents in bulk (/en/docs/user-guide/guides/document-extraction) When the task is always the same, such as reading contracts and extracting parties, amounts and deadlines, a Workflow delivers more than an Agent. The path is fixed, the result is structured and every run is recorded. This guide builds the bulk extraction flow, from upload to result. ## Prerequisites [#prerequisites] * The **Owner**, **Curator** or **Editor** role in the workspace. * An enabled model, preferably a cheap one, since the task is repetitive. * A few sample files that represent the real variation in the documents. ## The flow design [#the-flow-design] ### Input: receive the list of files [#input-receive-the-list-of-files] In the **Input** node, declare a variable that receives the files. It becomes the form field the person running the workflow fills in. Give it a readable name: the person running it reads that label on screen. ### File extractor: convert to text [#file-extractor-convert-to-text] Connect a **File extractor** node to the Input. It turns the binaries into text and returns a list, accessible as `{{ extrator_arquivos.contents }}`. Without this node, the files don't reach the model in a usable form. ### Iteration: repeat per document [#iteration-repeat-per-document] Add an **Iteration** node and point its input at the list of extracted texts. Inside the loop, the **Iteration start** node provides `item`, the text of one document, and `index`. ### LLM: extract the fields [#llm-extract-the-fields] Inside the Iteration, connect an **LLM** node to the Iteration start. In the prompt, ask for the fields and **require the format**. ```text Extract the fields below from the contract and answer only with valid JSON, with no text before or after. Fields: parties, total_amount, start_date, end_date, termination_notice. Use null when the field isn't in the document. Contract: {{ inicio_da_iteracao.item }} ``` The format instruction isn't optional. Without it, the model returns free text and nothing downstream can handle the output reliably. ### Iteration output: collect the results [#iteration-output-collect-the-results] Under **Output variables** of the Iteration node, declare the name of the list that leaves the loop, for example `extracted_contracts`, and point the source variable at the inner LLM node's answer. ### Output: return the result [#output-return-the-result] Connect the list to the **Output** node. For a result another system will consume, declare separate fields; for human reading, a single field with the consolidated result is enough. If the person running it needs a file, add a **File generator** node before the Output. ## Before publishing [#before-publishing] Run it from the studio with two or three real documents, including an atypical one. The run log shows what each node received and returned, step by step. The most common failure point is the LLM node returning an inconsistent format on non-standard documents. You fix that in the prompt, not in the next node. ## The cost [#the-cost] An LLM node inside an Iteration runs **once per item**. A hundred documents are a hundred calls. Before releasing it to the team, estimate the cost of a typical batch in **Observability** and, if it matters, set a cap in **Quotas**. ## Publish [#publish] Publish the Workflow. It then shows up in the **Agents** area of the Chat module, where people run it without needing Admin access. ## Next steps [#next-steps] * Choose the right node for each step in [Node catalog](/en/docs/user-guide/workflows/nodes). * Investigate a run that went wrong in [Runs](/en/docs/user-guide/workflows/runs). # Put an agent in your team's hands (/en/docs/user-guide/guides/rollout) Publishing an Agent takes one click. Getting a team to use it involves three things the publishing screen doesn't mention: who can access it, how much it will cost and how you'll know whether it's working. This guide covers those three. ## Before publishing [#before-publishing] A short check prevents most first-day problems: * **The documents are Active.** Collections still indexing make the Agent answer as if it were empty. * **The model is still enabled** in the workspace. A removed model breaks the Agent without warning. * **A real question was tested**, and the cited reference supports the answer. ## Who will be able to use it [#who-will-be-able-to-use-it] Chatting in Chat only requires being a **workspace member**. No administrative role is needed, and **User** is enough. Adding someone takes two steps, on different screens: 1. The person must belong to the **organization**. If they don't yet, someone with the Admin role invites them. 2. The person must be added to the **workspace**, by its Owner. A common first-day symptom: someone signs in and sees no Agent at all. It is almost always step 2 missing, or the Agent left as a draft. ## Estimate and cap the cost [#estimate-and-cap-the-cost] Before opening it to many people, it is worth having a sense of the order of magnitude. Let the Agent run with a small group for a few days and watch the per-model consumption in **Observability**, and the per-Agent usage in the **Dashboard**. From there: * Set a **Workspace** cap with headroom over the observed peak, not over the average. * Consider a per-**User** cap, which is what protects against a single case eating the whole month. Starting too tight causes blocks on the first day of heavy use, and the fix ends up becoming a permanently high policy. ## Communicate what it does [#communicate-what-it-does] The Agent's **name** and **description** are the only instructions most people will read. They show up in the Chat selector. Describe the job and the limit: "HR policy questions: vacation, expenses and benefits" says more than "HR Assistant", and reduces out-of-scope questions. ## The first weeks [#the-first-weeks] Three screens, in order of usefulness: * **Logs › Response feedback**: where problems show up first. Low volume is normal; people rarely rate answers, and almost always when something went wrong. * **Logs › Conversations**: what people actually ask. It usually yields the second version of the prompt and a list of missing documents. * **Dashboard**: whether usage holds up once the novelty wears off. ## Changing an agent in use [#changing-an-agent-in-use] There is no draft of an already published Agent. Saving a change puts it into production on everyone's next conversation. For large changes, duplicate the Agent, adjust the copy as a draft and only then swap it in. ## Next steps [#next-steps] * Adjust the instructions based on what you read in [Write the prompt](/en/docs/user-guide/agents/prompt). * Set the caps in [Set limits](/en/docs/user-guide/models/quotas/limits). # Support agent on your own knowledge base (/en/docs/user-guide/guides/support-agent) This is the platform's most common use case: an Agent that answers recurring questions about the expense policy, the vacation process or the product catalog, from the documents the company already has. This guide goes beyond [your first agent](/en/docs/user-guide/get-started/first-agent): it covers what separates an agent that demos well from one that holds up under real use. ## Prerequisites [#prerequisites] * The **Owner**, **Curator** or **Editor** role in the workspace. * At least one model enabled under **Settings › Models**. * The documents that back the answers, in a format with selectable text. ## Scope the collections [#scope-the-collections] ### Split by subject, not by origin [#split-by-subject-not-by-origin] One Collection per topic, such as "HR Policies" or "Product Catalog", works better than a single Collection with everything. Splitting by subject makes search more precise and lets you take one set out of circulation without affecting the rest. ### Discard what is outdated [#discard-what-is-outdated] Contradictory documents are the most common way for an Agent to give wrong answers that look right. Two versions of the same policy, both indexed, and the Agent cites the old one. Before uploading, confirm which version of each document is current. ### Wait for indexing [#wait-for-indexing] Check under **Collections › Files** that every document has reached the **Active** state. Documents still processing don't take part in answers, and the Agent screen gives no warning about it. ## Write the prompt [#write-the-prompt] The form's default text covers tone and format. For a support agent, add three things: * **The role and the audience**: who it serves and what it answers about. * **The order of priority**: answer from the retrieved documents, not from the model's general knowledge. * **The behavior when there's a gap**: say it didn't find the answer, and point to whom to ask. The third one saves the most rework. Without it, the model fills the gap with what it learned in training, and the answer comes out plausible, with no references, and wrong. ## Test before publishing [#test-before-publishing] Test with real questions, not the ones you would write. Three categories that reveal problems: * **Ambiguous questions**, which could refer to two documents. * **Out-of-scope questions**, to check that it declines instead of making things up. * **Questions whose answer changed** recently, to check that the right version is indexed. For each answer, open the **References** block and check that the cited passage supports what was said. ## Publish and monitor [#publish-and-monitor] Check **Publish on save**. The Agent then shows up in the Chat selector for the workspace. In the first weeks, two screens tell you whether it is working: * **Logs › Conversations** shows what people actually ask, which is rarely what you imagined. * **Logs › Response feedback** gathers the cases that went wrong. Reading these two usually yields the second version of the prompt and a list of missing documents. ## Next steps [#next-steps] * Adjust the instruction text in [Write the prompt](/en/docs/user-guide/agents/prompt). * Cap the agent's cost in [Quotas](/en/docs/user-guide/models/quotas). # User Guide (/en/docs/user-guide) AUMO is an enterprise AI platform: you connect your company's documents and systems, create agents that answer from them, and put those agents in people's hands through Chat. Admin and Chat share the same login and the same navigation bar. What changes is the area you are in. **Organization** covers what applies to the whole company. **Workspace** covers what belongs to a team or project. **Chat** and **Agents** are for day-to-day use. ## Start here [#start-here] Sign in to the platform and pick the right organization and workspace. Understand the areas, the sidebar, and why you see fewer items than someone else. Create a collection, publish an agent and chat with it in about 15 minutes. # Knowledge domains (/en/docs/user-guide/knowledge/allowed-domains) The **Knowledge Sources** tab controls which external domains Collection connectors can access, service by service. A domain that isn't on the list is refused when the connector is configured, in the workspace. ## The services covered [#the-services-covered] * **Atlassian**: allowed domains for Confluence and Jira. * **SharePoint**: allowed domains. * **OneDrive**: allowed domains. Each has its own list. Allowing a domain for Atlassian doesn't allow it for SharePoint. ## Why the list exists [#why-the-list-exists] Without it, anyone with permission to create Collections in the workspace could index an arbitrary site using the organization's infrastructure and credentials. The list flips the default: nothing is reachable until someone with the **Superadmin** role explicitly authorizes that domain. ## Add a domain [#add-a-domain] Open the configuration for the corresponding service and add the domain to the allowlist. Check the exact domain the service uses. An Atlassian instance at `company.atlassian.net` isn't reached by an `atlassian.net` entry, and the error only shows up when someone tries to configure the connector. When a connector fails to be created with a domain error, the cause is here, not in the workspace permissions or the service credential. ## Next steps [#next-steps] * Understand what connectors feed in [Collections and knowledge](/en/docs/user-guide/concepts/knowledge). * See the other tabs in [Settings](/en/docs/user-guide/admin/org-settings). # Confluence (/en/docs/user-guide/knowledge/connectors/confluence) The **Confluence** connector brings pages from your Atlassian instance's spaces into the Collection. It is one of the highest-return connectors, because Confluence usually holds exactly the kind of content a support Agent needs: policies, procedures and recorded decisions. ## Prerequisites [#prerequisites] 1. The Confluence OAuth credentials registered in the organization, under **Credentials**. 2. The instance's domain allowed under **Settings › Knowledge Sources**. ## Configure [#configure] The form asks for the Atlassian instance and the spaces to sync. The platform reads the list of available sites from the authorized credential. When the credential gives access to more than one instance, the selection has to point explicitly at one of them. Draft pages and personal spaces are included in the sync if they fall within the selected scope. Since Confluence tends to pile up old versions in archive spaces, check the scope before turning on the schedule. ## Outdated content [#outdated-content] The typical Confluence risk is having two pages on the same subject, one current and one old, both indexed. The Agent finds both and may cite the wrong one. Restricting the sync to maintained spaces, and excluding archive ones, solves more than tweaking the Agent's prompt afterwards. ## Next steps [#next-steps] * Configure the sibling connector in [Jira](/en/docs/user-guide/knowledge/connectors/jira). * See the other connectors in [Overview](/en/docs/user-guide/knowledge/connectors). # Google Drive (/en/docs/user-guide/knowledge/connectors/google-drive) The **Google Drive** connector brings documents from Drive folders into the Collection, with periodic syncing. The platform has two variants: connecting through the account of whoever configures it, and connecting through a service account, which accesses on behalf of the organization. ## Choose the variant [#choose-the-variant] * **Personal account**: the connector sees what that account sees. Simple to set up, but access dies if the person leaves the company. * **Service account**: access belongs to the organization and survives team changes. It requires configuration on the Google Workspace side. For content a whole team depends on, the second keeps the connector from breaking without warning months later. ## Configure [#configure] The flow asks for authorization on Google and, after that, for the selection of folders or files to sync. The platform also offers the Google picker, which requires the `VITE_GOOGLE_CLIENT_ID`, `VITE_GOOGLE_PICKER_API_KEY` and `VITE_GOOGLE_APP_ID` keys configured in the environment. Without them, selection goes through the alternative path. A permission revoked on Google brings the sync down without changing what was already indexed. The old documents keep answering, now outdated, and the failure only shows up on the connector. ## Formats [#formats] Native Google documents (Docs, Sheets, Slides) and regular files stored in Drive go through the same extraction path as files uploaded by hand. Scanned files with no text layer depend on recognition-based extraction and may fail. ## Next steps [#next-steps] * Follow the processing in [Indexing](/en/docs/user-guide/knowledge/indexing). * See the other connectors in [Overview](/en/docs/user-guide/knowledge/connectors). # Overview (/en/docs/user-guide/knowledge/connectors) A **connector** links a Collection to an external source and brings its content in periodically. Where an uploaded file stays as it is until someone replaces it, a connector goes back and fetches again. They live on the Collection's **Connectors** tab, next to Files. ## When to use one [#when-to-use-one] Connectors pay off when the source changes often and someone would otherwise have to re-upload files by hand: a knowledge base in Confluence, a document repository, a public website used as a reference. For a stable set of documents that changes once a year, manual upload is simpler and doesn't depend on a credential or an allowed domain. ## Add a connector [#add-a-connector] In the Collection, click **+ Source** and choose **Create connector**. The other option, **Upload Files**, uploads one-off files. Choose the type and click **Next**. The form changes with the type. The **Indexer** asks for a **Name**, a **URL** and the **Extraction type**; when following internal links, it also asks whether to **Use links from external sites** and the **Extraction depth**. A repository connector asks for the space and the access credential. Under **Task type** you set when the sync runs: **Run immediately**, **Run routinely** or **Run on the selected date**. External domains need to be allowed in the organization. An Atlassian, SharePoint or OneDrive connector pointing to a domain that isn't on the list is refused at creation. The list lives under **Organization › Settings › Knowledge Sources**. ## Syncs [#syncs] Each run of a connector is a **sync**, with its own state. Queued, running or failed syncs show up as pending items on the connector. A failed sync doesn't invalidate what was already indexed: content brought in earlier keeps answering. What stops is the update. ## When a sync fails [#when-a-sync-fails] The most common causes are outside the platform: * **Expired credential** at the source. * **Revoked permission** for the account the connector uses. * **Domain not allowed** in the organization settings. The error shows up on the connector, not on the documents. A document indexed by an earlier sync stays **Extracted** even if the next sync failed. ## Next steps [#next-steps] * Check the state of the documents brought in under [Indexing](/en/docs/user-guide/knowledge/indexing). * See who allows domains in [Knowledge domains](/en/docs/user-guide/knowledge/allowed-domains). ## Available connectors [#available-connectors] Crawl public pages. The only one that needs no credential. Drive folders and files, through a personal or service account. Microsoft 365 document libraries. Personal and shared Microsoft 365 folders. Spaces and pages from the Atlassian instance. Issues and projects, for questions about history. # Website indexer (/en/docs/user-guide/knowledge/connectors/indexer) The **Indexer** crawls public URLs and brings the pages' text into the Collection. It is the connector that doesn't depend on a credential: if the page opens in the browser without logging in, it can reach it. Internally the platform identifies it as `web_scraper`. ## When to use it [#when-to-use-it] It is meant for content that is already published and is the source of truth: public documentation, a help center, product pages, policies on a corporate website. It isn't meant for content behind a login, or for pages that build their text with JavaScript after loading. ## Configure [#configure] The form asks for the list of URLs to crawl and the type of extraction applied to the content found. When you leave the connector's description empty, it gets the default value `Indexador`. Replace it with something that says which site it is, because the connector list shows that text. ## Scheduling [#scheduling] Like the other connectors, it accepts a schedule. The frequency sets how often the URLs are crawled again. Pages that rarely change don't justify a daily sync: each run reprocesses the content and uses indexing time. The Indexer doesn't get past paywalls or sessions. A URL that requires login returns the login page, and that text is what ends up indexed in the Collection. ## Next steps [#next-steps] * Check the state of the documents brought in under [Indexing](/en/docs/user-guide/knowledge/indexing). * See the other connectors in [Overview](/en/docs/user-guide/knowledge/connectors). # Jira (/en/docs/user-guide/knowledge/connectors/jira) The **Jira** connector brings issue content into the Collection: title, description and whatever is recorded in the text fields. It shares Atlassian authentication with the Confluence connector, and the configuration can reuse the credential already registered. ## Prerequisites [#prerequisites] 1. The Jira OAuth credentials registered in the organization, under **Credentials**. 2. The instance's domain allowed under **Settings › Knowledge Sources**. When the organization already uses Confluence, the form lets you point to the Confluence credential instead of requiring a new authorization. ## Configure [#configure] The form asks for the instance and the set of projects to sync. ## When Jira helps, and when it gets in the way [#when-jira-helps-and-when-it-gets-in-the-way] Issues are a good archive for questions about history: why a decision was made, whether a problem has come up before, what fix was applied. Issues also carry ongoing discussion, discarded hypotheses and individual opinion. Indexing an entire project makes the Agent treat all of that as fact, and it starts answering with things nobody decided. Scoping to resolved projects, or by issue type, usually works better than the full backlog. ## Next steps [#next-steps] * Configure the sibling connector in [Confluence](/en/docs/user-guide/knowledge/connectors/confluence). * See the other connectors in [Overview](/en/docs/user-guide/knowledge/connectors). # OneDrive (/en/docs/user-guide/knowledge/connectors/onedrive) The **OneDrive** connector brings files from personal or shared Microsoft 365 folders into the Collection. It shares its authentication base with the SharePoint connector, but points to individual storage instead of site libraries. ## Prerequisites [#prerequisites] As with SharePoint, two things need to exist first: 1. The OneDrive OAuth credentials registered in the organization, under **Credentials**. 2. The domain allowed under **Settings › Knowledge Sources**. ## Configure [#configure] After authorizing, select the folders to sync. The connector sees what the authorized account sees, including what was shared with it. ## OneDrive or SharePoint [#onedrive-or-sharepoint] The choice follows where the content actually lives: * **OneDrive** for material that belongs to one person or a small group. * **SharePoint** for a team's official documentation, in a site library. Content in a personal OneDrive usually leaves the company along with the person. For knowledge the team depends on, moving it to a SharePoint library before indexing avoids losing the source later. ## Next steps [#next-steps] * Compare with the alternative in [SharePoint](/en/docs/user-guide/knowledge/connectors/sharepoint). * See the other connectors in [Overview](/en/docs/user-guide/knowledge/connectors). # SharePoint (/en/docs/user-guide/knowledge/connectors/sharepoint) The **SharePoint** connector brings documents from your organization's Microsoft 365 libraries into the Collection. It is the path for companies whose internal documentation lives in SharePoint rather than in loose files. ## Prerequisites [#prerequisites] Two things need to be ready first, and neither is configured on this screen: 1. The SharePoint OAuth credentials registered in the organization, under **Credentials**. 2. Your instance's domain allowed under **Settings › Knowledge Sources**. The domain has to match exactly. An instance at `company.sharepoint.com` isn't reached by a `sharepoint.com` entry, and the error only shows up when you try to create the connector. ## Configure [#configure] After authorizing, you select the site and the document libraries to sync. The connector's permission is that of the authorized account. Libraries restricted to other groups don't show up in the selection, and that isn't a platform failure. ## Permissions and what becomes visible [#permissions-and-what-becomes-visible] The connector doesn't reproduce SharePoint permissions inside the Collection. Everything it indexes becomes available to any Agent attached to that Collection, and therefore to anyone in the workspace who chats with it. If part of the content is restricted, the scoping has to happen when selecting the libraries, not afterwards. ## Next steps [#next-steps] * Allow the domain in [Knowledge domains](/en/docs/user-guide/knowledge/allowed-domains). * See the other connectors in [Overview](/en/docs/user-guide/knowledge/connectors). # Create a collection (/en/docs/user-guide/knowledge/create) The **New Collection** form is short on purpose: name, description and the initial sources. Everything else is adjusted later, on the created Collection. You need the **Owner**, **Curator** or **Editor** role. ## Step by step [#step-by-step] ### Open the form [#open-the-form] Under **Workspace › Collections**, click **+ Collection**. ### Name the collection [#name-the-collection] The **Name** is required. It is what shows up in the list and when attaching the Collection to an Agent, so describe the subject, not where the files came from. The **Description** is optional and doesn't affect search. It exists so someone else understands what's inside six months from now. ### Add files [#add-files] Open **Add files** and select the documents. The counter next to the section shows how many are ready to upload. This step is optional. A Collection can start empty and receive files later. ### Add connectors [#add-connectors] Open **Add connectors** if you want the Collection to fetch content from an external source, instead of relying on manual uploads. ### Create [#create] Click **Create**. The Collection opens on the **Files** tab, with document processing under way. Creating the Collection doesn't make it usable right away. Documents go through extraction and indexing, and only answer once they reach the **Extracted** state. ## Choosing the scope [#choosing-the-scope] The question that decides how many Collections to create is who will look up what. One Collection per subject, with different Agents looking up the ones relevant to each, usually works better than a single Collection with everything inside. Search gets more precise and it becomes easier to take one set out of circulation without affecting the rest. ## Next steps [#next-steps] * Follow the processing in [Indexing](/en/docs/user-guide/knowledge/indexing). * Attach the Collection to whoever answers in [Create an agent](/en/docs/user-guide/agents/create). # Files (/en/docs/user-guide/knowledge/files) The **Files** tab lists the documents uploaded manually to a Collection, with the state of each one. It is the tab that opens by default when you enter a Collection, and where most "the agent doesn't know this" problems get solved. ## Upload documents [#upload-documents] Use **Upload files** on an empty collection, or **+ Source** in the top bar when there is already content. Formats with selectable text, such as native PDF, DOCX and TXT, are the most predictable. Scanned PDFs work, but depend on text extraction and take longer. ## Read the list [#read-the-list] Each row shows the document, its origin and its state. Search filters by name, and the filter icon narrows by state. The origin column tells manual uploads apart from what came through a connector: manual documents show as **Upload**, the rest show the source's URL or identifier. ## Replace a document [#replace-a-document] There is no content editing. To update a document, remove the old version and upload the new one. Uploading only the new one, without removing the old one, leaves both indexed. The Agent then finds passages from both versions and may answer with the outdated one. This is the most common way for an Agent to give contradictory answers: two versions of the same document live in the same Collection. ## Remove [#remove] Removing a document takes it out of future answers. Earlier conversations that cited it stay in the history as they are. Removal isn't immediate in every case. The document leaves the search index, which may take a few moments in large collections. ## When a file doesn't show up [#when-a-file-doesnt-show-up] * **It is still processing**: check its state in the list itself. * **It failed**: the error states are described in [Indexing](/en/docs/user-guide/knowledge/indexing). * **It came from a connector**: synced documents live on the **Connectors** tab, not here. ## Next steps [#next-steps] * Understand the processing states in [Indexing](/en/docs/user-guide/knowledge/indexing). * Automate content intake in [Connectors](/en/docs/user-guide/knowledge/connectors). # Overview (/en/docs/user-guide/knowledge) A **Collection** brings together the documents an Agent looks up before answering. It is what makes the platform answer with your company's content, not just with what the model learned in training. Collections belong to this workspace and aren't visible to any other. ## The list [#the-list] The screen shows Collections as a grid or a table, with search by name. The table view shows the number of **Documents**, the **Description** and the creation date. Creating and editing Collections requires the **Owner**, **Curator** or **Editor** role. An Auditor sees the list without changing it. ## How a Collection is used [#how-a-collection-is-used] A Collection on its own does nothing. It takes effect when someone attaches it to an Agent, in the **Collections** section of that Agent's form. An Agent can look up several Collections; a Collection can serve several Agents. Nothing is exclusive. The form, the initial files and the connectors. Upload, replace and remove a collection's documents. Sync external sources instead of uploading files by hand. A document's states and what to do when one fails. # Indexing (/en/docs/user-guide/knowledge/indexing) Between uploading a document and seeing it in an answer there is processing in stages. Each document carries the state of the stage it is in. Only **Active** documents take part in answers. Every other state is intermediate or an error. ## The states [#the-states] | State | What is happening | | ------------------- | ---------------------------------------------------------------- | | `Queued` | The file has arrived and is waiting to be processed. | | `Extracting` | The content is being turned into text. | | `Indexing` | The text is being split into passages and prepared for search. | | `Active` | The document is available for answers. | | `Extraction failed` | No text could be obtained from the file. | | `Indexing failed` | The text was obtained, but didn't make it into the search index. | The total time depends on the file's size and type. Scanned PDFs take longer because extraction has to recognize the text in the image. Neither error state recovers on its own. A document stuck in one stays invisible to Agents indefinitely, with no warning on the Agent screen. ## When extraction fails [#when-extraction-fails] **Extraction failed** almost always means the file has no recoverable text: * A PDF that is only the image of a scanned page, with no text layer. * A corrupted or password-protected file. * A format the platform doesn't process. The fix is to convert the file to a format with selectable text and upload it again. Re-uploading the same file produces the same failure. ## When indexing fails [#when-indexing-fails] **Indexing failed** is rarer and doesn't depend on the format: the text was obtained, but didn't make it into the index. Remove the document and upload it again. If the failure repeats with the same file, the content has some quirk worth reporting to support, with the document at hand. ## The effect of a stuck document [#the-effect-of-a-stuck-document] An Agent attached to a Collection whose documents are still processing answers as if the Collection were empty. There is no warning, in Admin or in Chat. So when you publish an Agent right after creating the Collection, come back to this tab and confirm that the documents reached **Active** before telling people. ## Next steps [#next-steps] * Manage the documents in [Files](/en/docs/user-guide/knowledge/files). * Understand how indexed passages become an answer in [Collections and knowledge](/en/docs/user-guide/concepts/knowledge). # The AUMO provider (/en/docs/user-guide/models/providers/aumo) The **AUMO** provider is the only one that doesn't depend on you bringing an account. Instead of registering an external service's credential, the organization requests access and AUMO provides it. For platform users, the result is identical: it shows up in the Providers list like any other, and its models are assigned to workspaces the same way. ## How access is granted [#how-access-is-granted] The flow has two ends and isn't completed on your side alone: 1. Your organization requests the AUMO provider. 2. The request stays **pending** until someone on the AUMO side approves it. 3. On approval, the quotas and the enabled models are defined. 4. The organization syncs the provider, and the approved models start showing up. While the request is pending, the provider doesn't serve calls. There is nothing to adjust on your end in the meantime. ## Negotiated quotas [#negotiated-quotas] Unlike your own account, where the ceiling is your contract with the vendor, the AUMO provider comes with limits defined at approval time. These limits are independent of the **Quotas** you configure on the platform. Your quotas split consumption among workspaces and people; the negotiated limit is the external ceiling, above all of that. A quota refusal can therefore come from two sources: your own cap on the platform or the limit agreed with AUMO. ## Enabled models [#enabled-models] The list of models the AUMO provider offers is defined at approval, not by you. If an expected model doesn't show up when assigning to a workspace, the way forward is to talk to AUMO, not to look for a setting on the platform. Some internal features require specific AUMO models. The platform's **Chat Agent**, for example, only accepts AUMO models with vision capability. ## Next steps [#next-steps] * Register your own accounts with other services in [Register a provider](/en/docs/user-guide/models/providers/register). * Split consumption among teams in [Quotas](/en/docs/user-guide/models/quotas). # Overview (/en/docs/user-guide/models/providers) A **Provider** is an account with an AI model service: AUMO, OpenAI, Bedrock and the like. Without at least one registered provider, no workspace enables models and no Agent answers. The screen requires the **Superadmin** role. Admin and Auditor can't reach it, because it is where the AI credentials are stored. ## The list [#the-list] Each row shows the provider, the service's icon and the creation date. Each row's action menu lets you edit and remove. A registered provider isn't available to anyone yet: each workspace enables its models, under **Settings › Models**. ## Where to go next [#where-to-go-next] Connect your own OpenAI, Bedrock or equivalent account. The case where access comes from the platform, with negotiated approval and quotas. The four fields that define a model's behavior and cost. # Model metadata (/en/docs/user-guide/models/providers/metadata) When you register a model the platform doesn't know in advance, you provide four values. Two govern what fits in a call; two govern how much it costs. Catalog models come with these values already filled in. You only enter them manually when adding your own model or a new variant. ## The fields [#the-fields] | Field | Unit | What it determines | | ------------------- | ------------- | --------------------------------------------------------------------------------- | | `Max Input Tokens` | tokens | The size of the context window, adding up prompt, history and retrieved passages. | | `Max Output Tokens` | tokens | The ceiling for a single answer. | | `Input cost` | USD per token | The price of each token sent to the model. | | `Output cost` | USD per token | The price of each token returned by the model. | The two cost fields are entered per token, not per thousand. A model that charges US$ 0.15 per million input tokens has an `Input cost` of `0.00000015`. ## The effect of each one [#the-effect-of-each-one] **Max Input Tokens** is the practical limit on how much knowledge fits in an answer. An Agent with many attached Collections and long conversations hits it before anything else. **Max Output Tokens** cuts the answer off when it grows too long. Answers cut off mid-sentence are usually this field, not the model. The two cost fields don't change any behavior. They feed the consumption calculation and quota enforcement. A wrong price here produces wrong reports and quotas across the whole organization, with no warning. Consumption keeps being counted; only the amount is wrong. Too low delays the block; too high blocks too early. ## Where these values show up later [#where-these-values-show-up-later] * **Observability** uses the costs to convert tokens into money. * **Quotas** uses the same costs to decide when to block a scope. * The Agent form uses `Max Output Tokens` as the ceiling for the field of the same name, under Advanced options. ## Next steps [#next-steps] * See the consumption calculated from these values in [Observability](/en/docs/user-guide/monitoring/observability). * Understand how to choose between models in [Providers and models](/en/docs/user-guide/concepts/models). # Register a provider (/en/docs/user-guide/models/providers/register) Registering a provider is what gives the platform the right to call that AI service. It is the first link in the chain that ends with an Agent answering in Chat. You need the **Superadmin** role and the service's access credential at hand. ## Step by step [#step-by-step] ### Open the form [#open-the-form] Under **Organization › Providers**, click **+ Provider**. ### Choose the service [#choose-the-service] Select the provider from the list of supported services. The choice determines which credential fields the form asks for next. ### Enter the credential [#enter-the-credential] The fields depend on the service. For most of them, like Anthropic, the **API Key** is all it takes, and the provider shows up in the list under the service's name. **Custom Provider** is the exception: besides the **API Key**, it asks for the **Provider name**, **Base URL** and **Supported APIs**. The credential is the access secret for the service. Once saved, the value isn't shown back. ### Create [#create] Optionally, open **Available models** to check the models that come with the provider, with each one's context window, cost and capabilities. Click **Create**. The provider goes into the organization's catalog and you go back to the Providers list. ## After registering [#after-registering] The provider doesn't reach anyone yet. Two steps remain, on different screens: 1. Under **Organization › Workspaces**, open each workspace and use **Manage models** to assign that provider's models. 2. Under **Workspace › Settings › Models**, confirm that the models show up for whoever creates Agents. Forgetting step 1 is the most common mistake. The workspace is left without a model, the Agent creation form won't save, and the message on screen doesn't mention that the cause is in workspace management. ## Unknown models [#unknown-models] If the model you want to use isn't in the platform's catalog, you register it by manually entering the four fields that determine behavior and cost. They are described in [Model metadata](/en/docs/user-guide/models/providers/metadata). ## Next steps [#next-steps] * Distribute the models to teams in [Workspaces](/en/docs/user-guide/admin/workspaces). * Cap how much each provider can consume in [Quotas](/en/docs/user-guide/models/quotas). # Temporary grants (/en/docs/user-guide/models/quotas/grants) A **temporary grant** adds headroom to a scope for a period, with a recorded reason, and expires on its own. It exists for the case where someone went over quota and needs to keep going today. Raising the policy would also work, but the policy has no end date and rarely comes back down. ## How it works [#how-it-works] * The granted amount **adds** to the current cap, rather than replacing it. * The grant applies until the expiration date you set. * There is no rollback routine: the platform simply stops counting expired grants. * When it expires, the scope goes back to the policy cap and blocks again if the month's consumption has already passed it. ## Create a grant [#create-a-grant] In the scope's **Temporary grants** section, click **+ New grant**. In the **New temporary grant** window, enter **Extra tokens**, **Extra cost (USD)** or both, the period under **Expires at**, with shortcuts for **24 hours**, **7 days** and **End of month**, and the **Reason**. Click **Grant**. The reason isn't red tape: since the grant disappears on its own, it is the only record of why that scope went over its cap that month. A grant takes up to about 30 seconds to take effect, because consumption is read from a cache. Whoever is blocked needs to try again after that interval, not right away. ## Revoke before it expires [#revoke-before-it-expires] The grant's action menu lets you revoke it. The extra headroom stops applying within the same interval of about 30 seconds. If the month's consumption has already passed the policy limit, the scope blocks again right after the revocation. ## When to use each [#when-to-use-each] * **Temporary grant**: a one-off spike, an end-of-quarter demand, a test that went over. Normal comes back on its own. * **Change the policy**: consumption has moved to a new level for good, and the old cap no longer reflects real usage. Repeated grants on the same scope, month after month, are the sign that the policy itself is wrong. ## Next steps [#next-steps] * Adjust the policy in [Set limits](/en/docs/user-guide/models/quotas/limits). * Confirm the consumption that prompted the grant in [Observability](/en/docs/user-guide/monitoring/observability). # Overview (/en/docs/user-guide/models/quotas) **Quotas** sets the monthly caps on AI model consumption. With no cap configured, a scope consumes without limit. The same screen exists in two places, **Organization › Quotas** and **Workspace › Quotas**, with different scopes and identical behavior. ## The scopes [#the-scopes] The two tabs at the top switch between **Organization** and **Workspace**. Within each there are breakdowns: * **General**: that scope's total cap. * **Providers**: one cap per provider, for when one of them is more expensive than the others. * **Users**: how much each person can consume. * **Project keys**: only in the workspace scope, for programmatic integrations. The Project keys tab exists because an integration consumes differently from a person: nonstop, and often with no one watching. The Organization quota takes **precedence** over the Workspace quota. Once the company's cap is used up, no workspace continues, however much headroom it has under its own limit. ## Who changes them [#who-changes-them] In the organization, the screen opens for **Superadmin**, **Admin** and, read-only, **Auditor**. In the workspace, for **Owner**, **Curator** and **Auditor**, but only the Owner saves changes. ## Exceptions per person and per key [#exceptions-per-person-and-per-key] On the Users and Project keys tabs you can create **exceptions** for individual cases, on top of the default cap. An exception overrides that scope's default cap for that person or key. Unlike a temporary grant, it doesn't expire on its own. The action menu lets you edit it, grant temporary headroom or remove it. ## What happens when a cap is exceeded [#what-happens-when-a-cap-is-exceeded] The call is refused and whoever is in Chat gets a quota-exceeded warning. The platform doesn't switch models or degrade the answer. The block applies only to the scope that went over. A person who hit their own limit can no longer use the platform, while the rest of the workspace carries on. Caps apply to the current month. The turn of the month resets accumulated consumption and unblocks automatically. ## In this section [#in-this-section] Configure caps in tokens or cost and read the month's projection. Unblock a scope for a period, without touching the policy. # Set limits (/en/docs/user-guide/models/quotas/limits) A limit is set in **tokens**, in **cost** or both. When there are both, whichever is reached first blocks. You need the **Superadmin** or **Admin** role. An Auditor sees the numbers, but can't save. ## Configure [#configure] Under **Limits and monthly usage**, fill in **Tokens**, **Cost (USD)** or both, and click **Save limits**. The **Remove** button undoes the cap. The walkthrough below sets the cap for the whole organization, under **Organization › Quotas**: Two conventions that are easy to mix up: * **A blank field** means no limit. * **A limit of zero** blocks every request in that scope. Below the form, **Tokens used** and **Cost used** show the month's actual consumption. That number, not an estimate, is what the block uses. ## Read the month's projection [#read-the-months-projection] The **Month projection** chart extends recent daily consumption to the end of the current month, by linear regression. The panel beside it shows four numbers: | Indicator | What it answers | | --------------------- | --------------------------------------------------- | | `Consumed this month` | How much has been spent so far. | | `Forecast at close` | Where the month ends, at the current pace. | | `Limit overrun` | When the cap would be reached, if it is reached. | | `Projected pace` | Average consumption per day over the recent window. | It is the most useful signal mid-month: it tells you whether the current pace will exceed the cap before the month turns, while there is still time to act. The projection is a straight line over recent consumption. It knows nothing about seasonality, or about the Agent you published yesterday. Treat it as a warning, not a forecast. ## Choose a starting value [#choose-a-starting-value] A predictable path, when there is no history: 1. Leave the scope without a limit for one cycle and follow actual consumption in **Observability**. 2. Set the cap with headroom over the observed peak, not over the average. 3. Adjust at the turn of the following month, now with two points of comparison. Starting too tight causes blocks on the first day of heavy use, and the fix ends up becoming a permanently high policy. ## Next steps [#next-steps] * Unblock a one-off case without touching the policy in [Temporary grants](/en/docs/user-guide/models/quotas/grants). * See detailed per-model consumption in [Observability](/en/docs/user-guide/monitoring/observability). # Workspace models (/en/docs/user-guide/models/workspace-models) **Models** defines which options, out of everything the organization's providers offer, show up in the form of an Agent in this workspace. The screen is accessible to the **Owner**; the **Auditor** sees it read-only. Curator and Editor can't reach it, even though they are the ones who create the most Agents. ## The list [#the-list] The enabled models, with search by name and each one's source provider. The list isn't the organization's catalog: it is the subset this workspace received. Models that exist in the organization but aren't assigned to this workspace don't show up. ## Where the list comes from [#where-the-list-comes-from] The chain has three links, on different screens: 1. **Organization › Providers**: the service account is registered. 2. **Organization › Workspaces › Manage models**: the models are assigned to this workspace. 3. **Workspace › Settings › Models**: this screen, where you confirm what became available. A workspace with no models won't let you create an Agent. The form's **Model** field is required and stays empty, and the error message doesn't point to link 2 of the chain. ## When a model disappears [#when-a-model-disappears] If an Agent that used to work stops listing its model, the broken link is almost always number 2: someone removed that model from this workspace in the organization's workspace management. The Agent stays saved with the old model, but doesn't run. Editing it requires choosing a model that is still available. ## Choose among the available ones [#choose-among-the-available-ones] Three criteria are usually enough: * **Context window**: Agents with many Collections or long conversations need larger windows. * **Cost**: larger models charge more per token, and the effect shows up in the Dashboard at the end of the month. * **Behavior**: the same prompt yields different answers across models. Test before publishing. ## Next steps [#next-steps] * Understand the metadata that defines each model in [Model metadata](/en/docs/user-guide/models/providers/metadata). * Cap consumption per model in [Quotas](/en/docs/user-guide/models/quotas). # Logged conversations (/en/docs/user-guide/monitoring/conversations) **Conversations** keeps the history of exchanges between people and the workspace's Agents. It is the raw record of usage, message by message. The screen opens for **Owner**, **Curator** and **Auditor**. Editor can't reach it. ## The list [#the-list] Six columns: **Created at**, **Subject**, **User**, **Application**, **Agent** and **Actions**. The **Subject** is generated automatically from the content, by the organization's Rename Chats automation. The **Application** tells where the conversation came from, when the workspace is accessed through more than one channel. ## Open a conversation [#open-a-conversation] Opening a row shows the full exchange. There are actions to copy a specific message or the whole conversation, which is the practical way to take a case to whoever will adjust the Agent. ## What it's for in practice [#what-its-for-in-practice] Three uses that justify the screen: * **Understanding what people actually ask**, which is rarely what you imagined when writing the prompt. * **Investigating a reported case**, with the real conversation instead of the reporter's recollection. * **Auditing**, when you need to show what was answered and on what basis. ## Privacy [#privacy] The content here is what people wrote, including what they pasted into the chat. Roles with access to this screen see all of it. Guardrails filter what reaches the model, not what gets logged. Sensitive data someone pasted into the chat shows up on this screen even when it was masked before going to the model. ## Conversations with removed agents [#conversations-with-removed-agents] Removing an Agent doesn't delete the history. The conversations stay listed, with the name of the Agent that handled them, but you can't keep chatting. ## Next steps [#next-steps] * See what people rated in [Response feedback](/en/docs/user-guide/monitoring/feedback). * Adjust the Agent based on what you read in [Write the prompt](/en/docs/user-guide/agents/prompt). # Dashboard (/en/docs/user-guide/monitoring/dashboard) The **Dashboard** is the workspace's first screen and answers a broad question: is this workspace being used, and at what cost. It opens for **Owner**, **Curator** and **Auditor**. Editor can't reach it. ## Token usage [#token-usage] At the top, two numbers for the period: **Tokens consumed** and **Total cost**. The cost comes from the prices registered in each model's provider. A wrongly registered price shows up here before it shows up anywhere else. ## The counters [#the-counters] A grid of absolute numbers about what exists in the workspace: members, collections, agents, workflows, MCPs, conversations and models. They are for a quick check, not for trends. A high conversation count with low agent usage, for example, points to short or abandoned conversations. The **Knowledge sources** counter is a leftover from the structure before v4, when sources and collections were separate screens. Today both live in Collections. ## Agent usage [#agent-usage] The chart spreads messages by Agent over the period, with the list of totals beside it. Clicking an Agent in the legend hides it from the chart. It is the best adoption signal the platform gives: it shows which Agents people actually use, and which were published and forgotten. ## Feedback, active users and visits [#feedback-active-users-and-visits] At the bottom of the screen, three activity breakdowns: * **Feedback**: the balance of ratings given to answers in the period. * **Active users**: how many people used it, by day, week or month. * **Platform visits**: the volume of sign-ins in the period. Active users and visits answer different questions. Many visits with few active users means a few people come back many times. ## Dashboard or Observability [#dashboard-or-observability] The Dashboard summarizes the workspace's activity. Observability details per-model consumption and gives access to traces. Use the Dashboard to find out whether something changed; Observability to find out what. ## Next steps [#next-steps] * Drill into consumption in [Observability](/en/docs/user-guide/monitoring/observability). * Read the ratings behind the balance in [Response feedback](/en/docs/user-guide/monitoring/feedback). # Response feedback (/en/docs/user-guide/monitoring/feedback) **Response feedback** gathers the feedback people gave to the Agents' answers in Chat. It is the platform's most direct quality signal: it doesn't measure usage, it measures whether what was answered was useful. The screen opens for **Owner**, **Curator** and **Auditor**. ## The list [#the-list] Five columns: **Date**, **Agent**, **Rater**, **Rating** and **Actions**. The **Agent** column is what turns the screen into a tool. Sorting or filtering by it quickly shows which Agent concentrates the negative ratings. ## How to use negative feedback [#how-to-use-negative-feedback] A negative rating rarely says what happened. The path is to go from the rating to the conversation and read the whole exchange. The most common causes, in order of frequency: * **The knowledge wasn't there**: the document wasn't uploaded, or never reached **Active** in the Collection. * **The answer came from the model, not the material**: the prompt doesn't tell it to say it doesn't know. * **The question was outside the Agent's scope**: the problem is one of expectations, solved in the name and description. ## The balance on the Dashboard [#the-balance-on-the-dashboard] The Dashboard summarizes these ratings into a balance for the period. The number alone says little; the useful reading is here, case by case. A low volume of ratings is normal. People rarely rate answers, and almost always when something went wrong. An Agent with no ratings isn't an approved Agent. ## Next steps [#next-steps] * Read the full conversation behind a rating in [Conversations](/en/docs/user-guide/monitoring/conversations). * Check whether the knowledge was available in [Indexing](/en/docs/user-guide/knowledge/indexing). # Observability (/en/docs/user-guide/monitoring/observability) **Observability** answers two different questions: how much was consumed, and what happened in a specific execution. The screen exists in both scopes, with the same features. The **Organization** one adds up every workspace; the **Workspace** one covers just one. It replaced the old Usage Logs page in version 4. ## Model usage [#model-usage] The first tab summarizes the chosen period in three numbers: **Tokens**, **Cost** and **Requests**. Below them, the **Consumption by model** chart spreads that total over time. The selector beside it switches the metric between tokens and cost and lets you group by another dimension. The legend on the right lists the models by consumption. Clicking one hides it from the chart, which helps when a dominant model flattens the scale of the others. ## The models table [#the-models-table] Under the chart, one row per model: | Column | What it's for | | ------------ | ---------------------------------------------------------------- | | `Requests` | How many calls were made to that model. | | `Tokens` | Total volume consumed. | | `Cost` | The corresponding amount, calculated from the provider's prices. | | `% of total` | The model's share of the period's consumption. | Few requests combined with many tokens usually points to long prompts or Agents with many attached Collections. ## Period and export [#period-and-export] The **Choose the period** selector sets the window for every number on the screen. The refresh button reloads without changing the period. **Export** downloads the current view's data, for analysis outside the platform. ## Traces [#traces] The second tab lists executions with **Root trace**, **Status**, **Duration** and **Cost**. The filters narrow by resource identifier, application and user. A trace covers the whole execution: the model call, the Collection search when there was one, and every tool call. It is how you answer what the Conversations screen can't: why the answer took so long, whether the MCP was actually called, how much that message cost. Administrative roles have a shortcut in the top bar to the detailed tracing tool, outside the platform. ## Which scope to use [#which-scope-to-use] Use the **Organization** one to understand the company's cost and trends; the **Workspace** one to investigate a team's behavior. People with an organization role reach both; people with only a workspace role see only their own. ## Next steps [#next-steps] * Turn what you observed into a limit in [Quotas](/en/docs/user-guide/models/quotas). * See the team's activity summary in [Dashboard](/en/docs/user-guide/monitoring/dashboard). # Credentials (/en/docs/user-guide/tools/credentials) **Credentials** is where the access that providers and integrations use to talk to outside systems is kept. Each secret is registered once and reused by whoever needs it. The screen requires the **Superadmin** role, for the same reason as Providers: it is where the secret lives. ## Why it exists [#why-it-exists] Without this screen, every integration in every workspace would ask for its own secret, and the same password would end up copied in dozens of places. With it, the design is clear: the Organization keeps the secret; the Workspace chooses what to turn on, without ever seeing the stored value. Rotating an access becomes an edit in a single place. ## Register a credential [#register-a-credential] 1. Click **+ Credential**. 2. Choose the type, according to the system it will access, and click **Next**. 3. Fill in the fields that type requires. 4. Click **Create**. The types fall into two groups: * **SMTP** and **Google Drive**: you fill in everything in the form itself. For SMTP, name, server, port, encryption, user and password; for Google Drive, the authentication type (**Personal** or **Organizational**), the allowed domains and the service account JSON file. * **Jira**, **Confluence**, **SharePoint** and **OneDrive**: the form only asks for a name and description. When you click **Create**, you're taken to the Atlassian or Microsoft consent screen, and the credential is only created once the sign-in comes back to AUMO. Before that, the service's domains must be configured in [Knowledge domains](/en/docs/user-guide/knowledge/allowed-domains); without them, the platform warns you and stops. The credential then becomes available to the organization's integrations, connectors and providers. The walkthrough below uses an SMTP credential: Once saved, a secret's value isn't shown back. When rotating an access, you replace the value; there is no way to check the previous one through the interface. ## Edit and remove [#edit-and-remove] **Edit** lets you change a credential's value without redoing the associations that depend on it. It is the path for password rotation or token renewal. **Remove** deletes the credential. Everything that depended on it stops working, and the failure shows up at the time of use, not at the time of removal. Check the associations first. ## Email credentials [#email-credentials] The server used by the Workflows send email node is registered here, as an **SMTP** credential. Each workspace then picks its own sender: under **Organization › Workspaces**, open the workspace and, in the **Credentials** tab, create an email credential with a name, a sender address and the SMTP credential it uses. This lets each team send from its own sender while reusing the same server. ## Next steps [#next-steps] * Attach credentials to registered connections in [Integrations](/en/docs/user-guide/tools/integrations). * Understand where they fit in the chain in [MCPs and Integrations](/en/docs/user-guide/concepts/tools). # DuckDuckGo (/en/docs/user-guide/tools/integrations/duckduckgo) The **DuckDuckGo** integration lets an Agent or Workflow search the web while answering. It is the right tool when the question depends on public, current information, outside what is indexed in the Collections. ## The tool [#the-tool] | Tool | What it does | | ------------------- | ----------------------------------------- | | `DuckDuckGo Search` | Searches the web and returns the results. | ## Fields [#fields] * **Search**: the term to search for. It accepts long text and usually comes from a flow variable or the user's question. * **Strip HTML**: when on, it cleans the markup from the returned content. It is on by default, and keeping it that way reduces the noise that reaches the model. ## When to use it [#when-to-use-it] Web search greatly expands the Agent's reach, and with it the chance that it answers with something that never went through any curation. Web results aren't a controlled source. In Agents that answer about internal policy or customer data, open search tends to hurt more than it helps: the model mixes the company's content with what it found on the internet. For those cases, the prompt needs to be explicit about when to search and when to stay within the Collections. ## Next steps [#next-steps] * Turn on the integration in the workspace in [Overview](/en/docs/user-guide/tools/integrations). * Use the tool inside a flow in [Integration](/en/docs/user-guide/workflows/nodes/integration). # GitHub (/en/docs/user-guide/tools/integrations/github) The **GitHub** integration queries public repositories: metadata, the latest commit and the details of a pull request. The scope is public. Private repositories aren't reached by this integration. ## The tools [#the-tools] | Tool | What it does | | ----------------- | --------------------------------------------- | | `Repository Info` | Retrieves a public repository's metadata. | | `Latest Commit` | Retrieves a repository's most recent commit. | | `Pull Request` | Fetches the details of a public pull request. | Each tool is checked separately in the Agent form. An Agent that only needs to check the latest published version doesn't need access to pull requests. ## Use cases [#use-cases] The most productive combination is a technical support Agent that checks the real state of the repository instead of answering from memory. What the current version is, what went into the last commit, whether a given change has already been merged. In Workflows, `Latest Commit` works as a check trigger: the flow compares the current commit with the recorded one and decides whether to proceed. ## Limits [#limits] Since the query is public and has no credential, it is subject to the rate limits GitHub applies to anonymous calls. Flows that query in a loop may be refused for too many requests. ## Next steps [#next-steps] * Turn on the integration in the workspace in [Overview](/en/docs/user-guide/tools/integrations). * For private repositories, the path is an [MCP](/en/docs/user-guide/tools/mcp). # Overview (/en/docs/user-guide/tools/integrations) **Integrations** are connections to services the platform already knows how to talk to. Unlike MCPs, you don't describe the protocol: you pick the service from a list and provide the access. Like MCPs, they follow the path of a catalog in the organization and activation in the workspace. ## Register in the organization [#register-in-the-organization] **Organization › Integrations** opens for **Superadmin** and **Admin**, with two tabs: * **Available**: the catalog of integrations the platform knows that haven't been registered yet. * **Installed**: the ones the organization has already registered and can distribute to workspaces. To register one, open **Available** and click **Install** on the service card. There is no form at this stage: the integration goes straight to **Installed**. The access it needs is provided later, when each workspace installs it. When the **Available** tab shows up empty, every known integration has already been registered in this registry. ## Associate with a workspace [#associate-with-a-workspace] The association is made under **Organization › Workspaces**: open the workspace and, in the **Integrations** tab, turn on the card's switch. Its state goes from **Inactive** to **Active**. Associating and dissociating are reversible actions. ## Turn it on in the workspace [#turn-it-on-in-the-workspace] **Workspace › Integrations** has the same two tabs, **Installed** and **Available**, applied to what the organization associated with this workspace. This screen is accessible only to the workspace **Owner**. No other role reaches it, not even read-only. A Curator building an Agent sees the integration in the form's list, but can't turn it on. It has to be turned on by someone with that role. When installing in the workspace, the window asks for a name, a description and the credentials the integration requires. Integrations that depend on authorization at the source service open the consent flow at this point. ## Hand it to an agent [#hand-it-to-an-agent] Turning it on in the workspace doesn't hand the integration to any Agent. Each Agent checks what it can call in the **Integrations** section of its own form. Workflows also reach integrations, through the canvas **Integration** node. ## Name and description [#name-and-description] The organization registry's action menu lets you edit a registered integration's name and description. Use it when the same integration is registered more than once, pointing to different environments: the catalog's default name doesn't tell one from the other. ## Remove [#remove] Turning off an integration in the workspace cuts off access for the Agents and Workflows that depended on it. The failure shows up at the time of use, not at the time of removal. ## Next steps [#next-steps] * Keep the access they use in [Credentials](/en/docs/user-guide/tools/credentials). * Compare with the tool server path in [MCPs](/en/docs/user-guide/tools/mcp). ## The current catalog [#the-current-catalog] Public web search, with a single search tool. Metadata, commits and pull requests from public repositories. Video search, trends, categories and channels. # YouTube (/en/docs/user-guide/tools/integrations/youtube) The **YouTube** integration uses the YouTube Data API to search videos and retrieve information about them, about channels and about what is trending. It is the integration with the most tools in the catalog, so check in the Agent only the ones it actually uses. ## The tools [#the-tools] | Tool | What it does | | ------------------ | -------------------------------------------------------------------------------- | | `Search Vídeos` | Searches videos with filters by channel, date, duration, language and relevance. | | `Trending Vídeos` | Lists the most popular videos by region or category. | | `Video Details` | Retrieves a video's full details by ID. | | `Video Categories` | Lists the video categories available by region. | | `Channel Info` | Retrieves a channel's information by ID or username. | ## How the tools chain together [#how-the-tools-chain-together] Typical use goes through two calls: `Search Vídeos` returns the identifiers, and `Video Details` fetches the details of one of them. An Agent with both checked does this chaining on its own, as long as the iteration limit allows more than one call per answer. ## Use cases [#use-cases] Brand monitoring and content research are the two direct cases: what was published about a topic, which channel covers a given subject, what is trending in a region. ## Limits [#limits] The YouTube Data API works with a daily consumption quota. Flows that search in a loop, or heavily used Agents, can exhaust the quota before the end of the day, and calls fail until it resets. ## Next steps [#next-steps] * Turn on the integration in the workspace in [Overview](/en/docs/user-guide/tools/integrations). * Adjust the limit of calls per answer in [Create an agent](/en/docs/user-guide/agents/create). # Overview (/en/docs/user-guide/tools/mcp) **MCP** is an open protocol for exposing tools to AI models. An MCP server publishes a set of tools, and the Agent decides when to call them. Turning on an MCP takes two steps, on different screens: the organization **registers** the server in the catalog, and each workspace **installs** what it will use. This page covers both. ## The organization registry [#the-organization-registry] **Organization › MCPs** is the catalog of servers approved by the company. No workspace installs an MCP that hasn't gone through here. The screen opens for **Superadmin** and **Admin**, but registering new servers is the Superadmin's privilege. It has three tabs: * **Installed**: the servers already registered in the organization. * **Docker Hub**: public catalog of MCPs distributed as images. * **GitHub**: public catalog of MCPs distributed as repositories. The two public catalogs let you discover and register without leaving the platform. The step by step is in [Register a server](/en/docs/user-guide/tools/mcp/register). ## Make it available to a workspace [#make-it-available-to-a-workspace] Registering doesn't hand the server to anyone. Availability is set under **Organization › Workspaces**, in each workspace's MCPs section. This is the step people tend to forget: a server in the registry with no workspace able to install it almost always means that association wasn't made. ## Install in the workspace [#install-in-the-workspace] **Workspace › MCPs** is where the server is actually turned on. Installing and configuring requires the **Owner**, **Curator** or **Editor** role. The screen has two tabs: * **Installed**: the servers already turned on in this workspace, with each one's configuration. * **Available**: what the organization made available and hasn't been installed here yet. When installing, you give the server a name and the configuration this workspace needs. The same registry server can be installed **several times** in the same workspace, as long as each installation has a different name. That is how you point to two environments of the same system. Configuration and behavior belong to the **installation**, not to the registry entry. Changing one installation doesn't affect the others or the item registered in the organization. ## Hand it to an agent [#hand-it-to-an-agent] Installing in the workspace still isn't enough. Each Agent has to check the MCP in the **MCPs** section of its own form. That is also where the **maximum iterations** lives, which limits how many times that Agent can call tools in a single answer. This prevents a loop when a tool returns something unexpected. ## Remove [#remove] Removing an **installation** stops its use in that workspace. Agents that had it checked stop calling those tools and answer without them, with no error visible to the person chatting. Removing the server from the organization **registry** doesn't undo what workspaces have already installed, because the configuration belongs to the installation. To stop its use for good, you need to remove it in both places. ## When a tool isn't called [#when-a-tool-isnt-called] * **The MCP isn't checked in the Agent**: installing in the workspace isn't handing it to the Agent. * **The iteration limit was reached**: the Agent wrapped up the answer before completing the calls. * **The server is down**: the failure shows up in the traces, under Observability. ## In this section [#in-this-section] Through the public catalogs or by pasting a JSON configuration. The validation layers and what the verified badge means. # Register a server (/en/docs/user-guide/tools/mcp/register) There are two ways to register an MCP server, and the choice depends on where it is published. Both require the **Superadmin** role and end in the same place: the server shows up on the registry's **Installed** tab. ## The two paths [#the-two-paths] Use this when the server is published on Docker Hub or GitHub. 1. Open the **Docker Hub** or **GitHub** tab. 2. Search for the server by name. 3. Click **Install** on its card. 4. Review the window and click **Install**. The platform fills in the description, version and repository from the published metadata. The window also lists the server's **Environment Variables**, such as access tokens; they are optional at this stage. Use this for internal servers that aren't in a public catalog. 1. Click **+ MCPs**. 2. In the **Import MCPs** window, paste a valid JSON configuration. 3. Click **Import MCPs**. This is the path for an MCP developed by your own team, or for a vendor that hands over the configuration instead of publishing it in a catalog. ## After registering [#after-registering] The server goes into the registry, but no workspace reaches it yet. Availability is set under **Organization › Workspaces**, in each workspace's MCPs section. Once made available, it shows up under **Workspace › MCPs**, on the **Available** tab, so the team can install it with its own name and configuration. The same registry server can be installed several times in the same workspace, as long as each installation has a different name. That is how you point to two environments of the same system. ## Before registering [#before-registering] An MCP gives the Agent the ability to **act** on external systems, not just read them. Registering a server of unknown origin exposes the organization to whatever that code does. Check the result of the automatic analysis before releasing the server to teams. See [Security scanner](/en/docs/user-guide/tools/mcp/security). ## Next steps [#next-steps] * Release the server to teams in [Workspaces](/en/docs/user-guide/admin/workspaces). * Compare with the Integrations path in [MCPs and Integrations](/en/docs/user-guide/concepts/tools). # Security scanner (/en/docs/user-guide/tools/mcp/security) The **MCP Security Scanner** analyzes the servers registered in the organization before they reach workspaces. It exists because an MCP isn't passive content: it is code the Agent can call against real systems. Registering a server is a security decision, not a catalog one. ## Where each thing lives [#where-each-thing-lives] The configuration and the result live on different screens: * **Settings › General** defines which validation layers the scanner applies in the organization. * **MCPs** shows the result. Each server has the **View security** action, which opens that item's analysis. An approved server gets a **verified** badge in the list, visible without opening the details. ## How to read the result [#how-to-read-the-result] The badge answers a single question: whether the server passed the configured layers. It doesn't claim the server is safe for your use case. Two things the scanner doesn't know: * **What the server does with the data** the Agent sends it. * **Whether the exposed tools are appropriate** for the people in that workspace. The badge is a necessary condition, not a sufficient one. A verified server from an unknown vendor is still an unknown vendor with write access to your systems. ## Adjust the layers [#adjust-the-layers] Under **Settings › General**, the **MCP Security Scanner** section lists the available layers and lets you turn each one on or off. Loosening the layers lets more servers through; tightening them may fail servers that were already in use. The change applies to the whole organization, and only the **Superadmin** can make it. ## Next steps [#next-steps] * Register servers in [Register a server](/en/docs/user-guide/tools/mcp/register). * See the screen's other sections in [Settings](/en/docs/user-guide/admin/org-settings). # Variables (/en/docs/user-guide/tools/variables) **Variables** stores named values that the workspace's configurations consume: an environment address, a system identifier, a parameter that differs between staging and production. Instead of repeating the same value in several places, you name it once and reference the name. ## The list [#the-list] The table shows the **Type** (public or secret), the **Variable**, the **Value** and when it was **Updated at**. Search filters by name. The value has reveal and copy actions. Copying is useful when it is long or needs to be checked against another system. ## Create a variable [#create-a-variable] Click **+ Variable** and enter the **Variable name** and the **Value**. The name follows the environment-variable convention, in uppercase with underscores, such as `DATABASE_URL` or `API_BASE_URL`. **Variable visibility** is **Public**, when the value can be shown again, or **Secret**, when it stays hidden after saving. Masked visibility hides the value on screen; it doesn't turn it into a managed secret. Access credentials for systems belong under **Organization › Credentials**, which is where the secret is actually protected. ## Who can change them [#who-can-change-them] **Owner**, **Curator** and **Editor** create and change variables. **Auditor** only reads. Deleting a variable is the **Owner**'s privilege. Curator and Editor can create and edit, but not remove, which keeps a value in use from disappearing by mistake. ## Effect of changing a value [#effect-of-changing-a-value] Changing a variable changes the value for everyone who references it, on the next run. There is no versioning or history. Before changing a value in use, check where it is referenced: there is no screen that lists a variable's consumers. ## Next steps [#next-steps] * Keep access secrets in [Credentials](/en/docs/user-guide/tools/credentials). * See where named values come into automation in [Workflows](/en/docs/user-guide/workflows). # Build on the canvas (/en/docs/user-guide/workflows/build) The canvas is where the Workflow takes shape. You add nodes, connect one's output to another's input and configure each one in the side panel. Every runnable flow starts at an **Input** node and ends at an **Output** node. ## Add and connect nodes [#add-and-connect-nodes] The add button opens the palette, with nodes grouped by purpose and search by name. Nodes can also be dragged straight onto the canvas. Each node has input and output handles. Dragging from an output handle to an input handle creates the connection and sets the execution order. Clicking a node opens the side panel with its configuration. That is where you choose an LLM node's model, a vector node's Collections, an HTTP request's URL. ## Input and output [#input-and-output] The **Input** node defines the form the person fills in when running the flow. Each field declared here becomes a field in that form. The **Output** node defines what the person gets at the end. Anything that doesn't go through it stays in the run log, but isn't shown as a result. Design the input form with the person running it in mind, not the person who built it. Field names like `input_1` reach the user's screen as they are. ## Reference what came before [#reference-what-came-before] Nodes consume what earlier nodes produced. An LLM node builds its prompt from earlier outputs; a condition node evaluates those same values. Since the connection sets the order, a node only reaches what is upstream of it. Nodes in parallel branches don't see each other until an aggregation node brings them together. ## Draft and publishing [#draft-and-publishing] Like Agents, Workflows have a draft and a published version. Only the published one is available for other people to run, in the Chat **Agents** area. Editing and republishing replaces the version in use. Runs already recorded stay as they are. ## Test before publishing [#test-before-publishing] Run the flow from the studio itself before publishing, with real input. The run log shows what each node received and returned, which is the fastest way to find a misconfigured node. A flow that always fails at the same node is almost never a connection problem: it is that node's configuration, visible in the side panel. ## Next steps [#next-steps] * Choose the right nodes in [Node catalog](/en/docs/user-guide/workflows/nodes). * Investigate the result in [Runs](/en/docs/user-guide/workflows/runs). # Overview (/en/docs/user-guide/workflows) A **Workflow** is a sequence of steps built on a canvas. Where an Agent converses, a Workflow executes: the person using it fills in a form and gets a result. Creating and editing Workflows requires the **Owner**, **Curator** or **Editor** role. ## The list [#the-list] The screen lists the workspace's Workflows with search by name. Each item opens the editing canvas. The screen was called **AI Studio** in earlier versions of the platform and shows up as **Workflows** in the sidebar. ## When to choose a Workflow [#when-to-choose-a-workflow] The question that separates a Workflow from an Agent is whether the path is known in advance. * **Workflow**: you know the steps and the order. Process a document, extract fields, query a system, generate a file. * **Agent**: the person asks open questions and the model decides what to do on each message. A Workflow is more predictable and easier to audit, because every run is recorded step by step. ## Where people run them [#where-people-run-them] Published Workflows show up in the **Agents** area of the Chat module, not in Admin. The person running them doesn't need administrative access to the workspace. Add nodes, connect outputs to inputs and publish. What each node does and when to use it. Follow and investigate recorded runs. # Code (/en/docs/user-guide/workflows/nodes/code) The **Code executor** node runs a script inside the flow. It is for transforming data, calculating derived values and applying business rules the standard nodes don't cover. It is the escape hatch for the specific case, not the default path. ## Input variables [#input-variables] Before the code, you declare which data it receives. Each input has two parts: * **Field name**: what the variable is called inside the script, for example `text` or `number1`. * **Value**: where the data comes from, such as `{{ entrada.mensagem }}`. The names declared here become the main function's arguments. ## The code [#the-code] The editor accepts **Python** or **Node.js**. The script must expose a `main` function whose parameters match the declared input variables. ```python def main(arg1, arg2): result = arg1 + arg2 return {"sum": result} ``` Whatever the function returns becomes the node's output, accessible to the following nodes. ## When not to use it [#when-not-to-use-it] A flow whose work all happens inside a code node loses what the canvas offers: the step-by-step reading in the run log. If the script does three distinct things, splitting them into their own nodes makes investigation much more direct. The log then shows which step failed, instead of pointing at a single block. Before writing code, check whether there is a ready-made node. Extracting a CPF, querying Collections, calling an API and assembling a file already have dedicated nodes, with their own error handling. ## Next steps [#next-steps] * See the full catalog in [Overview](/en/docs/user-guide/workflows/nodes). * Check the script's output in [Runs](/en/docs/user-guide/workflows/runs). # CPF extractor (/en/docs/user-guide/workflows/nodes/documents/cpf-extractor) The **CPF extractor** finds CPF and CNPJ numbers, the Brazilian individual and company taxpayer IDs, inside an already processed text. It validates each one and returns the ones that pass. Unlike a pattern search, it applies the check-digit algorithms and resolves detection conflicts. ## Validation, not just detection [#validation-not-just-detection] A regular expression finds any sequence shaped like a CPF, including made-up numbers and fragments of other identifiers that happen to match. This node applies the check-digit calculation and discards whatever doesn't add up. The result is a list of identifiers that are actually valid numbers. Validating the check digit confirms that the number is well formed, not that it belongs to someone or that it is correct in the context of the document. ## Typical use [#typical-use] The common chain has three nodes: **File extractor** converts the document to text, this node retrieves the identifiers, and an **HTTP request** node looks each one up in an internal system. The output is a list, accessible by index when the flow expects a single value, such as `{{ extrator_cpf.cpfs[0] }}`. ## Personal data [#personal-data] CPF and CNPJ are personal data, and what this node extracts flows through the rest of the flow and is recorded in the run. Check who has access to that workspace's run logs before building a flow that handles documents with this kind of information. ## Next steps [#next-steps] * Convert the document first in [File extractor](/en/docs/user-guide/workflows/nodes/documents/file-extractor). * Query a system with the result in [Integration](/en/docs/user-guide/workflows/nodes/integration). # File extractor (/en/docs/user-guide/workflows/nodes/documents/file-extractor) The **File extractor** turns raw documents into plain text. PDFs, spreadsheets and images go in as binaries and come out as content a model can read. It is the first node of practically every flow that processes documents. ## Why it is needed [#why-it-is-needed] A file that arrives through the Input is a reference to a binary. Connecting that reference straight to an LLM node doesn't deliver the content: the model receives the pointer, not the text. The extractor bridges that gap, and nothing after it needs to know the original format. ## The output [#the-output] The node returns a list of extracted texts, accessible as `{{ extrator_arquivos.contents }}`. It is a list because the Input can receive several files. To process them one by one, connect that list to an **Iteration** node. ## Formats [#formats] Files with selectable text come out clean and fast. Scanned documents depend on text recognition, take longer and may fail when the scan quality is low. A PDF that contains only the image of a scanned page may return empty text without an explicit error. The flow carries on with blank content, and the next LLM node answers from nothing. Handle that case with a **Condition** node right after, checking whether the extracted text came back empty. ## Next steps [#next-steps] * Process each document separately with [Logic](/en/docs/user-guide/workflows/nodes/logic). * Extract identifiers from the text in [CPF extractor](/en/docs/user-guide/workflows/nodes/documents/cpf-extractor). # File generator (/en/docs/user-guide/workflows/nodes/documents/file-generator) The **File generator** turns what the flow assembled into a downloadable document, in Markdown, DOCX or PDF. It is the closing node of flows that produce a report, an assessment or a consolidated summary. ## The formats [#the-formats] * **Markdown**: the text output as is, useful when another system will consume it. * **DOCX**: an editable document, for when someone will still review and adjust it. * **PDF**: a final document, rendered from HTML. ## Images [#images] PDFs are rendered from HTML, and the allowed image sources are restricted for security. Images embedded as `data:`, the HTTPS bucket configured by the platform and the official CDN are accepted. Local URLs, plain HTTP and arbitrary external origins are blocked. An image from a blocked origin doesn't bring the run down. The file is generated without it, and the problem only shows up when someone opens the document. ## Where the file is kept [#where-the-file-is-kept] The result is persisted by the platform and delivered to the person who ran the flow, according to what the **Output** node declares. Files generated by older runs stay accessible through that run's log. ## Next steps [#next-steps] * Declare the result in [Output](/en/docs/user-guide/workflows/nodes/io/output). * Build the document's content in [LLM](/en/docs/user-guide/workflows/nodes/llm). # Overview (/en/docs/user-guide/workflows/nodes/documents) Four nodes handle documents: two that bring content into the flow, one specialized in identifiers and one that produces files at the end. ## What each node does [#what-each-node-does] * **File extractor**: converts files received at the Input into plain text. The first node of almost every document flow. * **CPF extractor**: finds, validates and extracts CPF and CNPJ numbers from an already processed text. * **Vector database**: searches the workspace's Collections and returns the relevant passages. It is what enables RAG on the canvas. * **File generator**: produces Markdown, DOCX or PDF from what the flow assembled. ## The common chain [#the-common-chain] Document flows almost always follow the same order: the File extractor converts, a Logic node repeats per item, the LLM node interprets and the File generator closes. The Vector database comes into flows that answer questions, not into the ones that process received files. Turn PDFs, spreadsheets and images into usable text. Retrieve valid identifiers from inside the text. Query the Collections and choose how many passages to bring back. Close the flow with a downloadable document. # Vector database (/en/docs/user-guide/workflows/nodes/documents/vector-db) The **Vector database** runs a semantic search over the workspace's Collections and returns the passages closest to the query. It is the node that enables RAG inside a Workflow, the equivalent of attaching Collections to an Agent. ## Configure [#configure] The configuration has three parts, and each answers a different question: * **Collections**: where to search. One or several, out of the workspace's. * **Search text**: what to search for. Usually the question coming from the Input, but the field accepts a composed query, such as `{{ entrada.pergunta }} in the context of {{ entrada.categoria }}`. * **Number of chunks**: how much to bring back, through a slider. ## How many chunks to bring back [#how-many-chunks-to-bring-back] | Range | When to use it | | ------- | ----------------------------------------------------------------------------- | | 3 to 5 | Objective questions. Balances context and cost. | | 5 to 10 | Broad summaries and research. More context, more tokens in the next LLM node. | Raising the number doesn't always help: barely relevant passages dilute the context and increase the chance that the model leans on the wrong material. This node requires at least one configured Collection. An empty list doesn't mean "search everything". It means the node has nowhere to look, and it returns nothing. ## What it returns [#what-it-returns] The output is `chunks`: a list with the texts found, the similarity score and the source metadata. It doesn't write an answer. The **LLM** node that follows is what turns the passages into text, receiving `chunks` in its prompt. ## When it returns nothing [#when-it-returns-nothing] Three causes, in order of frequency: the Collection's documents didn't reach the **Active** state, the configured Collection is empty, or the search text has nothing to do with the indexed content. The run log shows what the node returned, which tells the third case apart from the first two. ## Next steps [#next-steps] * Write the answer in [LLM](/en/docs/user-guide/workflows/nodes/llm). * Check the documents' state in [Indexing](/en/docs/user-guide/knowledge/indexing). # Overview (/en/docs/user-guide/workflows/nodes) **Nodes** are the pieces of the canvas. Each one receives data, does one thing and hands a result to the next. The palette groups them by purpose, and the following pages follow that split. ## Reference what came before [#reference-what-came-before] Every node consumes what earlier nodes produced, through variables in the `{{ node.field }}` format. ```text {{ entrada.pergunta_usuario }} {{ extrator_arquivos.contents }} {{ llm.classificacao }} ``` In fields that accept variables, the `/` key opens the selection menu, which avoids getting the node or field name wrong. A node only reaches what is **above** it in the flow. Parallel branches don't see each other until an Aggregation node brings them together. ## The groups [#the-groups] The two required ends: the form the person fills in and the result they get. Call an AI model with a prompt built from the flow. Extract text from files, query Collections and generate documents. Branch, repeat over lists and choose between results. Talk to outside systems through HTTP, email or an installed integration. Run Python or Node.js for what no ready-made node covers. # Send email (/en/docs/user-guide/workflows/nodes/integration/email) The **Send email** node sends messages over SMTP during the run. It is for notifying someone or delivering a report the flow generated. It doesn't configure a sender. It only lists the credentials already registered for the workspace. ## Prerequisites [#prerequisites] The setup happens outside the canvas, at two levels: 1. The organization needs an SMTP credential registered. 2. An administrator creates the email credential for that workspace, under **Organization › Workspaces › Email credentials**. Without an available credential, the node fails at **run time**, not at build time. The canvas accepts the flow, publishing works, and the error only shows up when someone runs it. ## Recipients [#recipients] Three fields, each accepting several addresses: | Field | Behavior | | ----- | ------------------------------------------ | | `TO` | Main recipients. | | `CC` | Receive a copy visible to the others. | | `BCC` | Receive a copy without the others knowing. | The addresses accept variables, which lets you send to whoever the flow determined instead of a fixed list. ## Content [#content] * **Subject**: the message title. * **Body (text)**: the plain-text version. * **HTML body**: the formatted version, with links and tables. Filling in both covers email clients that block HTML. ## Attachments [#attachments] Files are attached by the file's **public URL**. A document produced by the **File generator** node can be attached this way. ## Next steps [#next-steps] * Produce the document to send in [File generator](/en/docs/user-guide/workflows/nodes/documents/file-generator). * See where the credential is created in [Workspaces](/en/docs/user-guide/admin/workspaces). # HTTP request (/en/docs/user-guide/workflows/nodes/integration/http) The **HTTP request** node is a full API client inside the canvas. It is for fetching real-time data or sending information to an external system. It is the way out for systems that have neither an MCP nor a ready-made integration. ## Method and URL [#method-and-url] The available methods are `GET`, `POST`, `PUT`, `DELETE` and `PATCH`. The URL accepts variables, which lets you build the address from the flow: ```text https://api.store.com/orders/{{ entrada.numero_pedido }} ``` ## Headers [#headers] Key-value pairs, used mostly for authentication: | Key | Value | | --------------- | -------------------------------- | | `Authorization` | `Bearer {{ entrada.token_api }}` | A token typed directly into the value is saved in the flow definition, visible to anyone who opens the canvas. Prefer passing it through a workspace [Variable](/en/docs/user-guide/tools/variables), or using an Integration, which keeps the access outside the design. ## Body [#body] For `POST` and `PUT`, the body is the JSON sent, built with variables from earlier nodes: ```json { "customer": "{{ extrator_cpf.cpfs[0] }}", "reason": "{{ llm.classificacao }}" } ``` ## Advanced settings [#advanced-settings] * **Timeout**: the maximum time to wait for the response, in seconds, with a default of 360. * **Content-Type** and **Accept**: the data format, usually `application/json`. A slow endpoint that exceeds the timeout fails the whole run. For services known to be slow, raise the value before publishing. ## Next steps [#next-steps] * Keep credentials out of the design in [Variables](/en/docs/user-guide/tools/variables). * For well-known services, compare with [Integration](/en/docs/user-guide/workflows/nodes/integration/tool). # Overview (/en/docs/user-guide/workflows/nodes/integration) Three nodes talk to external systems. The difference between them is how much configuration you have to do by hand. ## What each node does [#what-each-node-does] * **HTTP request**: a full API client. Method, URL, headers and body, all set up by you. * **Send email**: sends messages over SMTP using a credential already registered for the workspace. * **Integration**: calls one of the ready-made connections turned on in the workspace, with the tools it exposes. ## Which one to choose [#which-one-to-choose] For services the platform already knows, the **Integration** needs less configuration and keeps the access outside the flow's design. For internal systems or ones without a ready-made integration, the **HTTP request** is the way, taking care not to leave credentials written in the node. ## Failures at run time, not at build time [#failures-at-run-time-not-at-build-time] All three depend on configuration done outside the canvas: an SMTP credential, an integration turned on in the workspace, an endpoint that is up. The canvas accepts the flow anyway. The error shows up when someone runs it, and the run log points to the node. Call any endpoint, with method, headers and body. Recipients, content, attachments and the credential prerequisite. Call DuckDuckGo, GitHub or YouTube from the flow. # Integration (/en/docs/user-guide/workflows/nodes/integration/tool) The **Integration** node calls one of the ready-made connections already turned on in the workspace, using the tools it exposes. It is the lower-configuration alternative to the HTTP request. ## Integration or HTTP [#integration-or-http] The choice is straightforward: * **Integration**, when the service is in the platform's catalog. It already knows how to talk to that system, and the access is stored outside the flow's design. * **HTTP request**, when the service has no ready-made integration. You set up the method, URL, headers and body. ## Prerequisites [#prerequisites] The integration has to be registered in the organization and turned on in the workspace before it shows up here. An empty list in the node means no integration was turned on in that workspace, and the fix is under **Workspace › Integrations**, accessible to the Owner. ## Choose the tool [#choose-the-tool] An integration exposes one or more tools, and the node calls one of them at a time. YouTube, for example, exposes five distinct tools. The panel's fields change with the chosen tool, and all of them accept variables from earlier nodes. ## The current catalog [#the-current-catalog] The platform currently offers DuckDuckGo, GitHub and YouTube. The details of each, with its tools and fields, are in [Integrations](/en/docs/user-guide/tools/integrations). ## Next steps [#next-steps] * Turn on an integration in the workspace in [Integrations](/en/docs/user-guide/tools/integrations). * For internal systems, compare with [MCPs](/en/docs/user-guide/tools/mcp). # Overview (/en/docs/user-guide/workflows/nodes/io) Every Workflow starts at an **Input** node and ends at one or more **Output** nodes. Together they define the flow's interface: what the person fills in and what they get back. A flow without an Output node runs to completion and delivers nothing. ## What each node does [#what-each-node-does] * **Input**: declares the variables the flow receives. Each one becomes a field in the run form. * **Output**: declares the structure of the result returned to the person who ran it or to the system that called it through the API. * **Iteration start**: appears on its own inside an Iteration node and represents the current item of the loop. ## How data flows through [#how-data-flows-through] Input variables are available to every following node, in the `{{ entrada.variable_name }}` format. Anything that doesn't go through the Output node is still recorded in the run, but doesn't show up as a result. Declare the variables and build the run form. Define the result's fields, and when to use more than one output. The `item` and `index` variables inside a loop. # Input (/en/docs/user-guide/workflows/nodes/io/input) The **Input** node is the flow's entry point. It declares the variables the Workflow needs to receive to start, and each declared variable becomes a field in the run form. Every flow has exactly one Input node, and it can't be removed. ## Declare variables [#declare-variables] In the side panel you add one variable per piece of information the flow needs. Each has a name, a type and a description. On the canvas, the node shows the list of configured variables, so you can check the flow's contract without opening the panel. The name and the description reach the screen of the person running the flow. `order_number` with the description "Order number, without punctuation" produces a usable form; `input_1` with no description doesn't. ## Use them in the following nodes [#use-them-in-the-following-nodes] The variables are available to every node in the flow, in the `{{ entrada.variable_name }}` format. ```text Analyze customer {{ entrada.customer_name }}'s request about order {{ entrada.order_number }}. ``` In fields that accept variables, the `/` key opens the selection menu. ## Files [#files] When the flow processes documents, the Input receives the file and hands it to the **File extractor** node, which converts it to text. Connecting the Input straight to an LLM node without going through the extractor doesn't work: the model receives a reference to the binary, not the content. ## Next steps [#next-steps] * Define what the flow returns in [Output](/en/docs/user-guide/workflows/nodes/io/output). * Convert files to text in [Documents](/en/docs/user-guide/workflows/nodes/documents). # Iteration start (/en/docs/user-guide/workflows/nodes/io/iteration-start) **Iteration start** is the only node you don't add. It appears automatically inside an **Iteration** node and marks where the sub-flow begins. On the canvas it is the small highlighted node inside the larger Iteration block. ## What it provides [#what-it-provides] It represents the item being processed in that pass of the loop, and exposes two variables to the inner nodes: | Variable | Content | | -------- | ---------------------------------------------------- | | `item` | The current item of the list the Iteration received. | | `index` | The item's position, starting at zero. | ```text Summarize the contract below in up to three sentences. {{ inicio_da_iteracao.item }} ``` ## Connect the inner logic [#connect-the-inner-logic] To build the sub-flow, click the handle to the right of the start node and add the next node. Whatever you connect there runs once per item. An LLM node inside the loop runs once per item. A list of 200 elements means 200 model calls, with the corresponding cost. ## Outside the loop [#outside-the-loop] The `item` and `index` variables only exist inside the Iteration. Nodes placed after the block can't reach them. To carry results outside, use the Iteration node's **Output variables**, which gather the individual results into a new list. ## Next steps [#next-steps] * Understand the full loop in [Logic](/en/docs/user-guide/workflows/nodes/logic). * See the two ends of the flow in [Input](/en/docs/user-guide/workflows/nodes/io/input). # Output (/en/docs/user-guide/workflows/nodes/io/output) The **Output** node defines the answer that goes back to the person who ran the flow, or to the system that called it through the API. A flow without an Output node runs to completion and delivers no result at all. ## Declare the fields [#declare-the-fields] On the canvas, the node shows the keys that will be returned. The format follows the flow's purpose: * **A single text field** suits a conversational flow, with a single answer. An `answer` field is usually enough. * **Several fields** suit a data automation. An extraction flow can return `summary`, `status` and `extracted_data` separately. Separate fields are what let another system consume the result without having to interpret free text. ## What doesn't go through the output [#what-doesnt-go-through-the-output] Everything the flow produced is recorded in the run, step by step, even what wasn't declared here. When you investigate an incomplete result, the run log shows what each node returned. Data that exists there but doesn't show up in the result is a field missing from this node, not a node that failed. ## More than one output [#more-than-one-output] A flow with branches can have one Output node per branch. Each path delivers its own result, and only the branch actually taken returns something. The alternative is to bring the branches together in an **Aggregation** node before a single Output, which keeps the flow's contract stable. ## Next steps [#next-steps] * See where the data comes from in [Input](/en/docs/user-guide/workflows/nodes/io/input). * Bring branches together before the output in [Logic](/en/docs/user-guide/workflows/nodes/logic). # LLM (/en/docs/user-guide/workflows/nodes/llm) The **LLM** node is where the flow uses an AI model. It processes natural language: it classifies, summarizes, extracts information from free text and generates content. It is the most expensive node on the canvas, because every run consumes tokens. ## Choose the model [#choose-the-model] The side panel lists the models enabled in the workspace, under **Settings › Models**. A workspace with no models enabled doesn't let you configure this node. Different LLM nodes in the same flow can use different models. It is common to use a cheap model to classify and a better one to write the final text. ## Write the prompt [#write-the-prompt] The prompt is built with variables from earlier nodes, in the `{{ node.field }}` format. The `/` key opens the menu of variables available at that point in the flow. ```text Classify the request below into one of the categories: refund, exchange, question. Answer only with the category, without explanation. Request: {{ entrada.mensagem_cliente }} ``` If the next node consumes this one's output, be explicit about the format. A prompt that doesn't constrain the answer returns free text, and the Condition or Code node that follows can't handle it. ## Combine with knowledge [#combine-with-knowledge] An LLM node on its own answers with what the model knows. To answer from the company's documents, put a **Vector database** node before it and inject the retrieved passages into the prompt. That pair, search followed by prompt, is what implements RAG inside a Workflow. The equivalent in an Agent is attaching Collections to it. ## Cost [#cost] This node's consumption shows up in the workspace's Observability, attributed to the chosen model. Flows with an LLM node inside an Iteration multiply the cost by the size of the list. A list of 200 items means 200 calls. ## Next steps [#next-steps] * Retrieve knowledge before the prompt in [Documents](/en/docs/user-guide/workflows/nodes/documents). * Repeat the same logic over a list in [Logic](/en/docs/user-guide/workflows/nodes/logic). # Aggregation (/en/docs/user-guide/workflows/nodes/logic/aggregation) The **Aggregation** node unifies variables from different branches into a single output. It doesn't concatenate or add. It evaluates the sources in order and returns the **first valid value** it finds. ## How it works [#how-it-works] 1. You provide a list of sources in order of priority. 2. The node tests the first, then the second, and so on. 3. When it finds a valid value, it stops and returns that result. 4. An empty source makes the flow move on to the next one automatically. This behaves like a chain of fallbacks, not a merge. To combine content from several sources into a single text, the path is an LLM node receiving all of them in its prompt. ## Typical use [#typical-use] The natural place for this node is after a **Condition**. Each branch produces its own result, only one of them ran, and the Aggregation collects whatever was actually filled in. This keeps the flow's contract stable: whichever path was taken, the Output node always receives the same variable. ## Unstructured output [#unstructured-output] Returns a single value: the first valid source in the list. ```json { "config": { "assign_variables": [ "{{primary.result}}", "{{secondary.result}}", "{{fallback.value}}" ] } } ``` The result is the content of the first of those three that has a value. ## Structured output [#structured-output] Returns a set of fixed fields. You declare the fields in `output_schema`, and each source becomes an object with those fields. ```json { "config": { "assign_variables": [ { "result": "{{branch1.result}}", "status": "{{branch1.status}}" }, { "result": "{{branch2.result}}", "status": "{{branch2.status}}" } ], "output_schema": ["result", "status"] } } ``` ## In the side panel [#in-the-side-panel] **Add** includes new input sources. The order of the list is the order of priority, and the first is the most important. The structured output switch is in the same panel, and turning it on changes the sources' format from a simple value to an object. ## Next steps [#next-steps] * See the node that opens the branches in [Condition](/en/docs/user-guide/workflows/nodes/logic/condition). * Declare the final result in [Output](/en/docs/user-guide/workflows/nodes/io/output). # Condition (/en/docs/user-guide/workflows/nodes/logic/condition) The **Condition** node evaluates the data it received and routes execution down one path. It is the only node with **multiple outputs** on the canvas, one per branch. It handles the "if the customer asked for a refund, go this way; otherwise, go that way" case. ## How evaluation happens [#how-evaluation-happens] 1. The node evaluates the condition groups from top to bottom. 2. The **first** true group determines the path taken. 3. Evaluation stops there. The other branches don't run. The order of the groups decides the result. A broad condition placed at the top catches cases that a more specific condition further down will never get to evaluate. In practice, this means writing the most restrictive conditions first and leaving the most generic one for last. ## Build the branches [#build-the-branches] Each output of the node on the canvas corresponds to a condition group. Connect each one to the part of the flow that should run in that case. Parallel branches don't see each other. To bring the results together afterwards, use an **Aggregation** node. ## The default case [#the-default-case] Always have a branch for whatever didn't match any condition. Without it, unexpected input makes the flow end without going down any path, and the result comes out empty with no visible error. ## Next steps [#next-steps] * Bring the branches together in [Aggregation](/en/docs/user-guide/workflows/nodes/logic/aggregation). * See which branch was taken in [Runs](/en/docs/user-guide/workflows/runs). # Overview (/en/docs/user-guide/workflows/nodes/logic) Three nodes control the route. They are what separates a linear flow from one that handles different cases. ## What each node does [#what-each-node-does] * **Condition**: evaluates condition groups from top to bottom and follows the first true one. The only node with multiple outputs on the canvas. * **Iteration**: creates a sub-flow and runs the inner nodes once per item of a list. * **Aggregation**: evaluates sources in order and returns the first valid value. ## How they combine [#how-they-combine] Condition opens branches, Aggregation closes them. That pair keeps the flow's contract stable: whichever path was taken, the Output node always receives the same variable. Iteration is independent of the other two and usually appears right after a node that returns a list, such as the File extractor. ## The cost of repeating [#the-cost-of-repeating] Each node inside an Iteration runs once per item. An LLM node over a list of 200 elements means 200 model calls. Branch the flow, and why the order of the groups decides the result. Repeat a section over each item and collect the results. Pick the first valid value, in simple or structured mode. # Iteration (/en/docs/user-guide/workflows/nodes/logic/iteration) The **Iteration** node processes lists item by item, applying the same logic to each. Unlike other nodes, it creates a **sub-flow**: on the canvas it shows up as a larger block, with nodes drawn inside it. ## The cycle [#the-cycle] 1. **Input**: receives a list variable, such as `{{ extrator_arquivos.contents }}`. 2. **Processing**: runs the inner nodes once per item. 3. **Output**: gathers the individual results into a new list. The input has to be a list. Pointing it at a single value makes the node fail at run time. ## Inside the loop [#inside-the-loop] The **Iteration start** node appears automatically inside the block and provides `item` and `index` to the inner nodes. A typical chain connects the Iteration start to an LLM node whose prompt uses `{{ inicio_da_iteracao.item }}`. ## Output variables [#output-variables] This is where you declare what leaves the loop, with two fields: * **Output name**: the name of the new list, for example `summaries`. * **Source variable**: which piece of the sub-flow's data feeds each position, usually the inner LLM node's answer. Without declaring output variables, the loop runs and nothing reaches the following nodes. Each node inside the loop runs once per item. An LLM node over a list of 200 elements means 200 model calls. Estimate the cost before releasing the flow to the team. ## Next steps [#next-steps] * Understand the inner node in [Iteration start](/en/docs/user-guide/workflows/nodes/io/iteration-start). * See a complete batch flow in [Extract data from documents in bulk](/en/docs/user-guide/guides/document-extraction). # Runs (/en/docs/user-guide/workflows/runs) Each execution of a Workflow produces a **run** with its own record: the input received, the steps taken, what each node returned and the final result. This is the practical difference between a Workflow and an Agent when you investigate. An Agent gives an answer; a Workflow leaves a trail of how it got there. ## What a run records [#what-a-run-records] * **Input**: the values the person filled in on the form. * **Intermediate steps**: what each node received and produced, in execution order. * **Output**: the result shown to the person who ran it. * **Errors**: which node the run stopped at, when it stopped. ## Investigate a wrong result [#investigate-a-wrong-result] The trail makes investigation mechanical. Walk the nodes backwards until you find the first one whose output is already wrong. The problem is in that node or in the input it received. The two most common cases: * **The vector node returned nothing**: the Collections configured in it are empty, or the documents never reached **Active**. * **The LLM node returned something outside the expected format**: the node's prompt isn't explicit about the format, and the next node can't consume the output. ## When a run fails [#when-a-run-fails] A failure stops the flow at the problematic node and records the error there. The following nodes don't run. Failures in integration nodes are usually external: an expired credential, an endpoint that is down, a domain that isn't allowed. Failures in logic or code nodes are usually configuration. A Send email node fails at run time, not at build time, when the workspace has no SMTP credential configured. The canvas accepts the flow; it is the run that reports it. ## Version that ran [#version-that-ran] A run keeps the version of the Workflow that was published at the time it ran. This matters when you investigate an old case: the flow may have changed since then, and what you see on the canvas today isn't necessarily what ran. ## Next steps [#next-steps] * Adjust the flow in [Build on the canvas](/en/docs/user-guide/workflows/build). * See the model consumption of these runs in [Observability](/en/docs/user-guide/monitoring/observability). # What's new (/en/docs/whats-new) Each release brings new features, fixes and optimizations across the **Admin**, **Workflows** and **Chat** modules. Versions are listed from newest to oldest. ## v4.0.0: Platform Unification [#v400-platform-unification] August 24, 2026 An update focused on unifying the **Admin** and **Chat** experience, simplifying the agent and collection creation flows, improving visibility into platform usage, and a batch of general visual adjustments. ### Highlights [#highlights] * **Unified login and navigation**: Admin and Chat now share the same login and a single navigation bar, with both modules' tabs side by side. * **Observability**: The "Usage Logs" page gave way to the **Observability** page, with better visualization of usage information (such as usage per model), more specific filters and traces for detailed execution tracking. * **Quotas**: New control of AI provider usage quotas, configurable at the organization, workspace and user levels. * **Simplified Collections**: Knowledge Sources and Collections were merged: now there are only Collections, where files and connectors are added directly, with a simpler form. * **New agent creation form**: Now on a single page, organized into sections (accordion), much easier to fill in and review. ### Admin [#admin] * Improved organization switcher menu and settings/user dialog. * New **API Keys** screen in the user settings. * General visual adjustments: alignment, standardized colors, new icons and more consistency across screens. * "Projects" are now called **Workspaces** across the platform. * Better rendering of code blocks. ### Chat [#chat] * Updated look to follow the same pattern as Admin. * The initial message field is now centered on the screen, expanding as you type; message suggestions now appear only when a knowledge base (RAG) is attached. * Improved chat information sidebar. ### Bug fixes [#bug-fixes] * Fixes for several general bugs and minor visual adjustments across various screens. *** ## v3.3.0: SuperAgents and Native Integrations [#v330-superagents-and-native-integrations] July 7, 2026 A release with major advances in **SuperAgents**, **native integrations**, **MCP security** and several experience improvements in **Chat**, **Workflows** and **Admin**. ### Highlights [#highlights-1] * **SuperAgents**: New ability to register and configure **SuperAgents**, with a dedicated interface both for configuration and for use in chat, orchestrating multiple agents/flows. * **Native Integrations**: The platform now offers native integrations (e.g. **Jira**, **GitHub**, **DuckDuckGo**), usable both in Agents and in dedicated nodes inside Workflows. * **MCP Security (MCP Scanner)**: Introduction of a protection layer for MCP servers, with security checks based on static rules and semantic evaluation, including security status (`VERIFIED`, `UNVERIFIED`, `UNSAFE`) and on-demand revalidation. ### SuperAgents and Agents [#superagents-and-agents] * Registration and configuration of **SuperAgents** in the organization and project. * Front-end interface for configuring and using the SuperAgent. * Per-user favoriting/pinning of agents in chat. * Fix in sub-agent selection, which listed the agent itself. ### Integrations [#integrations] * New native integrations: **Jira**, **GitHub** and **DuckDuckGo**. * Interface for using integrations when creating/editing agents. * New **integration nodes** in workflows. ### MCPs and Security [#mcps-and-security] * **MCP Scanner:** configuration via org settings (YARA + LLM as Judge), security status and a revalidation button in the MCP registry. * Support for **Resources**, **Prompts**, **Progress** and **Elicitation** in the MCP client. * Support for **MCP App** in chat. * Security fixes. ### AI Studio (Workflows) [#ai-studio-workflows] * **Workflow versioning and lifecycle:** publishing, unpublishing, republishing and listing versions. * Workflow status indicator (draft, published or with pending changes) inside the studio. * Running the **latest published version** of the workflow in chat/agents. * **Cancelling** workflow runs, with a cancel button. * New **code suggestion** button in the execution node. * **File/artifact creation** node (PDF, Word, Markdown) for sending by email. * Fixes in the HTTP nodes (timeout and query parameters via variables), code executor and aggregation node. ### RAG and Knowledge [#rag-and-knowledge] * **Hybrid semantic search** applied to file search in collections. * Ability to edit context length, cost and other settings for custom provider models. * Fixes in connectors (association/dissociation, status, Google Drive) and file extraction. ### Providers and Models [#providers-and-models] * Support for the **Vertex AI** provider. * Full support for **custom providers** and the **Responses API**. ### Chat [#chat-1] * Pagination and optimized loading of a chat's message history (including long chats and chats with many images). * Pinning the user's most used chats and better sorting of old chats. * Pre-filling a chat message through a custom URL. * Fixes for scrolling, flicker before streaming, message editing and branch switching. ### Admin and Governance [#admin-and-governance] * Configuration of **usage quotas** (tokens and real cost) for projects. * Links to documentation on admin pages to make them easier to use. * Fixes in member import/export (CSV, roles). ### Security [#security] * Security fixes stemming from pentests. *** ## v3.2.0: Customization [#v320-customization] June 8, 2026 A release with improvements in the **Admin**, **AI Studio (Workflows)**, **Chat**, **Templates**, **MCPs** and **Governance** modules. This version brings native registration of **custom providers**, expanded support for **remote MCPs**, creating assistants from templates, a library of reusable prompts, a guided onboarding tour and new security, isolation and quota controls. ### Highlights [#highlights-2] * **Custom Providers**: Native registration of custom AI providers, with configuration of `base_url`, `api_key` and syncing of the available models directly with the provider's catalog. * **MCP Evolution**: Expanded MCP protocol support, including **Resources**, **Prompts**, an OAuth tool registry and better compatibility with remote MCPs. * **Assistant Templates and Prompt Library**: Creating assistants from templates, configuration hints and a library of reusable prompts. * **Visual Customization**: Organization administrators can now set the chat color scheme for all users in the organization, enabling a visual identity aligned with the company. * **Governance, Security and Quotas**: Authentication improvements, per-organization isolation and usage quota control by tokens and cost at the project level. ### Admin [#admin-1] * **Custom providers:** Registration of custom AI providers. * **Usage quotas:** Configuration of quotas by tokens and monthly cost. * **Project dashboards:** Clearer, friendlier metrics. * **Charts:** Adjustments to the assistants, users, feedback and usage charts. * **Visual improvements:** Adjustments to modals, dark mode, headers, filters and cards. ### AI Studio (Workflows) [#ai-studio-workflows-1] * **Visual Markdown editor:** New editor for prompts and instructions. * **Markdown:** Improvements in editing and viewing. * **Disabled providers:** Better handling of workflows that depend on disabled providers. * **Validation:** Improved validation with hints for templates and dependencies. ### Templates and Prompts [#templates-and-prompts] * Creating assistants from templates. * Hints indicating the required models, MCPs, collections and credentials. * New library of reusable prompts. * Button to copy prompts directly on the platform. ### MCPs and Integrations [#mcps-and-integrations] * Support for **Resources** in the MCP client. * Support for **Prompts** in the MCP client. * Improvements in the OAuth tool registry and compatibility with remote MCPs. ### Chat [#chat-2] * General interface improvements. * Support for a **global assistant**. * Persistence of the last assistant used per workspace/organization. * Support for **public projects** in chat. * Improvements for opening buttons in a new tab. ### Onboarding [#onboarding] * Initial implementation of a guided tour. ### Governance and Security [#governance-and-security] * Adjustments stemming from internal security validations and pentests. * Improvements in authentication, per-organization isolation and quota control. #### Bug fixes [#bug-fixes-1] * Fixes in workflows, assistants, templates and MCPs. * Visual fixes in Admin and Chat. * Fixes in CSV export, filters and modals. * Fixes in providers, Azure and Bedrock models. * Fixes for chat failures caused by invalid or missing tools. * Fixes in onboarding and in the behavior of public projects. *** ## v3.1.0: Templates [#v310-templates] April 23, 2026 A release with improvements in **Admin**, **AI Studio (Workflows)** and **Chat**: centralized workflow templates, support for the **Anthropic** provider, a new **roles** system and optimizations in **RAG** (hybrid search). ### Highlights [#highlights-3] * **Sub-agents**: New feature for building multi-agent structures, where an orchestrator agent can call sub-agents and assistants. * **Centralized Template System**: Dedicated infrastructure for managing workflow templates, letting you reuse flows created by the AUMO team for your use case. * **New Anthropic Provider**: Full support for the Anthropic provider, expanding the model options on the platform. * **Performance and Stability Improvements**: Significant optimizations to the search system (RAG). ### Admin [#admin-2] * **Sub-agent configuration:** Assistants and AI flows can be enabled as sub-agents and become available as MCPs to other assistants and flows. * **Role management:** New permission system with project-oriented roles (Auditor, Owner, Curator, Editor, User). * **AUMO Assistant configuration:** Organization-level option to enable or disable the side chat in the admin panel for questions about using the platform. * **Disabling providers:** Turn off AI providers without deleting them, removing the API key from the database. * **Logo in workflows:** Custom logo for AI Studio workflows. * **Advanced parameters:** Temperature and `max_tokens` controls in the assistants' advanced settings. * **Smart redirect:** When opening **Chat** from admin, the user goes to the right project instead of the last project visited. * **Direct link to chat:** Button to open the corresponding chat from the assistant. * **Cache invalidation:** Improvements to the organization logo cache. * **Models JSON update:** Removal of deprecated or inaccessible models from the Fireworks AI, Bedrock, OpenAI and AUMO providers. * **Terms of use:** Acknowledgment and tacit acceptance of the Terms of Use with a technical record for legal validity. #### Bug fixes (Admin) [#bug-fixes-admin] * Scrolling in the add-files modal in collections. * Adding users to the workspace. * Modals on small screens (laptops). * Assistant icons that disappeared. ### AI Studio (Workflows) [#ai-studio-workflows-2] * **Template system:** Create a flow from a template provided by the AUMO team. * **Conflict fix:** Simultaneous workflow editing without false conflicts. * **Scheduling:** Fix in workflow scheduling. * **Validation:** Additional validations, including types. * **Publishing:** Publishing system for workflows and assistants. ### Chat [#chat-3] * **Hybrid search:** Migration in Qdrant to hybrid search in RAG, improving performance. * **Stop message button:** Interrupt the assistant's response streaming. * **Open in new tab:** Chat and admin buttons support middle-click or right-click to open in a new tab. * **Message editing:** Edit messages already sent to generate a new answer. #### Fixes and performance (Chat) [#fixes-and-performance-chat] * Visual bug fixes. * Pointer cursor on the chat sidebar icons. * Fewer unnecessary re-renders in chat. *** ## v3.0.0: Governance [#v300-governance] February 11, 2026 A release focused on **corporate MCP governance**, **Custom Guardrails** and **new automation nodes** in AI Studio. Now only Organization Admins and Superadmins can authorize which MCPs will be available for use in projects, ensuring compliance and centralized control. The Guardrails feature was expanded to allow customizing the types of information that must not be sent to AI models, with anonymization and blocking options. New **Email** and **Code Execution** (Python and Node.js) nodes were also added to Workflows, along with the ability to schedule flow runs, significantly expanding the automation possibilities. ### Highlights [#highlights-4] * **Complete MCP Governance**: A robust governance system at the organization level. MCPs with OAuth (Google) now work with full authentication. * **Customizable Guardrails**: A system for customizing guardrails at the organization level. You can now choose how the platform behaves when various types of information show up in chat, such as names, CPFs, payment data and many others. * **New Workflow Nodes**: An Email node for automatic sending and a Code Execution node in Python and Node.js. ### Admin [#admin-3] * **Infinite pagination:** Infinite scroll in the Assistants, Collections, Knowledge Sources and MCPs lists, improving performance and the browsing experience. * **Customizable information display:** All lists now open in card view by default, with the option to switch to a table. * **Model filters:** Added a filter to model selection when creating projects and in the project's "Models" menu. * **Improvements to adding members:** Fix in listing and searching members when adding users to the workspace, with pagination support for large organizations. * **Dependency warnings:** When trying to delete an MCP, the system now reports which workflows and assistants are using it. * **Orphan assistants:** Visual identification of assistants that use models removed from the workspace. * **Form fixes:** Adjustments and fixes in the Collection creation and editing form. * **Improved error messages:** Login errors and other operations now show more informative, targeted messages. * **Customizable Guardrails:** In the organization settings, you can now detail how guardrails work for each data type. ### MCPs [#mcps] * **Organization-managed MCPs:** MCPs are now managed in the organization. Only MCPs authorized in the organization can be added to projects, and only Organization Admins and Superadmins can decide which MCPs a project can use. * **Editing MCPs:** You can now edit MCP server settings after creating them in the organization. * **Support for MCPs with OAuth:** MCPs with Google OAuth now work with authentication. ### AI Studio (Workflows) [#ai-studio-workflows-3] * **Copying workflows:** You can copy workflows between different projects or within the same project. * **Import by JSON:** New option in the "New Workflow" button to create workflows from templates or import them via JSON. * **Scheduled runs:** Scheduled workflow runs using CRON expressions. * **Built-in documentation:** Links to workflow documentation directly on the platform. * **MCP iterations parameter:** New parameter in the LLM node to control the number of MCP call iterations. * **New Email Node:** A new node that sends an email according to the flow. * **New Code Execution Node:** Allows running code in Python and Node.js. ### Chat [#chat-4] * **Improved Markdown formatting:** Significant improvement in Markdown rendering, including lists, headings, code and tables with hyperlinks. * **Color improvements:** Swapped the sidebar and background colors to improve the experience. * **Optimized scrolling:** Adjustments to message scrolling behavior for a better reading experience. * **Rerun button for workflows:** Added a button to run workflows again from previous runs. * **File limit tooltip:** Visual indication of file upload limits. * **Consistent icons:** Fixed issues with assistant icons that disappeared. * **Visual and UX improvements:** Pointer cursor in the sidebar and improved sidebar icons. * **Responsive alignment:** Alignment fixes for smaller screens (laptops). * **New Copy MCP Result button:** You can now copy the result of an MCP call to the clipboard. * **Multi-chat bug fixes:** Better experience when sending messages in several chats at the same time. *** ## v2.6.0: Analytics [#v260-analytics] December 19, 2025 A release focused on **metrics and analytics**, bringing a new metrics view for projects and organizations. It also includes new knowledge source sync settings, organization logo customization and provider credential verification at creation time. ### Admin [#admin-4] * Bug fixes and visual improvements. * **Knowledge source:** you can now configure syncing in minutes, hours or days. * Organization logo customization. * **Permission change:** only organization ADMIN and SUPERADMIN can change the models available to workspaces. * Character limit on prompts when creating assistants, so they don't exceed the models' limit. * **Providers:** credentials are verified when creating a provider; it can't be created if the API key isn't valid. * New screen for viewing project and organization metrics, with a history of the actions users performed. * The assistant's visual icon can now be set by the user. ### AI Studio (Workflows) [#ai-studio-workflows-4] * Description fields added to the flow's inputs. * Real-time AI flow execution with a visual indication of the current step. * New iteration (loop) node. * New API call node. * Visual restructuring of AI flow editing: node settings now live in a menu on the right. ### Chat [#chat-5] * Sending images in chat to models with vision. * Initial message suggestions in chat personalized according to the accessible documents. *** ## v2.5.0: Performance [#v250-performance] November 10, 2025 A release focused on **performance and connectors**. It includes automatic personal project creation, improvements to the SharePoint, Google Drive and OneDrive connectors, drag-and-drop support in collections, a new IF node in Workflows and performance optimization in Chat. ### Admin [#admin-5] * Bug fixes. * Automatic personal project creation for Admin/Superadmin (with a default assistant). * Display of permissions by profile (role) in the panel. * Improvements in the feedback list. * **Connectors:** * **SharePoint:** support for multiple URLs and an updated card with more data. * **Google Drive:** clickable cards with a link/type icon, folder name display, option to add individual files. * **OneDrive:** backend support and front-end adjustments. * **Web:** clearer limits and explanatory texts. * **Collections:** download/view extracted content and drag-and-drop files into collections. * **MCPs:** A list of MCPs made available for simpler, easier installation. * More intuitive display of the `{context}` tag in the prompt when creating and editing assistants. * Organization and project settings menu. * Display of AI model details when creating assistants. ### AI Studio (Workflows) [#ai-studio-workflows-5] * IF node and visual/UX adjustments. * REST API node. * Duplicate a workflow and select outputs from previous nodes in the Output Node. * Layout cleanup (sidebar removed). * Undo / Redo with `Ctrl+Z` and `Ctrl+Shift+Z`. * Support for asynchronous workflow execution via API. ### Chat [#chat-6] * Fixes for bugs specific to certain models. * More explanatory error messages. * New table component in answers. * More responsive "Thinking" and "Running tool" indicators. * Clearer error messages and better formatting (line break after tools; support for `
` in markdown). * Drag-and-drop of files in chat. * User settings screen. * Performance optimization for listing assistants and sending messages. *** ## v2.4.0: Collaboration [#v240-collaboration] September 29, 2025 A release focused on **collaboration and integrations**. Highlights include the SharePoint integration, MCP support in the Workflow LLM node, new forms for creating AI providers, and tool results shown directly in chat. ### Admin [#admin-6] * Example of how to access the models API. * SharePoint integration. * MCPs in the LLM node of the AI Studio Workflow. * New forms for creating AI providers. * The admin chat viewer now shows tool calls and uploaded files. * The system now remembers the last organization and project used. * New feedback screens when creating Atlassian and SharePoint credentials. * New RAG feature that returns full documents. * Bug fixes and general improvements. ### Chat [#chat-7] * Tool results show up directly in chat. * Ability to add comments when giving feedback. * Button to copy user messages. * Chat now remembers the last organization and project used. * Viewing the specific passages returned by the RAG system. * Paste images and files directly from the clipboard (`Ctrl+V`). * Screens for when something isn't found and for generic errors. * Bug fixes and general improvements. *** ## v2.3.0: Integration [#v230-integration] September 12, 2025 A release focused on **MCP integration and content indexing**. It includes configuring MCPs directly in AI Studio, registering MCPs via JSON, a website indexer that extracts multiple pages and tool responses shown in chat. ### Admin [#admin-7] * Centralized models in Admin (internal organization improvement). * Configuring MCPs directly on the AI Studio page, linked to the LLM node. * **Registering MCPs via JSON:** add multiple MCPs just by copying and pasting the JSON. * **Website indexer:** option to extract pages beyond the starting one, allowing more complete content to be indexed. ### Chat [#chat-8] * New fallback pages to handle error scenarios. * Tool responses: access to the responses returned by the MCP-linked tools the model used. * Display of the MCPs associated with an assistant. *** ## v2.2.0: Intelligence [#v220-intelligence] September 2, 2025 A release focused on **intelligence and automation**. Highlights include real-time display of the tools/MCPs called by assistants, a new page for running AI agent runs, and admin panel improvements including the new OCI (Oracle) provider and importing members via CSV/JSON. ### Chat [#chat-9] * Assistants with more knowledge about the platform and about what they can and can't do. * The chat name is now set when the user sends the message. * Real-time display of the tools/MCPs called by assistants. * New page for running and viewing runs of AI agents (created in AI Studio). * Fix for bugs related to message feedback. ### Admin [#admin-8] * System compliant with Google for Google Picker authentication (creating a Drive knowledge source). * New supported provider: **OCI (Oracle)**. * Knowledge Collections' name and description can now be edited. * Better view of Projects in which the user has the Basic role. * Bug fixes in the MCP creation and editing form. * Searching organization and project members through the interface. * Improved user experience when editing assistants and agents. * Importing new organization and project members through `.CSV` or `.JSON` files. * New button to export all of a project's feedback. * Ability to regenerate the API Key and view it for API integrations. *** ## v2.1.0: Connectivity [#v210-connectivity] July 20, 2025 A release focused on **connectivity and user experience**. It includes improvements to conversation history, a visual restructuring of chat, a new CPF and CNPJ Extractor node in AI Studio, and several bug fixes and visual improvements. ### Chat [#chat-10] * Informative toasts in Portuguese. * Interface adjustments that prevent unexpected changes to the assistant and project while uploading files. * Visual bug fixes. * Prevention of duplicate file uploads. * Improved conversation history management, allowing quick search for previous chats, projects and assistants. * Visual restructuring of the chat color scheme and of code snippets in assistant answers. * New button to copy code snippets, markdown, CSV, etc. from the assistant's answer. ### Admin [#admin-9] * Visual adjustments to the feedback charts, with colors aligned to the feedback's meaning. * Fixes in the provider list. * Fixes when displaying the assistant type (with or without RAG). * In AI Studio, new validations and initial checks in internal flows (nodes). * New AI Studio node: **CPF and CNPJ Extractor**. * When creating connectors, you can now type or paste a Drive folder ID instead of choosing it through the Google Picker. *** ## v2.0.0: Foundation [#v200-foundation] August 18, 2025 The platform's base release, focused on **foundation and stability**. Highlights include support for uploading many file types in chat and AI Studio, full MCP support in assistants, a new Oracle provider and several quality-of-life improvements in AI Studio. ### Chat [#chat-11] * Visual adjustments to login and colors. * Fix for bugs related to browser cookies. * Support for uploading many file types in chat: audio, images with text, Office files from different versions, code files and more. ### Admin [#admin-10] * New chart on a project's Dashboard screen: Most used assistants. * Support for a new AI provider: **Oracle**. * New feature to edit a credential. * New organization page listing basic information about all projects, even those the ADMIN, SUPERADMIN or CONTROLLER user isn't part of. * New warning to the user when trying to create a project with a slug that already exists (even if deleted). * Full MCP support in assistants: create MCPs, associate them with assistants and use them in chat. * Quality-of-life improvements in AI Studio: error warnings when something is misconfigured, indicating what needs to be fixed. * The output of file extraction and CPF nodes in an AI Studio workflow can be connected directly to the output node. * Ability to customize the field names of the input and output nodes of AI Studio workflows. * Support for uploading many file types in AI Studio: audio, images with text, Office files from different versions, code files and more. * Bug fixes in the Jira and Confluence knowledge sources and in the routine tasks that update collections.