OHarness
Baixar

Plugin do Composio

connector-composio é um RuntimePlugin comum do OHarness. Ele usa a API REST oficial do Composio para inspeção de contas, descoberta de schemas e execução de ferramentas. Ele não introduz MCP, outro loop do Agent, um segundo plugin host nem uma dependência de SDK. createConnectorPlugin continua sendo o helper de adaptador independente de fornecedor.

Escopo e verificação

  • Implementado: listas explícitas de ferramentas permitidas, vínculo de conta/usuário, conversão de schemas, fixação de versão, cancelamento, limites de tamanho de resposta e os portões de permissão do OHarness.
  • Implementado: criação explícita, operada por uma pessoa, de links de autenticação hospedados e status da conta.
  • Não implementado: Pipedream, webhooks, ACLs de contas compartilhadas, verificação automática de identidade do callback OAuth no OHarness Cloud, instalação remota de plugins, automação de upload/download de arquivos nem recarregamento a quente em runtime.
  • Os testes usam respostas HTTP simuladas e não exigem credenciais. Um teste de fumaça com uma conta real precisa ser feito à parte, com as suas próprias credenciais e o seu consentimento.

O Composio recomenda Sessions para novas integrações de agentes e classifica a execução direta como legada. Este primeiro adaptador usa de propósito os endpoints diretos, ainda documentados, para manter no controle o registro de ferramentas existente do OHarness e as permissões por ferramenta. Só as ferramentas escolhidas explicitamente são expostas, em vez de um roteador genérico capaz de invocar uma ação arbitrária. Veja o guia oficial de execução direta.

Este adaptador direto é para uso em desenvolvimento/auto-hospedado configurado explicitamente. No produto hospedado, a chave do Composio da plataforma pertence ao Cloud, não a cada cliente. Use o conector do Cloud no produto hospedado: ele oferece cartões de autorização, vínculo de usuário verificado pelo servidor e continuação da tarefa.

1. Defina a chave de API do projeto

Defina COMPOSIO_API_KEY no ambiente do processo que roda o OHarness. Não a coloque no seu repositório, em mensagens de chat nem no JSON do plugin. A configuração pode indicar outra variável de ambiente via apiKeyEnv.

O transporte só envia essa chave para https://backend.composio.dev, recusa redirecionamentos HTTP e não aceita uma origem de API configurável. Todas as chamadas remotas são requisições explícitas do cliente; construir/importar o plugin não faz nenhuma chamada.

2. Veja o que já está conectado

Toda entrada de toolkit na configuração precisa de um connectedAccountId, e a primeira pergunta é se você já tem um:

npm run composio:auth -- list --user YOUR_USER_ID

Somente leitura, restrito a esse usuário e paginado — passe --toolkit SLUG para filtrar, --limit N (1-100, padrão 50) para definir o tamanho da página e --cursor com o cursor retornado por uma chamada anterior. Ele imprime id, toolkit, status e disabled de cada conta e nada mais: as linhas de origem trazem campos de credencial e de estado, e este comando os descarta do mesmo jeito que a inspeção de contas.

Uma conta listada sob outro usuário é recusada em vez de escondida, já que uma resposta que mistura usuários não é confiável nem para as linhas que bateram.

3. Conecte uma conta

Se a lista estiver vazia, ou se faltar nela o toolkit de que você precisa, crie uma configuração de autenticação para o app no Composio e depois solicite explicitamente um Connect Link hospedado a partir do repositório:

npm run composio:auth -- link --user YOUR_USER_ID --auth-config ac_YOUR_AUTH_CONFIG

O comando faz um POST remoto e imprime redirectUrl, connectedAccountId e uma expiração opcional. Abra essa URL você mesmo e conclua o consentimento. Trate-a como um link de autorização privado: não a compartilhe com outro usuário. O comando não abre navegador, não aprova acesso, não salva configuração nem expõe ao Agent uma ferramenta de criação de links.

Inspecione a conexão resultante com uma requisição somente leitura:

npm run composio:auth -- status --user YOUR_USER_ID --account ca_YOUR_ACCOUNT

Continue quando o status for ACTIVE, o toolkit estiver correto e disabled for false. Use o mesmo ID de usuário para vincular e para executar. O adaptador rejeita de propósito uma conta que pertença a outro usuário, mesmo que a chave de API do projeto consiga acessá-la. A inspeção de contas nunca retorna campos de credencial/estado.

Em um produto hospedado multiusuário, derive userId do estado autenticado do aplicativo e crie instâncias do Harness devidamente isoladas. Não o aceite como entrada do modelo. A verificação opcional de identidade do callback do Composio exige um verificador HTTPS autenticado no seu aplicativo; este adaptador local não implementa esse servidor. Veja a documentação oficial de conexão e identidade do callback.

