---
title: "Conectores"
description: "Como os conectores e as conexões dão aos agentes acesso limitado a ferramentas externas."
---
Um conector vincula um projeto a uma ferramenta ou serviço externo. O agente
faz chamadas a ele como uma ferramenta. O Beeuni intermedia cada chamada, para que o sandbox nunca retenha a credencial do conector.
Você declara a maioria dos conectores em `beeuni.yaml`. Consulte a
[referência do manifesto](/docs/pt/project/manifest) para ver todos os campos. O Beeuni declara
conectores de canal e de computador quando você conecta uma plataforma de chat ou uma
máquina.
## Procurar e adicionar um conector
Abra **Connectors** para explorar o catálogo gerenciado. A lista padrão contém
kits de ferramentas de provedores gerenciados que podem ser conectados com autenticação gerenciada pelo provedor ou com uma configuração de autenticação personalizada ativada. Ela não exige uma conexão existente no projeto. Um kit de ferramentas que precisa de uma configuração OAuth personalizada não verificada permanece oculto até que essa configuração possa ser verificada.
Para fontes diretas, ative **Connectors API Discover** nos sinalizadores de recursos do projeto e, em seguida, selecione **API / MCP** na mesma página. Ativar o sinalizador não substitui o padrão gerenciado. O catálogo direto agrupa superfícies publicadas de OpenAPI, MCP, GraphQL, Postman e outras APIs. Selecione um cartão, escolha uma superfície publicada e preencha o formulário de conexão. Superfícies que contêm apenas documentação abrem a documentação do provedor; elas não são apresentadas como modelos prontos para conexão.
Use **Add → Manual** para uma API bruta ou um esquema que não esteja no catálogo.
A descoberta direta também funciona sem um provedor gerenciado configurado.
## Conectores, conexões e contas
Um conector é o pacote de acesso voltado ao agente: uma capacidade declarada (quais
ações, como acessar o serviço). Não é uma função e não concede permissões do Beeuni:
um agente só acessa um conector quando a concessão do manifesto lista o
slug e a decisão da função permite a chamada. Consulte
[Um vocabulário, dois vínculos](/docs/pt/accounts#one-vocabulary-two-bindings). Um
conector contém:
- um slug exclusivo no projeto
- um nome de exibição
- um app do provedor
- políticas do conector
Uma conexão é uma **conta** — uma identidade autorizada — para o
conector: uma credencial, uma concessão OAuth ou uma chave de API. Um conector pode ter
várias contas lado a lado. Cada conta usa as políticas do conector.
O `owner_type` de cada conta determina quem pode executar uma chamada usando-a:
- `project` — uma conta **compartilhada**. Acessível a qualquer pessoa a quem o conector
foi concedido, seja uma pessoa ou uma conta de serviço (agente, gatilho).
- `member` — uma conta **privada**, pertencente a um membro do projeto
(`owner_id`). Acessível somente por esse membro, e apenas em uma sessão **privada**.
Uma conta de serviço (um agente ou gatilho atuando sem supervisão) nunca pode
usar a conta privada de um membro.
Vários conectores podem referenciar o mesmo app do provedor. Use conectores separados quando um app precisar de políticas diferentes.
### Adicionar uma conta
Abra o conector em **Customize → Connectors**. A guia **Accounts** lista
em uma única lista todas as contas que você pode usar ou gerenciar. Cada cartão mostra quem pode usar
a conta: **Only you**, **Everyone in project** ou os grupos e pessoas com quem ela é compartilhada.
Selecione **Add account**, dê um nome à conta e escolha **Who can use it**:
- **Only you** — uma conta privada. Qualquer membro pode adicionar uma.
- **Everyone in the project** — uma conta compartilhada.
- **Specific people or groups** — uma conta compartilhada, limitada às pessoas,
aos grupos e aos agentes que você escolher.
As duas opções compartilhadas exigem `project.connector.connections.manage`. Para
**Specific people or groups**, o Beeuni grava as concessões antes de você autorizar
a conta, para que ela nunca retenha uma credencial enquanto estiver aberta a todo o
projeto. O nome da conta deve ser exclusivo: um nome já usado por uma conta do mesmo
proprietário é recusado.
Quando um agente precisa de uma conta, ele publica um cartão **Connect** no chat. O
cartão abre a mesma caixa de diálogo, com o nome sugerido pelo agente já preenchido
e o público solicitado pré-selecionado. O Beeuni cria uma conta nova, nunca
reatoriza uma existente, e informa ao agente o nome da nova conta para que ele
possa executar chamadas usando essa conta.
### Escolher quem pode usar uma conta compartilhada
Uma conta compartilhada pode ser usada por todos no projeto até que você restrinja o acesso.
Selecione **Share** no cartão da conta. A caixa de diálogo é a mesma **Grant access**
usada para agentes. Ela lista quem pode usar a conta no momento, e você adiciona:
- **Everyone in the project** — o padrão.
- **Groups** — todos os membros de cada grupo.
- **People** — um membro por vez. Escolha apenas você para restringir a conta a você.
- **Agents** — todas as sessões desse agente, incluindo gatilhos e sessões compartilhadas.
Qualquer pessoa que possa executar o agente pode usar a conta por meio dele.
Nada muda até você selecionar **Save**. Remover o último grupo ou pessoa
faz com que a conta volte a poder ser usada por todos; a caixa de diálogo informa o resultado antes de você salvar.
Uma conta com acesso restrito segue as regras de contas privadas, com o público no lugar do proprietário:
- Uma pessoa do público pode usá-la, somente em uma sessão privada.
- Um agente do público pode usá-la em todas as suas sessões.
- Nenhum outro agente, nem um gatilho de qualquer outro agente, pode usá-la.
- Uma sessão que a vincule não pode ser compartilhada, a menos que a conta seja compartilhada com o próprio agente dessa sessão.
- Somente uma pessoa pode alterar quem pode usar uma conta. Uma sessão de agente recebe `403`.
Uma pessoa fora do público não vê a conta. Uma pessoa que gerencia as conexões
do projeto ainda a vê, marcada como **Not shared with you**, para poder alterar quem pode usá-la.
### Compartilhar sua própria conta privada
Sua própria conta **Only you** também tem um botão **Share**. Compartilhá-la a transforma em uma conta compartilhada com as pessoas e os grupos que você escolher (você continua incluído, a menos que se remova), ou com todos no projeto. A partir daí, ela é uma conta compartilhada: as pessoas que gerenciam as conexões do projeto também podem gerenciá-la.
- Compartilhar exige `project.connector.connections.manage`, o mesmo direito necessário para
adicionar uma conta compartilhada. Sem ele, o botão fica desativado e explica o motivo.
- O Beeuni grava as concessões primeiro e transforma a conta em compartilhada em uma única atualização,
para que ela nunca fique aberta a todo o projeto nesse intervalo.
- Uma conta compartilhada com o mesmo nome no conector impede a operação (`409`): renomeie
uma delas primeiro.
```text
POST /projects/{projectId}/connections/{connectionId}/share
{"principals": [{"principal_type": "group", "principal_id": ""}]}
```
Uma lista `principals` vazia compartilha a conta com todos. Pela CLI:
`beeuni connectors connections share --group `
(também `--user `, repetível, ou `--everyone`).
Cada entrada do público é uma atribuição de objeto `connection` no armazenamento de concessões:
```text
POST /accounts/{accountId}/iam/assignments
{"principal_type": "group", "principal_id": "",
"role_key": "agent-user", "scope_type": "project", "scope_id": "",
"object_type": "connection", "object_id": ""}
DELETE /accounts/{accountId}/iam/assignments/{assignmentId}
```
Pela CLI, as mesmas gravações são:
```bash
beeuni access grant --group --connection
beeuni access grant --everyone --connection
beeuni access revoke
beeuni connectors connections ls # the WHO CAN USE column
```
- `principal_type` é `user`, `group` ou `project` (todos no projeto;
`principal_id` é o ID do projeto).
- Para conceder ou revogar, é necessário `project.connector.connections.manage`.
- Somente uma conta compartilhada pode ter o acesso restringido por meio dessas concessões. Uma conta privada,
ou um ID que não seja uma conexão neste projeto, retorna `404`; compartilhe sua
própria conta privada pela rota `share` acima.
- `GET /projects/{projectId}/connections` retorna as concessões de cada conta compartilhada
em `shared_with`, e `usable: false` em uma conta que a pessoa que fez a chamada só pode ver para
gerenciá-la. O seletor de sessão oferece somente contas utilizáveis.
### Qual identidade uma conta usa
O `label` de uma conta é um nome escolhido antes da autorização. Ele não informa qual login foi usado. `connected_as` informa: o e-mail, login ou nome de exibição que o provedor informa para a conta autorizada.
- O Beeuni lê esse dado quando uma autorização gerenciada é concluída: primeiro, o nome de exibição da conta conectada; depois, a ferramenta "who am I" do toolkit (Gmail, Google Calendar, Google Drive, Linear, GitHub, Slack, Notion, Outlook, Microsoft Teams, HubSpot, Jira, Asana, Figma, Airtable, Salesforce, Trello, Dropbox, Calendly). O Google Docs e o Google Sheets não oferecem essa ferramenta, então o `connected_as` deles continua `null`.
- Se uma conta ainda tiver um rótulo padrão (`Private connection`, `Project connection` ou o nome do conector), ele será substituído pela identidade da conta. Um rótulo escolhido por alguém nunca é substituído.
- A página de conexão mostra "Connected as …" assim que a conta é adicionada, para que uma conta compartilhada autorizada com um login pessoal fique visível imediatamente.
- O `connected_as` aparece em todas as conexões (`GET /projects/{projectId}/connections`), na lista de contas, em `beeuni connectors accounts ` e `beeuni connectors connections ls` (a coluna `CONNECTED AS`) e nas linhas das contas em **Customize → Connectors**.
### Renomear uma conta
Renomeie uma conta sem autorizá-la novamente:
```text
PUT /projects/{projectId}/connections/{connectionId}/label {"label": "Support inbox"}
beeuni connectors connections rename Support inbox
```
No painel, abra o conector e clique em **⋯ → Rename** na linha da conta. Só o rótulo muda. A conta autorizada, seu proprietário, seu indicador padrão e o estado do provedor permanecem iguais. A mesma restrição aplicada à desconexão também se aplica: sua própria conta privada ou `project.connector.connections.manage` para uma conta compartilhada.
A renomeação é recusada com `400` para `me`, `project` ou um rótulo no formato UUID, porque `--account` resolve esses valores antes dos rótulos. Ela é recusada com `409` quando outra conta do mesmo proprietário já tem esse rótulo, sem diferenciar maiúsculas de minúsculas.
### Conectar outra conta
Um link de conexão para um espaço que já contém uma conta ativa não a autoriza novamente. O provedor reutiliza a conta, e a página de conexão mostra **Already connected**. Para usar outro login, adicione uma nova conta ao conector, defina-a como padrão e desconecte a antiga.
Uma chamada que não especifica uma conta é direcionada primeiro à conta privada padrão do autor da chamada e, em seguida, à conta compartilhada padrão do projeto. O resultado de cada chamada indica com qual conta ela foi executada (`account: { connection_id, label, owner_type }`), para que a transcrição sempre mostre a identidade usada pela chamada da ferramenta. Liste as contas que podem ser usadas em chamadas para um conector, com a padrão primeiro, usando `GET /connectors/projects/{projectId}/connectors/{slug}/accounts`.
> **Warning**
>
> `authorization_strategy` (`project` | `user`) era um MODE no nível do conector que tornava mutuamente exclusivos os acessos às contas pertencentes ao projeto e às pertencentes aos membros — um conector com estratégia `user` não podia oferecer uma conta compartilhada, portanto não tinha um fluxo de conexão em nenhum lugar onde um agente de serviço pudesse usá-lo. Esse recurso foi descontinuado: o manifesto e `PUT .../authorization-strategy` ainda o aceitam e respondem sem erro, mas ninguém mais o lê. `owner_type` em cada conexão é agora a regra de acesso completa.
## Provedores
Um conector usa um tipo de provedor:
- **composio** — OAuth gerenciado para aplicativos SaaS compatíveis
- **pipedream** — OAuth gerenciado legado, mantido apenas para reversão
- **openapi**, **postman**, **graphql**, **http** — conectores de API direta
- **mcp** — um servidor MCP remoto por HTTP ou SSE
- **channel** — uma conexão com uma plataforma de chat
- **computer** — a máquina conectada de cada membro é uma conta
Consulte [Slack e canais](/docs/pt/connect/slack) e [Computadores](/docs/pt/connect/computers) para ver os fluxos de provedores gerenciados.
### Disponibilidade de aplicativos
O catálogo de conectores mostra os aplicativos disponíveis para conexão. Alguns exigem uma configuração adicional de autenticação e podem aparecer apenas após a conclusão dessa configuração.
## Autenticação e política
Uma conexão é autenticada com:
- OAuth gerenciado, pela instalação de um canal ou por uma concessão OAuth2 nativa
- uma chave de API ou um token informado pelo painel
O Beeuni criptografa os dados da conexão e os resolve no servidor para cada chamada de ferramenta. O agente solicita uma ação. O Beeuni anexa a credencial, verifica a concessão do agente e a política do conector e da conexão, chama a API externa e retorna o resultado.
As políticas dos conectores pertencem ao conector. Uma conexão não pode substituí-las. As proteções do projeto têm precedência sobre as políticas do conector e da conexão.
Por padrão, uma ação do conector que não corresponda a uma regra é executada sem aprovação. Defina `policy.default_mode: risk` para exigir aprovação para ações de gravação e destrutivas sem regra correspondente. Defina `sensitive: true` para tornar `require_approval` o padrão do conector para ações sem regra correspondente, inclusive leituras. As regras explícitas do projeto ou do conector e da conexão continuam tendo precedência.
### Aprovar uma chamada sujeita a regras
`require_approval` cria uma decisão para uma chamada de conector. O Connector retorna `202 pending_approval` com `approval_url`, `approval_summary` e `execution_id`. Ele não mantém uma solicitação HTTP aberta.
Compartilhe `approval_url` com qualquer colega de equipe. O URL identifica a solicitação, mas não concede autoridade. A página exige uma conta Beeuni com sessão iniciada. Em seguida, o Beeuni verifica se a conta pode acessar o projeto e aprovar ações nele.
A página de aprovação mostra os parâmetros ocultando os dados confidenciais que o conector receberá. Quem faz a chamada pode adicionar `approval_context` (CLI: `--reason`) para descrever o efeito. Use essa opção quando os parâmetros forem apenas referências: `gmail.send_draft` recebe o ID de um rascunho, então o agente informa o destinatário, o assunto e o corpo. A página mostra esse texto como descrição do agente, não como informação verificada. Os parâmetros continuam sendo a evidência. O Beeuni nunca envia `approval_context` ao provedor.
Aprove ou negue a chamada uma única vez. Adicione uma mensagem opcional à decisão. A mensagem é enviada ao agente junto com a decisão, para que uma negativa possa indicar o que fazer em vez disso.
Todas as chamadas pendentes também aparecem em **Review → Needs you** para o projeto. Abra **Review** na barra lateral; o contador mostra quantos itens aguardam sua atenção. Uma chamada é aberta na mesma tela de aprovação do link correspondente, para que você veja o conector, os parâmetros e a descrição do agente antes de decidir.
Quando a chamada vem de uma sessão do Slack ou do Teams, o Beeuni publica um
cartão de aprovação nessa conversa. O cartão mostra a descrição do agente, os parâmetros
e **Approve** / **Deny**. No Slack, **Reply…** abre uma caixa para enviar uma mensagem
ao agente; no Teams, o cartão tem a caixa de mensagem incorporada. Somente um gerente
de projeto ou a pessoa que iniciou a sessão pode decidir. Uma decisão tomada em qualquer
lugar (na conversa, no Beeuni ou na página de aprovação) substitui os botões do cartão
pelo resultado, e o agente continua na mesma conversa. O Beeuni envia a decisão de volta
à sessão por meio de um callback durável. Uma aprovação se aplica somente ao digest exato
da solicitação. Um destinatário, assunto, corpo, canal, URL ou outro parâmetro alterado
exige uma nova decisão.
Abra o painel **Audit** da sessão para usar a mesma visualização de parâmetros. As
entradas históricas permanecem somente leitura. Não existe uma opção de aprovação para
toda a sessão. Use uma política explícita `always_run` somente quando uma ação do conector
precisar ser executada sem supervisão.
## Conectar com OAuth
1. **Abra a página de conectores do projeto**
Abra o projeto. Selecione **Connectors** e, em seguida, selecione o aplicativo.
2. **Selecione o escopo da conta**
Selecione **Project** para uma conta compartilhada, acessível por qualquer pessoa a quem
o conector seja concedido. Selecione **User** para uma conta privada, de sua propriedade
e acessível somente por você, apenas em uma sessão privada.
3. **Conclua a autorização**
Conclua o fluxo OAuth. O Beeuni armazena a conta conectada como uma conexão.
## Conectar um servidor MCP que usa OAuth 2.1
O Beeuni implementa a especificação de autorização do MCP. Abra o conector,
selecione **Add credential** e, em seguida, selecione a aba **OAuth 2.0**. O Beeuni
consulta o servidor e lê os metadados dele:
1. A consulta não autenticada retorna `401` com
`WWW-Authenticate: Bearer resource_metadata="…"`.
2. O Beeuni lê os metadados do recurso protegido (RFC 9728) nesse URL ou em
`/.well-known/oauth-protected-resource`.
3. O Beeuni lê os metadados do servidor de autorização (RFC 8414 ou descoberta do OpenID Connect)
para o primeiro servidor de autorização nomeado pelo recurso.
Quando esse servidor anuncia `registration_endpoint`, o Beeuni se registra como
um cliente OAuth (RFC 7591) e mostra um único botão: **Connect <server>**. Você
não cria nenhum aplicativo nem copia nenhum ID ou segredo do cliente. O Beeuni então
executa o Authorization Code com PKCE (S256) e vincula o token ao servidor com o
parâmetro `resource` (RFC 8707).
Registre este URI de redirecionamento quando um servidor exigir um antecipadamente:
```text
https://api.beeuni.ai/v1/connectors/oauth2/callback
```
Quando o servidor publica endpoints, mas nenhum `registration_endpoint`, o Beeuni
preenche previamente o URL de autorização, o URL do token e os escopos. Insira o ID do
cliente de um aplicativo que você criar com esse provedor. Quando o servidor não publicar
metadados, insira todos os campos.
O Beeuni mantém a sessão MCP: ele executa `initialize` e
`notifications/initialized` sob demanda e, em seguida, envia `Mcp-Session-Id` nas chamadas
posteriores. Um servidor que responde sem uma sessão nunca vê o handshake.
O Beeuni vincula cada conexão ao servidor de autorização que a emitiu. Quando o callback
contém um parâmetro `iss` (RFC 9207), o Beeuni o rejeita, a menos que corresponda ao
emissor registrado — um código criado por outro servidor é recusado antes de ser resgatado.
### Autorizar pela CLI
O dashboard é uma forma de executar este fluxo, não a única. Declare o conector em
`beeuni.yaml` e, em seguida, autorize-o em um terminal ou em uma sessão de agente:
```yaml
connectors:
- slug: read-ai
name: Read AI
provider: mcp
url: 'https://api.read.ai/mcp'
auth:
type: bearer
```
```text
beeuni connectors authorize read-ai --json
```
O comando cria a conexão, executa a cadeia de descoberta, registra o Beeuni como cliente
quando o servidor é compatível com a RFC 7591 e retorna o URL para aprovação:
```json
{
"connection_id": "7b1a16b2-...",
"registered": true,
"scopes": ["openid", "offline_access", "mcp:execute", "meeting:read"],
"authorization_url": "https://authn.read.ai/oauth2/auth?response_type=code&...",
"expires_at": "2026-08-19T14:48:26.345Z"
}
```
Um agente retorna `authorization_url` à pessoa com quem está trabalhando. Depois que ela aprova,
o agente confirma:
```text
beeuni connectors authorize read-ai --status
```
O comando termina com um código diferente de zero enquanto o status for `error`. Use
`--scope` para restringir o que é solicitado. Use `--client-id` e `--client-secret` para um servidor
que não é compatível com o registro dinâmico de clientes.
O Beeuni busca novamente o catálogo de ferramentas do conector assim que a autorização é
concluída, portanto o conector sai do estado `error` sem uma sincronização manual.
## Conectar uma API direta com OAuth2
Os conectores diretos são compatíveis com:
- credenciais de cliente
- código de autorização com PKCE
- autorização de dispositivo
- registro dinâmico de clientes (RFC 7591)
Para credenciais de cliente, insira o URL do token, o ID do cliente, os escopos e o
segredo do cliente. Você pode usar autenticação do endpoint de token `client_secret_basic`,
`client_secret_post`, `client_secret_jwt` ou `private_key_jwt`.
Para o código de autorização, insira o URL de autorização e o URL do token. Para a
autorização de dispositivo, insira o URL de autorização do dispositivo e o URL do token.
Um URL de descoberta RFC 8414 pode fornecer esses endpoints.
O Beeuni criptografa a configuração e os tokens do OAuth2. Ele atualiza os tokens de
acesso antes da expiração e armazena cada token de atualização rotacionado. Revogar a
conexão bloqueia a próxima chamada do conector.
Para o Microsoft Graph, use:
```text
https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
https://graph.microsoft.com/.default
```
Para chamadas REST diretas do SharePoint, use o escopo de recurso do SharePoint:
```text
https://{tenant}.sharepoint.com/.default
```
## Conectar com uma chave de API
1. **Declare o conector**
```yaml
connectors:
- slug: stripe-read
name: Stripe read access
provider: openapi
spec: 'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json'
auth:
type: bearer
policies:
- match: 'get_*'
action: always_run
- match: '*'
action: block
```
O manifesto ainda aceita uma chave `authorization_strategy` para compatibilidade
com versões anteriores. O Beeuni a ignora: defina o proprietário (compartilhado ou
privado) por conexão ao adicionar a credencial.
2. **Mescle a solicitação de alteração**
O Beeuni lê o manifesto do branch padrão. O conector fica ativo depois que a solicitação
de alteração é mesclada.
3. **Adicione a conexão**
Abra o conector e defina a credencial. O Beeuni armazena o valor criptografado. Ele não
escreve o valor no manifesto.
## Conceder acesso a um agente
Adicione o slug do conector ao campo `connectors` do agente:
```yaml
agents:
release-bot:
connectors: [stripe-read]
```
Omita `connectors`, e o agente receberá `none`. Mescle a alteração antes que ela entre
em vigor.
`connectors_required` está obsoleto. O manifesto ainda o aceita, mas nada o lê: uma sessão nunca é
recusada no momento da criação por um conector sem uma conta utilizável. Na prática, uma
recusa na criação da sessão por falta de um conector era inacessível — um conector apenas
privado não tinha uma conta compartilhada para oferecer, portanto a recusa não tinha uma
solução que o chamador pudesse aplicar. O bloqueio agora ocorre na **chamada** do conector:
um agente ao qual foi concedido `stripe-read` pode iniciar sua vez imediatamente, e somente
uma chamada que realmente precise do conector é negada (consulte [Quando uma chamada é negada](#when-a-call-is-denied)) — com uma solução associada.
## Selecionar uma conta
Há duas formas independentes de escolher com qual conta uma chamada será executada —
fixar uma para toda a sessão ou indicar uma em uma única chamada.
### Fixar um padrão para toda a sessão
Uma sessão pode substituir a conta padrão do conector para todas as chamadas que fizer:
```json
{
"connector_bindings": {
"stripe-read": {
"connection_id": "00000000-0000-4000-8000-000000000000"
}
}
}
```
A chave de vinculação é o slug do conector. O valor é uma conta (conexão) que o chamador
desta sessão tem permissão para acessar.
Use `GET /projects/{projectId}/sessions/{sessionId}/scope` para ler a vinculação efetiva. Use `PUT` no mesmo caminho para
substituí-la. A substituição se aplica à próxima chamada de ferramenta sem reiniciar a
sessão.
### Indicar uma conta em uma chamada
Liste as contas como quais um conector pode ser chamado — primeiro a padrão — com:
```text
GET /connectors/projects/{projectId}/connectors/{slug}/accounts
```
```json
{
"connector": "stripe-read",
"accounts": [
{ "connection_id": "...", "label": "Shared workspace", "owner_type": "project", "is_default": true, "connected_as": "billing@example.com" },
{ "connection_id": "...", "label": "My Stripe", "owner_type": "member", "is_default": false, "connected_as": null }
]
}
```
Em seguida, nomeie uma delas na chamada pelo ID de conexão ou pelo rótulo (sem distinção entre maiúsculas e minúsculas), ou
com as duas palavras seletoras `me` (sua própria conta privada padrão) e
`project` (a conta compartilhada padrão do projeto):
```text
beeuni connectors call stripe-read get_balance '{}' --account me
beeuni connectors call stripe-read get_balance '{}' --account "Shared workspace"
```
Uma chamada que não nomeia nenhuma conta é resolvida primeiro para a própria conta privada padrão do chamador e, depois, para a conta compartilhada padrão do projeto — sem alteração em relação ao comportamento anterior a um conector poder conter mais de uma conta. Uma conta nomeada que não for resolvida é **negada**, nunca substituída silenciosamente por outra (consulte [Quando uma chamada é negada](#when-a-call-is-denied)). Todo resultado de chamada bem-sucedida informa como qual conta foi executado: `account: { connection_id, label,
owner_type }`.
## Usar um conector em uma sessão
Dentro de uma sessão, use a CLI do Connector:
```text
beeuni connectors ls
beeuni connectors accounts stripe-read
beeuni connectors call stripe-read '' [--account ]
```
`connectors` lista os conectores no escopo. `accounts` lista as contas que este
chamador pode usar `stripe-read` — primeiro a padrão, depois as compartilhadas e, por fim, as privadas dentro de cada grupo. `call` executa uma ação como a `--account` nomeada ou, quando omitida, usando a mesma resolução padrão de antes de um conector poder conter mais de uma conta.
### Resultados grandes
Uma chamada de lista ou pesquisa pode retornar mais dados do que um modelo consegue ler: a saída da ferramenta acima de aproximadamente 50 KB é truncada. Salve o resultado em um arquivo e trabalhe nele com código:
```text
beeuni connectors call linear graphql.issues '{"first":250}' --out /workspace/output/issues.json
# → { "ok": true, "account": …, "saved_to": "/workspace/output/issues.json",
# "bytes": 93037, "shape": { "issues": { "nodes": "array(250) of {id,title,…}",
# "pageInfo": { "hasNextPage": true, "endCursor": "…" } } } }
jq '.data.issues.nodes[] | {id, title}' /workspace/output/issues.json
```
`--out` grava o resultado JSON completo, criando os diretórios pai. O stdout recebe o envelope da chamada sem `data`, além de `saved_to`, `bytes` e `shape`: a estrutura de `data` (chaves, comprimentos de arrays e cada `pageInfo`). O código de saída não é alterado.
### Anexar arquivos
Uma chamada nunca transporta bytes de arquivo em seus argumentos. Prepare o arquivo e coloque sua referência nos argumentos. O gateway lê os bytes no servidor e os grava na solicitação.
```text
beeuni connectors call microsoft-graph.sendmail @mail.json \
--attach /workspace/artifacts/report.pdf
```
`--attach` prepara o arquivo e acrescenta uma referência ao array de anexos da ação. O array é encontrado no esquema de entrada da ação: `attachments` para o canal Email, `body.message.attachments` para o Microsoft Graph `sendMail`. Nomeie-o com `--attach-path body.message.attachments` quando o esquema for incomum.
Argumentos JSON grandes devem ser colocados em um arquivo (`@mail.json`) ou no stdin (`-`).
Para posicionar um arquivo por conta própria, prepare-o primeiro:
```text
beeuni connectors upload /workspace/artifacts/report.pdf --connector microsoft-graph
# → { "attachment_id": "…", "ref": { "$beeuni_attachment": "…" }, … }
```
Coloque `ref` em qualquer lugar dos argumentos. O gateway o substitui de acordo com a posição:
| Posição de `ref` | Substituído por |
| --- | --- |
| Um elemento de um array de anexos cujos itens são objetos | O item de anexo do provedor. O esquema do item seleciona o formato: Microsoft Graph `fileAttachment` (`name` + `contentBytes` ou `@odata.type`), Postmark (`Name` + `Content`), Mailjet (`Filename` + `Base64Content`), SendGrid e Resend (`filename` + `content`), Brevo (`name` + `content`). Qualquer outro formato de item é recusado com `attachment_item_shape_unknown`. |
| Um campo de string, por exemplo `contentBytes` ou um arquivo do GitHub `content` | O base64 do arquivo. |
| O `attachments[]` do canal Email | Uma URL de download assinada para o provedor de Email. |
Regras:
- Os arquivos devem vir de `/workspace/output`, `/workspace/artifacts`,
`/workspace/reports` ou `/workspace/deliverables`. Links simbólicos e links físicos são recusados. Copie o arquivo para lá primeiro.
- Uma chamada comporta até 20 arquivos e 25 MiB no total. A API upstream pode definir um limite menor: o Microsoft Graph documenta 3 MB como o maior arquivo que uma solicitação `sendMail` pode anexar.
- Um arquivo preparado é privado para a sessão que o preparou, usado uma vez e excluído após 24 horas. Uma chamada com falha o libera para uma nova tentativa.
- O registro de auditoria, a prévia de aprovação e o modelo veem apenas a referência, nunca os bytes. Se um erro upstream repetir o arquivo, o base64 será removido.
- Os conectores gerenciados não aceitam arquivos preparados (`connector_attachments_unsupported`).
O servidor MCP oferece o mesmo fluxo: `call` recebe `attachment_files` (e um `attachment_path` opcional), e `upload_attachment` retorna um `ref`. O equivalente no SDK é `connectors.uploadAttachment(bytes, { filename, contentType,
connector })`, which returns `ref`.
### Resultados de chamadas
`POST /connectors/projects/{projectId}/call` responde com um objeto JSON. Estes campos são iguais para todas as integrações (OpenAPI, HTTP, MCP, GraphQL, `composio`, `pipedream`, computers):
| Campo | Em | Valor |
| --- | --- | --- |
| `data` | 200 | A resposta bruta do upstream, sem alterações. |
| `output` | 200 | O payload sem o envelope da integração: `composio` `data.result`, MCP `result.structuredContent ?? result.content`, GraphQL `data.data`. Ausente quando é igual a `data` (chamadas OpenAPI, HTTP, Postman, de canal, `pipedream` e de computador), para que o corpo contenha o payload uma única vez: leia `output ?? data`. O SDK o preenche. |
| `binding` | 200, 500, 429, 503 | A integração que executou a chamada: `openapi`, `http`, `mcp`, `graphql`, `composio`, `pipedream`, `pipedream_proxy`, `postman`, `tunnel`. `null` em caso de erro antes da resolução da ação. |
| `upstream_status` | 200, 500, 429, 503 | O status HTTP do upstream. `null` quando nenhum upstream respondeu (timeout, solicitação recusada ou computador). `composio` e `pipedream` informam uma falha do provedor dentro de uma resposta 200, portanto o Beeuni define `502` para ela (`400` para uma consulta do Linear rejeitada, `429` para um limite de taxa). |
| `upstream_error` | 200 | Presente quando o upstream informou uma falha dentro de uma resposta 2xx: um resultado de ferramenta MCP com `isError: true` ou um erro JSON-RPC, ou `errors` do GraphQL sem dados. A chamada ainda conta como executada: `ok` permanece `true`. |
| `retry_after_seconds` | 429, 503 | O `Retry-After` do upstream, em segundos, quando ele enviou um. A resposta também contém o cabeçalho `Retry-After`. |
O status HTTP de uma chamada com falha:
- Um `429` upstream responde `429`. Um `503` upstream responde `503`. Aguarde `retry_after_seconds` (ou use backoff) e faça a chamada novamente.
- Outras falhas do serviço de destino respondem `500` com a causa em `reason`.
- Uma resposta upstream maior que 64 MiB responde `500` com `reason: "upstream_response_too_large: …"`. O Beeuni para de ler ao atingir o limite. Peça uma página menor ou use um filtro.
- Um upstream que não responde dentro do prazo responde `500` com `reason: "upstream_timeout: …"`. O prazo padrão é de 60 segundos. Defina um timeout do cliente acima desse valor para que o gateway sempre responda primeiro.
Uma chamada de conector não é idempotente. O Beeuni não deduplica uma chamada repetida. Após `upstream_timeout` ou um cancelamento no cliente, a chamada pode ter sido executada no upstream: verifique seu efeito antes de repetir uma gravação (um email enviado, um registro criado).
### Chamadas tipadas a partir do código
`beeuni connectors types` grava um arquivo de declaração TypeScript para cada ação que você pode chamar. Cada ação recebe seu tipo de argumento do esquema de entrada e seu tipo de resultado do esquema de saída. O tipo de resultado descreve o campo `output` da chamada.
```sh
beeuni connectors types --out src/beeuni-connectors.d.ts
beeuni connectors types --connector linear,github --out src/beeuni-connectors.d.ts
```
Inclua o arquivo no seu `tsconfig.json`. Em seguida, chame por meio de `callAction`:
```ts
import { createBeeuni } from '@beeuni/sdk';
const connectors = createBeeuni({ backendUrl, getToken }).project(projectId).connectors;
const result = await connectors.callAction('linear', 'list_issues', { team: 'CORE' });
if (result.ok) console.log(result.output?.issues.length);
```
O identificador do conector lê o mesmo arquivo, e `run` retorna a própria saída tipada ou lança um erro tipado (consulte Conectores a partir do código):
```ts
const issues = await createBeeuni({ backendUrl, getToken })
.project(projectId)
.connector('linear')
.run('list_issues', { team: 'CORE' });
```
`callAction(slug, action, args, options)` envia a mesma solicitação que `call('.', args, options)` e retorna o mesmo resultado. Somente os tipos diferem: um argumento ausente ou desconhecido gera erro de compilação, e `output` tem o tipo gerado. Uma ação que não está no arquivo aceita qualquer objeto e retorna `output: unknown`.
- Os conectores OpenAPI, HTTP, MCP e GraphQL publicam um esquema de saída quando a fonte declara um. Um resultado GraphQL é tipado como objeto.
- Os conectores gerenciados não publicam esquemas de saída. O resultado é `unknown`. A CLI os nomeia depois de gravar o arquivo.
- Cada entrada `$defs` se torna um tipo nomeado (`BeeuniConnectorDef_`), de modo que um esquema recursivo permaneça finito. Um esquema que não pode ser compilado (uma união que contém a si mesma) ou cujos tipos ultrapassem 256 KB para uma ação se torna `unknown`.
- Execute o comando novamente depois de adicionar um conector ou quando ele sincronizar uma nova versão.
- O catálogo retorna esquemas de saída somente quando solicitado:
`GET /connectors/projects/{projectId}/catalog?include_output_schemas=true`
adiciona `outputSchema` a cada ação (`null` quando nenhum estiver armazenado).
### Quando uma chamada é negada
Uma chamada negada responde `{ ok: false, status: "denied", reason, hint }`. `reason` é um código estável; `hint` diz o que fazer.
| `reason` | HTTP | Significado | Também no corpo |
| --- | --- | --- | --- |
| `connector_not_assigned` | 403 | A concessão `connectors:` do agente em execução em `beeuni.yaml` não inclui este conector. | `agent`, `granted` (a lista ou `"all"`), `manifest_revision` e `manifest_commit` (o manifesto de origem da concessão). |
| `connector_not_connected` | 403 | Não há uma conta utilizável para esta chamada. Ou o conector não tem nenhuma conta para este chamador (nenhuma credencial armazenada ou o app nunca foi autorizado — `beeuni connectors ls` o mostra como `needs_auth`), ou `--account` indicou uma conta que não foi encontrada. | `connect_url` — um link hospedado para autorizar uma conta, quando o chamador pode gerar um — quando não há nenhuma conta conectada. `requested_account` e `available_accounts` — o nome que não foi encontrado e os nomes encontrados — quando `--account` indicou uma conta. |
| `connector_disabled` | 403 | O conector está declarado, mas desativado. | — |
| `connector_not_found` | 404 | Nenhum conector com este slug está declarado no projeto. | — |
| `action_not_found` | 404 | O conector não tem essa ação. | — |
`connect_url` é a única solução para um conector não conectado: uma sessão nunca é recusada antecipadamente por esse motivo (consulte [Conceder acesso a um agente](#grant-an-agent-access)), então a própria recusa traz a solução. O agente exibe o link sem alterações; a transcrição na web o apresenta como um botão Conectar de um clique. Por padrão, o link autoriza uma conta privada para a pessoa que o abre — conectar uma conta compartilhada é uma escolha explícita (`beeuni connectors connect stripe-read --owner project`, condicionada a `project.connector.write`).
O conector do canal que criou uma sessão (Slack, Teams, email) sempre pode ser chamado a partir dela, independentemente do que diz a concessão do agente, para que o agente sempre possa responder na conversa em que foi solicitado.
A concessão de uma sessão segue `beeuni.yaml`: uma alteração em `connectors:` do agente em execução (incluindo `beeuni connectors add --apply`) se aplica na chamada seguinte. A concessão registra de qual blob do manifesto e commit se originou; uma leitura que a substituiria pelo mesmo blob é confirmada primeiro por uma segunda leitura, e uma leitura de um commit mais antigo nunca a substitui.
Slack e Microsoft Teams se conectam pelo painel da mesma forma que os apps OAuth. Conectar o Slack grava um conector `channel` em `beeuni.yaml` para você. Consulte [Slack e canais](/docs/pt/connect/slack).