Pular para o conteúdo

Introdução aos agentes de programação com IA

A forma mais rápida de ligar é dentro do próprio PlaidCloud: abra o menu do avatar (utilizador) e escolha Ligue a sua IA, selecione o cliente que utiliza e siga os passos apresentados — incluindo o URL do servidor MCP da sua área de trabalho, já preenchido. Está disponível sempre que a sua área de trabalho tem o direito de IA ativado. O resto desta página, e as páginas por cliente que se lhe seguem, continuam a ser a referência — continue a ler se não estiver na interface web ou se pretender uma visão completa da autenticação e do que o servidor expõe.

O Model Context Protocol é um padrão aberto para permitir que agentes de IA comuniquem com ferramentas e dados externos. O PlaidCloud executa um servidor MCP em cada área de trabalho que encapsula os mesmos auxiliares centrais que a API REST utiliza — agrupados por intenção (find, describe, upsert, run, organize) para que um agente possa navegar pela superfície sem carregar mais de 1000 nomes de métodos RPC de baixo nível.

O servidor encontra-se em:

https://<your-workspace>.plaid.cloud/mcp

Substitua <your-workspace> pelo subdomínio da sua área de trabalho (o que utiliza para iniciar sessão na interface do PlaidCloud).

O catálogo abrange a maior parte da superfície quotidiana de que um agente precisa:

  • Projetos, fluxos de trabalho, passos — find/describe/upsert/run/organize, incluindo a reexecução ao nível do passo e o histórico de versões.
  • Tabelas, vistas, consultas — introspeção de esquemas, execução de consultas, exportações, instantâneos, ramos. As vistas são as mesmas que vê no PlaidCloud, quer as tenha criado no explorador de tabelas quer as tenha criado um fluxo de trabalho.
  • Dimensões — describe, find, upsert, versões, gestão de nós/aliases/propriedades.
  • Ligações — find/upsert/test de ligações a sistemas externos.
  • Lakehouse — ramos, instantâneos, operações de optimize/vacuum.
  • Identidade — membros, grupos, sessões, listas de distribuição.
  • Documentos, painéis de controlo, UDFs, editores, agentes, publicações — ferramentas específicas de cada domínio.
  • Migração de fluxos de trabalho — converta exportações do Alteryx (alteryx_convert), do KNIME (knime_convert), do Prophecy (prophecy_convert) e do Savant (savant_convert) preparadas em Documentos em fluxos de trabalho do PlaidCloud e coordene o trabalho de migração do portefólio.
  • Documentação do PlaidCloud — docs_search encontra páginas na documentação do PlaidCloud por palavra-chave e docs_fetch lê uma página na íntegra, para que o seu agente possa verificar como funciona uma funcionalidade antes de construir com ela.
  • Registos de fluxos de trabalho e acompanhamento de execuções — workflow_logs, workflow_run_status, workflow_job_track.

Cada ferramenta devolve um envelope uniforme {ok, data, next_cursor?, total?}; as falhas utilizam {ok: false, error: {code, retryable, message, hint?}}. As mutações aceitam dry_run=True para validação sem escrita.

Os resultados das ferramentas são o maior consumidor individual do contexto de um agente, pelo que as ferramentas find e describe devolvem por predefinição uma fatia modesta e permitem alargá-la:

  • Linhas. Um find devolve 25 correspondências por página (step_find devolve 50). Uma página limitada define next_cursor e as ferramentas find indicam adicionalmente a lista truncada em truncated — qualquer um dos dois significa “há mais”, não “são todas”. total indica sempre a contagem completa. Aumente limit ou pagine com o cursor.
  • Colunas. Passe fields=['id', 'name', 'update_time'] para obter apenas essas colunas. Um nome de campo que não aparece em nenhum registo é um erro que lista os campos disponíveis, e não uma omissão silenciosa — assim, um erro de escrita falha de forma visível em vez de devolver discretamente menos do que pediu. As ferramentas que oferecem conjuntos selecionados também aceitam field_set='minimal' | 'default' | 'full'; chame mcp_introspect para ver os parâmetros que uma determinada ferramenta aceita.
  • Contagens. count_only=True dimensiona um conjunto de resultados sem o obter.

O spec que uma ferramenta recebe, como o de project_upsert ou workflow_upsert, aceita apenas os campos que lista. Um campo que não reconhece é recusado com um erro que indica o campo, em vez de ser ignorado e de o deixar descobrir mais tarde que não fez nada. Corrija o nome e envie novamente o pedido. workflow_upsert recebe a descrição de um fluxo de trabalho como memo e aceita description como outro nome para ela.

mcp_batch agrupa várias chamadas de ferramentas num único pedido. Aceita no máximo 100 chamadas, executa um número limitado delas de cada vez e não pode ser aninhado dentro de outro mcp_batch nem de uma receita — liste as chamadas num único lote plano, o que não custa mais a enviar. Um lote acima do limite é recusado com uma mensagem que o indica, em vez de ser discretamente reduzido; o limite restringe o trabalho que um único pedido pode iniciar, não o total que pode fazer, pelo que deve dividir uma tarefa maior por vários lotes.

