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

# Agent Studio

> Inspecione um agente, teste a working copy num sandbox, publique só quando for a sério.

URL: `https://mcp.chatsailer.com/mcp/studio`

Inspecione e teste agentes de IA da Sailer. Edições se aplicam à **working
copy**. Conversas ao vivo continuam rodando a versão publicada até alguém
publicar.

Conecte este servidor só se você de fato edita agentes. É um audience OAuth
separado — um token de CRM é 401 aqui, não "scope faltando". Reconecte; não
tente de novo.

<Note>
  A primeira conexão é [somente leitura](/pt-BR/mcp/auth). `publish_agent` e o
  sandbox não vão aparecer até você reconectar com `agents:publish` e
  `sandbox:run`.
</Note>

`whoami` também está montado aqui. A mesma tool do CRM: qual workspace, quem
autorizou, quais scopes.

## Inspecionar

### `list_agents`

Scope: `agents:read`. Mais novos primeiro, `limit` 1–100 (default 25).
Devolve `id`, `name`, `is_published`. Use isso para obter um `agent_id`.

> Which agents are in this workspace?

### `get_agent_graph`

Scope: `agents:read`. Nós e connections da working copy. Nós são endereçados
por uma key estável (com fallback para o name) — fale nessas keys, não em ids
internos. O resultado inclui um `head_hash`; passe-o de volta em qualquer
write para que uma edição concorrente seja detectada em vez de sobrescrita em
silêncio.

> Show me this agent's graph.

### `validate_agent`

Scope: `agents:read`. Cada problema de uma vez, endereçado por node key. Uma
lista vazia significa que o graph publicaria limpo.

> Is this agent's graph valid?

### `diff_agent_vs_production`

Scope: `agents:read`. O que mudaria se você publicasse agora, mais o
`head_hash` e o `change_count` que `publish_agent` exige.

> What would change if I published this agent?

Chame isso antes de fazer ship. Publicar sem ter acabado de ler o diff é
rejeitado.

## Publicar

### `publish_agent`

Scope: `agents:publish`. Destrutivo. Conversas ao vivo de clientes começam a
usar a working copy **na hora**. Ele envia toda mudança não publicada, não um
subconjunto escolhido.

Required, e verificado no servidor:

* `expected_head_hash` — de `get_agent_graph` ou `diff_agent_vs_production`
* `acknowledged_change_count` — de `diff_agent_vs_production`

Se outra pessoa editou o agente no meio, a chamada falha e pede para você
fazer diff de novo. `version_name` / `version_description` opcionais
aterrissam no histórico de versões.

`agents:publish` está separado de read de propósito: você pode entregar uma
conexão que itera num draft e não consegue fazer ship.

> Diff this agent against production, then publish it.

## Sandbox

O sandbox roda a working copy. Nada aqui toca clientes reais. Um turno leva
dezenas de segundos, então são duas tools em vez de uma: uma chamada
bloqueante morreria no load balancer depois que o trabalho já tivesse
committed.

### `start_sandbox_turn`

Scope: `sandbox:run`. Envie uma mensagem (máximo 4.000 caracteres). Devolve
na hora um `turn_id`.

| Argumento          | O que faz                                                                  |
| ------------------ | -------------------------------------------------------------------------- |
| `message`          | O que o contato simulado diz                                               |
| `agent_id`         | Qual agente responde. Omita para deixar a fila decidir — isso é production |
| `queue_id`         | Encaminha para uma fila específica                                         |
| `conversation_key` | Continua uma conversa de sandbox anterior. Omita para começar do zero      |

Comportamento multi-turno depende do histórico. Um graph que só se comporta
mal no terceiro turno não se reproduz uma mensagem por vez — passe o mesmo
`conversation_key` de volta.

> In the sandbox, say hi to this agent as a new contact.

### `get_sandbox_turn`

Scope: `sandbox:run`. Faça poll com o `turn_id`. Enquanto `settled` for
false, o agente ainda pode responder — isso não é silêncio. Depois de
settled, `outcome` diz o que aconteceu e `remedy` diz o que fazer a respeito.
"No reply" tem várias causas; não são o mesmo conserto.

> Has that sandbox turn finished?

### `get_turn_trace`

Scopes: `sandbox:run` **e** `inference:read`. Chame depois que o turno tiver
settled. Quais edges foram avaliadas, qual foi tomada, e para cada uma que
perdeu, qual condição falhou e o que o campo comparado realmente tinha.

Esta é a tool para "por que ele não avançou?". Costuma ser um gate que
comparou um campo que nunca foi coletado — `actual` é null e `likely_cause`
nomeia o campo. Não inclui prompts nem completions do modelo.

> Why didn't the agent leave that node?