# ToolCall

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

```tsx
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.

```tsx
<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`.

## Importação

```tsx
import { ToolCall } from '@rivocode/ui/ai'
```

## Exemplos

### Os estados

```tsx
import { ToolCall } from '@rivocode/ui/ai'
import { useState } from 'react'

export function States() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <ToolCall name="buscar_entregas" title="Consultando as entregas de agosto" status="pending" />
      <ToolCall name="buscar_entregas" title="Consultando as entregas de agosto" status="running" />
      <ToolCall
        name="buscar_entregas"
        title="Consultando as entregas de agosto"
        status="done"
        input={{ mes: 8, ano: 2026, situacao: 'atrasada' }}
        output={{ total: 3, atrasadas: 1 }}
      />
      <ToolCall
        name="rastrear_pacote"
        title="Rastreando o pacote BR4821"
        status="error"
        input={{ codigo: 'BR4821' }}
        error="A transportadora não respondeu em 30 segundos."
      />
    </div>
  )
}
```

### Aguardando aprovação

```tsx
import { ToolCall } from '@rivocode/ui/ai'
import { useState } from 'react'

export function AwaitingApproval() {
  const [status, setStatus] = useState<'approval' | 'running' | 'error'>('approval')

  return (
    <div className="w-full max-w-xl">
      <ToolCall
        name="reembolsar_pedido"
        title="Reembolsar o pedido 10482 da Mariana Teles"
        status={status}
        input={{ pedido: '10482', cliente: 'Mariana Teles', valor: 248.9 }}
        error={status === 'error' ? 'Reembolso recusado por você.' : undefined}
        onApprove={() => setStatus('running')}
        onReject={() => setStatus('error')}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `name` | `string` | sim |  | - | O nome da ferramenta, como o modelo a chamou: `buscar_notas`. |
| `status` | `ToolCallStatus` | sim |  | - | Em que pe a chamada esta. |
| `classNames` | `Partial<Record<"actions" \| "error" \| "name" \| "panel" \| "status" \| "trigger", string>>` |  |  | - |  |
| `defaultOpen` | `boolean` |  |  | - | Comeca aberto. |
| `error` | `ReactNode` |  |  | - | A frase do erro, quando `status` e `error`. |
| `input` | `unknown` |  |  | - | Os argumentos da chamada. |
| `labels` | `Partial<Record<"approve" \| "input" \| "output" \| "reject" \| ToolCallStatus, string>>` |  |  | - | Os textos dos estados e dos botoes, para outra lingua ou outro tom. |
| `onApprove` | `(() => void)` |  |  | - | Chamado pelo botao de aprovar, que so aparece em `approval`. |
| `onOpenChange` | `((open: boolean) => void)` |  |  | - |  |
| `onReject` | `(() => void)` |  |  | - | Chamado pelo botao de recusar, que so aparece em `approval`. |
| `open` | `boolean` |  |  | - | Aberto, controlado. |
| `output` | `unknown` |  |  | - | O que a ferramenta devolveu, com a mesma regra do `input`. |
| `title` | `ReactNode` |  |  | - | A frase para gente, ao lado do nome: "Consultando os pedidos em aberto". |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AILabel](/componentes/ai-label.md)
- [Conversation](/componentes/conversation.md)
- [Message](/componentes/message.md)
- [MessageMedia](/componentes/message-media.md)
- [PromptInput](/componentes/prompt-input.md)
- [ShimmerText](/componentes/shimmer-text.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