A receita paginate_through_listing pára após 200 páginas, por mais alto que seja o max_pages que lhe passe, e comunica partial: true quando pára antes do fim. Entre isso e o seu limite max_items, uma única chamada de paginação termina sempre.

Uma receita recusa uma chave de params que não reconhece e a mensagem lista as chaves que essa receita aceita — assim, um parâmetro opcional mal escrito falha de forma visível em vez de ser descartado, o que deixaria a chamada a responder discretamente a uma pergunta diferente da que fez. Chame mcp_recipes(name=...) para saber as chaves que uma determinada receita aceita.

Um resultado grande cujas linhas têm todas os mesmos campos é devolvido orientado por colunas, e não como uma lista de objetos, para que os nomes dos campos sejam enviados uma vez em vez de uma vez por linha:

{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}

A linha i é dict(zip(cols, rows[i])). Os resultados pequenos, e qualquer resultado cujas linhas não partilhem um conjunto idêntico de campos, mantêm-se como matrizes de objetos normais — pelo que ambas as formas aparecem, e o código que lê estas respostas diretamente deve tratar cada uma. O envelope em redor não muda e nenhum valor é convertido ou arredondado pelo caminho. Os agentes são informados desta forma quando se ligam e leem-na sem qualquer indicação da sua parte; a poupança é de cerca de 30% dos carateres e de cerca de 15% do orçamento de leitura de um agente no tráfego típico de listagens, o que é contexto que sobra para a sua pergunta real. (Os dois valores diferem porque os nomes de campos repetidos são baratos de ler para um modelo — a poupança em carateres é sempre a maior das duas.)

Para o catálogo atual, aponte o seu agente para o servidor e chame mcp_introspect (sem argumentos) — devolve o número atual de ferramentas, resumos por domínio e assinaturas de parâmetros. Utilize mcp_recipes para playbooks comuns de várias ferramentas (paginar listas grandes, instantâneo e depois modificação, reexecutar um passo com falha, etc.).

Cada ferramenta upsert que define etiquetas, para tabelas, fluxos de trabalho, passos, projetos, dimensões, vistas, editores, UDFs, ligações e armazéns, recebe dois parâmetros: labels adiciona etiquetas e remove_labels remove-as. As outras etiquetas do objeto mantêm-se. As remoções aplicam-se antes das adições, pelo que uma única chamada pode mudar o nome de uma etiqueta:

{"remove_labels": ["01"], "labels": ["001"]}

Remover uma etiqueta que o objeto não tem não faz nada.

As ferramentas de vistas funcionam com as vistas que vê no PlaidCloud:

  • view_find lista vistas e view_describe devolve uma por ID ou nome.
  • view_upsert cria uma vista ou atualiza uma no local. Uma atualização mantém o ID e as etiquetas da vista, e pode alterar apenas as suas etiquetas sem voltar a enviar a consulta.
  • view_organize elimina, muda o nome, duplica e move vistas.
  • Escreva os parâmetros de consulta como marcadores %(name)s.

As vistas partilham a árvore de pastas das tabelas, pelo que deve utilizar table_organize para gerir as respetivas pastas.

Construir fluxos de trabalho a partir de passos nativos

Seção intitulada “Construir fluxos de trabalho a partir de passos nativos”

Depois de os seus dados estarem no PlaidCloud, o seu agente é orientado a construir cada transformação a partir de passos nativos de tabela — os passos Table Extract, os de junção, Table Melt, Table Union All e Table Lookup — em vez de utilizar o passo Extrair SQL. Um passo nativo substitui as suas variáveis nos filtros e nas expressões, e o PlaidCloud gera o respetivo SQL para o armazém do seu projeto. Um passo Extrair SQL envia a sua consulta ao armazém tal como foi escrita: não substitui nenhuma variável e o SQL é escrito para um único armazém.

O seu agente pode experimentar uma configuração de Table Extract com query_run(mode='config') — a configuração que guardaria com step_upsert — e ver as respetivas linhas antes de guardar o passo. Quando guarda um passo Extrair SQL, step_upsert devolve uma entrada prefer_native_steps em config_warnings que indica os passos nativos a utilizar em alternativa, e describe_step_operation apresenta a mesma nota. O passo Extrair SQL continua disponível para o que nenhum passo nativo consegue exprimir.

O servidor inclui um pequeno conjunto de pontos de partida para as tarefas que as pessoas pedem pelo nome. Um cliente que suporte prompts MCP lista-os e oferece-os como um menu — consulte a documentação do seu cliente para saber onde os coloca — para que escolha a tarefa em vez de descrever a sequência de chamadas de ferramentas que ela exige:

