| name | build-agent-flow |
| description | Construir ou modificar fluxos de AGENTE DE IA na APIPASS (Agent Builder). Use quando o pedido envolve um agente de IA, RAG ou base de conhecimento — "crie um agente de IA que...", "agente que analisa/responde...", "chatbot com base de conhecimento", "fluxo de RAG", "ingestao para vector store", "agente que consulta o banco e responde".
Ponto de entrada para fluxos com `.service.ai.AiAgent`, modelos LLM, memoria, tools, embeddings, vector store, document loaders e splitters. Carregue ANTES de montar os steps de IA. A mecanica compartilhada (trigger, stop, auth, versao, publish) e delegada a `/apipass-integrations:build-flow`.
|
| disable-model-invocation | false |
Construir Fluxo de Agente de IA na APIPASS
Fluxos de agente tem uma topologia diferente da cadeia linear de um fluxo comum. Este guia cobre SO o que e
especifico de agente. Para o resto (autenticacao, trigger, stop/responses/OAS, contadores, posicoes,
save → version → publish, autorizacoes por referencia), siga /apipass-integrations:build-flow e
/apipass-integrations:apipass-patterns. A anatomia de cada acao de IA esta em /apipass-integrations:apipass-agent-actions.
0. Quando usar esta skill
- Agente de IA (decide, usa tools/memoria, base de conhecimento) → esta skill (
.service.ai.AiAgent).
- Completion simples ("chame o ChatGPT para gerar/classificar X", sem tools) → passo linear
CHATGPT_CREATE_COMPLETION na build-flow comum. NAO precisa de agente.
- Fluxo de integracao comum (sem IA) →
/apipass-integrations:build-flow.
1. O conceito central: hub-and-spoke
O agente e um hub. Modelo, memoria e tools sao satelites que NAO entram na cadeia nextSteps —
eles "penduram" no agente por campos de id (*RouteConfigId) e ficam posicionados ABAIXO dele no canvas.
trigger → [ … pre-processamento … ] → AGENTE (a0) → a999
│ (ligacoes por *RouteConfigId, sem nextSteps)
┌───────────────┼───────────────┐
modelo (a1) memoria (a2) tool(s) (a3…)
│ (se for retriever RAG)
embedding (a4)
Apenas o agente participa do nextSteps (vem do pre-processamento, vai pro stop). Os satelites se ligam assim
(detalhe e shape de inputData em apipass-agent-actions):
| De → Para | Campo no pai | Back-ref no filho |
|---|
| Agente → Modelo (1) | llmModelRouteConfigId | aiAgentRouteConfigId |
| Agente → Memoria (1, opcional) | memoryRouteConfigId | aiAgentRouteConfigId |
| Agente → Tools (N) | toolRouteConfigs: [{ id, state: "LINKED" }] | aiAgentRouteConfigId (opcional) |
| Retriever → Embedding | embeddingModelRouteConfigId (em inputData) | vectorStoreRouteConfigId |
| Ingestor → Loader → Splitter | documentLoaderRouteConfigId / documentSplitterRouteConfigId (em inputData) | vectorStoreRouteConfigId / documentLoaderRouteConfigId |
2. Regras que mudam em relacao ao fluxo comum
- Saida do agente via
.response: leia {{$.a0.response}} no stop/interpolacoes — NAO .body. (As demais acoes de IA seguem .body.)
- Satelites fora do
nextSteps: se voce ligar modelo/memoria/tool por nextSteps, o designer quebra e o agente aparece "sem modelo". O vinculo e SO por *RouteConfigId.
endpointDefinitions faz o designer DESENHAR as arestas (o *RouteConfigId faz EXECUTAR — sozinho NAO renderiza). Hub e ingestor precisam de endpointDefinitions.bottomEndpoints (as portas de saida); cada satelite precisa de endpointDefinitions.targetPosition: "Top". Sem isso o canvas fica quebrado / "sem modelo" mesmo com a execucao funcionando — e a falha de render mais comum em fluxos com tool/embedding (um agente so-com-modelo as vezes renderiza sem, mas multi-satelite nao). Shapes exatos por no em apipass-agent-actions.label de porta = chave i18n REAL ou texto literal: portas do agente usam AI_AGENT.MODEL/.MEMORY/.TOOLS; loader usa DOCUMENT_LOADER.TEXT_SPLITTER. Para portas sem chave conhecida (ex. embedding de vector store) use texto literal ("Embedding") — uma chave i18n inexistente aparece crua no canvas.- Ligacoes simetricas: todo forward (
llmModelRouteConfigId) tem um back-ref (aiAgentRouteConfigId). Mantenha os dois lados.
toolRouteConfigs deduplicado: uma entrada por tool (o JSON exportado as vezes repete ids).- Tools dinamicas: parametros que o LLM preenche usam
{{$fromAI('nome','descricao','tipo')}} no inputData da tool; o label da tool e o nome que o LLM ve.
- Posicoes: o agente e
nodeSize: "large"; os satelites ficam ABAIXO (mesmo positionX aproximado, positionY ~210-500 maior). Todo step precisa de positionX/Y (ver build-flow).
3. Receita A — Agente conversacional / analitico (com tools)
- Trigger (REST para chatbot/webhook; ver
build-flow). Pre-processamento opcional (ler arquivo, etc.).
- Agente
.service.ai.AiAgent: systemMessage (instrucoes), userMessage (ex. {{$.trigger.body.text}}), nextSteps → a999.
- Modelo (
OPENAI/ANTHROPIC/…): inputData.modelName etc.; ligue via llmModelRouteConfigId/aiAgentRouteConfigId.
- Memoria (
SIMPLE_MEMORY) se for multi-turno: memoryRouteConfigId/aiAgentRouteConfigId.
- Tools: cada acao (SQL/HTTP/custom/retriever) entra em
toolRouteConfigs; use $fromAI(...) nos parametros que o LLM decide.
- Stop lendo
{{$.a0.response}} (com responses[] + oas — ver build-flow/apipass-patterns).
4. Receita B — Agente com base de conhecimento (RAG retrieval)
Igual a Receita A, com uma tool retriever de vector store:
- Tool
MONGODB_READ_DOCUMENT em toolRouteConfigs, com inputData.embeddingModelRouteConfigId → step de embedding.
- Embedding (
OPENAI_EMBEDDING…) com back-ref vectorStoreRouteConfigId apontando para o retriever.
- A base precisa estar populada — veja a Receita C (normalmente um fluxo separado de ingestao).
5. Receita C — Pipeline de ingestao para vector store (popular a base)
Fluxo (frequentemente um child flow / agendado) que indexa documentos. Cadeia linear ate o ingestor:
- (Opcional) limpar a colecao (
MONGODB_REMOVE) → listar arquivos (AFS_LIST_FILES/LIST_FILES) → LoopCanvas por arquivo (ver loop em build-flow).
- Dentro do loop: baixar/identificar o arquivo, depois o ingestor
MONGODB_INSERT_DOCUMENT (coreRouteType: "AI_VECTOR_STORE_INGESTOR").
- O ingestor amarra os satelites por
inputData: embeddingModelRouteConfigId → embedding; documentLoaderRouteConfigId → FILE_DOCUMENT_LOADER; e o loader aponta documentSplitterRouteConfigId → DOCUMENT_SPLITTER_BY_PARAGRAPH/_WORD/_CHARACTER. Back-refs simetricos (vectorStoreRouteConfigId, documentLoaderRouteConfigId).
- O splitter e OBRIGATORIO — todo
FILE_DOCUMENT_LOADER/URL_DOCUMENT_LOADER precisa de um splitter ligado (nao e opcional). Sem ele a ingestao fica incompleta.
- Ingerir TEXTO PURO (sem arquivo): nao existe loader de string. Grave o texto com
WRITE_FILE (coreRouteType: "WRITE_FILE_UTILITY"; saida em {{$.aX.filename}}) e aponte o FILE_DOCUMENT_LOADER.filePath para esse arquivo com documentType: "TEXT". Padrao util tambem para indexar resolucao de chamado vinda de webhook.
6. Construir, validar, publicar (delegado)
Pesquise o catalogo de IA com list_actions(group) e confirme shapes com get_action_struct(id) ou lendo um fluxo
existente (get_flow_development) — nunca invente campos.
Caveat de descoberta: list_actions pode truncar (~40 de N) e nao aplicar o filtro group — os grupos de IA (AI/VECTOR_STORE/CHAT_MEMORY) podem nem aparecer. Para os shapes de IA, prefira ler um fluxo real (list_flows(projectId) → get_flow_development(flowId)) ou get_action(groupId, id) com o id conhecido. A descoberta dependente de MCP deve ficar na thread principal: subagentes (Explore/researcher) rodam em sessao de auth separada e caem em login_necessario — eles nao compartilham o token.
Depois siga o ciclo padrao de build-flow:
create_flow → montar steps → save_flow_development (valida automatico) → create_version → publish_flow
(tudo com confirm: true e confirmacao do usuario). Autorizacoes (authId/authProvider) por provider via list_authorizations.
Principios
- A topologia e hub-and-spoke: satelites NUNCA na cadeia
nextSteps, so por *RouteConfigId (simetrico).
- Saida do agente sempre por
.response; demais acoes por .body.
- Nunca invente
type/actionId/campos de inputData — pesquise (apipass-agent-actions, get_action_struct, fluxo real).
- Credenciais sempre por referencia; nunca embuta chave de provider de IA no step.
Skills relacionadas
/apipass-integrations:apipass-agent-actions — anatomia das acoes de IA e do agente (referencia)/apipass-integrations:build-flow — mecanica compartilhada (trigger, stop, auth, save/version/publish)/apipass-integrations:apipass-patterns — estrutura do fluxo, contadores, publicacao, OAS/apipass-integrations:apipass-gotchas — erros comuns e debug de execucao