4. Habilite o plugin

Compile o espaço de trabalho (npm run build) e adicione uma entrada ao seu arquivo de plugins do OHarness do usuário, normalmente ~/.oharness/plugins.json (ou $OHARNESS_HOME/plugins.json). Substitua o caminho do módulo, o ID de usuário e o ID da conta; não copie os placeholders como estão.

{
  "runtimePlugins": [
    {
      "id": "connector-composio",
      "module": "/absolute/path/to/OHarness/packages/engine/dist/runtime-plugins/composio/index.js",
      "enabled": true,
      "required": false,
      "config": {
        "userId": "YOUR_USER_ID",
        "apiKeyEnv": "COMPOSIO_API_KEY",
        "timeoutMs": 30000,
        "toolkits": [
          {
            "slug": "gmail",
            "connectedAccountId": "ca_YOUR_ACCOUNT",
            "version": "latest",
            "tools": ["GMAIL_GET_PROFILE"]
          }
        ]
      }
    }
  ]
}

required: false mantém o OHarness utilizável se este conector opcional não conseguir iniciar; a falha aparece em /plugins e na lista de plugins da Web. Defina como true só se a inicialização tiver de falhar sem o conector. A configuração do projeto não pode habilitar plugins executáveis nem substituir a configuração de conta confiável deles.

Para embutir, use a mesma implementação diretamente:

import { Harness, composioPlugin, jsonlAuditPlugin } from "@oharness/engine";

const harness = await Harness.create({
  runtimePlugins: [
    {
      plugin: composioPlugin,
      config: {
        userId: authenticatedUserId,
        toolkits: [{
          slug: "gmail", connectedAccountId: approvedAccountId,
          version: "latest", tools: ["GMAIL_GET_PROFILE"],
        }],
      },
    },
    { plugin: jsonlAuditPlugin, config: { path: "/absolute/path/to/audit.jsonl" } },
  ],
});
// Use the existing Session / Agent API, then await harness.close().

Semântica de execução

  1. A inicialização verifica se cada conta configurada pertence ao usuário configurado, tem o toolkit configurado e está ativa/não desabilitada.
  2. Só os slugs de ferramenta nomeados são buscados; no máximo 40 ferramentas em 20 toolkits.
  3. O slug/toolkit retornado precisa bater com a lista de permissões. latest é resolvido na inicialização para uma versão datada concreta, reutilizada na execução. Uma versão datada configurada precisa bater exatamente com a versão do schema retornado.
  4. As ferramentas são registradas como composio__SLUG. Nomes com mais de 64 caracteres são encurtados com um sufixo de hash estável. Os nomes exatos aparecem no ToolRegistry.
  5. As chamadas passam pelo engine de permissões normal do OHarness. Todas as ferramentas do Composio têm readOnly: false e sessionLocal: false, mesmo as operações remotas de leitura. A aprovação só é pulada quando a sua política de permissões explícita normal permite.
  6. Antes de cada execução, a posse, o status e o toolkit da conta são verificados de novo. O envelope do POST usa o usuário/a conta confiáveis e a versão fixada; os parâmetros do modelo ficam aninhados em arguments e não podem substituir esses campos.
  7. Os dados de sucesso são convertidos em um ToolResult e entram no fluxo normal do Agent e na auditoria de execução. Falhas de HTTP/API viram erros de ferramenta.

A entrada da ferramenta precisa ser um objeto. A validação detalhada do schema dos argumentos é feita pelo Composio; o JSON Schema retornado é fornecido ao modelo. Só implementações explícitas de ferramentas são suportadas, e não execução via proxy, substituições de autenticação personalizadas, execução em linguagem natural nem URLs remotas arbitrárias. Este adaptador não lê nem envia nenhum arquivo local.

Nenhuma chamada HTTP é repetida automaticamente. Um POST cancelado ou com falha pode já ter executado a ação remota: inspecione o serviço externo ou o log do Composio antes de tentar de novo. O timeout por requisição tem padrão de 30 segundos e é configurável de 100 ms a 120 segundos. As respostas são limitadas a 2 MiB. Corpos de erro brutos e chaves de API não são repassados para os logs; os dados de sucesso continuam sendo dados sensíveis do aplicativo e ficam visíveis para o Agent, como esperado.

As primeiras requisições de conta/metadados acontecem quando o plugin é habilitado na inicialização; a inicialização não cria uma conta nova nem executa nenhuma ação da lista de permissões.

Contrato da API oficial usado

O adaptador usa as rotas documentadas /api/v3 em backend.composio.dev. Elas foram conferidas com a documentação oficial em 2026-09-02; testes de contrato HTTP não comprovam a autorização de uma conta real nem a disponibilidade do fornecedor.

← PluginsConectores na nuvem →