Ponto de partida O que lhe fornece
Importar um ficheiro CSV para uma tabela O ficheiro e, opcionalmente, o projeto, a pasta que o contém e um nome para a nova tabela
Explicar uma alteração de custos A tabela de resultados e, opcionalmente, o projeto e os dois períodos
Depurar um fluxo de trabalho com falha O fluxo de trabalho e, opcionalmente, o projeto
Explorar os dados do projeto O que procura e, opcionalmente, o projeto

Cada um é uma mensagem inicial, não um comando: o seu agente lê-a e depois comanda ele próprio as ferramentas, pelo que pode editá-la ou continuar a conversa a partir daí.

Importar um ficheiro sem conhecer o modelo de objetos

Seção intitulada “Importar um ficheiro sem conhecer o modelo de objetos”

O ponto de partida de importação é o que mais trabalho poupa, porque o caminho ingénuo exige quatro ferramentas pela ordem certa — encontrar a conta de documentos, navegar até ao ficheiro, criar a tabela de destino e depois executar a importação — e um palpite errado em qualquer uma delas termina o fluxo várias chamadas depois.

Lê texto delimitado — CSV, TSV e semelhantes. Um livro do Excel ou um ficheiro Parquet é rejeitado em vez de mal interpretado; para os importar, utilize antes o passo de importação correspondente num fluxo de trabalho.

Em vez disso, o playbook bulk_import_csv recebe a conta pelo nome e o ficheiro pelo nome ou caminho:

mcp_recipe_run(name='bulk_import_csv', params={
'project_id': '<project>',
'document_path': 'sales_2026.csv',
'document_account': 'Demo Data',
})

Resolve a conta para o respetivo identificador, localiza o ficheiro, cria a tabela com as colunas e os tipos lidos do próprio ficheiro e carrega-a — pelo que não fornece nem um id de conta nem uma especificação de colunas. table_name assume por predefinição o nome do ficheiro sem a extensão e table_path a raiz do projeto.

Indique a pasta quando a souber — 'document_path': 'raw/sales_2026.csv' — e a pesquisa fica confinada a ela. Um ficheiro indicado numa pasta só é correspondido nessa pasta: um ficheiro com o mesmo nome mais abaixo é oferecido como uma opção em vez de ser importado no seu lugar.

Quando um argumento é ambíguo, o resultado pergunta em vez de adivinhar:

{
"needs_choice": "document_account",
"question": "More than one document account is named 'Archive'. Which one?",
"candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]
}

Mostre os candidatos à pessoa que está a ajudar e depois chame novamente o playbook com a resposta dela, devolvendo o candidato exatamente como foi indicado. Quando o ficheiro não é encontrado, a resposta lista os nomes mais próximos e indica quantos ficheiros pesquisou, para que “não está lá” se possa distinguir de “não está onde procurei”.

O servidor MCP do PlaidCloud aceita dois caminhos de autenticação:

  1. OAuth 2.1 + PKCE através do Dynamic Client Registration (DCR). É o que a interface de conectores personalizados do Claude.ai utiliza e é também a predefinição da ponte MCP do Claude Code. O cliente regista-se e redireciona-o para o início de sessão do Keycloak do PlaidCloud. Depois de iniciar sessão, o PlaidCloud mostra uma página Application Access Request que indica a aplicação e o URI de redirecionamento para o qual enviará as credenciais — aprove-a uma vez por autorização para obter o seu token. Trata-se de um controlo de segurança, não de uma formalidade: verifique se o nome da aplicação e o URI de redirecionamento correspondem ao cliente a que se está realmente a ligar e não aprove um pedido que não iniciou.
  2. Token de portador estático num cabeçalho Authorization. Para runtimes de agentes que não têm um redirecionamento de navegador utilizável ou que pretendem um token de longa duração num ficheiro de configuração. O PlaidCloud disponibiliza uma página auxiliar para o gerar por si (veja abaixo).

Abra este URL num separador do navegador onde já tenha iniciado sessão no PlaidCloud:

https://<your-workspace>.plaid.cloud/mcp/setup/token

A página devolve um excerto JSON pronto a colar na configuração MCP do seu agente. Cada área de trabalho tem o seu próprio excerto.

A duração do token é regida pela política de duração do token de acesso do realm Keycloak (normalmente entre algumas horas e um dia). Para o atualizar, volte a carregar o mesmo URL — a sessão do navegador volta a gerar o token automaticamente.

O resto desta secção percorre a configuração de clientes de agentes de IA específicos:

  • Claude Code — o agente de programação da Anthropic (CLI, extensão do VSCode, plugin do JetBrains).
  • Claude Desktop e Claude.ai — a aplicação Claude para consumidores (ambiente de trabalho) e a web (claude.ai) com “Custom Connectors”.
  • Cursor — o editor de código nativo de IA.
  • GitHub Copilot — o modo de agente do Copilot no VSCode.
  • Google Gemini CLI — gemini-cli e Gemini Code Assist.
  • ChatGPT — estado atual do suporte e solução alternativa recomendada.
  • Grok — ligar os conectores personalizados do Grok.
  • Resolução de problemas — erros comuns e como os corrigir.