Conectores personalizados

Qual experiência você está usando?

Esta documentação cobre as duas experiências. Se Settings → Personal → My Okou estiver disponível, siga as etapas de My Okou. Se você usar uma página Agents com New agent, siga as etapas de Legacy Agents. A disponibilidade pode variar entre membros; esta documentação não altera sua experiência.

Em qualquer das experiências, você pode executar vários chats ou tarefas ao mesmo tempo, reutilizar fluxos de trabalho e compartilhar com sua equipe o trabalho revisado. Um subagente de execução em runtime é uma ferramenta de execução, não um perfil de produto separado que você precise criar.

Diferenças de configuração: My Okou usa instruções pessoais (Instructions) em Settings → Personal → My Okou e fluxos de trabalho do espaço de trabalho. Qualquer etapa abaixo que peça para você escolher, criar ou autorizar um agente nomeado se aplica apenas a Legacy Agents. No My Okou, use seu próprio Chat e siga a solicitação de conta e permissão nomeada mostrada. Os fluxos de trabalho compartilhados não compartilham credenciais; as automações usam o contexto e o acesso do respectivo proprietário.

Um conector personalizado permite que um administrador da organização registre uma API HTTPS ou, quando habilitado, um servidor MCP Streamable HTTP que não esteja no catálogo integrado. Ele define a fronteira de rede e o método de autenticação. Ele não gera automaticamente uma referência completa da API para o agente.

Quem configura o quê

• Administradores da organização criam, editam e excluem a definição do conector.
• Membros conectam o próprio segredo ou concluem o fluxo OAuth do conector.
• Autorização e permissões controlam quais ações nomeadas o Okou pode solicitar com a conexão. Os Legacy Agents também usam autorização específica do agente.

A definição é compartilhada na organização. As credenciais do membro permanecem restritas ao membro e à organização.

Conector de API HTTP

1. Abra Connectors → Custom e escolha New connector.
2. Selecione HTTP API e insira um nome de exibição.
3. Adicione um ou mais Prefixes HTTPS, um por linha. Uma solicitação precisa corresponder a um prefixo configurado antes que o conector possa autorizá-la.
4. Adicione autenticação se a API precisar dela:
   • API authentication: insira o nome do cabeçalho e um modelo de cabeçalho contendo {{secret}}, por exemplo Authorization e Bearer {{secret}}.
   • OAuth 2.0: insira a URL de autorização, a URL de token, o client ID, o client secret, os scopes e o método de autenticação do endpoint de token. Registre com o provedor a URL de redirecionamento exata mostrada no formulário.
5. Crie o conector. Cada membro que precisar dele seleciona então Connect e fornece seu segredo ou conclui o OAuth.
6. Revise e autorize as permissões nomeadas obrigatórias. Em Legacy Agents, também selecione o agente pretendido.

Alterar uma definição OAuth existente ou suas credenciais de cliente desconecta as conexões OAuth atuais. Os membros precisam se conectar novamente depois da alteração.

Conector MCP

Se MCP aparecer como um tipo de conector no seu espaço de trabalho, insira um endpoint MCP HTTPS Streamable HTTP e configure a autenticação por API ou OAuth no mesmo formulário. Se o MCP não for oferecido no seletor, ele não está habilitado para esse espaço de trabalho.

Ensine ao agente o procedimento da API

Um conector personalizado fornece acesso seguro à rede e injeção de credenciais. O formulário de criação não envia nem descobre automaticamente um documento OpenAPI. Dê ao agente o endpoint, o método, os parâmetros e a resposta esperada na solicitação, ou registre esse procedimento em um fluxo de trabalho com uma referência de API anexada como arquivo.

Valide um novo conector com uma solicitação estreita, somente leitura, para um endpoint conhecido. Não existe uma solicitação genérica de Test connection, porque muitas APIs não expõem um endpoint raiz significativo.

Limites de segurança

• Somente prefixos HTTPS e endpoints MCP são aceitos.
• O firewall injeta a credencial salva apenas em solicitações correspondentes.
• O segredo salvo é criptografado em repouso e não é exposto ao agente como uma variável de ambiente.
• Não coloque chaves, tokens ou segredos de cliente em mensagens de chat, instruções de fluxo de trabalho ou arquivos anexados.
• Use uma credencial de serviço com os escopos upstream mínimos necessários para o fluxo de trabalho.

Solução de problemas

Próximos passos

• Veja Fluxos de trabalho para registrar trabalhos repetidos com conectores personalizados.
• Veja Permissões para entender como as credenciais de conectores personalizados são tratadas.
• Veja o Catálogo antes de criar algo personalizado — seu serviço já pode ser compatível.