> ## Documentation Index > Fetch the complete documentation index at: https://docs.zas.red/llms.txt > Use this file to discover all available pages before exploring further. # Referência do agente do Zas: ferramentas MCP e erros > Cada ferramenta que o servidor MCP do Zas expõe, cada código de erro, os arquivos que ele escreve em disco e os ajustes que mudam para onde ele aponta. Tudo que o servidor MCP `zas-agent` expõe, numa página só. | | | | -------------------- | --------------------------------------------------------------------------- | | Pacote | [`zas-agent`](https://www.npmjs.com/package/zas-agent) no npm | | Nome no registro MCP | `io.github.soke1556/zas-agent` | | Transporte | stdio | | Runtime | Node.js 22 ou mais novo | | Código | [github.com/soke1556/zas-agent](https://github.com/soke1556/zas-agent), MIT | ## Comandos ```text theme={null} zas-agent [--profile ] serve as ferramentas MCP por stdio zas-agent pair [--profile ] pareia este agente com uma conta do Zas [--kind claude_code|codex|other] [--host ] [--no-open] zas-agent telemetry [on|off] diz o que esta máquina reporta, ou muda zas-agent --version ``` Sem comando ele serve as ferramentas MCP, que é para isso que um harness o inicia. ## Ferramentas `channel` aceita o nome ou o id de um canal. Um nome precisa bater com exatamente um canal liberado. Com uma liberação só, todas as ferramentas que aceitam `channel` podem omitir, menos `zas_list_items` e `zas_get_item`, que sempre nomeiam o canal delas. ### `zas_status` Diz se a máquina está pareada e lista os canais para onde o agente pode mandar ou que ele pode ler. Também imprime a versão do pacote, o perfil e o estado da telemetria. Sem argumentos. ### `zas_pair` Pareia esta máquina com uma conta do Zas. A primeira chamada devolve uma URL para você abrir; uma chamada seguinte diz se você aprovou. Num perfil já pareado, a aprovação substitui o agente anterior. | Argumento | Tipo | Notas | | --------- | ---------------- | --------------------------------------------------------------------------------- | | `code` | string, opcional | O código que a página mostra quando o navegador não conseguiu alcançar a máquina. | ### `zas_send_file` Manda um arquivo da máquina para um canal liberado. Devolve o id do item, ou um id de trabalho quando a subida passa de um minuto. | Argumento | Tipo | Notas | | ----------------- | ------------------- | ------------------------------------------------------------------------------------- | | `path` | string, obrigatório | Caminho absoluto ou relativo do arquivo. | | `channel` | string, opcional | Nome ou id. Opcional com uma liberação só. | | `title` | string, opcional | Rótulo do item. Por padrão, o nome do arquivo. | | `expires_in_days` | inteiro, opcional | Quantos dias inteiros o item vive, mínimo 1. Omitido, ele usa a vida normal da conta. | Um canal em modo Direto recusa esta ferramenta com `direct_mode`. Ali vai `zas_send_direct`. Ela manda qualquer arquivo que o processo consiga ler, segredos incluídos. Veja [Recomendações](/pt-BR/agents/recommendations). ### `zas_send_note` Manda uma nota: texto simples, ou um trecho de código com a linguagem. | Argumento | Tipo | Notas | | ----------------- | ------------------- | -------------------------------------------------- | | `text` | string, obrigatório | O corpo da nota. | | `channel` | string, opcional | Nome ou id. Opcional com uma liberação só. | | `title` | string, opcional | Rótulo. Por padrão, a primeira linha. | | `lang` | string, opcional | Linguagem para o realce, por exemplo `ts` ou `py`. | | `secret` | boolean, opcional | Cobre o corpo até quem recebe abrir. | | `expires_in_days` | inteiro, opcional | Quantos dias inteiros o item vive, mínimo 1. | ### `expires_in_days` As duas ferramentas de envio aceitam, e ele só encurta a vida de um item. Um pedido mais longo do que o plano dá é respondido com o número do plano em vez de recusado, então pedir 100 dias dá cinco. O piso é um dia inteiro, porque o anel conta dias inteiros. Vale a pena para saída que amanhã já está velha: um log de build, uma rodada de testes, o print de uma correção. ### `zas_send_direct` Manda um arquivo pelo [Direto](/pt-BR/concepts/direct): uma transferência ao vivo, de aparelho para aparelho, para um canal liberado que está em modo Direto. Nada é guardado. Alguém precisa apertar **Receber** em outro aparelho dentro de dez minutos. A chamada espera um minuto e depois devolve um id de trabalho para consultar com `zas_jobs`. | Argumento | Tipo | Notas | | --------- | ------------------- | ------------------------------------------ | | `path` | string, obrigatório | Caminho absoluto ou relativo do arquivo. | | `channel` | string, opcional | Nome ou id. Opcional com uma liberação só. | Um canal que não está em modo Direto recusa esta ferramenta com `not_direct_mode`. ### `zas_receive_direct` Recebe nesta máquina um arquivo mandado pelo Direto. Espera a oferta, pega e escreve o arquivo em disco. Só num canal em modo Direto, e só com uma liberação que inclua **leitura**, porque escreve na máquina. | Argumento | Tipo | Notas | | --------- | ---------------- | -------------------------------------------------------------------------------------------------------- | | `channel` | string, opcional | Nome ou id. Opcional com uma liberação só. | | `dest` | string, opcional | Onde escrever o arquivo. Um diretório significa "dentro dele". Por padrão, um diretório temporário novo. | Nunca sobrescreve um arquivo existente. Esperar uma oferta pode levar dez minutos, então a chamada devolve um id de trabalho depois de um minuto. ### `zas_send_direct_fallback` Quando um trabalho de `zas_send_direct` falhou em voo, entrega o mesmo arquivo pela via confiável. O Zas cifra o arquivo nesta máquina e guarda só essa cópia cifrada por até 24 horas; ela não usa nada do seu espaço, e o aparelho que já pegou a oferta pode baixar depois. | Argumento | Tipo | Notas | | --------- | ------------------- | ------------------------------------------------------------- | | `job` | string, obrigatório | O id de trabalho que reportou o envio pelo Direto que falhou. | Isso deixa de ser Direto: os bytes cifrados passam pelo armazenamento. A descrição da ferramenta manda o modelo perguntar antes, porque a decisão é sua. ### `zas_receive_direct_fallback` Quando um trabalho de `zas_receive_direct` falhou em voo, baixa a cópia cifrada que quem mandou escolheu guardar. Só funciona se essa pessoa escolheu a via confiável para aquela transferência. O arquivo é decifrado nesta máquina e escrito no mesmo destino. | Argumento | Tipo | Notas | | --------- | ------------------- | ------------------------------------------------------- | | `job` | string, obrigatório | O id de trabalho que reportou o recebimento que falhou. | ### `zas_list_items` Lista os itens mais recentes de um canal. Precisa de uma liberação com leitura. | Argumento | Tipo | Notas | | --------- | ------------------- | -------------------------- | | `channel` | string, obrigatório | Nome ou id. | | `limit` | inteiro, opcional | De 1 a 50. Por padrão, 20. | ### `zas_get_item` Traz um item. Uma nota volta como texto; um arquivo é escrito em disco. | Argumento | Tipo | Notas | | --------- | ------------------- | -------------------------------------------------------------------------------------------------------- | | `channel` | string, obrigatório | Nome ou id. | | `id` | string, obrigatório | Id do item, como `zas_list_items` reporta. | | `dest` | string, opcional | Onde escrever o arquivo. Um diretório significa "dentro dele". Por padrão, um diretório temporário novo. | Nunca sobrescreve um arquivo existente. Um nome ocupado ganha um sufixo, e o caminho que volta é o que foi realmente escrito. ### `zas_jobs` Lista os envios e as transferências pelo Direto que este servidor começou, do mais novo para o mais velho, com a fase que cada um alcançou e como terminou. Um `job_id` de um envio longo é resgatado aqui, e um trabalho terminado guarda o resultado. ## Códigos de erro O agente responde com um conjunto fechado. Qualquer coisa vinda de uma rota que não esteja nesse conjunto vira `upload_failed` ou `network`, então um texto cru do servidor, ou um stack trace, nunca chega a um terminal. ### Pareamento e identidade | Código | O que significa | | ---------------------- | ---------------------------------------------------------------------- | | `not_paired` | Esta máquina ainda não está pareada. | | `identity_corrupt` | O arquivo de identidade em disco está danificado. | | `agent_revoked` | O dono revogou este agente. | | `agent_forbidden` | Isso só o dono da conta pode fazer. | | `pairing_expired` | O pareamento expirou. Pareie de novo. | | `pairing_cancelled` | O dono cancelou o pareamento. | | `pairing_not_approved` | Ninguém aprovou este pareamento ainda. | | `pairing_claimed` | Este pareamento já foi reclamado. | | `claim_mismatch` | O código não bate. | | `agent_limit` | A conta não comporta outro agente. | | `grant_limit` | O plano permite menos canais por agente do que este pareamento libera. | | `feature_disabled` | Os agentes não estão ligados para esta conta. | | `sign_in_failed` | O Zas não aceitou esta sessão de agente. | | `bad_signature` | O Zas recusou a assinatura deste agente. Pareie de novo. | | `missing_token` | Falta o token de sessão. Pareie de novo. | ### Canais e liberações | Código | O que significa | | ----------------- | -------------------------------------------------------- | | `grant_missing` | Este agente não tem acesso a esse canal. | | `send_forbidden` | Este agente não pode mandar para esse canal. | | `read_forbidden` | Este agente não pode ler esse canal. | | `direct_mode` | Esse canal está em modo Direto. Use `zas_send_direct`. | | `not_direct_mode` | Esse canal não está em modo Direto. Use `zas_send_file`. | | `key_stale` | A chave do canal mudou. Abra o Zas para atualizar. | ### Mandar e ler | Código | O que significa | | ---------------- | ---------------------------------------------------------------------------------------------------- | | `quota_exceeded` | A conta chegou ao limite de armazenamento. | | `rate_limited` | Envios demais seguidos. | | `file_too_big` | O arquivo passa do limite do plano. | | `duplicate` | Esse item já está no canal. | | `not_found` | Esse item não está no canal. | | `not_yours` | Esse item não foi mandado por este agente. Ele só pode mudar os dele. | | `stale` | Esse item mudou enquanto este agente trabalhava nele. Leia de novo e tente outra vez. | | `not_a_note` | Esse item é um arquivo, não uma nota. Só o título pode mudar; para os bytes, use `zas_replace_file`. | | `not_a_file` | Esse item é uma nota, não um arquivo. Use `zas_edit_item`. | | `item_shared` | Esse item tem um link público. O dono tira o link primeiro. | | `invalid_cap` | Esse arquivo não está mais disponível. | | `write_failed` | Não deu para salvar o arquivo no destino. | | `upload_failed` | A subida falhou. | | `oprf_failed` | O Zas respondeu errado enquanto preparava o arquivo. | ### Direto | Código | O que significa | | ---------------------- | ----------------------------------------------------------------------------------------- | | `not_claimed` | Ninguém recebeu o arquivo em dez minutos. A oferta foi retirada. | | `no_offer` | Ninguém ofereceu um arquivo pelo Direto enquanto esta chamada esperava. | | `offer_taken` | Outro aparelho recebeu esse arquivo primeiro. | | `direct_cancelled` | A oferta foi cancelada do outro lado. | | `direct_failed` | A transferência pelo Direto falhou em voo. Uma ferramenta de resgate ainda pode entregar. | | `direct_not_failed` | Esse trabalho não é uma transferência pelo Direto que falhou em voo. | | `file_changed` | O arquivo mudou depois da oferta pelo Direto. Mande de novo. | | `webrtc_unavailable` | Não deu para carregar o motor WebRTC (`node-datachannel`) nesta máquina. | | `fallback_unavailable` | A via confiável não está disponível agora. | ### O resto | Código | O que significa | | ---------- | ----------------------------- | | `network` | Não dá para alcançar o Zas. | | `internal` | Algo falhou dentro do agente. | ## Arquivos em disco Um diretório por perfil, então uma máquina pode ter um agente do Claude Code e um do Codex sem que nenhum leia as chaves do outro. | Sistema | Caminho | | ------------ | ---------------------------------- | | macOS, Linux | `~/.zas/agent/PERFIL/` | | Windows | `%USERPROFILE%\.zas\agent\PERFIL\` | | Arquivo | O que tem | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identity.json` | O uid do agente, o do dono, o nome e os dois pares de chaves. Guarde como uma chave privada, ou apague e pareie de novo. | | `pending.json` | Um pareamento não reclamado. Some quando ele completa, expira ou é cancelado. | | `grants.json` | Um cache de um minuto dos canais do agente e das chaves seladas. O nome do canal continua cifrado aqui. Descartável. | | `fingerprints.json` | Hashes do que um envio idêntico produziu nos últimos dez minutos, para uma repetição responder sem tocar a rede. Só hashes, nunca um título. Descartável. | Um arquivo vive um nível acima, em `~/.zas/agent/`, porque é uma decisão sobre a máquina e não sobre uma identidade: | Arquivo | O que tem | | --------------- | ----------------------------------------------------------------------------------------- | | `settings.json` | A decisão de telemetria desta máquina, e se o aviso inicial já foi mostrado. Descartável. | Cada arquivo é escrito num temporário e renomeado, então uma queda no meio da escrita não deixa meio arquivo. No macOS e no Linux o diretório é criado `0700` e cada arquivo `0600`. No Windows esses bits não fazem nada: os arquivos ficam com as permissões do perfil de usuário onde vivem, e o pacote não define outras. Apagar o diretório faz a máquina esquecer o agente. **Não** revoga. Isso é em **Configurações → Agentes → Revogar**. ## Telemetria O agente reporta o funil de pareamento e um evento `agent.tool_call` por chamada, para o Zas ver quais ferramentas funcionam e quais falham. Vem ligada e imprime um aviso na primeira vez. **O que ela nunca manda:** nomes de arquivo, títulos, corpos de notas, nomes de canal, caminhos nem conteúdo. Três formas de desligar, na ordem em que são lidas: | Interruptor | Efeito | | ------------------------- | --------------------------------------------------------------------------- | | `ZAS_AGENT_TELEMETRY=off` | Desligada para este processo. `on` força ligada. | | `DO_NOT_TRACK=1` | Desligada. O interruptor comum entre produtos, respeitado só para desligar. | | `zas-agent telemetry off` | Desligada para esta máquina, lembrado em `settings.json`. | `zas-agent telemetry` sem valor imprime o estado atual e qual dos três decidiu. `zas_status` imprime a mesma linha. ## Ajustes | Ajuste | Padrão | O que muda | | --------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--profile NOME` | `claude-code` | Qual diretório de identidade este processo usa. Letras, dígitos, `.`, `_` e `-`, até 64, e não pode começar com ponto. | | `--kind` | pelo nome do perfil | O harness mostrado na aprovação: `claude_code`, `codex` ou `other`. | | `--host NOME` | o hostname da máquina | O host mostrado na aprovação. | | `--no-open` | desligado | Não abrir o navegador ao parear. O link é impresso do mesmo jeito. | | `ZAS_NO_OPEN` | sem valor | O mesmo que `--no-open`. | | `ZAS_AGENT_HOME` | `~/.zas/agent` | Onde ficam os diretórios de perfil. | | `ZAS_AGENT_TELEMETRY` | sem valor | `off` ou `on`, para este processo. | | `DO_NOT_TRACK` | sem valor | `1` desliga a telemetria. | | `ZAS_WEB_BASE` | `https://zas.red` | O app web para onde a URL de pareamento aponta. | | `ZAS_API_BASE` | `https://zas.red/api` | A API. | Só `--profile`, `ZAS_AGENT_HOME` e os interruptores de telemetria valem a pena na mão. O resto existe para apontar o pacote a um ambiente de teste. ## Números | | Valor | | ------------------------------------------- | ---------------------------------------------------------- | | Agentes, plano grátis | 5, revogados incluídos | | Canais por agente, plano grátis | 5, contando os que ele já teve | | Agentes, sem conta | Nenhum | | Agentes por membro, padrão numa organização | 2, faixa de 0 a 10 | | Canais por agente, numa organização | Sem teto; o alcance é governado pela participação no canal | | Teto duro, qualquer conta | 10 | | Maior arquivo guardado | O limite do seu plano, 50 MB no grátis | | Maior arquivo que o agente lê | 5 GiB | | Maior transferência pelo Direto | O limite do seu plano, 10 GB no grátis | | Vida mais curta que um agente pode pedir | 1 dia | | Vida do token de sessão | 1 hora, assinado de novo sozinho | | O pareamento espera a aprovação | 10 minutos | | Um pareamento aprovado espera ser reclamado | 5 minutos | ## Por onde seguir Pareamento, comandos do harness e o que fazer quando falha. Cada limite que o Zas aplica, agentes incluídos. Respostas curtas para as perguntas de sempre. Bons hábitos, e o aviso sobre segredos.