ToolCall
Os estados
{
"codigo": "BR4821"
}A transportadora não respondeu em 30 segundos.
Aguardando aprovação
{
"pedido": "10482",
"cliente": "Mariana Teles",
"valor": 248.9
}import { ToolCall } from '@rivocode/ui/ai'Quando usar
O cartão recolhível de uma chamada de ferramenta feita por um assistente: o
nome da ferramenta, em que pé ela está, a entrada e a saída. Quando a chamada
precisa de permissão, ele traz os botões de aprovar e recusar. Vive em
@rivocode/ui/ai.
import { ToolCall } from '@rivocode/ui/ai'
<ToolCall
name="buscar_entregas"
title="Consultando as entregas de agosto"
status="done"
input={{ mes: 8, ano: 2026 }}
output={{ total: 3, atrasadas: 1 }}
/>
Os cinco estados
status |
O que a pessoa vê |
|---|---|
pending |
relógio e "Pendente", em neutro |
running |
círculo girando e "Rodando", em informação; o cartão anuncia aria-busy |
done |
visto e "Concluída", em sucesso |
error |
xis e "Erro", em perigo; o painel abre sozinho e mostra o error, e fecha sozinho quando sai dele |
approval |
mão e "Aguardando aprovação", em atenção; o painel abre sozinho, e fecha sozinho quando sai dele |
Cor nunca é o único sinal. Cada estado sai com ícone E texto, e o texto
entra no nome do gatilho: o leitor de tela ouve "buscar_entregas, Consultando as
entregas de agosto, Rodando". labels troca os textos, para outra língua.
Entrada e saída
input e output saem no CodeBlock da casa. Objeto sai como JSON indentado;
texto sai como veio. O painel começa fechado, porque quem lê a conversa quer a
resposta e não o encanamento, e abre no toque do gatilho. Sem entrada, saída
nem erro, não há gatilho: o cabeçalho sai como texto, e não como um botão
que não abre nada, anunciado expandido e apontando para um painel que não
existe.
Nome e título longos quebram em até duas linhas, em vez de cortar numa linha
só; o nome inteiro da ferramenta fica no title, para quem pousa o ponteiro.
defaultOpen troca o ponto de partida, e open com onOpenChange controla.
Sem open, o painel abre sozinho também quando o status muda para
error ou approval: a chamada que nasce running e falha no meio do caminho
mostra o erro sem esperar um toque. Fechado à mão, ele só abre de novo na
próxima troca de estado.
O que abriu sozinho, fecha sozinho. Quando o painel abriu por causa do
approval ou do error, ele fecha quando o status sai desse estado: a
pessoa aprova, a chamada roda e termina em done, e a entrada e a saída não
ficam ocupando a conversa. O que a pessoa abriu com a mão continua aberto,
inclusive se ela fechou e reabriu durante a aprovação. Com open, quem decide
é sempre quem controla.
Aprovar antes de rodar
Em approval, onApprove e onReject ligam os dois botões. Eles ficam fora
do painel recolhível, na base do cartão: decisão que espera a pessoa não se
esconde atrás de um toque. O painel abre sozinho, para que a pessoa leia os
argumentos antes de decidir.
<ToolCall
name="reembolsar_pedido"
title="Reembolsar o pedido 10482 da Mariana Teles"
status="approval"
input={{ pedido: '10482', valor: 248.9 }}
onApprove={() => approve(call.id)}
onReject={() => reject(call.id)}
/>
Texto longo em labels.approve ou labels.reject quebra a linha dentro do
botão, e não vaza do cartão.
A peça não guarda a decisão: quem aprovou muda o status para running, e
quem recusou muda para error com a frase do motivo.
Partes
classNames alcança trigger (o cabeçalho, seja o botão ou o texto sem
painel), name, status, panel, error e actions.
Quando não usar
- Seções de conteúdo que se abrem são
Accordion. OAccordionorganiza texto que já existe; oToolCallé um acontecimento com estado, e o estado é o que a pessoa lê primeiro. - Um bloco só que esconde detalhe é
Collapsible. Se não há ferramenta, estado nem aprovação (é só "ver mais"), oCollapsiblefaz o mesmo sem a moldura.
No React Native
Traduz, no caminho próprio @rivocode/ui-native/ai, com os mesmos name, status, input, output, error, onApprove, onReject, labels, defaultOpen, open e onOpenChange. title e error são string, porque texto no nativo mora dentro de um Text.
Cor continua não sendo o único sinal. Cada estado sai com o ícone do web antes do nome, no icon do Badge, do lucide-react-native (Clock, CircleCheck, CircleX e Hand), e running ganha o giro. O gatilho diz o nome da ferramenta e o estado ao leitor de tela, e a marca fica escondida dele.
As partes vestem pelo mesmo classNames do web, as seis: trigger, name, status, panel, error e actions.
API
| Prop | Tipo |
|---|---|
nameobrigatóriaO nome da ferramenta, como o modelo a chamou: `buscar_notas`. | string |
statusobrigatóriaEm que pe a chamada esta. | ToolCallStatus |
classNames | Partial<Record<"actions" | "error" | "name" | "panel" | "status" | "trigger", string>> |
defaultOpenComeca aberto. | boolean |
errorA frase do erro, quando `status` e `error`. | ReactNode |
inputOs argumentos da chamada. | unknown |
labelsOs textos dos estados e dos botoes, para outra lingua ou outro tom. | Partial<Record<"approve" | "input" | "output" | "reject" | ToolCallStatus, string>> |
onApproveChamado pelo botao de aprovar, que so aparece em `approval`. | (() => void) |
onOpenChange | ((open: boolean) => void) |
onRejectChamado pelo botao de recusar, que so aparece em `approval`. | (() => void) |
openAberto, controlado. | boolean |
outputO que a ferramenta devolveu, com a mesma regra do `input`. | unknown |
titleA frase para gente, ao lado do nome: "Consultando os pedidos em aberto". | ReactNode |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.