YepAPI/skills

Agentes de IA

Regras

• Defina ferramentas como funções tipadas com descrições — o modelo escolhe qual ferramenta chamar
• Esquema da ferramenta: { nome, descrição, parâmetros: zodSchema, executar: async (args) => resultado }
• Loop multi-etapas: enviar mensagens → modelo retorna chamada de ferramenta → executar ferramenta → realimentar resultado → repetir até concluir
• Limite maxSteps para evitar loops infinitos — padrão de 5 a 10 etapas dependendo da complexidade
• Saídas estruturadas com Zod: generateObject({ schema: z.object({...}) }) para formato garantido
• Lógica de retry: envolver execução da ferramenta em try/catch, repetir falhas transitórias 2 a 3 vezes com backoff exponencial
• Orquestração de agentes: dividir tarefas complexas em subagentes com conjuntos de ferramentas focados, agente coordenador delega
• Sempre valide os resultados das ferramentas antes de realimentar o modelo — sanitize dados não confiáveis
• Use streamText com onToolCall para visibilidade em tempo real do raciocínio do agente

Padrões

// Definição de ferramenta
const tools = {
  searchDatabase: tool({
    description: "Pesquisar no banco de dados de produtos",
    parameters: z.object({ query: z.string(), limit: z.number().default(10) }),
    execute: async ({ query, limit }) => db.products.search(query, limit),
  }),
};

// Loop do agente
const result = await generateText({
  model,
  tools,
  maxSteps: 10,
  messages,
});

Evitar

• Dar aos agentes acesso irrestrito a ferramentas — limite as ferramentas à tarefa
• Esquecer de definir maxSteps — agentes podem entrar em loop infinito
• Confiar nas saídas das ferramentas sem validação — sempre verifique antes de agir com base nos resultados
• Agentes monolíticos — prefira subagentes focados em vez de um único agente com mais de 20 ferramentas