Conectores

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

POST /projects/{projectId}/connections/{connectionId}/share
     {"principals": [{"principal_type": "group", "principal_id": "<group-id>"}]}

Uma lista principals vazia compartilha a conta com todos. Pela CLI: beeuni connectors connections share <connection-id> --group <group-id> (também --user <email|id>, repetível, ou --everyone).

Cada entrada do público é uma atribuição de objeto connection no armazenamento de concessões:

POST   /accounts/{accountId}/iam/assignments
       {"principal_type": "group", "principal_id": "<group-id>",
        "role_key": "agent-user", "scope_type": "project", "scope_id": "<project-id>",
        "object_type": "connection", "object_id": "<connection-id>"}
DELETE /accounts/{accountId}/iam/assignments/{assignmentId}

Pela CLI, as mesmas gravações são:

beeuni access grant --group <group-id> --connection <connection-id>
beeuni access grant --everyone --connection <connection-id>
beeuni access revoke <assignment-id>
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 <slug> 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:

PUT /projects/{projectId}/connections/{connectionId}/label   {"label": "Support inbox"}
beeuni connectors connections rename <connection-id> 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.

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 e Computadores 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

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:

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:

connectors:
  - slug: read-ai
    name: Read AI
    provider: mcp
    url: 'https://api.read.ai/mcp'
    auth:
      type: bearer

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:

{
  "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:

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:

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:

https://{tenant}.sharepoint.com/.default

Conectar com uma chave de API

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

Conceder acesso a um agente

Adicione o slug do conector ao campo connectors do agente:

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) — 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:

{
  "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:

GET /connectors/projects/{projectId}/connectors/{slug}/accounts

{
  "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):

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). 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:

beeuni connectors ls
beeuni connectors accounts stripe-read
beeuni connectors call stripe-read <action> '<json-args>' [--account <id|label|me|project>]

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:

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.

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:

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:

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):

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.

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:

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):

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('<slug>.<action>', 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<n>_<name>), 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.

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), 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.