---
title: "Operações `mentor`"
---

<!-- i18n: source=docs/reference/operations/mentor.md blob=7893c77086ab087e1a7a997a0a406af5c6c3016a model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/mentor.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/mentor.md), which is authoritative.

<a id="mentor-operations"></a>

Os campos exatos que cada operação `mentor.*` recebe e retorna.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Toda op é `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue; em uma chamada HTTP sem token em um servidor de usuário único, vale a org da instalação em toda op exceto `code.*` e `tracker.*` (que mantêm a do seu plano), e [em algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) também o namespace e o agente; veja [identidades e namespaces](/docs/pt-BR/concepts/identities-and-namespaces). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

<!-- prettier-ignore-start -->

<a id="mentorbrief"></a>

## `mentor.brief`

O perfil de uso de um agente e as dicas do armazenamento.

`POST /v1/mentor.brief` · MCP `loom_mentor_brief` · role `viewer` · read

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou escreve. |
| `agent` | `str` | `''` | O agente que escreve ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `window_seconds` | `int` | `604800` | Até onde no passado chega a leitura do ledger, em segundos; de 1 hora a 90 dias. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `org` | `str` | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | O namespace que a op lê ou escreve. |
| `agent` | `str` | O agente que escreve ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `window_seconds` | `int` | A janela sobre a qual o perfil foi calculado, em segundos; um perfil servido do cache mantém a janela com que foi calculado. |
| `computed_at` | `datetime` | Quando o perfil foi calculado (UTC); anterior à chamada quando servido do cache. |
| `sessions` | `int` | Sessões distintas nomeadas pelo cliente deste agente na janela (`-` e `*` não contam). |
| `usage` | `dict[str, int]` | Chamadas por operação feitas por este agente na janela. |
| `planes` | `list[MentorPlane]` | Todos os planos que o mentor conhece, com as chamadas deste agente a cada um e se está disponível. |
| `hints` | `list[MentorHint]` | As regras que dispararam para este agente, cada uma com as contagens que a dispararam; vazia quando nenhuma. |
| `adoption` | `list[MentorAdoption]` | Por código de dica, as sessões em que foi exibida e em que foi seguida, das mais exibidas para as menos; vazia quando nenhuma dica chegou ao agente ou a leitura falhou. |
| `usage_evidence` | `list[UsageRung]` | O uso do Loom pelo agente na janela, um degrau cada, da afirmação mais fraca para a mais forte: de uma chamada feita a uma execução avaliada. |
| `ledger_from` | `datetime \| None` | A linha mais antiga do ledger deste agente na janela, de qualquer tipo; None quando não há nenhuma ou a leitura falhou. |
| `ledger_retention_days` | `int \| None` | Dias que a retenção configurada mantém as linhas do ledger de chamadas deste namespace; 0 mantém até serem apagadas, None quando a leitura falhou. |
| `agents` | `list[str]` | Os escritores do namespace na janela, dos mais ativos para os menos; o brief usa o primeiro por padrão quando quem chama não tem nome de agente próprio (o painel) — `agent_defaulted` indica isso. |
| `agent_defaulted` | `bool` | True quando quem chamou não informou um agente real e o brief escolheu o escritor mais ativo em `agents`. |
| `skipped` | `list[str]` | Fatos que o brief não conseguiu ler, no formato "etapa: motivo". |
| `healthy` | `bool` | Nenhuma dica de aviso ou crítica. |

<a id="mentorguide"></a>

## `mentor.guide`

O guia do agente que este servidor distribui; o mesmo para todo chamador.

`POST /v1/mentor.guide` · MCP `loom_mentor_guide` · role `viewer` · read · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | `''` | O tenant (primeiro elemento da tupla de identidade). |
| `part` | `Literal['skill', 'reference', 'all']` | `'skill'` | Qual parte: `skill` (o ciclo e as regras, o padrão), `reference` (cada plano) ou `all`. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `version` | `str` | A versão do guia (`metadata.version` de skills/loom/SKILL.md). |
| `part` | `Literal['skill', 'reference', 'all']` | A parte retornada, conforme solicitada. |
| `text` | `str` | O guia em Markdown, sem o frontmatter da skill. |

<!-- prettier-ignore-end -->
