Tools de sessão de agente

Referência para quem desenvolve ou configura um Runner. As tools de sessão fazem parte do servidor MCP do Elefante, mas só respondem a um Elefante Runner conectado com a identidade de uma conexão do espaço. Um assistente conectado como você mesmo (Claude, ChatGPT) recebe "Only runners can use session tools".

Eventos

O Runner fica sabendo do trabalho por eventos, um por acontecimento, numerados em ordem crescente. Cada evento traz o tipo, a sessão, a data, os dados e um texto de orientação para o agente (prompt).

Evento	Quando chega	Dados principais
`session.created`	A tarefa foi delegada ao papel atendido pelo Runner	Tarefa, entradas da tarefa, papel com instruções, prompt de sistema, repositório do projeto, número de sessões anteriores e quem delegou
`session.message`	Uma pessoa respondeu a uma pergunta ou mandou uma instrução	Texto ou opção escolhida, a pergunta respondida e quem escreveu
`session.approval`	A pessoa decidiu um pedido de aprovação	Pedido, aprovado ou não, comentário e quem decidiu
`session.cancel`	A sessão foi encerrada por alguém	Motivo: `stopped` (parada), `undelegated` (delegação removida) ou `redelegated` (outro agente) e quem fez

Os eventos chegam de dois jeitos: pelo canal de eventos em /mcp/events, ou pela tool events_wait, para agentes sem canal próprio. Um Runner desconectado recebe os eventos pendentes quando volta.

Tools

Tool	Permissão	O que faz
`events_wait`	leitura	Espera eventos com número maior que `after_id`. Volta na hora se houver eventos; senão espera até `timeout` segundos (padrão 25, máximo 50). Devolve até 100 eventos
`session_list`	leitura	Lista as sessões do Runner, as abertas por padrão (`open_only`), da mais nova para a mais antiga, até 100. Use ao reconectar para retomar o trabalho
`session_get`	leitura	Estado da sessão, a tarefa (com as entradas), o papel, o prompt de sistema, o repositório e as últimas 200 atividades, da mais antiga para a mais nova. Releia a cada evento em vez de guardar estado
`session_history`	leitura	A conversa das sessões anteriores da mesma tarefa: perguntas, respostas, aprovações, resultados. Use quando `session.created` informar sessões anteriores, para não perguntar de novo
`session_activity`	alteração	Publica na conversa: `thought` (resumo do raciocínio) e `action` (o que fez) aparecem recolhidos; `response` aparece como mensagem
`session_ask`	alteração	Faz uma pergunta, com `options` opcionais, e deixa a sessão em Aguardando resposta. Vai para o responsável pela tarefa, ou para `to_user_id`
`session_request_approval`	alteração	Pede aprovação com um resumo (`summary`) e deixa a sessão em Aguardando aprovação. Vai para o responsável pela tarefa, ou para `approver_id`
`session_artifact`	alteração	Entrega um resultado: `text` ou `markdown` (o conteúdo), `link` ou `image` (a URL), com `title` opcional. Use antes de encerrar
`session_usage`	alteração	Informa o modelo e os tokens medidos pelo Runner, o tempo de resposta em milissegundos e o custo em dólar. Os totais aparecem no cabeçalho da aba Agente. Aceita sessão já encerrada
`session_complete`	alteração	Encerra como Concluída, com um `summary` opcional. Deixe vazio quando a resposta ou o resultado já dizem tudo
`session_fail`	alteração	Encerra como Falhou, com o motivo em `error`

O primeiro session_activity ou session_artifact tira a sessão de Aguardando o agente e a leva para Trabalhando. A pergunta e o pedido de aprovação também avisam a pessoa em Atualizações e por notificação no celular, em nome do papel.

Regras

Cada Runner só enxerga as próprias sessões.
Só sessões abertas aceitam atividade, pergunta, aprovação, resultado e encerramento. session_get, session_history e session_usage funcionam também em sessões encerradas.
O destinatário de uma pergunta ou aprovação precisa ser o responsável pela tarefa, quem a criou ou um seguidor. Sem destinatário, vale o responsável (ou, sem ele, quem criou).
Delegar de novo a mesma tarefa encerra a sessão aberta com o motivo redelegated e abre outra.

Se deu errado

Mensagem ou sintoma	Causa	O que fazer
Only runners can use session tools	O token não é de uma conexão de Runner ativa	Conecte o Elefante Runner escolhendo a conexão do espaço na tela de autorização
Session not found	A sessão não existe ou é de outro Runner	Confira o `session_id` com `session_list`
Session is closed	A sessão já foi concluída, falhou ou foi parada	Pare o trabalho. Uma nova sessão chega por `session.created`
Recipient must be the task owner, creator or a follower	`to_user_id` ou `approver_id` não é responsável, criador nem seguidor da tarefa	Deixe o campo vazio para falar com o responsável, ou escolha outra pessoa

Onde acessar

Endereços a partir do domínio da sua conta.

Onde	Endereço	Acesso direto
Servidor MCP	`https://app.elefante.com/mcp`	Sim
Canal de eventos do Runner	`https://app.elefante.com/mcp/events`	Sim
Aba Agente da tarefa	`/task/{id}#agent`	Sim