Pular para o conteúdo
IA

ToolCall

/componentes/tool-call.mdmarkdown cru, para quem lê com agent em vez de olho

Os estados

buscar_entregasConsultando as entregas de agostoPendente
buscar_entregasConsultando as entregas de agostoRodando
Entrada
{
  "codigo": "BR4821"
}

A transportadora não respondeu em 30 segundos.

Aguardando aprovação

Entrada
{
  "pedido": "10482",
  "cliente": "Mariana Teles",
  "valor": 248.9
}
Importar
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. O Accordion organiza texto que já existe; o ToolCall é 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"), o Collapsible faz 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

PropTipo
nameobrigatória

O nome da ferramenta, como o modelo a chamou: `buscar_notas`.

string
statusobrigatória

Em que pe a chamada esta.

ToolCallStatus
classNamesPartial<Record<"actions" | "error" | "name" | "panel" | "status" | "trigger", string>>
defaultOpen

Comeca aberto.

boolean
error

A frase do erro, quando `status` e `error`.

ReactNode
input

Os argumentos da chamada.

unknown
labels

Os textos dos estados e dos botoes, para outra lingua ou outro tom.

Partial<Record<"approve" | "input" | "output" | "reject" | ToolCallStatus, string>>
onApprove

Chamado pelo botao de aprovar, que so aparece em `approval`.

(() => void)
onOpenChange((open: boolean) => void)
onReject

Chamado pelo botao de recusar, que so aparece em `approval`.

(() => void)
open

Aberto, controlado.

boolean
output

O que a ferramenta devolveu, com a mesma regra do `input`.

unknown
title

A 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.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.