diff --git a/README.md b/README.md index 45fe50234..5ec043aaf 100644 --- a/README.md +++ b/README.md @@ -20,43 +20,49 @@ -PraisonAI is a production-ready Multi-AI Agents framework with self-reflection, designed to create AI Agents to automate and solve problems ranging from simple tasks to complex challenges. By integrating PraisonAI Agents, AG2 (Formerly AutoGen), and CrewAI into a low-code solution, it streamlines the building and management of multi-agent LLM systems, emphasising simplicity, customisation, and effective human-agent collaboration. + +PraisonAI is a fork of the original [MervinPraison/PraisonAI](https://github.com/MervinPraison/PraisonAI) project. +This edition is maintained by [Habdel-Edenfield](https://github.com/Habdel-Edenfield) and aims to be a **learning laboratory** for AI agent development. +Our goal is to provide clear examples and practical documentation for building multi‑agent systems. +The repository is under continuous development, with new features being added over time.

Documentation

- +- 📄 **YAML Configuration** – [[YAML Guide]](docs/pt-br/03_usando_praisonai/06_configuracoes_yaml.md)
+For details in Portuguese, see the [PT-BR documentation](docs/pt-br/README.md). + ## Key Features -- 🤖 Automated AI Agents Creation -- 🔄 Self Reflection AI Agents -- 🧠 Reasoning AI Agents -- 👁️ Multi Modal AI Agents -- 🤝 Multi Agent Collaboration -- 🎭 AI Agent Workflow -- 📚 Add Custom Knowledge -- 🧠 Agents with Short and Long Term Memory -- 📄 Chat with PDF Agents -- 💻 Code Interpreter Agents -- 📚 RAG Agents -- 🤔 Async & Parallel Processing -- 🔄 Auto Agents -- 🔢 Math Agents -- 🎯 Structured Output Agents -- 🔗 LangChain Integrated Agents -- 📞 Callback Agents -- 🤏 Mini AI Agents -- 🛠️ 100+ Custom Tools -- 📄 YAML Configuration -- 💯 100+ LLM Support - -## Using Python Code - -Light weight package dedicated for coding: +- 🤖 **Automated Agent Creation** – [[Quick Guide]](docs/pt-br/03_usando_praisonai/04_criando_seu_primeiro_agente.md) +- 🔄 **Self‑Reflection Agents** – [[Evaluator/Optimizer]](docs/pt-br/04_workflows_avancados/07_avaliador_otimizador_agentico.md) +- 🧠 **Reasoning Agents** – [[Autonomous Workflows]](docs/pt-br/04_workflows_avancados/04_workflow_autonomo_agentico.md) +- 👁️ **Multimodal Agents** – [[Multimodal Agents]](docs/pt-br/04_workflows_avancados/09_agentes_multimodais.md) +- 🤝 **Multi‑Agent Collaboration** – [[Collaboration Processes]](docs/pt-br/04_workflows_avancados/01_processos_colaboracao_agentes.md) +- 🎭 **Agent Workflows** – [[Overview]](docs/pt-br/04_workflows_avancados/02_workflow_roteamento_agentico.md) +- 📚 **Add Custom Knowledge** – [[RAG Concepts]](docs/pt-br/02_conceitos_fundamentais/06_conhecimento_rag.md) +- 🧠 **Short- and Long‑Term Memory** – [[Memory Concepts]](docs/pt-br/02_conceitos_fundamentais/05_memoria.md) +- 📄 **Chat with PDFs** – [[RAG Concepts]](docs/pt-br/02_conceitos_fundamentais/06_conhecimento_rag.md#chat-with-pdf-agents) +- 💻 **Code Interpreter Agents** – [[Code Interpreter Agents]](docs/pt-br/04_workflows_avancados/10_code_interpreter_agents.md) +- 📚 **RAG Agents** – [[RAG Concepts]](docs/pt-br/02_conceitos_fundamentais/06_conhecimento_rag.md) +- 🤔 **Async & Parallel Processing** – [[Parallelization]](docs/pt-br/04_workflows_avancados/05_paralelizacao_agentica.md) +- 🔄 **Auto Agents** – [[Python Usage]](docs/pt-br/03_usando_praisonai/01_usando_com_python.md#explorando-mais-exemplos-python) +- 🔢 **Math Agents** – [[Math Agents]](docs/pt-br/04_workflows_avancados/11_math_agents.md) +- 🎯 **Structured Output** – [[Structured Output]](docs/pt-br/04_workflows_avancados/12_saida_estruturada.md) +- 🔗 **LangChain Integration** – [[Tools]](docs/pt-br/02_conceitos_fundamentais/04_ferramentas.md#conceito-fundamental-ferramentas-tools) +- 📞 **Callback Agents** – [[Callback Agents]](docs/pt-br/04_workflows_avancados/13_callback_agents.md) +- 🤏 **Mini Agents** – [[Mini Agents]](docs/pt-br/04_workflows_avancados/14_mini_agents.md) +- 🛠️ **100+ Custom Tools** – [[Tools]](docs/pt-br/02_conceitos_fundamentais/04_ferramentas.md) +- 📄 **YAML Configuration** – [[YAML Guide]](docs/pt-br/03_usando_praisonai/02_usando_com_yaml.md) +- 💯 **100+ LLM Support** – [[LLM Models]](docs/pt-br/06_modelos_llm/00_usando_diferentes_llms.md) + +## Using with Python + +Lightweight package for programming: ```bash pip install praisonaiagents ``` @@ -67,21 +73,22 @@ export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx ### 1. Single Agent -Create app.py file and add the code below: +Create a file named `app.py` and add the code below: ```python from praisonaiagents import Agent agent = Agent(instructions="Your are a helpful AI assistant") agent.start("Write a movie script about a robot in Mars") ``` -Run: +Execute: ```bash python app.py ``` -### 2. Multi Agents -Create app.py file and add the code below: +### 2. Multiple Agents + +Create a file named `app.py` and add the code below: ```python from praisonaiagents import Agent, PraisonAIAgents @@ -91,21 +98,22 @@ agents = PraisonAIAgents(agents=[research_agent, summarise_agent]) agents.start() ``` -Run: +Execute: ```bash python app.py ``` -## Using No Code -### Auto Mode: +## No-Code Usage + +### Automatic Mode: ```bash pip install praisonai export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx praisonai --auto create a movie script about Robots in Mars ``` -## Using JavaScript Code +## Using with JavaScript ```bash npm install praisonai @@ -546,6 +554,24 @@ uv pip install -r pyproject.toml --extra "crewai,autogen" - Submit a pull request via GitHub's web interface. - Await feedback from project maintainers. +### Setup for Local Development +To install the package in editable mode run: + +```bash +git clone https://github.com/MervinPraison/PraisonAI.git +cd PraisonAI +pip install -e .[dev] +``` + +External dependencies such as `duckduckgo_search` are not installed automatically. +Install them manually when running tests or examples that require them: + +```bash +pip install duckduckgo_search +``` + +Automated environments without network access should use a setup script that preinstalls these dependencies before executing tests. + ## Other Features - 🔄 Use CrewAI or AG2 (Formerly AutoGen) Framework diff --git a/docs/00_introducao/00_como_usar_esta_documentacao.md b/docs/00_introducao/00_como_usar_esta_documentacao.md new file mode 100644 index 000000000..853211096 --- /dev/null +++ b/docs/00_introducao/00_como_usar_esta_documentacao.md @@ -0,0 +1,45 @@ +# TODO: Translate this file to English + +# Como Usar Esta Documentação (E Dicas para Obsidian) + +Esta documentação foi pensada para ser um recurso completo para o seu aprendizado sobre o PraisonAI, com foco especial na utilização através do [Obsidian](https://obsidian.md/). + +## Navegação + +A estrutura de pastas foi organizada em módulos sequenciais. Recomendamos seguir a ordem para um aprendizado progressivo. Utilize os links internos para navegar entre os tópicos relacionados e construir um mapa mental dos conceitos. Para entender como aproveitar melhor cada módulo, consulte também a seção [Metodologia de Aprendizado](03_metodologia_de_aprendizado.md). +Para ver um exemplo completo e rápido de configuração de agentes, consulte [Criando Seu Primeiro Agente](../03_usando_praisonai/04_criando_seu_primeiro_agente.md). Para conhecer os diferentes [Modelos de Agentes](../03_usando_praisonai/05_modelos_de_agentes.md) disponíveis, acesse a seção dedicada. Se quiser personalizar seus próprios arquivos, veja também [Configurações com YAML](../03_usando_praisonai/06_configuracoes_yaml.md). +Caso surjam dúvidas durante seus testes, consulte também a [Dúvidas Frequentes](../09_duvidas_frequentes.md). + +## Plugins Obsidian Sugeridos + +Para a melhor experiência ao visualizar este material no Obsidian, sugerimos instalar os seguintes plugins (se ainda não os tiver): + +1. **Mermaid Tools / Charts / Diagrams:** + * **Utilidade:** Muitos diagramas neste curso são feitos com Mermaid (uma linguagem para gerar diagramas a partir de texto). Este tipo de plugin permite que o Obsidian renderize esses diagramas corretamente. + * **Como usar:** Após instalar, os blocos de código marcados como ```mermaid ... ``` serão transformados em diagramas visuais. + +2. **Advanced Tables:** + * **Utilidade:** Facilita a criação e edição de tabelas formatadas em Markdown. Usaremos tabelas para comparar funcionalidades, listar parâmetros, etc. + * **Como usar:** Oferece uma barra de ferramentas e atalhos para manipular tabelas. + +3. **Callout Manager (ou customização via CSS snippets):** + * **Utilidade:** O Obsidian suporta "callouts" (blocos de destaque) nativamente (ex: \`>[!info] ...\`). Um Callout Manager pode oferecer mais tipos de callouts ou facilitar a customização da aparência deles. Alternativamente, você pode usar CSS snippets para personalizar os callouts padrão. + * **Como usar:** Permite destacar informações como dicas, avisos, exemplos importantes de forma visual. Exemplo de callout: + ```markdown + > [!TIP] Dica Importante + > Esta é uma informação que você não vai querer perder! + ``` + +4. **Excalidraw (Opcional):** + * **Utilidade:** Permite integrar desenhos e diagramas no estilo "quadro branco" diretamente nas suas notas do Obsidian. Pode ser útil se você quiser fazer seus próprios esquemas visuais enquanto estuda. + * **Como usar:** Cria um novo tipo de arquivo (Excalidraw) que pode ser embutido ou linkado em suas notas Markdown. + +## Formato dos Arquivos + +Todos os arquivos são em formato Markdown (`.md`), o que garante portabilidade e fácil edição. + +## Feedback + +Se encontrar erros, tiver sugestões ou dúvidas, sinta-se à vontade para abrir uma issue no repositório original deste curso. + +Aproveite os estudos! diff --git a/docs/00_introducao/01_o_que_e_praisonai.md b/docs/00_introducao/01_o_que_e_praisonai.md new file mode 100644 index 000000000..0f471e736 --- /dev/null +++ b/docs/00_introducao/01_o_que_e_praisonai.md @@ -0,0 +1,158 @@ +# TODO: Translate this file to English + +# O que é o PraisonAI? + +

+ + + + PraisonAI Logo + +

+ +PraisonAI é um framework de **Múltiplos Agentes de IA (Multi-AI Agents)** pronto para produção e com capacidade de **auto-reflexão**. Ele foi projetado para criar Agentes de IA que automatizam e resolvem problemas, desde tarefas simples até desafios complexos. Ao integrar PraisonAI Agents, AG2 (anteriormente AutoGen) e CrewAI em uma solução de **baixo código (low-code)**, ele simplifica a construção e o gerenciamento de sistemas LLM multi-agentes, enfatizando a simplicidade, personalização e colaboração eficaz entre humanos e agentes. + +
+ +

+ Documentação Oficial +

+ +
+ +## Principais Recursos (Key Features) + +O PraisonAI oferece uma vasta gama de funcionalidades para construir agentes poderosos: + +- **Criação Automatizada de Agentes de IA:** Facilidade na definição e instanciação de agentes. +- **Agentes de IA com Auto-Reflexão:** Capacidade dos agentes de analisar e melhorar seu próprio desempenho. +- **Agentes de IA com Raciocínio:** Habilidade de realizar pensamentos lógicos e dedutivos. +- **Agentes de IA Multi Modais:** Suporte para processar diferentes tipos de dados (texto, imagem, etc.). +- **Colaboração Multi-Agente:** Permite que múltiplos agentes trabalhem juntos em tarefas complexas. +- **Workflow de Agentes de IA:** Definição de fluxos de trabalho para orquestrar a interação entre agentes. +- **Adição de Conhecimento Personalizado (RAG):** Integre bases de conhecimento específicas para seus agentes. +- **Agentes com Memória de Curto e Longo Prazo:** Capacidade de reter informações entre interações. +- **Agentes para Conversar com PDF:** Extraia informações e interaja com o conteúdo de arquivos PDF. +- **Agentes Interpretadores de Código:** Permitem que agentes executem código para realizar tarefas. +- **Processamento Assíncrono e Paralelo:** Execução eficiente de tarefas. +- **Auto Agents:** Agentes que podem gerar outros agentes ou modificar a si mesmos. +- **Agentes Matemáticos:** Especializados em resolver problemas matemáticos. +- **Agentes com Saída Estruturada:** Garantem que a resposta do agente siga um formato específico. +- **Agentes Integrados com LangChain:** Aproveite o ecossistema LangChain. +- **Agentes com Callback:** Funções que são chamadas em determinados pontos da execução do agente. +- **Mini Agentes de IA:** Agentes leves para tarefas específicas. +- **Mais de 100 Ferramentas Personalizadas:** Um vasto conjunto de ferramentas prontas para uso. +- **Configuração via YAML:** Defina agentes e workflows de forma declarativa. +- **Suporte a Mais de 100 Modelos de LLM:** Flexibilidade na escolha do modelo de linguagem. + +## Fluxo dos Agentes de IA (AI Agents Flow) + +Este diagrama ilustra um fluxo básico de como os agentes podem interagir em um sistema: + + + +```mermaid +graph LR + Inicio(Inicio) --> Agente1 + Agente1 --> Processo(Processar) + Processo --> Agente2 + Agente2 --> Resultado(Resultado) + Processo -.-> Agente1 + subgraph Agente1["Agente 1"] + Tarefa1(Tarefa) + IconeAgente1("Agente de IA") + Ferramentas1(Ferramentas) + Tarefa1 --- IconeAgente1 + IconeAgente1 --- Ferramentas1 + end + subgraph Agente2["Agente 2"] + Tarefa2(Tarefa) + IconeAgente2("Agente de IA") + Ferramentas2(Ferramentas) + Tarefa2 --- IconeAgente2 + IconeAgente2 --- Ferramentas2 + end + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef tools fill:#2E8B57,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Inicio,Resultado,Tarefa1,Tarefa2 input + class Processo,IconeAgente1,IconeAgente2 process + class Ferramentas1,Ferramentas2 tools + class Agente1,Agente2 transparent +``` + + + + +* **Explicação:** O processo geralmente começa com uma entrada (Início) que é passada para um Agente 1. Este agente, utilizando suas Ferramentas, processa sua Tarefa. O resultado pode ser passado para um Agente 2 para processamento adicional ou pode haver um ciclo onde o processo retorna ao Agente 1. Finalmente, um Resultado é produzido. + +## Agentes de IA com Ferramentas (AI Agents with Tools) + +Os agentes no PraisonAI podem utilizar ferramentas para interagir com sistemas externos e realizar ações: + +```mermaid +flowchart TB + subgraph Ferramentas + direction TB + T3["Busca na Internet"] + T1["Execucao de Codigo"] + T2["Formatacao"] + end + Entrada["Entrada"] ---> Agentes + subgraph Agentes + direction LR + A1["Agente 1"] + A2["Agente 2"] + A3["Agente 3"] + end + Agentes ---> Saida["Saida"] + T3 --> A1 + T1 --> A2 + T2 --> A3 + style Ferramentas fill:#189AB4,color:#fff + style Agentes fill:#8B0000,color:#fff + style Entrada fill:#8B0000,color:#fff + style Saida fill:#8B0000,color:#fff +``` +* **Explicação:** Diferentes agentes (Agente 1, Agente 2, Agente 3) podem ser equipados com diversas ferramentas (Busca na Internet, Execução de Código, Formatação). Com base na Entrada, os agentes utilizam suas ferramentas para processar a informação e gerar uma Saída. + +## Agentes de IA com Memória (AI Agents with Memory) + +A capacidade de memória permite que os agentes mantenham contexto e informação através de múltiplas tarefas: + +```mermaid +flowchart TB + subgraph Memoria ["Memoria"] + direction TB + MCP["Curto Prazo"] + MLP["Longo Prazo"] + end + subgraph Armazenamento ["Armazenamento"] + direction TB + BD["(Vector DB)"] + end + Entrada["Entrada"] ---> Agentes + subgraph Agentes + direction LR + A1["Agente 1"] + A2["Agente 2"] + A3["Agente 3"] + end + Agentes ---> Saida["Saida"] + Memoria <--> Armazenamento + Armazenamento <--> A1 + Armazenamento <--> A2 + Armazenamento <--> A3 + style Memoria fill:#189AB4,color:#fff + style Armazenamento fill:#2E8B57,color:#fff + style Agentes fill:#8B0000,color:#fff + style Entrada fill:#8B0000,color:#fff + style Saida fill:#8B0000,color:#fff +``` +* **Explicação:** Os agentes podem acessar memória de Curto Prazo (para contexto imediato) e de Longo Prazo (para conhecimento persistente). A memória de Longo Prazo é frequentemente implementada utilizando um Banco de Dados Vetorial (Vector DB) para buscas semânticas eficientes. Os agentes interagem com essa memória para informar suas ações e gerar a Saída. + +> [!NOTE] Nota sobre os Logos +> Os logos originais do PraisonAI (light/dark) não estão presentes neste repositório. Se desejar usá-los, você precisará baixá-los do repositório original ou da documentação oficial e colocá-los na pasta \`docs/pt-br/recursos/\`. As referências de imagem neste arquivo foram ajustadas para \`../recursos/logo_light.png\` e \`../recursos/logo_dark.png\`. + +Este arquivo serve como uma introdução geral ao PraisonAI. Nos próximos tópicos, detalharemos cada um desses recursos e conceitos. diff --git a/docs/00_introducao/02_filosofia_e_casos_de_uso.md b/docs/00_introducao/02_filosofia_e_casos_de_uso.md new file mode 100644 index 000000000..fbf076771 --- /dev/null +++ b/docs/00_introducao/02_filosofia_e_casos_de_uso.md @@ -0,0 +1,49 @@ +# TODO: Translate this file to English + +# Filosofia e Casos de Uso do PraisonAI + +## Filosofia do Projeto + +O PraisonAI foi construído com algumas filosofias centrais em mente, que guiam seu desenvolvimento e funcionalidades: + +1. **Pronto para Produção (Production-Ready):** O framework é projetado para ser robusto e confiável o suficiente para ser implantado em aplicações reais e ambientes de produção. +2. **Baixo Código (Low-Code):** Embora ofereça flexibilidade para codificação avançada, o PraisonAI visa simplificar o desenvolvimento de agentes de IA, permitindo que usuários com menos experiência em programação possam construir sistemas complexos, especialmente através da configuração via YAML. +3. **Simplicidade e Customização:** Busca um equilíbrio entre ser fácil de usar para iniciantes e altamente customizável para desenvolvedores experientes que precisam de funcionalidades específicas. +4. **Colaboração Eficaz Humano-Agente:** Enfatiza a criação de sistemas onde humanos e agentes de IA podem colaborar de forma produtiva. Isso inclui mecanismos de feedback, aprovação e monitoramento. +5. **Auto-Reflexão e Melhoria Contínua:** Os agentes são incentivados a ter capacidades de auto-reflexão, permitindo que analisem seus próprios resultados e melhorem seu desempenho ao longo do tempo. +6. **Integração e Ecossistema:** O PraisonAI se integra com outros frameworks populares como CrewAI e AG2 (AutoGen), e suporta uma vasta gama de Modelos de Linguagem (LLMs) e ferramentas, promovendo a interoperabilidade. +7. **Automação de Tarefas Complexas:** O objetivo final é capacitar os usuários a automatizar desde tarefas rotineiras simples até desafios multifacetados que exigem a colaboração de múltiplos agentes especializados. + +## Casos de Uso Comuns + +A flexibilidade do PraisonAI permite sua aplicação em uma ampla variedade de cenários. Alguns casos de uso comuns incluem: + +* **Atendimento ao Cliente Inteligente:** + * **Descrição:** Construção de agentes de suporte que podem entender as perguntas dos clientes, fornecer respostas precisas, resolver problemas e, se necessário, encaminhar para atendentes humanos. + * **Funcionalidades PraisonAI Relevantes:** RAG (para buscar em bases de conhecimento), Memória (para lembrar interações passadas), Integração com Ferramentas (para acessar sistemas de CRM). + +* **Análise de Dados Automatizada:** + * **Descrição:** Criação de agentes que podem processar grandes volumes de dados, identificar padrões, gerar insights e criar relatórios. + * **Funcionalidades PraisonAI Relevantes:** Agentes Interpretadores de Código (para executar scripts de análise), Saída Estruturada (para formatar os resultados), Ferramentas de Visualização de Dados. + +* **Criação de Conteúdo Personalizado:** + * **Descrição:** Desenvolvimento de agentes que podem gerar, editar e otimizar conteúdo para diferentes plataformas (artigos de blog, posts em redes sociais, roteiros de vídeo, etc.), adaptando-se a diferentes estilos e públicos. + * **Funcionalidades PraisonAI Relevantes:** Múltiplos Agentes (para diferentes etapas do processo criativo), Ferramentas de Busca na Web (para pesquisa), Auto-Reflexão (para melhorar a qualidade do conteúdo). + +* **Automação de Processos de Negócios (BPA):** + * **Descrição:** Orquestração de workflows complexos que envolvem múltiplas etapas e sistemas, como processamento de pedidos, integração de novos funcionários (onboarding) ou gerenciamento da cadeia de suprimentos. + * **Funcionalidades PraisonAI Relevantes:** Workflow de Agentes, Colaboração Multi-Agente, Ferramentas de Integração com APIs. + +* **Pesquisa e Coleta de Informações:** + * **Descrição:** Agentes que podem realizar pesquisas extensivas na web, em documentos ou bancos de dados, sumarizar informações e apresentar relatórios concisos. + * **Funcionalidades PraisonAI Relevantes:** RAG, Ferramentas de Busca (Tavily, Crawl4AI), Agentes de Sumarização. + +* **Desenvolvimento e Revisão de Código:** + * **Descrição:** Agentes que auxiliam no desenvolvimento de software, sugerindo código, revisando pull requests, identificando bugs ou explicando trechos de código. + * **Funcionalidades PraisonAI Relevantes:** Agentes Interpretadores de Código, Chat com a Base de Código, Ferramentas de Análise Estática. + +* **Assistentes Pessoais Inteligentes:** + * **Descrição:** Criação de assistentes personalizados que podem gerenciar agendas, responder e-mails, planejar viagens ou realizar tarefas específicas definidas pelo usuário. + * **Funcionalidades PraisonAI Relevantes:** Memória, Ferramentas de Calendário/Email, Capacidade de aprender as preferências do usuário. + +Estes são apenas alguns exemplos. A natureza modular e extensível do PraisonAI permite que ele seja adaptado para muitos outros domínios e desafios. O limite é, em grande parte, a criatividade e a necessidade do desenvolvedor. diff --git a/docs/00_introducao/03_metodologia_de_aprendizado.md b/docs/00_introducao/03_metodologia_de_aprendizado.md new file mode 100644 index 000000000..5490ff156 --- /dev/null +++ b/docs/00_introducao/03_metodologia_de_aprendizado.md @@ -0,0 +1,35 @@ +# TODO: Translate this file to English + +# Metodologia de Aprendizado + +Este curso foi estruturado com base em princípios de ensino científico para que você progrida de forma gradual e tenha segurança ao aplicar o PraisonAI na prática. + +## 1. Ciclo de Aprendizado + +1. **Apresentação do Conceito** + - Cada módulo inicia com uma breve exposição teórica do tema. +2. **Exemplos Guiados** + - Em seguida você encontra exemplos completos para reproduzir no terminal ou em seu editor. +3. **Prática Ativa** + - É recomendável digitar os comandos manualmente para reforçar a memorização. +4. **Reflexão e Revisão** + - Ao final de cada seção, revise o que funcionou e anote dúvidas antes de prosseguir. + +> [!TIP] +> Use a técnica de Feynman: tente explicar o assunto com suas próprias palavras a outra pessoa ou em notas. Se travar em alguma parte, retorne à documentação e revise. + +## 2. Ambiente de Estudos + +- Organize uma pasta dedicada para testar os exemplos. +- Mantenha um terminal aberto para executar os comandos passo a passo. +- Utilize o Obsidian ou outro editor Markdown para registrar suas observações. + +## 3. Aprofundamento Progressivo + +A documentação foi pensada para que cada módulo dependa do anterior. Se algum conceito ainda não estiver claro, volte ao módulo correspondente e refaça os exercícios. Essa repetição espaçada ajuda na fixação a longo prazo. + +## Próximos Passos + +Após dominar esta metodologia, avance para o módulo de **Instalação** e siga a sequência sugerida no README principal. + +Bom estudo! diff --git a/docs/01_instalacao/00_instalacao_windows.md b/docs/01_instalacao/00_instalacao_windows.md new file mode 100644 index 000000000..ae3359e39 --- /dev/null +++ b/docs/01_instalacao/00_instalacao_windows.md @@ -0,0 +1,188 @@ +# TODO: Translate this file to English + +# Guia de Instalação Local (Windows) + +Este guia detalha como instalar o framework PraisonAI em um ambiente Windows, permitindo que você comece a criar e executar seus próprios agentes de IA. + +## Pré-requisitos + +Antes de começar, garanta que você tenha os seguintes pré-requisitos instalados e configurados em seu sistema Windows: + +1. **Python:** + * **Versão:** É recomendável usar Python 3.8 ou superior. + * **Como verificar:** Abra o Prompt de Comando (CMD) ou PowerShell e digite: + ```bash + python --version + ``` + * **Como instalar:** Se não tiver o Python ou tiver uma versão muito antiga, baixe o instalador mais recente em [python.org](https://www.python.org/downloads/windows/). + > [!IMPORTANT] Durante a Instalação do Python + > Marque a opção **"Add Python to PATH"** (ou "Adicionar Python ao PATH") durante o processo de instalação. Isso facilitará a execução de comandos Python e pip diretamente do terminal. Se você esqueceu de fazer isso, precisará adicionar manualmente os diretórios do Python e Scripts ao PATH do sistema. + +2. **pip (Gerenciador de Pacotes Python):** + * **Como verificar:** O pip geralmente é instalado automaticamente com o Python (a partir da versão 3.4). Verifique com: + ```bash + pip --version + ``` + * **Como atualizar (recomendado):** + ```bash + python -m pip install --upgrade pip + ``` + +3. **Git (Opcional, mas Altamente Recomendado):** + * **Utilidade:** Necessário para clonar o repositório do PraisonAI se você quiser acessar os exemplos mais recentes, contribuir para o projeto ou trabalhar com a versão de desenvolvimento. + * **Como instalar:** Baixe e instale o Git para Windows em [git-scm.com](https://git-scm.com/download/win). + +## Configurando Variáveis de Ambiente + +Para que o PraisonAI funcione corretamente, especialmente ao interagir com modelos de linguagem pagos (como os da OpenAI), você precisará configurar variáveis de ambiente. A mais comum é a `OPENAI_API_KEY`. + +**Opção 1: Temporariamente (para a sessão atual do terminal)** + +Abra o Prompt de Comando ou PowerShell e use o comando `set`: +```bash +set OPENAI_API_KEY=sua_chave_api_aqui +``` +> [!WARNING] Chave Temporária +> Esta configuração será perdida quando você fechar o terminal. + +**Opção 2: Permanentemente (para o usuário atual)** + +Use o comando `setx`. Ele adiciona a variável permanentemente, mas você precisará abrir um **novo** terminal para que as alterações tenham efeito. +```bash +setx OPENAI_API_KEY "sua_chave_api_aqui" +``` +> [!NOTE] Aspas em `setx` +> É uma boa prática usar aspas ao redor do valor da chave com `setx`, especialmente se ela contiver caracteres especiais (embora chaves de API geralmente não contenham). + +**Opção 3: Permanentemente (via Interface Gráfica do Windows)** + +1. Pressione a tecla `Windows`, digite "variáveis de ambiente" e selecione "Editar as variáveis de ambiente do sistema". +2. Na janela "Propriedades do Sistema", clique no botão "Variáveis de Ambiente...". +3. Na seção "Variáveis de usuário para [Seu Nome de Usuário]", clique em "Novo...". + * **Nome da variável:** `OPENAI_API_KEY` + * **Valor da variável:** `sua_chave_api_aqui` +4. Clique "OK" em todas as janelas. Você precisará abrir um novo terminal para que as alterações tenham efeito. + +Outras variáveis de ambiente importantes, como `OPENAI_BASE_URL` (para usar com Ollama ou Groq), podem ser configuradas da mesma forma. + +## Instalação do PraisonAI + +Existem duas formas principais de instalar o PraisonAI: + +### 1. Para Usuários (`praisonaiagents` e `praisonai` CLI) + +Esta é a forma recomendada para a maioria dos usuários que desejam utilizar o PraisonAI para criar e executar agentes. + +* **`praisonaiagents` (Pacote leve para codificação):** + Se você pretende principalmente usar o PraisonAI programaticamente em Python. + ```bash + pip install praisonaiagents + ``` + +* **`praisonai` (Pacote completo com CLI e modo "No Code"):** + Se você quer a experiência completa, incluindo a interface de linha de comando (CLI) para executar arquivos YAML e o modo automático. + ```bash + pip install praisonai + ``` + Este pacote geralmente inclui `praisonaiagents` como dependência. + +### 2. Para Desenvolvedores (Trabalhando com o Código Fonte) + +Se você pretende contribuir para o PraisonAI, modificar seu código-fonte ou usar as versões mais recentes diretamente do repositório. + +1. **Clone o repositório:** + ```bash + git clone https://github.com/MervinPraison/PraisonAI.git + cd PraisonAI + ``` + +2. **Crie e Ative um Ambiente Virtual (Recomendado):** + ```bash + python -m venv .venv + # No CMD: + .venv\Scripts\activate + # No PowerShell: + .venv\Scripts\Activate.ps1 + ``` + +3. **Instale `uv` (um instalador Python rápido):** + O `README.md` do projeto sugere o uso de `uv`. + ```bash + pip install uv + ``` + +4. **Instale as dependências usando `uv`:** + O PraisonAI usa `pyproject.toml` para gerenciar suas dependências. + * Instalação básica: + ```bash + uv pip install -e . + ``` + O `-e .` instala o projeto em modo editável, o que significa que as alterações no código-fonte são refletidas imediatamente. + + * Instalação com extras (para funcionalidades específicas como `code`, `crewai`, `autogen`): + Consulte o arquivo `pyproject.toml` para ver os extras disponíveis. Exemplos: + ```bash + uv pip install -e .[code] + uv pip install -e .[crewai,autogen] + # Para instalar todos os extras, pode haver uma opção como [all] ou você precisará listá-los. + # Verifique o pyproject.toml para a sintaxe correta dos extras. + ``` + Alternativamente, se o `pyproject.toml` estiver configurado para isso, você pode instalar diretamente dele: + ```bash + uv pip install -r pyproject.toml --extra code + ``` + +## Verificando a Instalação + +Após a instalação, você pode verificar se tudo está funcionando corretamente. + +**Se você instalou `praisonaiagents`:** + +Crie um arquivo Python simples (ex: `teste_agente.py`): +```python +from praisonaiagents import Agent + +try: + # Certifique-se de ter sua OPENAI_API_KEY configurada como variável de ambiente + agente_teste = Agent(instructions="Você é um assistente prestativo.") + resposta = agente_teste.start("Escreva uma frase curta sobre IA.") + print("Resposta do Agente:", resposta) +except Exception as e: + print(f"Ocorreu um erro: {e}") + print("Verifique se sua chave OPENAI_API_KEY está configurada corretamente.") +``` +Execute-o: +```bash +python teste_agente.py +``` + +**Se você instalou `praisonai` (com CLI):** + +Verifique a CLI: +```bash +praisonai --version +``` +Tente o modo automático (requer `OPENAI_API_KEY`): +```bash +praisonai --auto "Conte uma piada curta sobre programadores" +``` + +## Solução de Problemas Comuns (Windows) + +* **`pip` ou `python` não é reconhecido como um comando:** + * **Causa:** Python não foi adicionado ao PATH durante a instalação. + * **Solução:** Reinstale o Python marcando "Add Python to PATH" ou adicione manualmente os diretórios `C:\Users\SEU_USUARIO\AppData\Local\Programs\Python\PythonXX` e `C:\Users\SEU_USUARIO\AppData\Local\Programs\Python\PythonXX\Scripts` às Variáveis de Ambiente do sistema. (Substitua `SEU_USUARIO` e `PythonXX` conforme sua instalação). + +* **Erro ao instalar pacotes com `pip` (ex: erros de compilação):** + * **Causa:** Alguns pacotes Python podem ter dependências que requerem ferramentas de compilação C/C++ (Microsoft Visual C++ Build Tools). + * **Solução:** Instale as "Build Tools for Visual Studio" do site da Microsoft. Geralmente, selecionar a carga de trabalho "Desenvolvimento para desktop com C++" é suficiente. + +* **Permissões:** + * **Causa:** Em alguns casos, você pode precisar de permissões de administrador para instalar pacotes globalmente (não recomendado) ou para modificar certas pastas. + * **Solução:** Prefira usar ambientes virtuais. Se realmente precisar, execute o Prompt de Comando ou PowerShell como Administrador. + +* **Conflitos de Pacotes:** + * **Causa:** Versões incompatíveis de pacotes. + * **Solução:** Use ambientes virtuais para isolar as dependências de cada projeto. Comandos como `pip freeze > requirements.txt` e `pip install -r requirements.txt` ajudam a gerenciar dependências. + +Com este guia, você deve ser capaz de instalar o PraisonAI em seu sistema Windows e começar sua jornada no desenvolvimento de agentes de IA! diff --git a/docs/02_conceitos_fundamentais/01_agentes.md b/docs/02_conceitos_fundamentais/01_agentes.md new file mode 100644 index 000000000..bd3db6f94 --- /dev/null +++ b/docs/02_conceitos_fundamentais/01_agentes.md @@ -0,0 +1,104 @@ +# TODO: Translate this file to English + +# Conceito Fundamental: Agentes + +No coração do PraisonAI, e de qualquer sistema de Inteligência Artificial baseado em agentes, está o conceito de **Agente**. Vamos explorar o que isso significa. + +## O que é um Agente de IA? + +De forma geral, um **Agente de Inteligência Artificial (Agente de IA)** é uma entidade autônoma que percebe seu ambiente através de sensores (entradas de dados) e atua sobre esse ambiente através de atuadores (saídas ou ações) para atingir objetivos específicos. + +Pense em um agente como um "trabalhador" inteligente que pode: + +1. **Perceber:** Coletar informações sobre o estado atual de uma situação ou sistema. +2. **Pensar/Raciocinar:** Processar essas informações, aplicar lógica, conhecimento e tomar decisões. +3. **Agir:** Executar ações para alcançar uma meta ou realizar uma tarefa. + +**Características comuns de Agentes de IA:** + +* **Autonomia:** Operam sem intervenção humana direta para cada decisão. +* **Reatividade:** Respondem a mudanças no ambiente. +* **Proatividade:** Tomam iniciativa para atingir seus objetivos. +* **Capacidade de Aprendizagem (opcional):** Alguns agentes podem aprender com a experiência e melhorar seu desempenho. +* **Comunicação (opcional):** Podem interagir com outros agentes ou com humanos. + +## Agentes no PraisonAI + +No PraisonAI, um Agente é a unidade fundamental de execução. Ele é tipicamente definido por: + +1. **Instruções (Instructions) / Prompt:** Uma descrição clara do que o agente deve fazer, qual seu papel, personalidade, e quais são seus objetivos. Este é o "cérebro" do agente, guiando seu comportamento. +2. **Modelo de LLM (Opcional, mas comum):** Geralmente, um agente PraisonAI é potencializado por um Modelo de Linguagem Grande (LLM) subjacente (como GPT, Claude, Llama, Gemini, etc.) que interpreta as instruções e gera as respostas ou ações. O PraisonAI permite configurar qual LLM o agente usará. +3. **Ferramentas (Tools - Opcional):** Um conjunto de capacidades ou funções que o agente pode usar para interagir com o mundo exterior (ex: buscar na internet, executar código, ler arquivos). +4. **Memória (Memory - Opcional):** Capacidade de lembrar informações de interações passadas para manter o contexto. +5. **Backstory / Papel (Role):** Define o contexto e a especialização do agente, ajudando o LLM a gerar respostas mais consistentes e relevantes. +6. **Objetivo (Goal):** Uma declaração clara do que o agente deve alcançar. + +### Como o PraisonAI Implementa Agentes + +O PraisonAI simplifica a criação e o gerenciamento desses agentes. Você pode definir agentes de duas formas principais: + +* **Programaticamente (usando Python com `praisonaiagents`):** + Você instancia classes como `Agent` e configura seus atributos (instruções, ferramentas, etc.) diretamente no código. + + *Exemplo (simplificado de `examples/python/agents/single-agent.py`):* + ```python + from praisonaiagents import Agent + + # Supondo que a variável de ambiente OPENAI_API_KEY está configurada + agente_roteirista = Agent( + role="Roteirista Criativo", + goal="Escrever um roteiro de filme envolvente sobre um tema específico.", + backstory="Você é um roteirista renomado, conhecido por sua habilidade em criar narrativas cativantes e diálogos impactantes.", + instructions="Sua tarefa é desenvolver um roteiro completo para um filme sobre robôs explorando Marte. O roteiro deve incluir descrições de cena, diálogos e desenvolvimento de personagens.", + # llm="gpt-4", # Opcional, pode usar o padrão + allow_delegation=False # Este agente não delega tarefas + ) + + # Para iniciar a tarefa principal do agente (definida implicitamente pelo goal e instructions) + # resultado = agente_roteirista.start("Desenvolva o roteiro sobre robôs em Marte.") + # Ou, se o agente tem tarefas explícitas (veremos em "Tarefas"): + # resultado = agente_roteirista.execute_task("Sua primeira tarefa aqui...") + ``` + > Veja o arquivo completo em: [examples/python/agents/single-agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/agents/single-agent.py) (link para o repositório original) + +* **Declarativamente (usando arquivos YAML com `praisonai` CLI):** + Você define as propriedades dos agentes em um arquivo `.yaml`, que o PraisonAI então interpreta para criar e executar os agentes. + + *Exemplo (simplificado de `agents.yaml` no README principal):* + ```yaml + framework: praisonai # Ou crewai, autogen + topic: Inteligência Artificial # Variável que pode ser usada nas descrições + roles: + roteirista: + backstory: "Habilidoso em criar roteiros com diálogos envolventes sobre {topic}." + goal: Criar roteiros a partir de conceitos. + role: Roteirista + # instructions: (Poderia ser definido aqui também) + tasks: + tarefa_escrita_roteiro: + description: "Desenvolver roteiros com personagens cativantes e diálogos sobre {topic}." + expected_output: "Roteiro completo pronto para produção." + # agent: roteirista # Especifica qual agente executa esta tarefa + ``` + > Veja exemplos mais complexos na pasta `examples/cookbooks/yaml/`. + +### Auto-Reflexão em Agentes PraisonAI + +Um dos recursos destacados do PraisonAI é a capacidade de "auto-reflexão". Isso significa que um agente pode ser configurado para: +1. Executar uma tarefa. +2. Analisar seu próprio resultado com base em critérios ou no objetivo original. +3. Se o resultado não for satisfatório, tentar novamente, possivelmente com uma abordagem diferente, até atingir o objetivo ou um limite de tentativas. + +Essa capacidade torna os agentes mais robustos e capazes de lidar com ambiguidades ou produzir resultados de maior qualidade. + +## Fundamentos por Trás + +A ideia de agentes vem de campos como a Inteligência Artificial Distribuída (DAI) e Sistemas Multi-Agentes (MAS). Os fundamentos teóricos incluem: + +* **Arquiteturas de Agentes:** Como BDI (Belief-Desire-Intention), que modela agentes com base em suas crenças sobre o mundo, seus desejos (objetivos) e suas intenções (planos de ação). +* **Teoria da Decisão:** Como os agentes escolhem a melhor ação entre várias alternativas. +* **Comunicação e Coordenação:** Protocolos e estratégias para que múltiplos agentes interajam e trabalhem juntos. + +O PraisonAI abstrai muitos desses detalhes complexos, mas entender os fundamentos pode ajudar a projetar agentes e sistemas de agentes mais eficazes. + +No próximo tópico, veremos como as **Tarefas (Tasks)** se relacionam com os Agentes. diff --git a/docs/02_conceitos_fundamentais/02_tarefas.md b/docs/02_conceitos_fundamentais/02_tarefas.md new file mode 100644 index 000000000..b16a6e2c2 --- /dev/null +++ b/docs/02_conceitos_fundamentais/02_tarefas.md @@ -0,0 +1,111 @@ +# TODO: Translate this file to English + +# Conceito Fundamental: Tarefas (Tasks) + +Após entendermos o que são [Agentes](./01_agentes.md), o próximo conceito crucial no PraisonAI (e em frameworks similares como CrewAI, do qual o PraisonAI se inspira) é a **Tarefa (Task)**. + +## O que é uma Tarefa? + +Uma Tarefa representa uma unidade de trabalho específica e bem definida que um Agente deve realizar. Se o Agente é o "trabalhador", a Tarefa é a "ordem de serviço" ou a "descrição do trabalho" que ele precisa executar. + +**Características de uma Tarefa:** + +* **Descrição Clara (Description):** Um texto detalhado que explica o que precisa ser feito, quais são os objetivos da tarefa e, possivelmente, o contexto relevante. +* **Resultado Esperado (Expected Output):** Uma descrição do que constitui a conclusão bem-sucedida da tarefa. Isso ajuda o agente (e o sistema) a avaliar se a tarefa foi completada satisfatoriamente. +* **Agente Responsável (Agent):** Especifica qual agente (ou tipo de agente/role) é designado para executar esta tarefa. +* **Contexto/Dependências (Context - Opcional):** Algumas tarefas podem depender dos resultados de tarefas anteriores. O sistema gerencia a passagem desse contexto. +* **Ferramentas (Tools - Opcional):** Pode especificar quais ferramentas o agente deve ou pode usar para realizar a tarefa, ou o agente pode decidir com base em suas ferramentas atribuídas. + +## Tarefas no PraisonAI + +No PraisonAI, as tarefas são o motor que impulsiona os agentes a agir. Elas fornecem o foco e a direção para o trabalho do agente. + +### Como o PraisonAI Implementa Tarefas + +Assim como os Agentes, as Tarefas podem ser definidas: + +* **Programaticamente (usando Python com `praisonaiagents`):** + Você instancia a classe `Task` (ou similar, dependendo da versão e se está usando integrações como CrewAI) e define seus atributos. + + *Exemplo (conceitual, inspirado na estrutura do CrewAI que o PraisonAI integra):* + ```python + from praisonaiagents import Agent # Supondo que Agent e Task venham daqui ou de um módulo integrado + # from crewai import Task # Se estiver usando a sintaxe CrewAI diretamente + + # Definindo um agente (como visto no tópico anterior) + pesquisador = Agent( + role='Pesquisador Sênior', + goal='Descobrir informações de ponta sobre IA e Machine Learning', + backstory='Você é um pesquisador renomado com anos de experiência em vasculhar artigos científicos e notícias de tecnologia.' + ) + + # Definindo uma tarefa para o agente pesquisador + tarefa_pesquisa = { # Em PraisonAI, tarefas podem ser dicionários dentro de uma lista de tarefas do agente ou workflow + 'description': ( + "Pesquise os últimos avanços em modelos de linguagem generativa nos últimos 3 meses. " + "Foque em novas arquiteturas, capacidades emergentes e preocupações éticas." + ), + 'expected_output': ( + "Um relatório resumido de 3-5 parágrafos destacando os principais achados, " + "incluindo links para as fontes primárias (artigos, posts de blog)." + ), + 'agent': pesquisador # Associando a tarefa ao agente + } + + # Em um workflow com múltiplos agentes, você teria uma lista de tarefas + # e o framework orquestraria a execução. + # Exemplo de como um agente poderia executar uma tarefa (pode variar na API exata): + # resultado_tarefa = pesquisador.execute_task(tarefa_pesquisa) + # print(resultado_tarefa) + ``` + > No PraisonAI, a definição de tarefas pode ser mais integrada à configuração do Agente ou do workflow YAML, como veremos abaixo. A API exata para `Task` em Python pode depender se você está usando a camada PraisonAI nativa ou a integração CrewAI/AutoGen. Veja os exemplos em `examples/python/` para a sintaxe precisa. + +* **Declarativamente (usando arquivos YAML com `praisonai` CLI):** + Esta é uma forma muito comum de definir tarefas no PraisonAI, especialmente ao usar múltiplos agentes. + + *Exemplo (do `agents.yaml` no README principal, focado na seção `tasks`):* + ```yaml + framework: praisonai + topic: Inteligência Artificial + roles: + roteirista: # Nome do papel/agente + # ... (backstory, goal, role do agente) ... + tasks: + tarefa_escrita_roteiro: # Nome da tarefa (identificador) + description: "Desenvolver roteiros com personagens cativantes e diálogos sobre {topic}." # O que fazer + expected_output: "Roteiro completo pronto para produção." # O que se espera ao final + # agent: roteirista # Opcional se a tarefa está sob o 'role' que a executa + # Mas útil se um 'manager_agent' distribui tarefas. + # context: # Opcional: especificaria quais tarefas devem ser concluídas antes desta + # - tarefa_ideias_brainstorm + ``` + > No exemplo acima, `tarefa_escrita_roteiro` é uma tarefa atribuída implicitamente ao agente `roteirista`. + > Em cenários mais complexos, você pode ter uma lista global de tarefas e atribuí-las explicitamente aos agentes. + > Consulte os arquivos YAML em `examples/cookbooks/yaml/` para ver diversas formas de estruturar tarefas. Por exemplo, em `examples/cookbooks/yaml/comprehensive_research_report_agents.ipynb` (que usa um YAML), você verá tarefas mais elaboradas. + +### Fluxo de Execução de Tarefas + +1. **Atribuição:** Uma tarefa é atribuída a um agente. +2. **Execução:** O agente usa suas instruções, LLM e ferramentas para trabalhar na tarefa. +3. **Resultado:** O agente produz um resultado. +4. **Avaliação (implícita ou explícita):** O resultado é comparado (pelo agente, por outro agente ou pelo sistema) com o `expected_output`. +5. **Passagem de Contexto:** O resultado da tarefa pode se tornar contexto para tarefas subsequentes. + +### A Importância do "Expected Output" + +O campo `expected_output` é vital. Ele serve como: +* Um guia para o LLM do agente, ajudando-o a entender o formato e o escopo do que precisa ser produzido. +* Um critério para a auto-reflexão do agente ou para agentes avaliadores determinarem se a tarefa foi bem-sucedida. +* Uma forma de garantir que a saída de uma tarefa seja utilizável pela próxima tarefa em um workflow. + +## Fundamentos por Trás + +O conceito de tarefas está ligado a: + +* **Decomposição de Problemas:** Dividir um problema complexo em partes menores e gerenciáveis (as tarefas). +* **Planejamento:** Em sistemas mais avançados, os próprios agentes podem gerar uma sequência de tarefas para atingir um objetivo maior. +* **Gerenciamento de Workflow:** Orquestrar a ordem de execução das tarefas, lidar com dependências e paralelismo. + +Ao definir tarefas claras e com resultados esperados bem descritos, você aumenta significativamente a chance de seus agentes PraisonAI alcançarem os objetivos desejados de forma eficaz. + +A seguir, exploraremos como os **Processos** gerenciam a execução e colaboração entre agentes e suas tarefas. diff --git a/docs/02_conceitos_fundamentais/03_processos.md b/docs/02_conceitos_fundamentais/03_processos.md new file mode 100644 index 000000000..6f0e031cc --- /dev/null +++ b/docs/02_conceitos_fundamentais/03_processos.md @@ -0,0 +1,165 @@ +# TODO: Translate this file to English + +# Conceito Fundamental: Processos (Process) + +Compreendidos os [Agentes](./01_agentes.md) e as [Tarefas](./02_tarefas.md), o próximo elemento essencial na arquitetura do PraisonAI é o **Processo (Process)**. O Processo define como os agentes colaboram e como as tarefas são executadas em um sistema multi-agente. + +## O que é um Processo? + +Em um sistema com múltiplos agentes, o Processo dita a estratégia de coordenação. Ele determina: + +* **A ordem de execução das tarefas:** Se as tarefas são executadas uma após a outra, em paralelo, ou de forma mais complexa. +* **Como os agentes interagem:** Se há um agente gerente, se os agentes passam o trabalho diretamente um para o outro, etc. +* **O fluxo de informação:** Como os resultados de uma tarefa são passados como contexto para a próxima. + +PraisonAI, especialmente através de sua integração com o CrewAI, oferece diferentes tipos de processos para acomodar diversas necessidades de workflows. + +## Tipos de Processos no PraisonAI (e CrewAI) + +O `README.md` principal do PraisonAI já ilustra alguns desses processos. Os mais comuns, inspirados no CrewAI, são: + +1. **Processo Sequencial (Sequential Process):** + * **Descrição:** É a forma mais simples de execução. As tarefas são realizadas uma após a outra, na ordem em que são definidas. O resultado de uma tarefa é automaticamente passado como contexto para a próxima. + * **Ideal para:** Workflows lineares onde cada etapa depende diretamente da anterior. + * **Diagrama:** + ```mermaid + graph LR + Entrada["Entrada"] --> A1 + subgraph Agentes + direction LR + A1["Agente 1 (Tarefa 1)"] --> A2["Agente 2 (Tarefa 2)"] --> A3["Agente 3 (Tarefa 3)"] + end + A3 --> Saida["Saida"] + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Entrada,Saida input + class A1,A2,A3 process + class Agentes transparent + ``` + +2. **Processo Hierárquico (Hierarchical Process):** + * **Descrição:** Utiliza um "agente gerente" (manager agent) para coordenar a execução das tarefas e designar trabalho para "agentes trabalhadores" (worker agents). O gerente recebe o input inicial, decide qual trabalhador (ou sequência de trabalhadores) deve atuar, e pode revisar ou agregar os resultados antes de produzir a saída final. + * **Ideal para:** Tarefas complexas que podem ser decompostas e onde é necessária uma supervisão ou um ponto central de controle e decisão. Permite mais flexibilidade e potencial para otimização. + * **Diagrama:** + ```mermaid + graph TB + Entrada["Entrada"] --> Gerente + subgraph SistemaDeAgentes ["Sistema de Agentes"] + Gerente["Agente Gerente"] + subgraph Trabalhadores ["Agentes Trabalhadores"] + direction LR + T1["Trabalhador 1"] + T2["Trabalhador 2"] + T3["Trabalhador 3"] + end + Gerente --> T1 + Gerente --> T2 + Gerente --> T3 + end + T1 --> Gerente + T2 --> Gerente + T3 --> Gerente + Gerente --> Saida["Saida"] + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Entrada,Saida input + class Gerente,T1,T2,T3 process + class SistemaDeAgentes,Trabalhadores transparent + ``` + * **Observação:** No PraisonAI, o agente gerente pode ter instruções específicas para gerenciar o fluxo, e os trabalhadores são focados em suas tarefas especializadas. O gerente também pode ter a capacidade de solicitar interações humanas (human input) ou aprovações. + +3. **Processo Baseado em Workflow (Workflow Process):** + * **Descrição:** É um tipo de processo mais avançado que suporta relações complexas entre tarefas e execução condicional. Permite construir fluxos de trabalho onde, por exemplo, dependendo do resultado de uma tarefa, diferentes agentes ou sequências de tarefas podem ser ativados. + * **Ideal para:** Lógica de negócios complexa, processos com múltiplos caminhos possíveis, ou quando a automação precisa se adaptar dinamicamente a diferentes cenários. + * **Diagrama (Exemplo com Condição):** + ```mermaid + graph LR + Entrada["Entrada"] --> InicioWorkflow["Inicio do Workflow"] + subgraph Workflow + direction LR + InicioWorkflow --> C1{"Condicao"} + C1 --o|Sim| A1["Agente 1"] + C1 --x|Nao| A2["Agente 2"] + A1 --> Juncao["Juncao"] + A2 --> Juncao + Juncao --> A3["Agente 3"] + end + A3 --> Saida["Saida"] + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef decision fill:#2E8B57,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Entrada,Saida input + class InicioWorkflow,A1,A2,A3,Juncao process + class C1 decision + class Workflow transparent + ``` + * **Observação:** O PraisonAI implementa workflows através de sua configuração YAML (ver `agents-advanced.yaml` ou exemplos em `examples/cookbooks/yaml/`) e programaticamente, permitindo definir a ordem, as dependências e as condições para a execução das tarefas. + +## Como Configurar o Processo no PraisonAI + +A escolha e configuração do processo geralmente ocorrem ao definir um "time" de agentes (Crew) ou um sistema multi-agente. + +* **Programaticamente (Python):** + Ao usar a integração CrewAI dentro do PraisonAI, você pode especificar o tipo de processo ao instanciar a classe `Crew`. + ```python + # Exemplo conceitual com CrewAI + from crewai import Crew, Process + # from praisonaiagents import Agent, Task # Supondo que venham do PraisonAI + + # ... (definição de agentes e tarefas) ... + + # Criando um time (Crew) com um processo específico + meu_time = Crew( + agents=[agente1, agente2], + tasks=[tarefa1, tarefa2], + process=Process.sequential # Ou Process.hierarchical + # verbose=True # Para ver o log de execução + ) + + resultado_final = meu_time.kickoff() + ``` + > Consulte os exemplos em `examples/python/general/` como `workflow_example_basic.py` ou `workflow_example_detailed.py` para ver a sintaxe específica do PraisonAI, que pode ter sua própria maneira de definir workflows. + +* **Declarativamente (YAML):** + Nos arquivos YAML do PraisonAI, a estrutura das `roles` (agentes) e `tasks`, e como elas são aninhadas ou referenciadas, implicitamente ou explicitamente definem o processo. Para processos hierárquicos, você pode definir um `manager_agent`. Para workflows complexos, a ordem e as dependências das tarefas são cruciais. + + *Exemplo de estrutura que sugere um processo (pode variar):* + ```yaml + framework: praisonai # ou crewai + # process: sequential # Pode haver uma chave explícita em algumas versões/configurações + + manager_agent: gestor_de_projetos # Sugere um processo hierárquico + + roles: + gestor_de_projetos: + # ... + pesquisador: + # ... + escritor: + # ... + + tasks: + - name: tarefa_pesquisa + agent: pesquisador + # ... + - name: tarefa_escrita + agent: escritor + context_tasks: [tarefa_pesquisa] # Define dependência, implicando ordem + # ... + ``` + > É importante notar que o `framework: crewai` ou `framework: autogen` no YAML pode influenciar como os processos são interpretados, pois o PraisonAI pode delegar a lógica de processo para esses frameworks. + +## Fundamentos por Trás + +Os diferentes tipos de processos em sistemas multi-agentes se baseiam em conceitos de: + +* **Arquiteturas de Software:** Padrões como pipeline (sequencial) ou blackboard (um espaço compartilhado onde agentes leem e escrevem informações, gerenciado por um controlador). +* **Teoria da Computação Distribuída:** Como coordenar múltiplos executores. +* **Gerenciamento de Projetos e Organização de Equipes:** O processo hierárquico espelha estruturas de gerenciamento onde um líder distribui tarefas e consolida resultados. + +A escolha do processo correto depende da natureza do problema a ser resolvido. Problemas simples e lineares se beneficiam de processos sequenciais, enquanto problemas mais complexos e dinâmicos podem exigir abordagens hierárquicas ou baseadas em workflows. + +O próximo conceito a ser explorado são as **Ferramentas (Tools)**, que dão aos agentes suas capacidades de interagir com o mundo. diff --git a/docs/02_conceitos_fundamentais/04_ferramentas.md b/docs/02_conceitos_fundamentais/04_ferramentas.md new file mode 100644 index 000000000..c2119b0bb --- /dev/null +++ b/docs/02_conceitos_fundamentais/04_ferramentas.md @@ -0,0 +1,116 @@ +# TODO: Translate this file to English + +# Conceito Fundamental: Ferramentas (Tools) + +Os [Agentes](./01_agentes.md) no PraisonAI, para serem verdadeiramente úteis e interagirem com o mundo além de apenas processar texto, precisam de **Ferramentas (Tools)**. As ferramentas expandem as capacidades dos agentes, permitindo-lhes realizar ações, buscar informações externas e interagir com outros sistemas. + +## O que são Ferramentas? + +No contexto de agentes de IA e LLMs, uma Ferramenta é essencialmente uma **função ou capacidade específica que um agente pode invocar para realizar uma tarefa que vai além das capacidades inerentes do modelo de linguagem**. + +Pense nas ferramentas como os "braços e pernas" do agente, ou como aplicativos especializados que ele pode usar: + +* **Exemplos Comuns:** + * **Busca na Web:** Para encontrar informações atualizadas na internet. + * **Execução de Código:** Para realizar cálculos, manipular dados ou interagir com sistemas via scripts. + * **Leitura/Escrita de Arquivos:** Para acessar ou persistir informações no sistema de arquivos. + * **Interação com APIs:** Para se conectar a serviços externos (ex: previsão do tempo, bancos de dados, redes sociais). + * **Cálculo Matemático:** Para resolver problemas matemáticos complexos. + * **Geração de Imagens:** Para criar imagens a partir de descrições textuais. + +O LLM dentro do agente decide *quando* usar uma ferramenta, *qual* ferramenta usar e com *quais parâmetros* chamá-la, com base na tarefa atual e em suas instruções. + +## Ferramentas no PraisonAI + +PraisonAI possui um rico ecossistema de ferramentas, mencionando "100+ Custom Tools" em sua documentação. Ele permite tanto o uso de ferramentas pré-construídas quanto a criação de ferramentas personalizadas. + +### Como o PraisonAI Implementa Ferramentas + +1. **Definição da Ferramenta:** + Uma ferramenta é tipicamente definida como uma função (em Python, por exemplo) que realiza uma ação específica. Crucialmente, a ferramenta deve ter uma **descrição clara** de seu propósito, argumentos e o que ela retorna. Essa descrição é usada pelo LLM para entender como e quando usar a ferramenta. + +2. **Atribuição ao Agente:** + As ferramentas são disponibilizadas para um agente. O agente, ao processar uma tarefa, pode então "decidir" usar uma de suas ferramentas disponíveis se julgar necessário. + +3. **Invocação pelo Agente (LLM):** + Quando o LLM do agente determina que uma ferramenta é necessária, ele geralmente formata uma "chamada de função" (function call) especificando o nome da ferramenta e os argumentos. O framework (PraisonAI) intercepta essa chamada, executa a função da ferramenta correspondente com os argumentos fornecidos, e retorna o resultado da ferramenta para o LLM. O LLM então usa esse resultado para continuar seu processo de pensamento e gerar a resposta final ou a próxima ação. + +### Usando Ferramentas Embutidas + +PraisonAI facilita o uso de muitas ferramentas comuns. A forma exata de habilitá-las pode variar: + +* **Automaticamente Disponíveis:** Algumas ferramentas básicas podem estar disponíveis por padrão para certos tipos de agentes. +* **Especificadas na Configuração YAML:** + ```yaml + # Exemplo conceitual em YAML + roles: + pesquisador_web: + role: Pesquisador Web + goal: Encontrar informações relevantes na internet. + tools: + - 'tavily_search' # Nome de uma ferramenta de busca na web + - 'web_scraper' # Nome de uma ferramenta para extrair conteúdo de páginas + # ... outras configurações do agente ... + ``` +* **Adicionadas Programaticamente (Python):** + ```python + from praisonaiagents import Agent + # Supondo a existência de ferramentas definidas em algum lugar + # from praisonai.tools import minha_ferramenta_busca, minha_ferramenta_calculo + + # Exemplo conceitual + agente_com_ferramentas = Agent( + role="Assistente Versátil", + goal="Resolver problemas usando informações da web e cálculos.", + # A forma de passar ferramentas pode variar; pode ser uma lista de funções, + # instâncias de classes de ferramentas, ou nomes de ferramentas registradas. + tools=[minha_ferramenta_busca, minha_ferramenta_calculo] + ) + ``` + > Consulte os exemplos em `examples/python/tools/` e `examples/python/general/example_custom_tools.py` para a sintaxe correta de como definir e atribuir ferramentas. O PraisonAI também se integra com ferramentas do LangChain, o que expande enormemente as opções. + +### Criando Ferramentas Personalizadas + +Uma das grandes vantagens do PraisonAI é a facilidade de criar suas próprias ferramentas. + +* **Em Python:** + Geralmente, você define uma função Python e a decora com um decorator específico (fornecido pelo PraisonAI ou pela biblioteca de ferramentas que ele usa, como LangChain) para expô-la como uma ferramenta. A descrição da função (docstring) é crucial, pois é o que o LLM usará para entender a ferramenta. + + *Exemplo (inspirado em `examples/python/general/example_custom_tools.py` e LangChain):* + ```python + from langchain_core.tools import tool # Exemplo usando decorator do LangChain + + @tool + def minha_ferramenta_personalizada(texto: str, numero: int) -> str: + """ + Esta ferramenta recebe um texto e um número. + Ela concatena o texto com o número e retorna a string resultante. + Use esta ferramenta quando precisar combinar uma string com um valor numérico. + """ + return f"{texto} - {numero}" + + # Depois, esta 'minha_ferramenta_personalizada' pode ser adicionada à lista de ferramentas de um agente. + # agente = Agent(tools=[minha_ferramenta_personalizada, ...]) + ``` + > A descrição dentro das aspas triplas (docstring) é fundamental! Ela deve explicar claramente o que a ferramenta faz, quais argumentos ela espera e o que ela retorna. O LLM usa essa informação para decidir se e como usar a ferramenta. + +### O Papel do LLM na Utilização de Ferramentas (Function Calling / Tool Using) + +Modelos de LLM modernos (como os da OpenAI, Gemini, etc.) foram treinados com a capacidade de "function calling" ou "tool using". Isso significa que, dada uma lista de ferramentas disponíveis (com suas descrições e esquemas de argumentos), o LLM pode: + +1. Entender a pergunta do usuário ou a tarefa atual. +2. Determinar se alguma das ferramentas disponíveis pode ajudar a responder à pergunta ou realizar a tarefa. +3. Se sim, gerar uma estrutura de dados (geralmente JSON) que especifica qual ferramenta chamar e com quais argumentos. +4. Receber o resultado da execução da ferramenta e usar essa informação para formular a resposta final. + +O PraisonAI gerencia esse fluxo de interação entre o LLM e as ferramentas. + +## Fundamentos por Trás + +* **Planejamento Automatizado:** A capacidade de um agente de decompor um problema e identificar que precisa de uma capacidade externa (ferramenta) para uma sub-etapa. +* **Integração de Sistemas:** Ferramentas são a ponte entre o mundo abstrato do LLM e sistemas ou fontes de dados concretos. +* **Extensibilidade:** Permitem que o comportamento dos agentes seja estendido dinamicamente sem retreinar o LLM. + +Dominar o uso e a criação de ferramentas é essencial para construir agentes PraisonAI verdadeiramente poderosos e capazes de resolver problemas do mundo real. + +Em seguida, veremos como a **Memória** permite que os agentes mantenham o contexto e aprendam com interações passadas. diff --git a/docs/02_conceitos_fundamentais/05_memoria.md b/docs/02_conceitos_fundamentais/05_memoria.md new file mode 100644 index 000000000..a664de2bb --- /dev/null +++ b/docs/02_conceitos_fundamentais/05_memoria.md @@ -0,0 +1,130 @@ +# TODO: Translate this file to English + +# Conceito Fundamental: Memória (Memory) + +Para que os [Agentes](./01_agentes.md) do PraisonAI tenham conversas coerentes, aprendam com interações passadas e mantenham o contexto ao longo de [Tarefas](./02_tarefas.md) complexas, eles precisam de **Memória (Memory)**. A memória é um componente crucial que eleva os agentes de simples processadores de comandos para assistentes mais inteligentes e contextuais. + +## O que é Memória para Agentes de IA? + +No contexto de Agentes de IA e LLMs, Memória refere-se à capacidade do sistema de **armazenar, reter e recuperar informações de interações ou experiências passadas**. Sem memória, cada interação com um agente seria isolada, e o agente não teria conhecimento do que foi dito ou feito anteriormente. + +**Tipos Comuns de Memória em Agentes:** + +1. **Memória de Curto Prazo (Short-Term Memory):** + * **Propósito:** Manter o contexto da conversa ou sessão atual. É como a "memória de trabalho" de um humano. + * **Implementação Comum:** Armazenar um histórico das últimas N interações (perguntas e respostas) e fornecê-lo como parte do prompt para o LLM a cada nova interação. Isso é frequentemente chamado de "janela de contexto deslizante" (sliding context window). + * **Limitações:** O tamanho da janela de contexto dos LLMs é finito. Para conversas muito longas, informações mais antigas podem ser perdidas. + +2. **Memória de Longo Prazo (Long-Term Memory):** + * **Propósito:** Permitir que o agente retenha informações importantes, fatos aprendidos, preferências do usuário ou resumos de conversas passadas por um período indefinido. + * **Implementação Comum:** + * **Bancos de Dados Vetoriais (Vector Databases):** Informações textuais são convertidas em embeddings (vetores numéricos) e armazenadas. Quando necessário, a pergunta atual do usuário ou o contexto da tarefa é usado para buscar semanticamente informações relevantes no banco de dados vetorial. O PraisonAI menciona integração com Mem0, que é um exemplo de memória de longo prazo inteligente. + * **Bancos de Dados Tradicionais (SQL, NoSQL):** Para armazenar dados estruturados ou semi-estruturados sobre o usuário ou o domínio. + * **Resumos de Conversas:** Agentes podem ser programados para resumir conversas periodicamente e armazenar esses resumos na memória de longo prazo. + +## Memória no PraisonAI + +PraisonAI enfatiza a importância da memória para seus agentes, listando "Agentes com Memória de Curto e Longo Prazo" como um recurso chave. + +### Como o PraisonAI Implementa a Memória + +A implementação específica pode variar dependendo da configuração e dos componentes usados, mas geralmente envolve: + +* **Gerenciamento Automático de Histórico (Curto Prazo):** O framework provavelmente lida com o histórico da conversa atual, enviando-o ao LLM conforme necessário, dentro dos limites da janela de contexto do modelo. + +* **Integração com Sistemas de Memória Externa (Longo Prazo):** + * **Bancos de Dados Vetoriais:** Para buscas semânticas e recuperação de informações relevantes de um grande corpus de dados ou de conversas passadas. Exemplos de Vector DBs incluem Pinecone, Weaviate, ChromaDB, FAISS. + * **Mem0:** O PraisonAI menciona especificamente a integração com [Mem0](https://mem0.ai/), uma plataforma de memória inteligente como serviço (MaaS) projetada para LLMs, que visa fornecer memória persistente e contextual de forma eficiente. + * **Outras Soluções:** Pode incluir o uso de bancos de dados relacionais ou NoSQL para armazenar perfis de usuário, preferências ou outros dados estruturados que o agente precise lembrar. + +### Configurando e Usando a Memória + +* **Programaticamente (Python):** + Ao definir um agente ou um "crew" (time de agentes), você pode configurar o tipo de memória a ser usado. + ```python + from praisonaiagents import Agent # ou de onde vier a classe Agent + # from praisonai.memory import AlgumModuloDeMemoria # Exemplo conceitual + + # Exemplo conceitual de como a memória poderia ser atribuída + agente_com_memoria = Agent( + role="Assistente Pessoal", + goal="Lembrar minhas preferências e histórico de pedidos.", + # ... + memory=True, # Habilita a memória padrão (curto prazo) + # long_term_memory_handler=MeuHandlerDeMemoriaMem0(), # Exemplo para longo prazo + # vector_database_config={...} # Outra forma de configurar + ) + + # O agente usaria a memória automaticamente ao processar tarefas + # agente_com_memoria.start("Lembre-se que minha cor favorita é azul.") + # agente_com_memoria.start("Qual é a minha cor favorita?") + ``` + > A sintaxe exata e as opções de configuração da memória podem ser encontradas nos exemplos do PraisonAI, como `examples/python/general/memory_example.py` ou `memory_simple.py`, e na documentação da API. + +* **Declarativamente (YAML):** + Em arquivos YAML, pode haver seções ou propriedades para configurar a memória dos agentes ou do workflow. + ```yaml + # Exemplo conceitual em YAML + roles: + assistente_pessoal: + role: Assistente Pessoal + goal: Lembrar preferências e histórico. + memory: + enabled: true + type: mem0 # ou 'vector_db', 'short_term_default' + # config: # Configurações específicas para o tipo de memória + # api_key: "sua_chave_mem0_aqui" + # user_id: "usuario123" + # ... + ``` + +### O Diagrama "AI Agents with Memory" do README + +O `README.md` principal do PraisonAI inclui um diagrama útil: + +```mermaid +flowchart TB + subgraph Memoria ["Memoria"] + direction TB + MCP["Curto Prazo"] + MLP["Longo Prazo"] + end + subgraph Armazenamento ["Armazenamento"] + direction TB + BD["(Vector DB)"] + end + Entrada["Entrada"] ---> Agentes + subgraph Agentes + direction LR + A1["Agente 1"] + A2["Agente 2"] + A3["Agente 3"] + end + Agentes ---> Saida["Saida"] + Memoria <--> Armazenamento + Armazenamento <--> A1 + Armazenamento <--> A2 + Armazenamento <--> A3 + style Memoria fill:#189AB4,color:#fff + style Armazenamento fill:#2E8B57,color:#fff + style Agentes fill:#8B0000,color:#fff + style Entrada fill:#8B0000,color:#fff + style Saida fill:#8B0000,color:#fff +``` +* **Interpretação:** + * Os **Agentes** recebem uma **Entrada**. + * Eles têm acesso à **Memória**, que é dividida em **Curto Prazo** e **Longo Prazo**. + * A **Memória de Longo Prazo** é frequentemente suportada por um **Armazenamento** externo, como um **Banco de Dados Vetorial (Vector DB)**. + * Há uma interação bidirecional entre a Memória e o Armazenamento (dados são salvos e recuperados). + * Os Agentes também interagem bidirecionalmente com o Armazenamento (ou com a camada de Memória que gerencia o armazenamento). + * Com base na entrada e nas informações recuperadas da memória, os Agentes produzem uma **Saída**. + +## Fundamentos por Trás + +* **Psicologia Cognitiva:** Os conceitos de memória de curto e longo prazo em IA são inspirados em modelos da memória humana. +* **Recuperação de Informação (Information Retrieval):** Técnicas para buscar eficientemente dados relevantes em grandes armazenamentos, especialmente buscas semânticas usando embeddings. +* **Gerenciamento de Contexto:** Estratégias para manter o fluxo da conversa e fornecer ao LLM as informações necessárias para gerar respostas relevantes e coerentes. + +Uma memória eficaz é o que permite aos agentes PraisonAI construir relacionamentos de longo prazo com os usuários, aprender com as interações e realizar tarefas complexas que exigem a lembrança de informações ao longo do tempo. + +O próximo conceito fundamental é **Conhecimento (Knowledge)** e como ele se relaciona com RAG (Retrieval Augmented Generation). diff --git a/docs/02_conceitos_fundamentais/06_conhecimento_rag.md b/docs/02_conceitos_fundamentais/06_conhecimento_rag.md new file mode 100644 index 000000000..052509d1b --- /dev/null +++ b/docs/02_conceitos_fundamentais/06_conhecimento_rag.md @@ -0,0 +1,129 @@ +# TODO: Translate this file to English + +# Conceito Fundamental: Conhecimento (Knowledge) e RAG + +Além da [Memória](./05_memoria.md) para conversas e interações, os [Agentes](./01_agentes.md) do PraisonAI frequentemente precisam acessar e utilizar um corpo de **Conhecimento (Knowledge)** específico para realizar suas [Tarefas](./02_tarefas.md) de forma eficaz. Uma técnica poderosa para isso é a **Retrieval Augmented Generation (RAG)**. + +## O que é Conhecimento no Contexto de Agentes de IA? + +Conhecimento, neste contexto, refere-se a um conjunto de informações, dados ou documentos que um agente pode consultar para: + +* Responder a perguntas factuais. +* Obter contexto específico sobre um domínio. +* Basear suas respostas e ações em informações atualizadas ou proprietárias. + +Os Modelos de Linguagem Grande (LLMs) são pré-treinados em vastas quantidades de texto da internet, mas esse conhecimento: + +1. **Não é atualizado em tempo real:** O conhecimento do LLM "congela" na data em que foi treinado. +2. **Não inclui dados privados ou proprietários:** LLMs públicos não conhecem os documentos internos da sua empresa, por exemplo. +3. **Pode "alucinar":** Às vezes, os LLMs podem gerar informações que parecem plausíveis, mas são factualmente incorretas. + +Fornecer aos agentes acesso a uma base de conhecimento externa ajuda a mitigar esses problemas. + +## RAG (Retrieval Augmented Generation) + +**RAG** é uma arquitetura que combina as capacidades de geração de texto dos LLMs com um sistema de recuperação de informação. Em vez de depender apenas do conhecimento interno do LLM, o processo RAG funciona da seguinte forma: + +1. **Pergunta/Consulta do Usuário:** O usuário faz uma pergunta ou atribui uma tarefa ao agente. +2. **Recuperação (Retrieval):** + * A consulta do usuário é usada para buscar informações relevantes em uma base de conhecimento externa (ex: um conjunto de documentos, uma base de dados, artigos da Wikipedia). + * Essa busca é frequentemente realizada usando **embeddings e bancos de dados vetoriais**. A consulta e os documentos na base de conhecimento são convertidos em vetores, e o sistema busca os documentos cujos vetores são mais "próximos" (semanticamente similares) ao vetor da consulta. +3. **Aumento (Augmentation):** + * Os trechos de informação mais relevantes recuperados da base de conhecimento são combinados com o prompt original do usuário. +4. **Geração (Generation):** + * O prompt aumentado (contendo a pergunta original + os dados recuperados) é então enviado ao LLM. + * O LLM utiliza tanto seu conhecimento interno quanto as informações contextuais fornecidas para gerar uma resposta mais precisa, relevante e baseada nos fatos recuperados. + +**Benefícios do RAG:** + +* **Respostas Mais Precisas e Factuais:** Reduz as alucinações, pois as respostas são ancoradas em dados recuperados. +* **Acesso a Conhecimento Atualizado:** A base de conhecimento pode ser atualizada independentemente do LLM. +* **Uso de Dados Proprietários:** Permite que os agentes utilizem informações específicas de um domínio ou organização. +* **Transparência:** É possível (e muitas vezes implementado) citar as fontes de onde a informação foi recuperada, aumentando a confiança na resposta do agente. + +## Conhecimento e RAG no PraisonAI + +PraisonAI destaca "Adicionar Conhecimento Personalizado" e "RAG Agents" como recursos importantes, indicando suporte robusto para essa arquitetura. + +### Como o PraisonAI Implementa Conhecimento e RAG + +A implementação geralmente envolve: + +1. **Preparação da Base de Conhecimento:** + * **Coleta de Documentos:** Reunir os documentos relevantes (PDFs, TXTs, páginas web, etc.). + * **Chunking (Fragmentação):** Dividir documentos longos em pedaços menores (chunks) para processamento e recuperação mais eficientes. + * **Embedding e Indexação:** Gerar embeddings para cada chunk e armazená-los em um banco de dados vetorial (Vector DB) para busca rápida. PraisonAI pode integrar-se com várias soluções de Vector DB. + +2. **Configuração do Agente RAG:** + * O agente é configurado para usar um processo RAG. Isso significa que, ao receber uma consulta, ele primeiro acionará o mecanismo de recuperação antes de chamar o LLM. + * Pode envolver a especificação do Vector DB a ser usado, como as consultas devem ser transformadas em embeddings, e como os resultados recuperados devem ser formatados no prompt para o LLM. + +### Exemplos e Uso + +* **Programaticamente (Python):** + Você provavelmente configuraria um `Retriever` (componente responsável pela busca no Vector DB) e o associaria a um agente ou a uma cadeia (chain) que implementa o fluxo RAG. + ```python + # Exemplo conceitual usando componentes comuns em RAG + from praisonaiagents import Agent + # from langchain.vectorstores import Chroma # Exemplo de Vector DB + # from langchain.embeddings import OpenAIEmbeddings # Exemplo de modelo de embedding + # from langchain.text_splitter import RecursiveCharacterTextSplitter + # from langchain.chains import RetrievalQA + + # 1. Carregar e preparar documentos (splitting, embedding, storing in Vector DB) + # ... (código para popular seu Vector DB com seus documentos) ... + # vector_store = Chroma(persist_directory="./chroma_db", embedding_function=OpenAIEmbeddings()) + # retriever = vector_store.as_retriever() + + # 2. Criar um agente ou cadeia RAG + # agente_rag = Agent( + # role="Especialista em Documentos", + # goal="Responder perguntas com base nos documentos fornecidos.", + # # ... + # # A forma de integrar o retriever pode variar: + # # Pode ser uma ferramenta, um tipo de memória, ou uma configuração específica do agente. + # tools=[meu_retriever_tool], # Onde meu_retriever_tool usa o 'retriever' + # # ou + # # retrieval_config={'retriever': retriever, 'type': 'rag'}, + # ) + + # Ou usando uma cadeia como RetrievalQA do LangChain, que o PraisonAI pode integrar + # qa_chain = RetrievalQA.from_chain_type(llm=meu_llm, chain_type="stuff", retriever=retriever) + # resultado = qa_chain.run("Qual é o principal tópico do documento X?") + ``` + > Veja exemplos como `examples/python/concepts/rag-agents.py` e `examples/python/concepts/knowledge-agents.py` no repositório PraisonAI para implementações concretas. + +* **Declarativamente (YAML):** + Arquivos YAML podem permitir a especificação de fontes de conhecimento, configurações de Vector DBs ou a ativação de um modo RAG para certos agentes. + ```yaml + # Exemplo conceitual em YAML + roles: + especialista_documentos: + role: Especialista em Documentos + goal: Responder perguntas com base em nossa base de conhecimento interna. + knowledge_base: + type: chroma_db # Ou outro tipo de Vector DB + path: "./minha_base_de_conhecimento_vectorial" + embedding_model: "text-embedding-ada-002" # Modelo para gerar embeddings + # ... + tasks: + responder_pergunta_documento: + description: "Com base no documento 'manual_produto_v2.pdf', qual é o procedimento para resetar o dispositivo?" + expected_output: "Uma explicação clara do procedimento de reset, citando a página se possível." + # O agente usaria sua knowledge_base configurada para responder. + ``` + +### "Chat with PDF Agents" + +Este é um caso de uso específico do RAG. O agente é configurado para usar um ou mais arquivos PDF como sua base de conhecimento. O PraisonAI simplifica a criação desses agentes, provavelmente lidando com o parsing do PDF, chunking, embedding e o fluxo RAG nos bastidores. + +## Fundamentos por Trás + +* **Recuperação de Informação (Information Retrieval):** A ciência de buscar informações em grandes coleções de dados. +* **Processamento de Linguagem Natural (PLN):** Técnicas para processar e entender texto, incluindo a geração de embeddings. +* **Bancos de Dados Vetoriais:** Sistemas otimizados para armazenar e pesquisar vetores de alta dimensionalidade. +* **Arquiteturas de LLM:** Compreender como os LLMs processam prompts e como o contexto adicional (dos documentos recuperados) influencia a geração. + +A capacidade de integrar conhecimento externo através de RAG torna os agentes PraisonAI significativamente mais poderosos, permitindo que eles operem com informações específicas do domínio, atualizadas e verificáveis. + +Isso conclui nossa exploração dos conceitos fundamentais! A seguir, veremos como usar o PraisonAI na prática. diff --git a/docs/03_usando_praisonai/01_usando_com_python.md b/docs/03_usando_praisonai/01_usando_com_python.md new file mode 100644 index 000000000..f201b3958 --- /dev/null +++ b/docs/03_usando_praisonai/01_usando_com_python.md @@ -0,0 +1,152 @@ +# TODO: Translate this file to English + +# Usando o PraisonAI com Python (`praisonaiagents`) + +A biblioteca `praisonaiagents` é o coração do PraisonAI para quem deseja construir e interagir com agentes de IA usando a linguagem Python. Ela oferece uma interface flexível e poderosa para definir agentes, suas tarefas, ferramentas e como eles colaboram. + +## Configuração Inicial + +Antes de começar, certifique-se de que você tem: +1. O pacote `praisonaiagents` instalado (veja o [Guia de Instalação](./../01_instalacao/00_instalacao_windows.md)). +2. Sua chave de API do OpenAI (ou de outro provedor de LLM suportado) configurada como uma variável de ambiente (ex: `OPENAI_API_KEY`). + +## Criando um Agente Simples (Single Agent) + +Um agente simples é um agente individual designado para realizar uma ou mais tarefas sem necessariamente colaborar com outros agentes. + +O `README.md` principal do PraisonAI fornece um exemplo claro: + +```python +from praisonaiagents import Agent + +# Crie uma instância do Agente +# As instruções (instructions) são o prompt principal que define o comportamento do agente. +agente = Agent(instructions="Você é um assistente de IA prestativo.") + +# Inicie o agente com uma tarefa/pergunta específica +# O método start() envia a string como a primeira tarefa/prompt para o agente. +resultado = agente.start("Escreva um roteiro de filme sobre um robô em Marte.") + +print(resultado) +``` + +**Desmembrando o Código:** + +* `from praisonaiagents import Agent`: Importa a classe `Agent` principal. +* `agente = Agent(instructions="...")`: Cria uma instância do agente. O parâmetro `instructions` é crucial, pois define a persona e o comportamento geral do agente. Você pode (e deve) ser muito mais específico em suas instruções para obter melhores resultados. Outros parâmetros importantes ao criar um `Agent` incluem: + * `role` (str): O papel do agente (ex: "Analista de Marketing"). + * `goal` (str): O objetivo principal do agente. + * `backstory` (str): Uma história de fundo para dar mais contexto ao LLM. + * `llm` (any): Permite especificar o modelo de LLM a ser usado (ex: instâncias de modelos da OpenAI, Ollama, etc.). Se não especificado, usará um padrão (geralmente baseado em OpenAI). + * `tools` (list): Uma lista de [ferramentas](./../02_conceitos_fundamentais/04_ferramentas.md) que o agente pode usar. + * `memory` (bool): Se o agente deve usar [memória](./../02_conceitos_fundamentais/05_memoria.md). + * `max_iter` (int): Número máximo de iterações que o agente pode executar (útil para evitar loops infinitos). + * `max_rpm` (int): Número máximo de requisições por minuto (para controle de custos/limites de API). + * `verbose` (bool): Se deve imprimir logs detalhados da execução do agente. + * `allow_delegation` (bool): Se este agente pode delegar tarefas para outros agentes (relevante em sistemas multi-agente). +* `resultado = agente.start("...")`: Este método inicia a execução do agente com a string fornecida como a primeira solicitação ou tarefa. O agente processará essa solicitação com base em suas instruções e LLM configurado. + +**Exemplo Mais Detalhado (`examples/python/agents/single-agent.py`):** + +O repositório PraisonAI contém exemplos mais elaborados. O arquivo `examples/python/agents/single-agent.py` mostra um agente roteirista: + +```python +# (Conteúdo adaptado de examples/python/agents/single-agent.py) +from praisonaiagents import Agent +from praisonaiagents.common.log_adapter import get_logger + +logger = get_logger(__name__) + +# Supondo que OPENAI_API_KEY está configurada +screenwriter_agent = Agent( + role="Roteirista Criativo", + goal="Escrever um roteiro de filme envolvente sobre um tema específico.", + backstory="Você é um roteirista renomado, conhecido por sua habilidade em criar narrativas cativantes e diálogos impactantes.", + instructions="Sua tarefa é desenvolver um roteiro completo para um filme sobre robôs explorando Marte. O roteiro deve incluir descrições de cena, diálogos e desenvolvimento de personagens.", + # llm="gpt-4", # Você pode especificar o modelo + verbose=True, + allow_delegation=False +) + +# Para executar a tarefa principal conforme definido no 'goal' e 'instructions' +# A string passada para start() pode refinar ou iniciar a tarefa. +final_script = screenwriter_agent.start( + "Desenvolva o roteiro sobre robôs em Marte, focando em um robô que desenvolve autoconsciência." +) + +logger.info(f"Roteiro Final Gerado:\n{final_script}") +``` +> **Para Rodar:** Navegue até a pasta `examples/python/agents/` no seu terminal (após clonar o repositório PraisonAI) e execute `python single-agent.py`. Certifique-se de ter suas credenciais de LLM configuradas. + +## Criando Múltiplos Agentes (Multi Agents) + +A verdadeira força do PraisonAI reside na capacidade de orquestrar múltiplos agentes que colaboram para resolver problemas complexos. + +O `README.md` principal também ilustra isso: + +```python +from praisonaiagents import Agent, PraisonAIAgents # PraisonAIAgents é o orquestrador + +# Agente 1: Pesquisador +agente_pesquisador = Agent( + instructions="Pesquise sobre os últimos avanços em Inteligência Artificial generativa.", + role="Pesquisador de IA", + goal="Coletar informações e artigos recentes sobre IA generativa." + # Você pode adicionar ferramentas de busca web aqui +) + +# Agente 2: Sumarizador +agente_sumarizador = Agent( + instructions="Sumarize as descobertas do agente pesquisador de forma concisa.", + role="Escritor Técnico", + goal="Produzir um resumo claro e informativo baseado na pesquisa fornecida." +) + +# Crie uma instância do orquestrador PraisonAIAgents +# A ordem na lista pode influenciar a execução em processos sequenciais. +sistema_multi_agente = PraisonAIAgents( + agents=[agente_pesquisador, agente_sumarizador] + # Você pode definir 'tasks' aqui também, ou elas podem ser inferidas + # e passadas entre os agentes dependendo do processo. +) + +# Inicie o sistema multi-agente +# O método start() do PraisonAIAgents gerenciará o fluxo entre os agentes. +# Em um processo sequencial padrão, o resultado do agente_pesquisador +# seria passado como entrada para o agente_sumarizador. +resultado_final_colaborativo = sistema_multi_agente.start() + +print(resultado_final_colaborativo) +``` + +**Desmembrando o Código Multi-Agente:** + +* `from praisonaiagents import PraisonAIAgents`: Importa a classe que gerencia um grupo de agentes. +* `agente_pesquisador = Agent(...)`, `agente_sumarizador = Agent(...)`: Define cada agente individualmente, com seus próprios papéis, objetivos e instruções. +* `sistema_multi_agente = PraisonAIAgents(agents=[...])`: Cria o "time" ou sistema de agentes. + * O construtor de `PraisonAIAgents` pode aceitar outros parâmetros importantes, como: + * `tasks` (list): Uma lista de [tarefas](./../02_conceitos_fundamentais/02_tarefas.md) a serem executadas pela equipe. Se não fornecido explicitamente, o sistema pode tentar inferir ou executar um fluxo mais simples. + * `process` (str ou Enum): Define o [processo](./../02_conceitos_fundamentais/03_processos.md) de colaboração (ex: 'sequential', 'hierarchical'). O padrão é geralmente sequencial. + * `manager_llm` (any): Se estiver usando um processo hierárquico, este LLM pode ser usado pelo agente gerente. + * `verbose` (bool): Log detalhado. +* `resultado_final_colaborativo = sistema_multi_agente.start()`: Inicia a colaboração. O `PraisonAIAgents` orquestra a passagem de informação (contexto) entre os agentes conforme o processo definido. + +### Explorando Mais Exemplos Python + +O diretório `examples/python/` no repositório PraisonAI é rico em exemplos que demonstram diversas funcionalidades: + +* **`examples/python/general/`**: Contém exemplos de conceitos como: + * `async_example*.py`: Execução assíncrona de agentes/tarefas. + * `auto_agents_example.py`: Demonstração de "Auto Agents". + * `example_custom_tools.py`: Como definir e usar ferramentas personalizadas. + * `memory_example.py` e `memory_simple.py`: Uso de memória. + * `workflow_example_basic.py` e `workflow_example_detailed.py`: Definição de workflows de agentes. +* **`examples/python/agents/`**: Diferentes tipos de agentes especializados. Consulte [Modelos de Agentes](05_modelos_de_agentes.md) para um resumo de cada um. +* **`examples/python/concepts/`**: Implementações de RAG, processamento de CSV, etc. +* **`examples/python/usecases/`**: Soluções para casos de uso específicos como análise de sentimentos, revisão de código, etc. + +**Recomendação:** +Clone o repositório PraisonAI (`git clone https://github.com/MervinPraison/PraisonAI.git`) e explore esses exemplos. Modifique-os, execute-os e veja como diferentes configurações afetam o comportamento dos agentes. Esta é uma das melhores maneiras de aprofundar seu entendimento prático. +Se surgirem problemas durante os testes, consulte a seção [Dúvidas Frequentes](../09_duvidas_frequentes.md) para possíveis soluções. + +No próximo tópico, veremos como usar o PraisonAI de forma "No-Code" ou "Low-Code" através de arquivos de configuração YAML. Para um resumo rápido dos campos disponíveis, consulte [Configurações com YAML](./06_configuracoes_yaml.md). diff --git a/docs/03_usando_praisonai/02_usando_com_yaml.md b/docs/03_usando_praisonai/02_usando_com_yaml.md new file mode 100644 index 000000000..f157209a0 --- /dev/null +++ b/docs/03_usando_praisonai/02_usando_com_yaml.md @@ -0,0 +1,162 @@ +# TODO: Translate this file to English + +# Usando o PraisonAI com YAML (No-Code / Low-Code) + +Uma das grandes vantagens do PraisonAI é sua capacidade de definir e orquestrar agentes de IA usando arquivos de configuração YAML. Essa abordagem "No-Code" ou "Low-Code" permite que usuários, mesmo sem profundo conhecimento de programação, construam sistemas de agentes complexos de forma declarativa. + +## A Interface de Linha de Comando (CLI) `praisonai` + +Para trabalhar com arquivos YAML, você usará principalmente a interface de linha de comando `praisonai`. Certifique-se de tê-la instalada (geralmente via `pip install praisonai` - veja o [Guia de Instalação](./../01_instalacao/00_instalacao_windows.md)). + +**Comandos Principais:** + +* `praisonai `: Executa a configuração de agentes definida no ``. +* `praisonai --auto "sua tarefa aqui"`: Modo de geração automática onde o PraisonAI tenta criar e executar agentes para a tarefa descrita. +* `praisonai --init "descrição da tarefa"`: Ajuda a inicializar um arquivo `agents.yaml` básico com base na descrição fornecida. +* `praisonai --version`: Mostra a versão instalada. +* `praisonai --help`: Exibe informações de ajuda e outras opções da CLI. + +## Estrutura Básica de um Arquivo YAML (`agents.yaml`) + +Um arquivo YAML para PraisonAI (comumente chamado `agents.yaml`, mas pode ter qualquer nome) define os componentes do seu sistema de agentes. Vamos analisar a estrutura com base nos exemplos do PraisonAI. + +**Exemplo Simples (adaptado do `README.md` principal):** + +```yaml +# framework: Define qual framework de agentes o PraisonAI deve utilizar por baixo dos panos. +# Pode ser 'praisonai' (nativo), 'crewai', ou 'autogen'. +framework: praisonai + +# topic: Uma variável global que pode ser usada dentro de outras strings no YAML +# usando a sintaxe {topic}. Útil para parametrizar seus agentes. +topic: "Inteligência Artificial e o Futuro do Trabalho" + +# roles: Define os diferentes agentes (ou papéis) no seu sistema. +roles: + # 'pesquisador' é um nome/identificador para este agente/papel. + pesquisador: + role: "Pesquisador Especialista em IA" # O nome formal do papel. + goal: "Conduzir pesquisas aprofundadas sobre o impacto da {topic}." + backstory: "Você é um analista de tendências tecnológicas com um olhar crítico e habilidade para encontrar informações relevantes e dados prospectivos sobre {topic}." + # instructions: (Opcional aqui, pode ser mais geral ou focado em tarefas específicas) + # llm: (Opcional) Especifica o modelo LLM para este agente. + # model: "gpt-3.5-turbo" + # temperature: 0.7 + # tools: (Opcional) Lista de ferramentas que este agente pode usar. + # - 'tavily_search' # Exemplo de ferramenta de busca + # memory: (Opcional) Configurações de memória para o agente. + # enabled: true + tasks: + # 'tarefa_coleta_dados' é um nome/identificador para esta tarefa. + tarefa_coleta_dados: + description: "Coletar artigos, estudos e opiniões de especialistas publicados nos últimos 6 meses sobre o impacto da {topic}. Identificar os principais argumentos, previsões e preocupações." + expected_output: "Um relatório compilado contendo um resumo dos principais achados, lista de fontes e trechos relevantes. O relatório deve ter no máximo 1000 palavras." + # agent: pesquisador # Opcional se a tarefa está aninhada sob o 'role' que a executa. + # async_execution: false # Se a tarefa pode ser executada de forma assíncrona. + + # Você pode definir múltiplos 'roles' (agentes) + escritor: + role: "Escritor de Conteúdo Estratégico" + goal: "Produzir um artigo de blog envolvente e informativo baseado na pesquisa sobre {topic}." + backstory: "Você é um escritor talentoso, capaz de traduzir informações complexas em conteúdo acessível e cativante para um público geral interessado em tecnologia." + tasks: + tarefa_redacao_artigo: + description: "Com base no relatório de pesquisa fornecido sobre {topic}, escrever um artigo de blog de aproximadamente 800 palavras. O artigo deve ser bem estruturado, com introdução, desenvolvimento dos pontos principais e conclusão. Usar uma linguagem clara e exemplos práticos." + expected_output: "O texto final do artigo de blog, pronto para publicação, incluindo um título chamativo e sugestões de subtítulos." + context_tasks: # Define que esta tarefa depende do resultado de outra(s). + - tarefa_coleta_dados # O resultado da 'tarefa_coleta_dados' do 'pesquisador' será passado como contexto. + +# tasks: (Opcional) Você também pode definir uma lista global de tarefas +# e atribuí-las aos agentes, especialmente útil para workflows mais complexos +# ou quando um agente gerente distribui tarefas. +# tasks: +# - name: tarefa_global_de_revisao +# agent: revisor # Supondo um agente 'revisor' definido em 'roles' +# description: "Revisar o artigo de blog final quanto à clareza, gramática e precisão." +# expected_output: "Artigo revisado com sugestões de melhoria." +# context_tasks: +# - tarefa_redacao_artigo + +# process: (Opcional) Define o tipo de processo de colaboração. +# Ex: sequential, hierarchical. Se não especificado, um padrão é usado (geralmente sequencial). +# process: sequential + +# manager_agent: (Opcional) Se estiver usando um processo hierárquico, +# especifica qual 'role' atua como o gerente. +# manager_agent: pesquisador # Exemplo +``` + +**Principais Seções do YAML:** + +* `framework` (Obrigatório): Especifica qual backend de agentes usar (`praisonai`, `crewai`, `autogen`). Isso influencia como o YAML é interpretado e quais funcionalidades estão disponíveis. +* `topic` (Opcional): Uma variável global para reutilizar texto. +* `roles` (Obrigatório): Define cada agente. + * `role` (str): O nome do papel do agente. + * `goal` (str): O objetivo principal do agente. + * `backstory` (str): Contexto para o LLM. + * `instructions` (str, Opcional): Instruções gerais para o agente. + * `llm` (dict, Opcional): Configurações do LLM (modelo, temperatura, etc.). + * `tools` (list, Opcional): Ferramentas que o agente pode usar. + * `memory` (dict, Opcional): Configurações de memória. + * `tasks` (dict, Opcional, aninhado sob um `role`): Tarefas específicas para este agente. + * `description` (str): O que a tarefa envolve. + * `expected_output` (str): O resultado esperado. + * `agent` (str, Opcional): Qual agente executa (útil se as tarefas são listadas globalmente). + * `context_tasks` (list, Opcional): Lista de nomes de tarefas das quais esta tarefa depende. O resultado dessas tarefas será passado como contexto. + * `async_execution` (bool, Opcional): Se a tarefa pode ser executada de forma assíncrona. +* `tasks` (list, Opcional, nível raiz): Uma lista global de tarefas. Útil para workflows onde um agente gerente distribui trabalho ou para definir uma sequência explícita. Cada item da lista é um dicionário com as mesmas chaves de uma tarefa aninhada (`name`, `description`, `expected_output`, `agent`, `context_tasks`, etc.). +* `process` (str, Opcional): Tipo de processo de colaboração (ex: `sequential`, `hierarchical`). +* `manager_agent` (str, Opcional): Nome do `role` que atua como gerente em processos hierárquicos. + +## Executando o Arquivo YAML + +1. Salve sua configuração em um arquivo (ex: `meus_agentes.yaml`). +2. Abra seu terminal. +3. Execute: + ```bash + praisonai meus_agentes.yaml + ``` +4. O PraisonAI irá: + * Ler e validar o arquivo YAML. + * Instanciar os agentes e tarefas definidos. + * Orquestrar a execução das tarefas pelos agentes, conforme o processo e as dependências especificadas. + * Imprimir os resultados e logs no console (o nível de detalhe pode depender de configurações `verbose` ou globais). + +## Modo Automático (`--auto`) + +Para tarefas mais simples ou para obter um ponto de partida rápido, você pode usar o modo `--auto`: + +```bash +praisonai --auto "Crie um resumo do livro 'O Pequeno Príncipe' em 3 parágrafos." +``` +O PraisonAI tentará interpretar a solicitação, possivelmente criar agentes e tarefas internamente, e executar o processo para gerar o resultado. + +## Inicializando um YAML (`--init`) + +Se você não tem certeza de como começar seu arquivo YAML, o PraisonAI pode ajudar: + +```bash +praisonai --init "Planejar uma campanha de marketing para um novo aplicativo de fitness" +``` +Isso geralmente cria um arquivo `agents.yaml` básico com uma estrutura inicial baseada na sua descrição, que você pode então refinar. + +## Vantagens da Abordagem YAML + +* **Acessibilidade:** Permite que não-programadores ou programadores com menos experiência em Python construam sistemas de IA. +* **Clareza e Legibilidade:** A estrutura declarativa do YAML pode tornar a configuração do sistema de agentes fácil de entender. +* **Configuração Rápida:** Ideal para prototipagem rápida e experimentação. +* **Reutilização:** Arquivos YAML podem servir como templates para diferentes projetos. + +## Explorando Exemplos YAML + +A pasta `examples/cookbooks/yaml/` no repositório PraisonAI é o melhor lugar para encontrar exemplos práticos e avançados de configurações YAML. Lá você encontrará diversos arquivos `.ipynb` (Jupyter Notebooks) que carregam e executam arquivos YAML para casos de uso como: + +* Geração de artigos +* Resposta automática de e-mails +* Escrita de livros +* Lançamento de produtos +* E muito mais! + +Analise esses exemplos para entender como estruturar seus próprios arquivos YAML para diferentes tipos de problemas e workflows. + +A seguir, veremos como interagir com o PraisonAI usando JavaScript e TypeScript. diff --git a/docs/03_usando_praisonai/03_usando_com_js_ts.md b/docs/03_usando_praisonai/03_usando_com_js_ts.md new file mode 100644 index 000000000..37caac7af --- /dev/null +++ b/docs/03_usando_praisonai/03_usando_com_js_ts.md @@ -0,0 +1,188 @@ +# TODO: Translate this file to English + +# Usando o PraisonAI com JavaScript e TypeScript + +PraisonAI também oferece suporte para desenvolvimento de agentes de IA usando JavaScript e TypeScript através do pacote `praisonai` no npm. Isso permite que desenvolvedores front-end e back-end que trabalham com o ecossistema Node.js integrem o poder do PraisonAI em suas aplicações. + +## Configuração Inicial + +1. **Node.js e npm/yarn:** Certifique-se de ter o Node.js instalado. O npm (Node Package Manager) vem com o Node.js. Se preferir, você pode usar o yarn. + * Para verificar: + ```bash + node -v + npm -v + ``` + * Download Node.js: [nodejs.org](https://nodejs.org/) + +2. **Instale o pacote `praisonai`:** + * Com npm: + ```bash + npm install praisonai + ``` + * Com yarn: + ```bash + yarn add praisonai + ``` + +3. **Configure sua Chave de API:** + Assim como na versão Python, você precisará de uma chave de API para o provedor de LLM que pretende usar (ex: OpenAI). Configure-a como uma variável de ambiente: + ```bash + export OPENAI_API_KEY=sua_chave_api_aqui + ``` + Em ambientes de produção Node.js, você pode usar pacotes como `dotenv` para gerenciar variáveis de ambiente a partir de um arquivo `.env`. + +## Usando com JavaScript (CommonJS ou ES Modules) + +O `README.md` principal do PraisonAI mostra um exemplo simples em JavaScript (CommonJS): + +**Exemplo JavaScript (CommonJS - `app.js`):** +```javascript +const { Agent } = require('praisonai'); // Importa a classe Agent + +// Cria uma instância do Agente +const agent = new Agent({ + instructions: 'Você é um assistente de IA prestativo.' + // Você pode adicionar outras configurações aqui, como: + // role: "Escritor Criativo", + // goal: "Escrever uma história curta", + // llm: { provider: "openai", model: "gpt-3.5-turbo" } // Exemplo de configuração de LLM +}); + +// Define a tarefa/prompt e inicia o agente +async function runAgent() { + try { + const result = await agent.start('Escreva um roteiro de filme sobre um robô em Marte.'); + console.log(result); + } catch (error) { + console.error("Erro ao executar o agente:", error); + } +} + +runAgent(); +``` + +**Para executar (CommonJS):** +```bash +node app.js +``` + +Se estiver usando ES Modules em seu projeto Node.js (com `"type": "module"` no seu `package.json` ou usando a extensão `.mjs`): + +**Exemplo JavaScript (ES Modules - `app.mjs`):** +```javascript +import { Agent } from 'praisonai'; // Importa a classe Agent + +const agent = new Agent({ + instructions: 'Você é um assistente de IA prestativo.' +}); + +async function runAgent() { + try { + const result = await agent.start('Escreva um roteiro de filme sobre um robô em Marte.'); + console.log(result); + } catch (error) + console.error("Erro ao executar o agente:", error); + } +} + +runAgent(); +``` + +**Para executar (ES Modules):** +```bash +node app.mjs +``` + +## Usando com TypeScript + +TypeScript adiciona tipagem estática ao JavaScript, o que pode ajudar a pegar erros mais cedo e melhorar a manutenibilidade do código. O PraisonAI também suporta TypeScript. + +1. **Instale o TypeScript e tipos (se necessário):** + ```bash + npm install -D typescript @types/node + # ou + yarn add -D typescript @types/node + ``` + +2. **Crie um arquivo `tsconfig.json` (se não tiver):** + ```bash + npx tsc --init + ``` + Ajuste as configurações no `tsconfig.json` conforme necessário (ex: `target`, `module`, `outDir`). + +**Exemplo TypeScript (`app.ts`):** +```typescript +import { Agent, AgentConfig } from 'praisonai'; // Importa Agent e o tipo de configuração + +const agentConfig: AgentConfig = { + instructions: 'Você é um escritor criativo que escreve contos com emojis.', + role: "Contador de Histórias com Emojis", + goal: "Escrever uma história curta e divertida sobre um tema dado, usando emojis apropriados.", + // llm: { provider: "openai", model: "gpt-4" } // Exemplo +}; + +const agent = new Agent(agentConfig); + +async function runAgent(): Promise { + try { + const storyPrompt: string = "Escreva uma história sobre um viajante do tempo que visita dinossauros."; + const result: string | undefined = await agent.start(storyPrompt); // O resultado pode ser string ou undefined + if (result) { + console.log("História Gerada:"); + console.log(result); + } else { + console.log("O agente não retornou um resultado."); + } + } catch (error) { + console.error("Erro ao executar o agente:", error); + } +} + +runAgent(); +``` + +**Para compilar e executar (TypeScript):** + +1. Compile o código TypeScript para JavaScript: + ```bash + npx tsc + ``` + Isso criará um arquivo `app.js` no seu diretório de saída (ex: `dist/app.js`). + +2. Execute o arquivo JavaScript compilado: + ```bash + node dist/app.js + ``` + + Alternativamente, você pode usar `ts-node` para executar diretamente arquivos TypeScript (ótimo para desenvolvimento): + ```bash + npm install -D ts-node + # ou + yarn add -D ts-node + + npx ts-node app.ts + ``` + +## Funcionalidades e Limitações + +A versão JavaScript/TypeScript do PraisonAI visa espelhar a funcionalidade da versão Python, permitindo: + +* Criação de agentes com instruções, papéis, objetivos. +* Configuração de LLMs. +* Execução de tarefas. +* Potencialmente, uso de ferramentas e memória (verifique a documentação da API JS para detalhes sobre a paridade de recursos com a versão Python). + +**Onde encontrar mais detalhes:** + +* **Repositório PraisonAI (`src/praisonai-ts/`):** A pasta `src/praisonai-ts/` no repositório principal do PraisonAI contém o código-fonte da biblioteca TypeScript. Dentro dela, a subpasta `examples/` é particularmente útil: + * `src/praisonai-ts/examples/simple/`: Contém exemplos básicos. + * `src/praisonai-ts/examples/tools/`: Pode conter exemplos de como usar ferramentas. + * `src/praisonai-ts/examples/concepts/`: Pode ilustrar conceitos como memória ou workflows. +* **Documentação Oficial (`docs.praison.ai`):** Embora a documentação possa focar mais na versão Python e YAML, procure por seções específicas sobre JavaScript/TypeScript ou referências à API JS. + +**Considerações:** + +* **Paridade de Recursos:** É comum que bibliotecas com versões em múltiplas linguagens tenham uma pequena defasagem de recursos entre elas, com a versão principal (neste caso, Python) geralmente sendo a mais completa inicialmente. Sempre verifique a documentação específica da API JavaScript/TypeScript do PraisonAI para confirmar as funcionalidades disponíveis. +* **Ecossistema Node.js:** Ao usar PraisonAI com JavaScript/TypeScript, você pode aproveitar todo o ecossistema Node.js, incluindo seus frameworks web (Express, NestJS), bibliotecas e ferramentas de desenvolvimento. + +Esta introdução deve ajudá-lo a começar a usar o PraisonAI em seus projetos JavaScript e TypeScript. A exploração dos exemplos no repositório é altamente recomendada para entender melhor as capacidades e a API da versão JS/TS. diff --git a/docs/03_usando_praisonai/04_criando_seu_primeiro_agente.md b/docs/03_usando_praisonai/04_criando_seu_primeiro_agente.md new file mode 100644 index 000000000..e90099d3c --- /dev/null +++ b/docs/03_usando_praisonai/04_criando_seu_primeiro_agente.md @@ -0,0 +1,60 @@ +# TODO: Translate this file to English + +# Criando Seu Primeiro Agente + +Este guia prático mostra passo a passo como colocar um agente PraisonAI em funcionamento usando Python. Se você já instalou o pacote `praisonaiagents`, siga em frente. + +## 1. Configure o Ambiente + +1. Abra um terminal e crie uma pasta para seus testes: + ```bash + mkdir meu_primeiro_agente + cd meu_primeiro_agente + ``` +2. (Opcional) Crie e ative um ambiente virtual: + ```bash + python -m venv .venv + source .venv/bin/activate # No Windows use `.venv\Scripts\activate` + ``` +3. Instale o pacote se ainda não o fez: + ```bash + pip install praisonaiagents + ``` + +## 2. Escreva o Código do Agente + +Crie um arquivo `roteirista.py` com o seguinte conteúdo: + +```python +from praisonaiagents import Agent + +agente = Agent( + instructions="Você é um roteirista de cinema muito criativo.", + role="Roteirista", + goal="Escrever um pequeno roteiro sobre robôs em Marte." +) + +resultado = agente.start("Crie o roteiro com três cenas principais.") +print(resultado) +``` + +## 3. Execute e Analise + +No terminal, rode: +```bash +python roteirista.py +``` + +O PraisonAI conectará ao modelo LLM configurado (por padrão OpenAI) e exibirá o roteiro gerado. + +- Se estiver tudo certo, experimente alterar as instruções, o papel ou o objetivo e observe como o resultado muda. +- Consulte [Usando o PraisonAI com Python](01_usando_com_python.md) para entender todos os parâmetros disponíveis. + +## 4. Próximos Passos + +Depois de dominar este exemplo simples, explore: +- [Criando múltiplos agentes](01_usando_com_python.md#criando-múltiplos-agentes-multi-agents) +- [Definindo agentes via YAML](02_usando_com_yaml.md) +- Os notebooks em `examples/python/` para casos de uso completos. + +Bom aprendizado! diff --git a/docs/03_usando_praisonai/05_modelos_de_agentes.md b/docs/03_usando_praisonai/05_modelos_de_agentes.md new file mode 100644 index 000000000..639de85d4 --- /dev/null +++ b/docs/03_usando_praisonai/05_modelos_de_agentes.md @@ -0,0 +1,139 @@ +# TODO: Translate this file to English + +# Modelos de Agentes Disponíveis + +Esta seção apresenta um resumo dos modelos de agentes fornecidos como exemplos no PraisonAI. Eles servem como ponto de partida para criar soluções adaptadas às suas necessidades. + +Cada agente abaixo possui um script dedicado em `examples/python/agents/`. A execução parte do mesmo princípio: instale o pacote `praisonaiagents`, configure sua chave de API do modelo de linguagem e rode o arquivo Python correspondente. + +## Agentes Especializados + +### 1. Agente Analista de Dados +Arquivo: `data-analyst-agent.py` + +Utiliza ferramentas de manipulação de CSV/Excel para ler, filtrar, agrupar e gerar insights de dados. +Execute: +```bash +python data-analyst-agent.py +``` + +### 2. Agente Financeiro +Arquivo: `finance-agent.py` + +Consulta preços, informações e histórico de ações. Útil para análises de mercado básicas. +```bash +python finance-agent.py +``` + +### 3. Agente de Pesquisa +Arquivo: `research-agent.py` + +Realiza buscas na web com `duckduckgo` e retorna resultados resumidos. +```bash +python research-agent.py +``` + +### 4. Agente de Planejamento +Arquivo: `planning-agent.py` + +Ajuda a planejar viagens ou atividades pesquisando informações relevantes on-line. +```bash +python planning-agent.py +``` + +### 5. Agente de Recomendação +Arquivo: `recommendation-agent.py` + +Gera recomendações (como filmes) a partir de buscas na web e de conhecimento prévio do LLM. +```bash +python recommendation-agent.py +``` + +### 6. Agente de Compras +Arquivo: `shopping-agent.py` + +Pesquisa produtos em diferentes sites e organiza os preços em formato de tabela. +```bash +python shopping-agent.py +``` + +### 7. Agente de Programação +Arquivo: `programming-agent.py` + +Contém ferramentas para execução de código, análise, formatação e acesso ao shell. Permite iterar no desenvolvimento de scripts. +```bash +python programming-agent.py +``` + +### 8. Agente de Markdown +Arquivo: `markdown-agent.py` + +Gera ou transforma textos em Markdown. +```bash +python markdown-agent.py +``` + +### 9. Agente de Busca na Web +Arquivo: `websearch-agent.py` + +Focado em pesquisas rápidas na internet. +```bash +python websearch-agent.py +``` + +### 10. Agente Wikipedia +Arquivo: `wikipedia-agent.py` + +Consulta a Wikipedia para reunir informações detalhadas sobre um tópico. +```bash +python wikipedia-agent.py +``` + +### 11. Agente SearxNG +Arquivo: `searxng-agent.py` + +Realiza buscas através de uma instância SearxNG (pode ser container Docker). Necessita do serviço rodando localmente. +```bash +python searxng-agent.py +``` + +### 12. Agente de Imagens +Arquivo: `image-agent.py` + +Aplica análise de imagens, podendo lidar tanto com URLs quanto com arquivos locais. +```bash +python image-agent.py +``` + +### 13. Agente de Imagem para Texto +Arquivo: `image-to-text-agent.py` + +Semelhante ao agente de imagens, mas com foco em descrever conteúdo visual (OCR/descrição). Execute: +```bash +python image-to-text-agent.py +``` + +### 14. Agente de Vídeo +Arquivo: `video-agent.py` + +Permite fornecer arquivos de vídeo para extração de informações e resumo de eventos. +```bash +python video-agent.py +``` + +### 15. Agente "Single" +Arquivo: `single-agent.py` + +Exemplo básico de um agente único com prompt simples. Ótimo ponto de partida. +```bash +python single-agent.py +``` + +## Dicas Gerais + +1. Abra um terminal na pasta `examples/python/agents`. +2. Ative seu ambiente virtual (se usar). +3. Execute o arquivo desejado conforme mostrado acima. +4. Explore e modifique os scripts para entender como cada agente opera. + +Com essas bases, você pode combinar os agentes ou adaptá-los para criar soluções personalizadas no PraisonAI. diff --git a/docs/03_usando_praisonai/06_configuracoes_yaml.md b/docs/03_usando_praisonai/06_configuracoes_yaml.md new file mode 100644 index 000000000..d39c41220 --- /dev/null +++ b/docs/03_usando_praisonai/06_configuracoes_yaml.md @@ -0,0 +1,48 @@ +# TODO: Translate this file to English + +# Configurações com YAML + +Os arquivos YAML permitem definir agentes, tarefas e parâmetros do PraisonAI de forma declarativa. Eles são utilizados principalmente pela CLI `praisonai` para iniciar fluxos complexos sem escrever código Python. + +## Estrutura Básica + +Um YAML comum segue o formato visto em `src/praisonai/agents.yaml`: + +```yaml +framework: praisonai +process: sequential +topic: exemplo de topico +memory: false +roles: + pesquisador: + role: Researcher + goal: Obter informações sobre o tema + tasks: + pesquisa: + description: Realizar buscas e resumir resultados + expected_output: Relatório da pesquisa + tools: + - search_tool +dependencies: [] +``` + +### Principais Campos + +- **framework**: define qual biblioteca será usada (“praisonai”, “crewai” ou “autogen”). +- **process**: forma de execução (sequencial, paralelo etc.). +- **topic**: assunto ou objetivo geral dos agentes. +- **memory**: habilita ou não memória. +- **roles**: cada agente é descrito aqui com suas tarefas e ferramentas. +- **dependencies**: lista de tarefas que dependem de outras. + +## Arquivos Avançados + +O `agents-advanced.yaml` demonstra configurações mais complexas, como uso de modelos diferentes para cada agente e escrita de saída em arquivos. + +Explore esses arquivos na pasta `src/praisonai` para entender como adaptar às suas necessidades. Após ajustar o YAML, execute: + +```bash +praisonai caminho/do/arquivo.yaml +``` + +Isso carregará as configurações e iniciará o fluxo definido. diff --git a/docs/03_usando_praisonai/07_importes_e_funcoes_essenciais.md b/docs/03_usando_praisonai/07_importes_e_funcoes_essenciais.md new file mode 100644 index 000000000..ec5f15daf --- /dev/null +++ b/docs/03_usando_praisonai/07_importes_e_funcoes_essenciais.md @@ -0,0 +1,97 @@ +# TODO: Translate this file to English + + +# Importações e Funções Essenciais + +Esta lição apresenta as importações mais comuns do PraisonAI para criar agentes e fluxos de trabalho. Use-a como referência rápida ao iniciar seus projetos. + +## Principais Módulos + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents, Tools +from praisonaiagents.utils import get_logger +``` + +- `Agent` define o comportamento de um agente individual. +- `Task` encapsula uma unidade de trabalho executável por um agente. +- `PraisonAIAgents` orquestra múltiplos agentes e tarefas. +- `Tools` dá acesso ao catálogo de ferramentas internas. +- `get_logger` cria um logger padronizado para acompanhar a execução. + +## Exemplo Rápido + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents, Tools +from praisonaiagents.utils import get_logger + +logger = get_logger() + +# Define a tarefa +minha_tarefa = Task( + description="Gerar resumo do texto", + tools=[Tools.SEARCH] +) + +# Define o agente +meu_agente = Agent( + role="Escritor", + goal="Produzir conteúdo de qualidade", + tasks=[minha_tarefa] +) + +# Cria o orquestrador e executa +workflow = PraisonAIAgents(agents=[meu_agente], logger=logger) +workflow.run() +``` + +O código acima demonstra como importar e iniciar rapidamente um fluxo simples com um único agente e uma tarefa. + +# Importações e Funções Essenciais para Desenvolvimento de Agentes + +Esta lição apresenta os principais módulos e utilitários usados ao trabalhar com o PraisonAI em Python. Mantenha este guia à mão como referência rápida dos `imports` mais comuns. + +## Classes Principais + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents +``` + +- `Agent`: cria um agente com instruções e configurações. +- `Task`: representa uma tarefa específica que pode ser atribuída a um agente. +- `PraisonAIAgents`: orquestra múltiplos agentes em um mesmo fluxo. + +### Ferramentas + +```python +from praisonaiagents.tools import Tool +``` + +Utilize a classe `Tool` (ou variações) para criar ferramentas personalizadas que expandem as capacidades do agente. + +### Utilidades + +```python +from praisonaiagents.common.log_adapter import get_logger +``` + +A função `get_logger(__name__)` fornece um logger padronizado para acompanhar a execução dos agentes e depurar eventuais problemas. + +## Exemplo de Uso + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents +from praisonaiagents.tools import Tool +from praisonaiagents.common.log_adapter import get_logger + +logger = get_logger(__name__) + +researcher = Agent(instructions="Pesquise sobre IA") +summarizer = Agent(instructions="Resuma os resultados") +workflow = PraisonAIAgents(agents=[researcher, summarizer]) + +resultado = workflow.start("Inicie a pesquisa sobre agentes autônomos") +logger.info(resultado) +``` + +Este exemplo demonstra como importar as classes básicas e o logger para estruturar um fluxo simples com dois agentes. + diff --git a/docs/04_workflows_avancados/01_processos_colaboracao_agentes.md b/docs/04_workflows_avancados/01_processos_colaboracao_agentes.md new file mode 100644 index 000000000..252dee078 --- /dev/null +++ b/docs/04_workflows_avancados/01_processos_colaboracao_agentes.md @@ -0,0 +1,70 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Processos de Colaboração entre Agentes + +No módulo de [Conceitos Fundamentais - Processos](./../02_conceitos_fundamentais/03_processos.md), introduzimos os diferentes tipos de processos que o PraisonAI utiliza para orquestrar a colaboração entre agentes: Sequencial, Hierárquico e Baseado em Workflow. Estes processos são a espinha dorsal para a construção de workflows avançados e sofisticados. + +Este tópico revisita esses processos sob a ótica da construção de sistemas multi-agente mais complexos e como eles preparam o terreno para os padrões de workflow "agênticos" que veremos a seguir. + +## Revisitando os Processos Base + +1. **Processo Sequencial (Sequential Process):** + * **Como Funciona:** Tarefas são executadas em uma ordem linear. O output de uma tarefa serve de input para a próxima. + ```mermaid + graph LR + Entrada[Entrada da Tarefa Inicial] --> A1[Agente A +(Tarefa 1)] + A1 -- Resultado 1 --> A2[Agente B +(Tarefa 2)] + A2 -- Resultado 2 --> A3[Agente C +(Tarefa 3)] + A3 -- Resultado Final --> Saida[Saída Final] + ``` + * **Configuração no PraisonAI:** + * **YAML:** Geralmente o padrão se nenhuma configuração de `process` ou `manager_agent` é especificada. A ordem das tarefas na lista (seja global ou sob um agente) e o uso de `context_tasks` definem o fluxo. + * **Python (com CrewAI):** `process=Process.sequential` ao criar a `Crew`. + * **Quando Usar:** Ideal para cadeias de processamento diretas, onde cada etapa é bem definida e depende da anterior. Ex: Ler um arquivo -> Extrair dados -> Formatar dados -> Salvar dados. + * **Limitações:** Pouca flexibilidade para lidar com variações ou decisões complexas no meio do fluxo. + +2. **Processo Hierárquico (Hierarchical Process):** + * **Como Funciona:** Um "Agente Gerente" (Manager Agent) delega tarefas para "Agentes Trabalhadores" (Worker Agents) e, opcionalmente, revisa e consolida seus resultados. + ```mermaid + graph TB + EntradaPrincipal[Entrada Principal] --> Gerente[Agente Gerente] + Gerente -- Delega Tarefa A --> Trabalhador1[Agente Trabalhador A] + Gerente -- Delega Tarefa B --> Trabalhador2[Agente Trabalhador B] + Trabalhador1 -- Resultado A --> Gerente + Trabalhador2 -- Resultado B --> Gerente + Gerente -- Consolida e Processa --> SaidaFinal[Saída Final] + ``` + * **Configuração no PraisonAI:** + * **YAML:** Definir um `manager_agent` na configuração do workflow. O agente gerente terá suas próprias instruções e lógica para delegar e processar. + * **Python (com CrewAI):** `process=Process.hierarchical`. O primeiro agente na lista de `agents` da `Crew` geralmente assume o papel de gerente, ou pode ser explicitamente definido. + * **Quando Usar:** + * Tarefas complexas que podem ser divididas em sub-tarefas especializadas. + * Quando é necessário um ponto central de controle, decisão ou revisão humana (o gerente pode ser configurado para pedir aprovação). + * Para otimizar a alocação de recursos (diferentes LLMs para gerente e trabalhadores). + * **Vantagens:** Maior flexibilidade, capacidade de lidar com erros e re-tentativas de forma mais inteligente (o gerente pode re-delegar). + +3. **Processo Baseado em Workflow (Custom Workflow Process):** + * **Como Funciona:** Permite a definição de fluxos de trabalho mais complexos, com ramificações condicionais, paralelismo e lógicas de execução personalizadas. Não se limita a uma estrutura estritamente sequencial ou hierárquica. + * **Configuração no PraisonAI:** + * **YAML:** Através da estrutura de `tasks`, `context_tasks`, e possivelmente usando a sintaxe específica do framework subjacente (`praisonai`, `crewai`, `autogen`) para definir fluxos condicionais ou paralelos. O arquivo `agents-advanced.yaml` no repositório PraisonAI é um bom exemplo de configurações mais elaboradas. + * **Python:** Construindo a lógica do workflow programaticamente, encadeando chamadas a agentes, processando resultados e tomando decisões sobre o próximo passo. + * **Quando Usar:** Para processos de negócios complexos, simulações, ou qualquer cenário que exija uma orquestração de tarefas e agentes que não se encaixe perfeitamente nos modelos sequencial ou hierárquico simples. + +## A Transição para Workflows "Agênticos" + +Os processos acima são fundamentais, mas o PraisonAI também promove o conceito de **Workflows Agênticos (Agentic Workflows)**, que são padrões mais específicos de interação e processamento de informação, muitas vezes construídos sobre ou combinando esses processos base. + +O `README.md` principal do PraisonAI ilustra vários desses padrões: + +* **Agentic Routing Workflow:** Direciona tarefas para diferentes LLMs ou agentes com base no conteúdo da tarefa. +* **Agentic Orchestrator Worker:** Um orquestrador que distribui trabalho e um sintetizador que reúne os resultados. +* **Agentic Autonomous Workflow:** Agentes que monitoram, agem e se adaptam com base no feedback do ambiente. +* **Agentic Parallelization:** Execução de tarefas em paralelo. +* **Agentic Prompt Chaining:** Encadeamento de prompts onde a saída de um LLM alimenta o próximo. +* **Agentic Evaluator Optimizer:** Um agente gera soluções, outro avalia, e o ciclo se repete. +* **Repetitive Agents:** Agentes que lidam com tarefas repetitivas em loop. + +Nos próximos tópicos deste módulo, detalharemos cada um desses padrões de workflow agêntico, mostrando como eles podem ser implementados ou conceitualizados dentro do PraisonAI, aproveitando os processos de colaboração que revisitamos aqui. Entender bem os processos sequencial, hierárquico e a flexibilidade dos workflows customizados é o primeiro passo para dominar essas técnicas avançadas. diff --git a/docs/04_workflows_avancados/02_workflow_roteamento_agentico.md b/docs/04_workflows_avancados/02_workflow_roteamento_agentico.md new file mode 100644 index 000000000..19c9c71ad --- /dev/null +++ b/docs/04_workflows_avancados/02_workflow_roteamento_agentico.md @@ -0,0 +1,110 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Roteamento Agêntico (Agentic Routing) + +O **Roteamento Agêntico (Agentic Routing Workflow)** é um padrão de workflow avançado onde as tarefas ou consultas são dinamicamente direcionadas para diferentes Modelos de Linguagem (LLMs) ou agentes especializados, com base no conteúdo ou na natureza da entrada. + +Este padrão é particularmente útil quando você tem acesso a múltiplos LLMs, cada um com suas próprias forças (ex: um LLM ótimo para escrita criativa, outro para análise de código, um terceiro mais rápido e barato para tarefas simples), ou quando diferentes agentes são especializados em domínios distintos. + +## Como Funciona o Roteamento Agêntico? + +O fluxo geral é: + +1. **Entrada (Input):** Uma nova tarefa, pergunta ou dado de entrada é recebido pelo sistema. +2. **Roteador (Router):** Um componente central, que pode ser ele mesmo um LLM ou um agente com lógica específica, analisa a entrada. +3. **Decisão de Roteamento:** Com base na análise, o Roteador decide qual LLM ou agente especializado é o mais adequado para processar a entrada. +4. **Delegação:** A entrada é enviada para o LLM ou agente selecionado. +5. **Processamento:** O LLM/agente selecionado processa a entrada e produz um resultado. +6. **Saída (Output):** O resultado é retornado. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada] --> Router[Roteador de Chamadas LLM] + Router -- Rota A --> LLM1[LLM/Agente A (Ex: Criativo)] + Router -- Rota B --> LLM2[LLM/Agente B (Ex: Código)] + Router -- Rota C --> LLM3[LLM/Agente C (Ex: Rápido/Simples)] + LLM1 -- Resultado A --> Out[Saída] + LLM2 -- Resultado B --> Out + LLM3 -- Resultado C --> Out + + style In fill:#8B0000,color:#fff + style Router fill:#2E8B57,color:#fff + style LLM1 fill:#189AB4,color:#fff + style LLM2 fill:#189AB4,color:#fff + style LLM3 fill:#189AB4,color:#fff + style Out fill:#8B0000,color:#fff +``` + +## Casos de Uso + +* **Otimização de Custos e Performance:** Usar LLMs menores e mais rápidos para tarefas simples e LLMs maiores e mais poderosos (e caros) apenas quando necessário. +* **Especialização de Tarefas:** Direcionar consultas sobre programação para um LLM treinado em código, perguntas sobre história para um LLM com vasto conhecimento histórico, etc. +* **Seleção de Agentes Especializados:** Em um sistema com múltiplos agentes PraisonAI, cada um com um `role` e `tools` diferentes, um roteador pode enviar a tarefa para o agente mais qualificado. +* **Tratamento de Linguagem:** Direcionar entradas em diferentes idiomas para LLMs com melhor performance naquele idioma específico. +* **Balanceamento de Carga:** Distribuir requisições entre vários LLMs idênticos para evitar sobrecarga. + +## Implementação no PraisonAI (Conceitual) + +A implementação de um Roteador Agêntico no PraisonAI pode ser feita de algumas maneiras: + +1. **Agente Roteador Dedicado (Manager Agent):** + * Você pode definir um agente PraisonAI específico para atuar como o roteador. + * **Instruções do Agente Roteador:** As instruções para este agente seriam algo como: "Dada uma tarefa, decida qual dos seguintes especialistas (Agente A, Agente B, Agente C) é o mais adequado para resolvê-la. Responda apenas com o nome do especialista." + * **Ferramentas:** Este agente não precisaria de ferramentas externas, apenas da capacidade de escolher entre opções. + * **Lógica de Workflow:** Um processo hierárquico ou um workflow customizado seria construído onde o Agente Roteador recebe a tarefa primeiro, e seu output (o nome do especialista) é usado para direcionar a tarefa para o próximo agente no fluxo. + + **Exemplo YAML Conceitual:** + ```yaml + framework: praisonai + # process: hierarchical # ou um workflow customizado + # manager_agent: roteador_principal + + roles: + roteador_principal: + role: "Coordenador de Tarefas Inteligente" + goal: "Analisar cada tarefa e designá-la ao especialista mais apropriado." + instructions: | + Você receberá uma tarefa. Sua função é decidir qual dos seguintes especialistas deve lidar com ela: + - 'escritor_criativo': Para tarefas que envolvem escrita de histórias, poemas, roteiros. + - 'programador_python': Para tarefas relacionadas a código Python, algoritmos ou scripts. + - 'assistente_geral': Para perguntas factuais simples ou tarefas gerais. + Responda APENAS com o identificador do especialista (ex: 'escritor_criativo'). + # tasks: # O roteador teria uma tarefa implícita de roteamento + + escritor_criativo: + role: "Escritor Criativo" + goal: "Gerar textos criativos e artísticos." + # ... tasks para escrita ... + + programador_python: + role: "Especialista em Python" + goal: "Resolver problemas de programação e gerar código Python." + # ... tasks para programação ... + + assistente_geral: + role: "Assistente Geral" + goal: "Responder a perguntas gerais e realizar tarefas simples." + # ... tasks gerais ... + + # A lógica do workflow (não mostrada aqui) usaria o output do 'roteador_principal' + # para enviar a tarefa original para o 'role' escolhido. + ``` + +2. **Uso de "Router Chains" (se integrado com LangChain):** + * Se o PraisonAI estiver usando LangChain por baixo dos panos, você pode aproveitar as "Router Chains" do LangChain. Essas cadeias são projetadas especificamente para analisar a entrada e direcioná-la para outra cadeia ou LLM. + * Isso envolveria definir as diferentes "rotas" (LLMs ou cadeias de destino) e os prompts que ajudam o LLM roteador a tomar a decisão. + +3. **Lógica Condicional em Workflows Customizados:** + * Em um workflow definido programaticamente (Python), você pode usar um LLM para classificar a intenção da entrada e, em seguida, usar estruturas `if/else` ou `switch` para enviar a tarefa para o agente ou LLM apropriado. + +## Considerações ao Implementar Roteamento Agêntico + +* **Qualidade do Roteamento:** A eficácia do sistema depende da capacidade do Roteador de tomar decisões precisas. Um roteamento ruim pode levar a resultados subótimos ou custos mais altos. +* **Overhead:** A etapa de roteamento adiciona uma chamada LLM (se o roteador for um LLM) ou lógica computacional, o que introduz alguma latência e custo. Isso precisa ser balanceado com os ganhos de usar o LLM/agente especializado correto. +* **Complexidade:** Configurar e manter um sistema de roteamento pode adicionar complexidade ao seu design de agentes. +* **Clareza das Descrições das Rotas:** Se o roteador é um LLM, ele precisa de descrições claras de cada rota/especialista para tomar boas decisões (semelhante a como os agentes usam descrições de ferramentas). + +O Roteamento Agêntico é uma técnica poderosa para construir sistemas de IA mais eficientes, especializados e econômicos. Ao permitir que seu sistema escolha dinamicamente a melhor "ferramenta" (neste caso, o melhor LLM ou agente) para o trabalho, você pode alcançar resultados significativamente melhores. + +A seguir, exploraremos o padrão **Agentic Orchestrator Worker**. diff --git a/docs/04_workflows_avancados/03_workflow_orquestrador_trabalhador.md b/docs/04_workflows_avancados/03_workflow_orquestrador_trabalhador.md new file mode 100644 index 000000000..8b4a1dcdd --- /dev/null +++ b/docs/04_workflows_avancados/03_workflow_orquestrador_trabalhador.md @@ -0,0 +1,142 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Orquestrador-Trabalhador Agêntico (Agentic Orchestrator Worker) + +O padrão **Orquestrador-Trabalhador Agêntico (Agentic Orchestrator Worker)** é uma evolução do conceito de [Processo Hierárquico](./01_processos_colaboracao_agentes.md#2-processo-hierárquico-hierarchical-process). Ele envolve um agente **Orquestrador** (semelhante a um gerente) que decompõe uma tarefa complexa, distribui sub-tarefas para múltiplos agentes **Trabalhadores** especializados, e depois um componente (que pode ser o próprio Orquestrador ou um agente **Sintetizador** dedicado) que coleta, analisa e combina os resultados dos trabalhadores para produzir a saída final. + +Este padrão é eficaz para problemas que podem ser paralelizados ou que se beneficiam da combinação de múltiplas perspectivas ou especialidades. + +## Como Funciona o Padrão Orquestrador-Trabalhador? + +1. **Entrada (Input):** Uma tarefa ou problema complexo é apresentado ao Orquestrador. +2. **Decomposição e Delegação (Orquestrador):** + * O Orquestrador analisa a tarefa principal e a divide em sub-tarefas menores e mais gerenciáveis. + * Ele pode usar um [Roteador Agêntico](./02_workflow_roteamento_agentico.md) interno ou sua própria lógica para designar cada sub-tarefa a um agente Trabalhador apropriado (ou a um LLM específico). Múltiplos trabalhadores podem operar em paralelo. +3. **Processamento (Trabalhadores):** + * Cada agente Trabalhador executa sua sub-tarefa designada, possivelmente usando suas próprias ferramentas e conhecimentos especializados. +4. **Coleta e Síntese (Orquestrador ou Sintetizador):** + * Os resultados das sub-tarefas executadas pelos Trabalhadores são retornados. + * O Orquestrador (ou um agente Sintetizador dedicado) coleta esses resultados parciais. + * Ele então analisa, filtra, combina e/ou resume as informações para construir uma resposta coesa e completa para a tarefa original. +5. **Saída (Output):** O resultado final consolidado é apresentado. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada Complexa] --> RouterOrchestrator[Orquestrador / Roteador de Chamadas LLM] + RouterOrchestrator -- Sub-Tarefa A --> LLM_Worker1[LLM/Agente Trabalhador A] + RouterOrchestrator -- Sub-Tarefa B --> LLM_Worker2[LLM/Agente Trabalhador B] + RouterOrchestrator -- Sub-Tarefa C --> LLM_Worker3[LLM/Agente Trabalhador C] + LLM_Worker1 -- Resultado A --> Synthesizer[Sintetizador / Orquestrador] + LLM_Worker2 -- Resultado B --> Synthesizer + LLM_Worker3 -- Resultado C --> Synthesizer + Synthesizer --> Out[Saída Final Consolidada] + + style In fill:#8B0000,color:#fff + style RouterOrchestrator fill:#2E8B57,color:#fff + style LLM_Worker1 fill:#189AB4,color:#fff + style LLM_Worker2 fill:#189AB4,color:#fff + style LLM_Worker3 fill:#189AB4,color:#fff + style Synthesizer fill:#2E8B57,color:#fff + style Out fill:#8B0000,color:#fff +``` +*No diagrama, "Router" e "Orchestrator" podem ser o mesmo agente, e o "Synthesizer" também pode ser uma função do Orquestrador ou um agente separado.* + +## Casos de Uso + +* **Relatórios de Pesquisa Abrangentes:** Um Orquestrador pode designar a diferentes Trabalhadores a tarefa de pesquisar diferentes aspectos de um tópico (ex: histórico, aplicações atuais, implicações éticas, futuro). Um Sintetizador então combina essas seções em um relatório coeso. +* **Análise de Múltiplas Fontes de Dados:** Cada Trabalhador analisa um conjunto de dados diferente; o Sintetizador integra os insights. +* **Desenvolvimento de Software Modular:** O Orquestrador define módulos de um software; diferentes Trabalhadores implementam cada módulo; o Sintetizador (ou o Orquestrador) lida com a integração. +* **Planejamento de Eventos Complexos:** Trabalhadores podem cuidar de diferentes partes do planejamento (local, catering, convidados, entretenimento), e o Orquestrador/Sintetizador monta o plano mestre. +* **Brainstorming e Geração de Ideias:** Múltiplos Trabalhadores geram ideias sobre um problema, e o Sintetizador as agrupa, filtra e prioriza. + +## Implementação no PraisonAI (Conceitual) + +A implementação deste padrão no PraisonAI geralmente envolve um processo hierárquico ou um workflow customizado: + +1. **Agente Orquestrador:** + * **Role/Goal:** "Gerente de Projeto de Pesquisa", "Arquiteto de Soluções". Seu objetivo é decompor o problema, delegar e garantir a qualidade da saída final. + * **Instructions:** Devem incluir como analisar a tarefa principal, como dividi-la, a quem delegar (com base nos `roles` dos trabalhadores disponíveis) e como os resultados devem ser sintetizados. + * **Pode usar ferramentas:** Para ajudar na decomposição ou para chamar os trabalhadores. + +2. **Agentes Trabalhadores:** + * São agentes especializados, cada um com seu `role`, `goal`, `backstory`, `instructions` e `tools` específicos para sua área de especialização. + * Ex: "Pesquisador de Dados Históricos", "Analista Financeiro", "Redator Técnico". + +3. **Agente Sintetizador (Opcional, ou função do Orquestrador):** + * Se for um agente separado: + * **Role/Goal:** "Editor Chefe", "Integrador de Relatórios". Seu objetivo é pegar múltiplos inputs e criar um output unificado e de alta qualidade. + * **Instructions:** Como combinar informações de diferentes fontes, resolver conflitos, garantir consistência e formato. + +**Exemplo YAML Conceitual:** + +```yaml +framework: praisonai +# process: hierarchical # Implícito pela estrutura ou explicitado + +# manager_agent: orquestrador_pesquisa (O Orquestrador é o gerente) + +roles: + orquestrador_pesquisa: + role: "Líder de Pesquisa de Mercado" + goal: "Produzir um relatório de análise de mercado completo sobre um novo produto." + instructions: | + Você recebeu a tarefa de criar um relatório de análise de mercado. + 1. Decomponha a análise em: Análise da Concorrência, Perfil do Público-Alvo, e Análise de Tendências de Mercado. + 2. Delegue cada uma dessas seções para os especialistas apropriados: 'analista_concorrencia', 'especialista_publico', 'analista_tendencias'. + 3. Colete os relatórios parciais de cada especialista. + 4. Sintetize esses relatórios em um documento final coeso, adicionando uma introdução e uma conclusão com recomendações estratégicas. + tasks: + gerenciar_relatorio_mercado: # Tarefa principal do orquestrador + description: "Coordenar a criação do relatório de análise de mercado." + expected_output: "Relatório de análise de mercado finalizado e abrangente." + + analista_concorrencia: + role: "Analista de Concorrência" + goal: "Analisar os principais concorrentes do novo produto." + # ... instructions, tools ... + tasks: + pesquisar_concorrentes: + description: "Identificar 3 principais concorrentes, seus pontos fortes, fracos e participação de mercado." + expected_output: "Relatório detalhado sobre a concorrência." + + especialista_publico: + role: "Especialista em Público-Alvo" + goal: "Definir e analisar o público-alvo do novo produto." + # ... instructions, tools ... + tasks: + definir_personas: + description: "Criar 2-3 personas detalhadas para o público-alvo, incluindo dados demográficos, necessidades e comportamentos." + expected_output: "Documento de personas." + + analista_tendencias: + role: "Analista de Tendências de Mercado" + goal: "Identificar as principais tendências de mercado relevantes para o novo produto." + # ... instructions, tools ... + tasks: + analisar_tendencias: + description: "Pesquisar e resumir as 3 principais tendências de mercado que podem impactar o produto." + expected_output: "Sumário das tendências de mercado." + +# O workflow implícito aqui é que o 'orquestrador_pesquisa' primeiro delega as tarefas +# para os outros três agentes. Depois que eles concluem, o 'orquestrador_pesquisa' +# executa uma etapa final de síntese (que poderia ser uma tarefa separada para ele mesmo, +# usando os resultados dos outros como contexto). +``` + +## Vantagens do Padrão + +* **Paralelização:** Sub-tarefas podem ser executadas em paralelo, acelerando o tempo total de processamento. +* **Especialização:** Permite o uso de agentes ou LLMs altamente especializados para cada sub-tarefa, melhorando a qualidade. +* **Escalabilidade:** Mais trabalhadores podem ser adicionados para lidar com problemas maiores. +* **Modularidade:** O sistema é mais fácil de entender, manter e atualizar, pois os componentes são especializados. + +## Desafios + +* **Decomposição da Tarefa:** A habilidade do Orquestrador em decompor a tarefa principal de forma eficaz é crucial. +* **Síntese dos Resultados:** Combinar os resultados de múltiplos trabalhadores pode ser complexo, especialmente se houver informações conflitantes ou redundantes. O Sintetizador precisa de boas instruções ou lógica para isso. +* **Gerenciamento do Fluxo:** Coordenar múltiplos trabalhadores, lidar com possíveis falhas em sub-tarefas e gerenciar o fluxo de dados pode ser desafiador. + +O padrão Orquestrador-Trabalhador Agêntico é uma abordagem robusta para resolver problemas complexos que se beneficiam de uma abordagem de "dividir para conquistar" com múltiplos especialistas. + +A seguir, exploraremos o **Agentic Autonomous Workflow**, onde os agentes têm mais autonomia para interagir com o ambiente. diff --git a/docs/04_workflows_avancados/04_workflow_autonomo_agentico.md b/docs/04_workflows_avancados/04_workflow_autonomo_agentico.md new file mode 100644 index 000000000..ce150ee0b --- /dev/null +++ b/docs/04_workflows_avancados/04_workflow_autonomo_agentico.md @@ -0,0 +1,119 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Workflow Autônomo Agêntico (Agentic Autonomous Workflow) + +O **Workflow Autônomo Agêntico (Agentic Autonomous Workflow)** representa um padrão onde os agentes de IA têm um grau significativo de autonomia para interagir com um ambiente, monitorar seu estado, tomar decisões e realizar ações para atingir seus objetivos, muitas vezes em um ciclo contínuo de feedback. Este padrão é fundamental para criar sistemas que podem operar com intervenção humana mínima em ambientes dinâmicos. + +Este conceito é a base de muitos sistemas de agentes autônomos, como os popularizados por projetos como Auto-GPT ou BabyAGI, e o PraisonAI fornece os blocos de construção para implementar tais workflows. + +## Como Funciona o Workflow Autônomo? + +O ciclo de operação de um workflow autônomo geralmente envolve: + +1. **Objetivo (Goal):** O agente (ou sistema de agentes) recebe um objetivo de alto nível do usuário. +2. **Planejamento/Raciocínio (LLM):** O agente usa seu LLM para: + * Analisar o objetivo. + * Decompor o objetivo em uma série de tarefas ou etapas menores. + * Priorizar essas tarefas. + * Decidir a próxima ação a ser tomada. +3. **Ação (Action):** O agente executa a ação decidida. Isso pode envolver: + * Usar uma [ferramenta](./../02_conceitos_fundamentais/04_ferramentas.md) (ex: buscar na web, escrever em um arquivo, executar código). + * Interagir com um ambiente simulado ou real. + * Comunicar-se com outro agente. +4. **Observação/Feedback (Environment/LLM):** O agente observa o resultado de sua ação e o feedback do ambiente. + * O ambiente pode ser o resultado de uma pesquisa na web, a saída de um script, uma resposta de uma API, ou uma mudança de estado em um sistema. + * O próprio LLM pode "refletir" sobre o resultado da ação em relação ao objetivo. +5. **Adaptação/Replanejamento (LLM):** Com base na observação e no feedback, o LLM: + * Atualiza seu entendimento do estado atual. + * Avalia o progresso em direção ao objetivo. + * Replaneja as próximas tarefas ou ações, se necessário. + * Pode adicionar novas tarefas, remover tarefas antigas ou re-priorizar. +6. **Ciclo Contínuo:** O processo retorna à etapa de "Ação" (ou "Planejamento/Raciocínio" para a próxima tarefa) e continua até que o objetivo seja alcançado, um critério de parada seja atingido (ex: número máximo de iterações), ou o usuário intervenha. +7. **Intervenção Humana (Opcional):** Em muitos sistemas autônomos, há pontos onde a aprovação ou feedback humano pode ser solicitado, especialmente para ações críticas ou quando o agente está incerto. PraisonAI suporta interação humana. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + Humano[Humano (Define Objetivo Inicial)] <--> LLM_Agente[LLM/Agente (Planeja, Raciocina)] + LLM_Agente -- AÇÃO --> Ambiente[Ambiente (Ferramentas, APIs, Web)] + Ambiente -- FEEDBACK/OBSERVAÇÃO --> LLM_Agente + LLM_Agente -- Decide Próxima Ação ou --> Parar[Parar (Objetivo Atingido / Limite)] + + style Humano fill:#8B0000,color:#fff + style LLM_Agente fill:#2E8B57,color:#fff + style Ambiente fill:#189AB4,color:#fff + style Parar fill:#333,color:#fff +``` + +## Casos de Uso + +* **Pesquisa Autônoma:** Um agente que recebe um tópico de pesquisa e autonomamente busca na web, lê artigos, resume informações e compila um relatório. +* **Gerenciamento de Projetos Simples:** Um agente que acompanha o progresso de tarefas, envia lembretes e atualiza status (com as ferramentas certas). +* **Testes de Software Automatizados:** Agentes que can interagir com uma aplicação, tentar diferentes inputs e relatar bugs. +* **Robôs de Comércio (Trading Bots) Simples:** Agentes que monitoram o mercado (ambiente), tomam decisões de compra/venda com base em regras e executam negociações. +* **Aprendizagem e Exploração:** Agentes que exploram um novo software ou API para aprender suas funcionalidades. + +## Implementação no PraisonAI (Conceitual) + +Construir um workflow verdadeiramente autônomo no PraisonAI geralmente requer uma combinação de: + +1. **Um Agente Principal (ou "Master" Agent):** + * **Role/Goal:** Seu objetivo é o objetivo de alto nível fornecido pelo usuário. + * **Instructions:** Devem ser muito bem elaboradas para guiar o ciclo de planejamento, ação e reflexão. Podem incluir: + * Como decompor o objetivo. + * Como gerar uma lista de tarefas. + * Como priorizar e selecionar a próxima tarefa. + * Como usar ferramentas para executar tarefas. + * Como avaliar o resultado de uma ação. + * Como decidir se o objetivo foi alcançado. + * **Tools:** Um conjunto robusto de ferramentas é essencial (busca na web, escrita de arquivos, execução de código, etc.). + * **Memory:** Memória de curto e longo prazo para manter o controle das tarefas realizadas, informações coletadas e o plano atual. + +2. **Loop de Execução:** + * **Programaticamente (Python):** Você precisaria implementar um loop `while` ou `for` (com um número máximo de iterações) que encapsula o ciclo de: + 1. Agente decide a próxima ação/tarefa. + 2. Agente executa a ação (chama uma ferramenta). + 3. Agente recebe o resultado/feedback. + 4. Agente atualiza sua memória/lista de tarefas. + 5. Verifica a condição de parada. + * **YAML:** A configuração YAML pode definir os agentes e suas capacidades, mas o loop de execução autônomo e a lógica de replanejamento dinâmico podem ser mais complexos de expressar puramente em YAML sem um framework que explicitamente suporte esse modo (como AutoGen, que PraisonAI integra). O PraisonAI com `framework: autogen` pode ser uma via. + +3. **Gerenciamento de Tarefas:** + * O agente precisa manter uma lista de tarefas a fazer, tarefas concluídas e, possivelmente, gerar novas tarefas com base no feedback. + +**Exemplo de Lógica Interna de um Agente Autônomo (Simplificado):** + +1. **Objetivo Inicial:** "Escrever um relatório sobre os benefícios da energia solar para residências." +2. **LLM (Planejamento Inicial):** + * Tarefa 1: Pesquisar "benefícios da energia solar residencial". + * Tarefa 2: Pesquisar "custos de instalação de energia solar residencial". + * Tarefa 3: Pesquisar "incentivos governamentais para energia solar residencial". + * Tarefa 4: Estruturar o relatório (introdução, benefícios, custos, incentivos, conclusão). + * Tarefa 5: Escrever a seção de introdução. + * ... (e assim por diante) ... + * Tarefa N: Revisar o relatório completo. +3. **Ação (Tarefa 1):** Agente usa a ferramenta de busca na web com "benefícios da energia solar residencial". +4. **Observação:** Recebe links e resumos de artigos. +5. **Adaptação/Memória:** Armazena os resultados. Pode decidir que precisa refinar a busca ou que encontrou informação suficiente para essa sub-tarefa. Marca Tarefa 1 como concluída (ou parcialmente). Decide que a próxima tarefa é a Tarefa 2. +6. **Ação (Tarefa 2):** Agente usa a ferramenta de busca na web com "custos de instalação de energia solar residencial". +7. ... (o ciclo continua) ... +8. **Ação (Tarefa 5):** Agente usa uma ferramenta interna (ou apenas seu LLM) para escrever a introdução, usando os dados coletados. +9. ... +10. **Parar:** Quando todas as tarefas são concluídas e o agente (ou um agente revisor) considera o relatório satisfatório. + +## PraisonAI e Integrações (AutoGen, CrewAI) + +* **AutoGen:** O framework AutoGen da Microsoft é projetado especificamente para criar conversas e colaborações entre múltiplos agentes LLM, o que é um componente chave para workflows autônomos. Ao usar `framework: autogen` no PraisonAI, você pode estar aproveitando as capacidades do AutoGen para esse tipo de ciclo de feedback e replanejamento. +* **CrewAI:** Embora mais focado na colaboração estruturada, os agentes CrewAI dentro do PraisonAI podem ser parte de um sistema autônomo maior, onde um "agente mestre" orquestra Crews para diferentes partes do objetivo autônomo. + +## Desafios dos Workflows Autônomos + +* **Manter o Foco:** Agentes podem se desviar do objetivo original ou entrar em loops improdutivos. +* **Custo:** Múltiplas chamadas de LLM para planejamento, reflexão e execução de ferramentas podem ser caras. +* **Confiabilidade das Ferramentas:** A autonomia depende da robustez das ferramentas. +* **Controle e Segurança:** Dar autonomia total a agentes que podem executar código ou interagir com a web requer medidas de segurança cuidadosas (sandboxing, permissões limitadas). +* **Avaliação do Progresso:** É difícil para o agente (e para o desenvolvedor) saber objetivamente se está progredindo em direção a objetivos complexos e de longo prazo. + +O Workflow Autônomo Agêntico é uma das áreas mais excitantes e desafiadoras da IA com LLMs. O PraisonAI, ao fornecer uma plataforma flexível para definir agentes, ferramentas, memória e integrar-se com frameworks como AutoGen, oferece os componentes necessários para experimentar e construir esses sistemas. + +A seguir, veremos o padrão de **Paralelização Agêntica (Agentic Parallelization)**. diff --git a/docs/04_workflows_avancados/05_paralelizacao_agentica.md b/docs/04_workflows_avancados/05_paralelizacao_agentica.md new file mode 100644 index 000000000..bb3dc17d0 --- /dev/null +++ b/docs/04_workflows_avancados/05_paralelizacao_agentica.md @@ -0,0 +1,139 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Paralelização Agêntica (Agentic Parallelization) + +A **Paralelização Agêntica (Agentic Parallelization)** é um padrão de workflow onde múltiplas tarefas ou chamadas a Modelos de Linguagem (LLMs)/agentes são executadas simultaneamente, em vez de sequencialmente. O objetivo principal é reduzir o tempo total de processamento para tarefas que podem ser divididas em partes independentes. + +Este padrão é uma forma específica do workflow [Orquestrador-Trabalhador](./03_workflow_orquestrador_trabalhador.md), com uma ênfase na execução concorrente das sub-tarefas. + +## Como Funciona a Paralelização Agêntica? + +1. **Entrada (Input) e Decomposição:** Uma tarefa principal é recebida. Um componente inicial (pode ser um Orquestrador ou um passo de pré-processamento) decompõe a tarefa principal em múltiplas sub-tarefas que podem ser processadas independentemente. +2. **Execução Paralela:** As sub-tarefas são distribuídas para diferentes LLMs ou agentes trabalhadores e são processadas ao mesmo tempo (em paralelo). +3. **Agregação/Sincronização:** Os resultados de todas as sub-tarefas paralelas são coletados por um componente Agregador ou Sincronizador. Este componente espera que todas (ou um número suficiente) das tarefas paralelas sejam concluídas. +4. **Processamento Final (Opcional):** O Agregador pode então processar os resultados combinados (ex: sumarizar, consolidar, filtrar) para produzir a saída final. +5. **Saída (Output):** O resultado final é apresentado. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada Principal] --> Decomposer[Decompositor/Orquestrador] + Decomposer -- Sub-Tarefa A --> LLM1[LLM/Agente A] + Decomposer -- Sub-Tarefa B --> LLM2[LLM/Agente B] + Decomposer -- Sub-Tarefa C --> LLM3[LLM/Agente C] + + LLM1 -- Resultado A --> Aggregator[Agregador/Sincronizador] + LLM2 -- Resultado B --> Aggregator + LLM3 -- Resultado C --> Aggregator + + Aggregator --> Out[Saída Final] + + style In fill:#8B0000,color:#fff + style Decomposer fill:#2E8B57,color:#fff + style LLM1 fill:#189AB4,color:#fff + style LLM2 fill:#189AB4,color:#fff + style LLM3 fill:#189AB4,color:#fff + style Aggregator fill:#7E57C2,color:#fff /* Cor diferente para o agregador */ + style Out fill:#8B0000,color:#fff +``` +*No diagrama, o "Decomposer" pode ser parte do Orquestrador no padrão Orquestrador-Trabalhador.* + +## Casos de Uso + +* **Processamento de Lotes (Batch Processing):** Aplicar a mesma operação a múltiplos itens de dados independentes. Ex: Traduzir vários segmentos de texto, classificar o sentimento de muitos comentários de usuários, gerar descrições para diversos produtos. +* **Coleta de Informações de Diversas Fontes:** Enviar consultas paralelas a diferentes APIs ou ferramentas de busca para coletar dados variados sobre um tópico. +* **Geração de Múltiplas Variantes:** Gerar várias versões de um texto criativo (ex: slogans, parágrafos introdutórios) em paralelo para depois selecionar a melhor. +* **Avaliação de Múltiplos Modelos/Prompts:** Enviar o mesmo prompt para diferentes LLMs (ou o mesmo LLM com diferentes configurações) em paralelo para comparar os resultados. +* **Análise Distribuída:** Dividir um grande conjunto de dados e fazer com que diferentes agentes analisem diferentes partes em paralelo. + +## Implementação no PraisonAI (Conceitual) + +A implementação da paralelização no PraisonAI pode ser alcançada através de: + +1. **Programação Assíncrona em Python:** + * A biblioteca `asyncio` do Python é fundamental para executar operações de I/O (como chamadas de API para LLMs) de forma concorrente. + * Você pode criar múltiplas tarefas `async` que chamam diferentes agentes ou LLMs e depois usar `asyncio.gather()` para esperar que todas sejam concluídas. + * PraisonAI menciona "Async & Parallel Processing" como um recurso, então provavelmente oferece abstrações ou exemplos de como fazer isso. Os arquivos `async_example*.py` em `examples/python/general/` são bons pontos de partida. + + **Exemplo Python Conceitual com `asyncio`:** + ```python + import asyncio + from praisonaiagents import Agent # Supondo que Agent suporta chamadas async + + # Supondo que 'agente_tarefa_a', 'agente_tarefa_b', 'agente_tarefa_c' + # são instâncias de Agent configuradas para suas respectivas sub-tarefas. + + async def executar_agente(agente, input_data): + # Supondo que o método start() ou um similar seja 'async' + return await agente.start(input_data) + + async def main_paralelo(): + input_a = "Dados para tarefa A" + input_b = "Dados para tarefa B" + input_c = "Dados para tarefa C" + + # Cria tarefas asyncio para cada agente + task_a = asyncio.create_task(executar_agente(agente_tarefa_a, input_a)) + task_b = asyncio.create_task(executar_agente(agente_tarefa_b, input_b)) + task_c = asyncio.create_task(executar_agente(agente_tarefa_c, input_c)) + + # Espera todos os resultados + resultados = await asyncio.gather(task_a, task_b, task_c) + + resultado_agregado = f"Resultado A: {resultados[0]}\nResultado B: {resultados[1]}\nResultado C: {resultados[2]}" + print("Resultados Agregados:") + print(resultado_agregado) + return resultado_agregado + + # if __name__ == "__main__": + # # Configurar agentes aqui (agente_tarefa_a, etc.) + # # Exemplo: + # agente_tarefa_a = Agent(instructions="Processar dados do tipo A") + # agente_tarefa_b = Agent(instructions="Processar dados do tipo B") + # agente_tarefa_c = Agent(instructions="Processar dados do tipo C") + # asyncio.run(main_paralelo()) + ``` + +2. **Configuração YAML com Suporte a `async_execution`:** + * Se o framework PraisonAI (ou o backend como CrewAI/AutoGen) suporta, tarefas podem ser marcadas para execução assíncrona no YAML. + * O orquestrador do PraisonAI precisaria então gerenciar o início dessas tarefas e a coleta de seus resultados. + + **Exemplo YAML Conceitual:** + ```yaml + framework: praisonai + # ... + tasks: + - name: sub_tarefa_alpha + agent: trabalhador_alpha + description: "Processar o item Alpha." + expected_output: "Resultado do item Alpha." + async_execution: true # Indica que pode rodar em paralelo + + - name: sub_tarefa_beta + agent: trabalhador_beta + description: "Processar o item Beta." + expected_output: "Resultado do item Beta." + async_execution: true # Indica que pode rodar em paralelo + + - name: tarefa_agregacao + agent: agregador_final + description: "Coletar os resultados de Alpha e Beta e sumarizar." + expected_output: "Sumário final." + context_tasks: [sub_tarefa_alpha, sub_tarefa_beta] # Depende da conclusão das tarefas paralelas + # async_execution: false # Esta geralmente é síncrona após as outras + ``` + *Neste exemplo, `sub_tarefa_alpha` e `sub_tarefa_beta` poderiam ser iniciadas em paralelo. A `tarefa_agregacao` só começaria após ambas serem concluídas.* + +3. **Bibliotecas de Filas de Tarefas (Task Queues):** + * Para sistemas mais robustos e distribuídos, bibliotecas como Celery (com RabbitMQ ou Redis) podem ser usadas para gerenciar a distribuição de tarefas para múltiplos workers que podem estar rodando em diferentes processos ou máquinas. O PraisonAI poderia atuar como o produtor de tarefas para tal sistema. + +## Considerações + +* **Independência das Tarefas:** A paralelização é mais eficaz quando as sub-tarefas são verdadeiramente independentes umas das outras. Se há muitas dependências, o ganho de performance pode ser limitado. +* **Overhead de Gerenciamento:** Iniciar e gerenciar múltiplas tarefas paralelas tem seu próprio overhead. Para tarefas muito pequenas, o overhead pode superar os ganhos. +* **Limites de API e Recursos:** Ao fazer múltiplas chamadas a LLMs em paralelo, esteja ciente dos limites de taxa (rate limits) da API do provedor de LLM e dos recursos computacionais disponíveis. +* **Complexidade da Agregação:** A lógica para agregar os resultados de tarefas paralelas pode ser complexa, especialmente se as tarefas podem falhar ou retornar dados em formatos ligeiramente diferentes. + +A Paralelização Agêntica é uma estratégia valiosa para otimizar a performance de workflows que envolvem múltiplas operações independentes. O suporte a `async` no PraisonAI e Python fornece uma base sólida para implementar este padrão. + +A seguir, exploraremos o **Encadeamento de Prompts Agêntico (Agentic Prompt Chaining)**. diff --git a/docs/04_workflows_avancados/06_encadeamento_prompts_agentico.md b/docs/04_workflows_avancados/06_encadeamento_prompts_agentico.md new file mode 100644 index 000000000..2b96b22b5 --- /dev/null +++ b/docs/04_workflows_avancados/06_encadeamento_prompts_agentico.md @@ -0,0 +1,176 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Encadeamento de Prompts Agêntico (Agentic Prompt Chaining) + +O **Encadeamento de Prompts Agêntico (Agentic Prompt Chaining)**, também conhecido como "Prompt Chaining" ou "Sequential Prompting", é uma técnica fundamental na construção de interações mais complexas e sofisticadas com Modelos de Linguagem (LLMs). Em vez de tentar resolver um problema com um único prompt massivo, o problema é decomposto em uma sequência de prompts menores e mais focados, onde a saída de um prompt alimenta a entrada (ou parte do contexto) do próximo. + +Este padrão é uma forma de processo sequencial, mas com ênfase na manipulação e transformação da informação através de múltiplas etapas de interação com o LLM (ou diferentes LLMs/agentes). + +## Como Funciona o Encadeamento de Prompts? + +1. **Entrada Inicial (Input):** O processo começa com uma entrada ou pergunta inicial. +2. **Primeiro LLM/Agente (LLM Call 1):** A entrada é processada pelo primeiro LLM ou agente com um prompt específico. +3. **Saída Intermediária 1:** Este LLM/agente produz uma saída. +4. **Portão/Decisão (Gate - Opcional):** Pode haver uma etapa de decisão ou validação aqui. + * **Passar (Pass):** Se a saída é satisfatória ou cumpre certas condições, ela (ou uma transformação dela) é passada para o próximo LLM/agente. + * **Falhar/Sair (Fail/Exit):** Se a saída não é satisfatória, o processo pode terminar ou seguir um caminho alternativo. +5. **Segundo LLM/Agente (LLM Call 2):** A saída intermediária alimenta o prompt do segundo LLM/agente. +6. **Saída Intermediária 2:** Este LLM/agente produz outra saída. +7. **(Repetir):** O processo pode continuar com mais chamadas LLM/agentes e portões, conforme necessário. +8. **Saída Final (Output):** A saída do último LLM/agente na cadeia é o resultado final do processo. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada Inicial] --> LLM1[LLM/Agente 1 (Prompt 1)] + LLM1 -- Saída 1 --> Gate{Portão/Decisão} + Gate -- Passar --> LLM2[LLM/Agente 2 (Prompt 2)] + LLM2 -- Saída 2 --> LLM3[LLM/Agente 3 (Prompt 3)] + LLM3 -- Saída Final --> Out[Resultado Final] + Gate -- Falhar/Alternativa --> Exit[Sair ou Rota Alternativa] + + style In fill:#8B0000,color:#fff + style LLM1 fill:#189AB4,color:#fff + style Gate fill:#FFCA28,color:#000 /* Amarelo para decisão */ + style LLM2 fill:#189AB4,color:#fff + style LLM3 fill:#189AB4,color:#fff + style Out fill:#8B0000,color:#fff + style Exit fill:#333,color:#fff +``` + +## Casos de Uso + +* **Refinamento Progressivo:** + * Prompt 1: Gerar um rascunho inicial de um texto. + * Prompt 2: Revisar o rascunho para gramática e clareza. + * Prompt 3: Adaptar o tom do texto revisado para um público específico. +* **Extração e Formatação de Dados:** + * Prompt 1: Extrair informações chave de um bloco de texto não estruturado. + * Prompt 2: Formatar as informações extraídas em JSON. +* **Tradução e Adaptação:** + * Prompt 1: Traduzir um texto para outro idioma. + * Prompt 2: Adaptar a tradução para nuances culturais ou um dialeto específico. +* **Geração de Código em Etapas:** + * Prompt 1: Descrever a funcionalidade de alto nível de uma função. + * Prompt 2: Gerar o esqueleto da função em Python com base na descrição. + * Prompt 3: Adicionar tratamento de erros e documentação à função gerada. +* **Resumo Multi-etapas:** + * Prompt 1: Identificar os pontos principais de um documento longo. + * Prompt 2: Gerar um resumo executivo com base nos pontos principais identificados. +* **Simulação de Conversa com Múltiplas Personas:** Cada "turno" da conversa pode ser um prompt, com o histórico da conversa alimentando o contexto do próximo. + +## Implementação no PraisonAI (Conceitual) + +O Encadeamento de Prompts é inerentemente suportado pela estrutura de agentes e tarefas sequenciais do PraisonAI. + +1. **Múltiplos Agentes Sequenciais:** + * Defina uma série de agentes onde cada um é especializado em uma etapa da cadeia. + * O `goal` e `instructions` de cada agente corresponderiam a um prompt específico na cadeia. + * Use o [Processo Sequencial](./01_processos_colaboracao_agentes.md#1-processo-sequencial-sequential-process) para que a saída de um agente seja automaticamente passada como contexto para o próximo. + + **Exemplo YAML Conceitual:** + ```yaml + framework: praisonai # ou crewai + process: sequential + + roles: + extrator_dados: + role: "Especialista em Extração" + goal: "Extrair nome, email e empresa de um texto de cartão de visita." + instructions: "Dado um texto, identifique e extraia o nome da pessoa, seu endereço de e-mail e o nome da empresa. Retorne apenas esses três dados, um por linha." + # tasks: # Tarefa implícita de extração + + formatador_json: + role: "Formatador JSON" + goal: "Converter dados extraídos para o formato JSON." + instructions: "Você receberá três linhas de texto: nome, email, empresa. Transforme essas informações em um objeto JSON com as chaves 'nome', 'email' e 'empresa'." + # tasks: # Tarefa implícita de formatação, usando a saída do 'extrator_dados' como contexto + + # A entrada inicial seria dada ao 'extrator_dados'. + # A saída do 'extrator_dados' seria automaticamente o input para 'formatador_json'. + ``` + +2. **Múltiplas Tarefas para um Único Agente (ou Agentes em um Workflow):** + * Defina um agente e atribua a ele uma série de tarefas sequenciais. + * A descrição de cada tarefa atuaria como um prompt na cadeia. + * Use `context_tasks` para garantir a ordem correta e a passagem de contexto. + + **Exemplo YAML Conceitual com Tarefas Explícitas:** + ```yaml + framework: praisonai + roles: + escritor_multifacetado: + role: "Assistente de Escrita Completo" + goal: "Produzir um artigo de blog bem escrito e otimizado." + # instructions gerais para o agente + + tasks: + - name: gerar_rascunho + agent: escritor_multifacetado + description: "Escreva um rascunho de 500 palavras sobre os benefícios da meditação para a produtividade." + expected_output: "Texto do rascunho inicial." + + - name: revisar_gramatica + agent: escritor_multifacetado + description: "Revise o texto fornecido (resultado do 'gerar_rascunho') para erros de gramática e ortografia. Forneça o texto corrigido." + expected_output: "Texto revisado gramaticalmente." + context_tasks: [gerar_rascunho] + + - name: otimizar_seo + agent: escritor_multifacetado + description: "Analise o texto revisado (resultado do 'revisar_gramatica') e sugira 3 palavras-chave de SEO para incorporar. Reescreva o primeiro parágrafo para incluir uma delas." + expected_output: "Primeiro parágrafo reescrito e lista de 3 palavras-chave." + context_tasks: [revisar_gramatica] + ``` + +3. **Programaticamente (Python):** + * Você pode simplesmente chamar `agente.start()` (ou um método similar) múltiplas vezes, usando a saída de uma chamada como entrada para a próxima. + * Bibliotecas como LangChain (que o PraisonAI integra) têm abstrações específicas para cadeias de prompts (ex: `SequentialChain`, `LLMChain`). + + **Exemplo Python Conceitual:** + ```python + from praisonaiagents import Agent + + # Supondo que OPENAI_API_KEY está configurada + agente_prompt1 = Agent(instructions="Traduza o seguinte texto para o francês: {texto_original}") + agente_prompt2 = Agent(instructions="Explique o significado da seguinte frase em francês em uma sentença simples em português: {frase_frances}") + + texto_ingles = "Hello, how are you today?" + + # Primeira chamada na cadeia + texto_frances = agente_prompt1.start(texto_original=texto_ingles) + # (A API do PraisonAI pode variar na forma de passar inputs nomeados para o prompt) + # Ou, mais diretamente: + # texto_frances = agente_prompt1.start(f"Traduza o seguinte texto para o francês: {texto_ingles}") + + + print(f"Texto em Francês: {texto_frances}") + + # Segunda chamada na cadeia, usando a saída da primeira + explicacao_portugues = agente_prompt2.start(frase_frances=texto_frances) + # Ou: + # explicacao_portugues = agente_prompt2.start(f"Explique o significado da seguinte frase em francês em uma sentença simples em português: {texto_frances}") + + print(f"Explicação em Português: {explicacao_portugues}") + ``` + +## Vantagens do Encadeamento de Prompts + +* **Melhora da Qualidade:** Decompor o problema permite que o LLM foque em uma sub-tarefa específica por vez, geralmente levando a resultados melhores do que um único prompt complexo. +* **Maior Controle:** Permite inspecionar e modificar saídas intermediárias. +* **Redução de Alucinações:** Prompts mais focados podem reduzir a chance de o LLM gerar informações incorretas. +* **Facilidade de Debugging:** Se algo der errado, é mais fácil identificar em qual etapa da cadeia o problema ocorreu. +* **Modularidade:** Cada prompt/agente na cadeia pode ser desenvolvido e testado independentemente. + +## "Gates" (Portões/Decisões) + +A inclusão de "gates" ou etapas de decisão entre as chamadas de LLM adiciona mais poder ao encadeamento. Um "gate" pode ser: +* Uma chamada a uma função Python que valida a saída intermediária. +* Outra chamada LLM que decide se a qualidade é suficiente para prosseguir. +* Uma solicitação de feedback humano. + +Se a saída não passar pelo "gate", o workflow pode terminar, tentar a etapa anterior novamente com um prompt modificado, ou seguir um caminho alternativo. + +O Encadeamento de Prompts Agêntico é uma técnica versátil e poderosa, fundamental para construir aplicações LLM robustas e capazes de realizar tarefas complexas em múltiplas etapas. + +A seguir, exploraremos o padrão **Avaliador-Otimizador Agêntico (Agentic Evaluator Optimizer)**. diff --git a/docs/04_workflows_avancados/07_avaliador_otimizador_agentico.md b/docs/04_workflows_avancados/07_avaliador_otimizador_agentico.md new file mode 100644 index 000000000..dd89534ad --- /dev/null +++ b/docs/04_workflows_avancados/07_avaliador_otimizador_agentico.md @@ -0,0 +1,162 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Avaliador-Otimizador Agêntico (Agentic Evaluator Optimizer) + +O padrão **Avaliador-Otimizador Agêntico (Agentic Evaluator Optimizer)**, também conhecido como ciclo Gerador-Avaliador ou Crítico-Executor, é um workflow iterativo projetado para refinar e melhorar progressivamente a qualidade de uma solução ou saída gerada por um Modelo de Linguagem (LLM) ou agente. + +Este padrão envolve pelo menos dois papéis principais (que podem ser desempenhados por diferentes LLMs/agentes ou pelo mesmo LLM com diferentes prompts): + +1. **Gerador (Generator) / Executor:** Responsável por criar uma solução inicial ou uma tentativa de resposta para um dado problema ou tarefa. +2. **Avaliador (Evaluator) / Crítico:** Responsável por analisar a solução gerada pelo Gerador, compará-la com critérios de qualidade ou objetivos, e fornecer feedback construtivo. + +## Como Funciona o Ciclo Avaliador-Otimizador? + +1. **Entrada (Input) / Problema:** O ciclo começa com um problema a ser resolvido ou uma tarefa a ser realizada. +2. **Geração (Generator):** O agente Gerador produz uma primeira versão da solução ou resposta. +3. **Avaliação (Evaluator):** A solução do Gerador é passada para o agente Avaliador. O Avaliador: + * Compara a solução com critérios pré-definidos, exemplos de boas respostas, ou o objetivo original. + * Identifica pontos fortes, fracos, erros, ou áreas para melhoria. + * Gera um feedback detalhado. +4. **Decisão:** Com base no feedback do Avaliador: + * **Aceitar:** Se a solução for considerada boa o suficiente (atinge um certo limiar de qualidade), o ciclo termina e a solução é aceita como saída final. + * **Rejeitar + Feedback (Otimizar):** Se a solução precisa de melhorias, o feedback do Avaliador é fornecido de volta ao Gerador. +5. **Re-Geração / Otimização (Generator):** O Gerador recebe a solução anterior e o feedback do Avaliador. Ele então tenta produzir uma nova versão melhorada da solução, incorporando o feedback. +6. **Loop:** O processo retorna à etapa de Avaliação (3) com a nova solução. Este ciclo iterativo continua até que a solução seja aceita ou um número máximo de iterações seja atingido. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada/Problema] --> Generator[LLM/Agente Gerador] + Generator -- SOLUÇÃO v1 --> Evaluator[LLM/Agente Avaliador] + Evaluator -- ACEITA --> Out[Saída Final Aceita] + Evaluator -- REJEITADA + FEEDBACK --> Generator + + style In fill:#8B0000,color:#fff + style Generator fill:#189AB4,color:#fff + style Evaluator fill:#FFCA28,color:#000 /* Amarelo para avaliação */ + style Out fill:#8B0000,color:#fff +``` + +## Casos de Uso + +* **Escrita de Textos de Alta Qualidade:** + * Gerador: Escreve um rascunho de um artigo. + * Avaliador: Verifica clareza, coesão, gramática, tom, e se o artigo cumpre os requisitos. Fornece sugestões de reescrita. +* **Geração de Código:** + * Gerador: Escreve uma função em Python. + * Avaliador: Verifica se o código funciona, segue as boas práticas, é eficiente, e tem tratamento de erros. Pode até tentar executar o código e analisar os resultados. +* **Design de Soluções:** + * Gerador: Propõe uma arquitetura para um sistema de software. + * Avaliador: Analisa a proposta quanto a escalabilidade, segurança, custo, e manutenibilidade. +* **Resolução de Problemas Complexos:** + * Gerador: Sugere uma estratégia para resolver um problema de lógica. + * Avaliador: Verifica a validade da estratégia e aponta falhas no raciocínio. +* **Otimização de Prompts:** O próprio feedback pode ser usado para refinar o prompt original que o Gerador está usando. +* **Auto-correção / Auto-reflexão Avançada:** O PraisonAI menciona "Self Reflection AI Agents". O ciclo Avaliador-Otimizador é uma forma poderosa de implementar auto-reflexão, onde o "Avaliador" pode ser o mesmo agente Gerador, mas operando sob um prompt diferente focado na crítica e melhoria. + +## Implementação no PraisonAI (Conceitual) + +Este padrão geralmente requer um workflow que gerencia o ciclo iterativo: + +1. **Agente Gerador:** + * `role`, `goal`, `instructions` focados na criação da solução inicial. + * Pode ter ferramentas específicas para sua tarefa de geração. + +2. **Agente Avaliador:** + * `role`, `goal`, `instructions` focados na análise crítica da solução do Gerador. Suas instruções devem incluir os critérios de avaliação. + * Pode ter ferramentas para ajudar na avaliação (ex: um linter de código, uma ferramenta para verificar fatos). + +3. **Lógica de Orquestração (Pode ser um Agente Gerente ou código Python):** + * Gerencia o loop: envia a tarefa inicial para o Gerador, passa a saída para o Avaliador, passa o feedback de volta para o Gerador. + * Implementa a condição de parada (solução aceita ou máximo de iterações). + +**Exemplo YAML Conceitual (com um Agente Gerente Orquestrando):** +```yaml +framework: praisonai +# process: hierarchical ou custom workflow +# manager_agent: orquestrador_ciclo + +roles: + orquestrador_ciclo: + role: "Orquestrador do Ciclo de Melhoria" + goal: "Gerenciar o processo iterativo de geração e avaliação para produzir um código Python de alta qualidade." + instructions: | + Seu objetivo é obter uma função Python que some dois números. + 1. Delegue a tarefa de escrever a função inicial para o 'programador_junior'. + 2. Receba a função e delegue a tarefa de avaliá-la para o 'revisor_codigo_senior'. + 3. Se o 'revisor_codigo_senior' aprovar (responder com "APROVADO"), a tarefa está concluída. + 4. Se o 'revisor_codigo_senior' fornecer feedback, passe a função original E o feedback para o 'programador_junior' para uma nova tentativa. + 5. Repita os passos 2-4 no máximo 3 vezes. Se não for aprovado em 3 tentativas, encerre com a última versão e o feedback. + # tasks: ... + + programador_junior: + role: "Programador Python Junior" + goal: "Escrever código Python funcional com base nas especificações e feedback." + instructions: "Escreva uma função Python chamada 'soma' que recebe dois argumentos e retorna sua soma. Se receber feedback, use-o para corrigir e melhorar a função." + # tasks: ... + + revisor_codigo_senior: + role: "Revisor de Código Senior" + goal: "Avaliar código Python quanto à funcionalidade, clareza e boas práticas, fornecendo feedback construtivo." + instructions: | + Você receberá uma função Python. Avalie-a com base nos seguintes critérios: + - Funcionalidade: Ela soma dois números corretamente? + - Clareza: O código é fácil de entender? + - Boas Práticas: Segue as convenções do Python (PEP8)? + Se a função estiver boa, responda APENAS com a palavra "APROVADO". + Caso contrário, forneça um feedback específico sobre o que precisa ser melhorado. + # tools: # Poderia ter uma ferramenta para executar o código + # tasks: ... +``` + +**Programaticamente (Python):** +```python +from praisonaiagents import Agent # ou de onde vier Agent + +# Configurar os agentes (gerador, avaliador) +gerador = Agent(instructions="Gere um slogan para uma cafeteria.") +avaliador = Agent(instructions="Avalie o slogan: '{slogan_gerado}'. É curto, memorável e atraente? Se não, sugira melhorias. Se sim, diga 'Perfeito'.") + +slogan_atual = None +feedback = None +max_iteracoes = 3 + +for i in range(max_iteracoes): + prompt_gerador = "Gere um slogan para uma cafeteria." + if feedback: # Se houver feedback, adiciona ao prompt do gerador + prompt_gerador += f" Considere o seguinte feedback para melhoria: {feedback}" + + slogan_atual = gerador.start(prompt_gerador) + print(f"Iteração {i+1} - Slogan Gerado: {slogan_atual}") + + feedback_avaliador = avaliador.start(slogan_gerado=slogan_atual) # Passando o slogan para o prompt do avaliador + print(f"Iteração {i+1} - Feedback do Avaliador: {feedback_avaliador}") + + if "Perfeito" in feedback_avaliador: # Condição de parada + print("Slogan final aceito!") + break + + feedback = feedback_avaliador # Prepara o feedback para a próxima iteração +else: + print("Máximo de iterações atingido. Usando o último slogan gerado.") + +# Resultado final é 'slogan_atual' +``` + +## Vantagens do Padrão + +* **Melhoria da Qualidade:** A natureza iterativa e o feedback explícito geralmente levam a resultados de maior qualidade do que uma única tentativa. +* **Resolução de Problemas Complexos:** Permite abordar problemas que são difíceis de resolver corretamente na primeira tentativa. +* **Simula Processos Humanos:** Espelha como os humanos frequentemente trabalham: criar, obter feedback, refinar. +* **Customização da Avaliação:** Os critérios de avaliação podem ser altamente personalizados para a tarefa em questão. + +## Desafios + +* **Custo e Latência:** Cada iteração envolve pelo menos duas chamadas LLM (uma para o Gerador, uma para o Avaliador), o que pode aumentar o custo e o tempo de execução. +* **Qualidade do Feedback:** A eficácia do ciclo depende muito da qualidade do feedback do Avaliador. Um feedback vago ou ruim não ajudará o Gerador. +* **Convergência:** Não há garantia de que o processo sempre convergirá para uma solução perfeita. É importante ter critérios de parada (ex: número máximo de iterações, tempo limite). +* **Definição dos Critérios de Avaliação:** Criar prompts ou lógica para o Avaliador que reflitam com precisão os critérios de qualidade desejados pode ser desafiador. + +O padrão Avaliador-Otimizador Agêntico é uma técnica poderosa para alcançar resultados de alta qualidade e para tarefas que se beneficiam de um processo de refinamento iterativo. O PraisonAI, com sua capacidade de orquestrar múltiplos agentes e workflows, está bem posicionado para implementar este padrão. + +A seguir, veremos os **Agentes Repetitivos (Repetitive Agents)**. diff --git a/docs/04_workflows_avancados/08_agentes_repetitivos.md b/docs/04_workflows_avancados/08_agentes_repetitivos.md new file mode 100644 index 000000000..4298083a2 --- /dev/null +++ b/docs/04_workflows_avancados/08_agentes_repetitivos.md @@ -0,0 +1,126 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Agentes Repetitivos (Repetitive Agents) + +O padrão de **Agentes Repetitivos (Repetitive Agents)** refere-se a um workflow onde um ou mais agentes são projetados para executar uma tarefa específica (ou um conjunto de tarefas) múltiplas vezes, geralmente sobre diferentes conjuntos de dados de entrada ou até que uma determinada condição seja satisfeita. + +Este padrão é útil para automação de processos que envolvem a aplicação da mesma lógica a vários itens ou para tarefas que requerem monitoramento ou ação contínua. + +## Como Funcionam os Agentes Repetitivos? + +1. **Definição da Tarefa:** Uma tarefa ou um conjunto de tarefas que o agente precisa realizar é claramente definida. +2. **Entrada de Dados (Iterável):** Há uma fonte de dados ou um gatilho que fornece a entrada para cada iteração. Pode ser: + * Uma lista de itens (ex: URLs, nomes de arquivos, registros de um banco de dados). + * Um fluxo de dados contínuo (ex: novos e-mails chegando, atualizações de um feed). + * Um contador ou uma condição de tempo (ex: executar a cada hora). +3. **Loop de Execução:** O agente (ou o sistema que o gerencia) entra em um loop: + * **Obter Entrada:** Pega o próximo item da lista, lê do fluxo, ou verifica a condição de tempo/evento. + * **Executar Tarefa:** O agente executa sua tarefa definida usando a entrada atual. + * **Produzir Saída/Efeito Colateral:** O agente gera um resultado para a iteração atual ou realiza uma ação (ex: salva um arquivo, envia uma notificação). +4. **Condição de Parada:** O loop continua até que: + * Todos os itens da lista tenham sido processados. + * O fluxo de dados termine. + * Uma condição específica de parada seja atingida (ex: um erro crítico, um sinal do usuário, um número máximo de iterações). + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + EntradaIteravel[Entrada / Lista de Itens / Gatilho] --> AgenteLoop[("Agente em Loop")] + AgenteLoop -- Processa Item/Evento --> Tarefa[Executa Tarefa Definida] + Tarefa -- Para Próxima Iteração / Item --> AgenteLoop + Tarefa -- Concluído / Condição de Parada --> Saida[Saída Agregada / Fim do Processo] + + style EntradaIteravel fill:#8B0000,color:#fff + style AgenteLoop fill:#2E8B57,color:#fff,shape:circle + style Tarefa fill:#189AB4,color:#fff + style Saida fill:#8B0000,color:#fff +``` + +## Casos de Uso + +* **Processamento em Lote de Arquivos:** + * Agente lê cada arquivo de uma pasta, extrai informações e salva em um banco de dados. +* **Web Scraping de Múltiplas Páginas:** + * Agente recebe uma lista de URLs, visita cada uma, extrai dados específicos e os armazena. +* **Envio de E-mails Personalizados em Massa:** + * Agente percorre uma lista de contatos, personaliza um template de e-mail para cada um e o envia. +* **Monitoramento e Alerta:** + * Agente verifica o status de um sistema a cada X minutos e envia um alerta se detectar um problema. +* **Tradução de Múltiplos Documentos:** + * Agente traduz uma série de documentos de um idioma para outro. +* **Classificação de Dados:** + * Agente analisa uma lista de comentários de clientes e classifica cada um como positivo, negativo ou neutro. + +## Implementação no PraisonAI (Conceitual) + +A implementação de agentes repetitivos no PraisonAI pode ser feita de várias formas: + +1. **Loop de Controle Externo (Python):** + * Você pode escrever um script Python que define um agente PraisonAI e, em seguida, usa um loop `for` ou `while` para chamar o método `start()` (ou similar) do agente repetidamente com diferentes dados de entrada. + + **Exemplo Python Conceitual:** + ```python + from praisonaiagents import Agent + + # Supondo que OPENAI_API_KEY está configurada + tradutor_agente = Agent( + instructions="Traduza o seguinte texto para o espanhol: {texto_para_traduzir}", + role="Tradutor Inglês-Espanhol" + ) + + lista_de_frases_ingles = [ + "Hello, world!", + "How are you?", + "This is a test." + ] + + traducoes_espanhol = [] + + for frase in lista_de_frases_ingles: + # A forma de passar o input pode variar. + # Idealmente, o agente é configurado para esperar uma variável no prompt. + # Se o método start apenas concatena, você faria: + # traducao = tradutor_agente.start(f"Traduza o seguinte texto para o espanhol: {frase}") + # Mas se o Agent suportar substituição de placeholders nas instructions: + traducao = tradutor_agente.start(texto_para_traduzir=frase) + traducoes_espanhol.append(traducao) + print(f"Inglês: {frase} -> Espanhol: {traducao}") + + # print("\nTraduções Finais:", traducoes_espanhol) + ``` + +2. **Agente com Capacidade de Iteração Interna (Menos Comum para LLMs):** + * Seria menos comum que um agente baseado em LLM gerenciasse um loop complexo internamente apenas com prompts, a menos que ele estivesse escrevendo e executando código que implementasse o loop. + * No entanto, um agente poderia ser instruído a processar uma *lista* de itens fornecida em um único prompt, se a lista não for muito grande. Ex: "Traduza as seguintes 3 frases: [frase1, frase2, frase3]". + +3. **Workflows YAML com Gatilhos ou Fontes de Dados Iteráveis:** + * Se o PraisonAI (ou o framework subjacente como AutoGen) suportar gatilhos baseados em tempo (agendamento) ou a capacidade de ler de uma fonte de dados que pode ser iterada (ex: um arquivo CSV, uma fila de mensagens), então o workflow YAML poderia ser configurado para executar repetidamente. + * O `schedule_config.yaml.example` no repositório PraisonAI sugere capacidades de agendamento, o que se alinha com tarefas repetitivas. + + **Exemplo YAML Conceitual (para um agendador hipotético):** + ```yaml + # Supondo uma configuração de agendamento no PraisonAI + schedule: + - name: "verificar_novos_pedidos_a_cada_5_minutos" + cron_expression: "*/5 * * * *" # A cada 5 minutos + workflow_yaml: "workflows/processar_pedido.yaml" # YAML que define o agente e a tarefa de processar um pedido + # input_source: "fila_de_pedidos_api" # De onde pegar o dado do pedido + ``` + +4. **Uso de Ferramentas que Gerenciam Iteração:** + * O agente pode ter uma ferramenta que, quando chamada, processa uma coleção de itens. Por exemplo, uma ferramenta `processar_lista_de_urls(urls: list)` que internamente itera sobre as URLs e realiza uma ação para cada uma. + +## Considerações para Agentes Repetitivos + +* **Gerenciamento de Estado entre Iterações:** Se o agente precisa lembrar informações de iterações anteriores (além do contexto de curto prazo), a [memória](./../02_conceitos_fundamentais/05_memoria.md) persistente é crucial. +* **Tratamento de Erros:** Em um loop longo, é importante ter um bom tratamento de erros. O que acontece se uma iteração falhar? O loop para? A falha é registrada e o loop continua? +* **Eficiência e Custo:** Executar um agente LLM muitas vezes pode ser lento e/ou caro. Para tarefas repetitivas muito simples, pode haver soluções não-LLM mais eficientes. Considere otimizações como: + * Usar LLMs menores e mais rápidos se a tarefa permitir. + * Processamento em lote (batching) de chamadas LLM, se possível. + * Paralelização (se as iterações forem independentes). +* **Limites de Taxa (Rate Limiting):** Cuidado com os limites de taxa das APIs dos LLMs ou outras APIs que suas ferramentas possam estar usando. +* **Idempotência:** Se possível, projete a tarefa do agente para ser idempotente, o que significa que executá-la múltiplas vezes com a mesma entrada produz o mesmo resultado ou não causa efeitos colaterais indesejados. Isso é útil se uma iteração precisar ser re-executada devido a uma falha. + +Os Agentes Repetitivos são um padrão essencial para automatizar tarefas que precisam ser aplicadas a múltiplos conjuntos de dados ou executadas de forma contínua. O PraisonAI fornece a flexibilidade para implementar este padrão, seja através de loops de controle externos em Python ou potencialmente através de configurações de workflow mais avançadas. + +Com este tópico, concluímos a exploração dos principais padrões de Workflows Avançados ilustrados no PraisonAI! diff --git a/docs/04_workflows_avancados/09_agentes_multimodais.md b/docs/04_workflows_avancados/09_agentes_multimodais.md new file mode 100644 index 000000000..34bf1b9e7 --- /dev/null +++ b/docs/04_workflows_avancados/09_agentes_multimodais.md @@ -0,0 +1,15 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Agentes Multimodais + +Agentes multimodais conseguem lidar com diferentes tipos de dados, como texto e imagens, dentro do mesmo fluxo de trabalho. No PraisonAI, você pode combinar ferramentas de visão computacional com seus agentes tradicionais. + +```python +from praisonaiagents import Agent +from praisonaiagents.tools import image_to_text + +agent = Agent(tools=[image_to_text]) +agent.start("Analyze the image at example.png and summarise it") +``` + +Utilize esse padrão quando precisar de entradas visuais ou de outros formatos além de texto. diff --git a/docs/04_workflows_avancados/10_code_interpreter_agents.md b/docs/04_workflows_avancados/10_code_interpreter_agents.md new file mode 100644 index 000000000..8d0dd5b4d --- /dev/null +++ b/docs/04_workflows_avancados/10_code_interpreter_agents.md @@ -0,0 +1,15 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Code Interpreter Agents + +Esses agentes utilizam a ferramenta `code_interpreter` para executar trechos de código e retornar o resultado. É útil para análises de dados, geração de gráficos ou qualquer tarefa que exija execução dinâmica de scripts. + +```python +from praisonaiagents import Agent +from praisonaiagents.tools import code_interpreter + +agent = Agent(tools=[code_interpreter]) +agent.start("Calculate the factorial of 5") +``` + +A saída do código é repassada para o agente, permitindo ciclos de raciocínio baseados em resultados programáticos. diff --git a/docs/04_workflows_avancados/11_math_agents.md b/docs/04_workflows_avancados/11_math_agents.md new file mode 100644 index 000000000..f9b79b934 --- /dev/null +++ b/docs/04_workflows_avancados/11_math_agents.md @@ -0,0 +1,15 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Math Agents + +Math Agents são especializados em resolver cálculos e problemas matemáticos. Combinam o raciocínio do modelo de linguagem com ferramentas que efetuam operações precisas. + +```python +from praisonaiagents import Agent +from praisonaiagents.tools import math_tool + +agent = Agent(tools=[math_tool]) +agent.start("Solve the equation 2*x + 3 = 9") +``` + +Esse padrão ajuda a garantir respostas numéricas corretas e detalhadas. diff --git a/docs/04_workflows_avancados/12_saida_estruturada.md b/docs/04_workflows_avancados/12_saida_estruturada.md new file mode 100644 index 000000000..08fba152f --- /dev/null +++ b/docs/04_workflows_avancados/12_saida_estruturada.md @@ -0,0 +1,14 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Structured Output + +Em muitas aplicações, é importante que as respostas sigam um formato fixo, como JSON ou tabelas. Os agentes podem ser configurados com instruções claras para sempre retornarem dados estruturados. + +```python +from praisonaiagents import Agent + +agent = Agent(instructions="Answer using a JSON object with keys 'summary' and 'sources'.") +agent.start("Summarise the benefits of solar energy") +``` + +Definir um esquema de saída torna o pós-processamento muito mais simples. diff --git a/docs/04_workflows_avancados/13_callback_agents.md b/docs/04_workflows_avancados/13_callback_agents.md new file mode 100644 index 000000000..67766f774 --- /dev/null +++ b/docs/04_workflows_avancados/13_callback_agents.md @@ -0,0 +1,17 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Callback Agents + +Callback Agents permitem executar funções específicas em pontos determinados da conversa, como antes ou depois do uso de uma ferramenta. Isso facilita monitoramento e extensões personalizadas. + +```python +from praisonaiagents import Agent + +def log_step(data): + print("Agent step:", data) + +agent = Agent(callbacks=[log_step]) +agent.start("Tell me a joke") +``` + +Use callbacks para registro, métricas ou integrações extras. diff --git a/docs/04_workflows_avancados/14_mini_agents.md b/docs/04_workflows_avancados/14_mini_agents.md new file mode 100644 index 000000000..f3a789ea5 --- /dev/null +++ b/docs/04_workflows_avancados/14_mini_agents.md @@ -0,0 +1,14 @@ +# TODO: Translate this file to English + +# Workflows Avançados: Mini AI Agents + +Mini Agents são versões simplificadas focadas em uma tarefa específica. Por serem leves, podem ser executados em paralelo ou incorporados a aplicações maiores com facilidade. + +```python +from praisonaiagents import Agent + +agent = Agent(instructions="Answer only with emoji reactions") +agent.start("How are you?") +``` + +São úteis quando se deseja um comportamento muito pontual sem a complexidade de um workflow completo. diff --git a/docs/05_ferramentas/00_visao_geral_ferramentas.md b/docs/05_ferramentas/00_visao_geral_ferramentas.md new file mode 100644 index 000000000..fe61c2156 --- /dev/null +++ b/docs/05_ferramentas/00_visao_geral_ferramentas.md @@ -0,0 +1,140 @@ +# TODO: Translate this file to English + +# Módulo: Ferramentas (Tools) no PraisonAI + +As **Ferramentas (Tools)** são um componente essencial que transforma os [Agentes](./../02_conceitos_fundamentais/01_agentes.md) do PraisonAI de meros processadores de linguagem em entidades capazes de interagir com o mundo real, executar ações e acessar informações externas. O PraisonAI destaca o suporte a "Mais de 100 Ferramentas Personalizadas", além da capacidade de criar as suas próprias. + +Este módulo explora como as ferramentas funcionam no PraisonAI, como utilizá-las e como desenvolvê-las. Já introduzimos o conceito básico de ferramentas em [Conceitos Fundamentais - Ferramentas](./../02_conceitos_fundamentais/04_ferramentas.md), aqui vamos aprofundar. + +## A Importância das Ferramentas e Suas Descrições + +Para um Modelo de Linguagem Grande (LLM) utilizar uma ferramenta eficazmente, ele precisa entender: +1. **O que a ferramenta faz:** Qual seu propósito? +2. **Quando usá-la:** Em que situações ou para quais tipos de perguntas/tarefas ela é relevante? +3. **Quais argumentos ela espera:** Que informações de entrada a ferramenta necessita? +4. **O que ela retorna:** Qual o formato e o tipo de saída da ferramenta? + +Essa compreensão é quase inteiramente derivada da **descrição da ferramenta** (geralmente a docstring da função em Python) e do **esquema dos seus argumentos** (tipos e nomes dos parâmetros). + +> [!CRITICAL] Descrições Claras São Cruciais! +> A qualidade da descrição da sua ferramenta impacta diretamente a capacidade do LLM de usá-la corretamente. Descrições vagas ou imprecisas levarão a um uso incorreto ou à não utilização da ferramenta. + +## Usando Ferramentas Embutidas no PraisonAI + +PraisonAI oferece um vasto conjunto de ferramentas prontas para uso. Embora uma lista exaustiva esteja além do escopo deste guia (consulte a documentação oficial do PraisonAI ou explore o código-fonte para detalhes específicos), o uso delas geralmente segue um padrão: + +* **Identificação da Ferramenta:** Você precisa saber o nome ou identificador da ferramenta que deseja usar (ex: `tavily_search`, `web_scraper`, `code_interpreter`, `file_read_tool`). +* **Atribuição ao Agente:** + * **Em YAML:** Na definição de um `role` (agente), você pode listar as ferramentas que ele tem permissão para usar na seção `tools`: + ```yaml + roles: + pesquisador_avancado: + role: "Pesquisador Avançado" + goal: "Encontrar e analisar informações detalhadas sobre tópicos complexos." + tools: + - "tavily_search" # Ferramenta de busca na web (exemplo) + - "web_page_reader" # Ferramenta para ler conteúdo de URLs + # - "nome_outra_ferramenta_embutida" + # ... outras configurações ... + ``` + * **Em Python:** Ao instanciar um `Agent`, você passa uma lista de objetos de ferramenta ou nomes de ferramentas registradas para o parâmetro `tools`. + ```python + from praisonaiagents import Agent + # Supondo que as ferramentas embutidas possam ser importadas ou referenciadas por nome + # from praisonai.tools import TavilySearchTool, WebScraperTool # Exemplo conceitual + + # ferramentas_disponiveis = [TavilySearchTool(), WebScraperTool()] + # OU, se referenciadas por nome: + # ferramentas_disponiveis = ["tavily_search", "web_scraper"] + + # agente = Agent( + # role="Pesquisador", + # goal="Coletar informações da web.", + # tools=ferramentas_disponiveis + # ) + ``` + A forma exata de instanciar/referenciar ferramentas embutidas em Python dependerá de como elas são expostas pela biblioteca `praisonaiagents`. Verifique os exemplos no repositório. + +* **Invocação pelo LLM:** Uma vez que um agente tem uma ferramenta atribuída, o LLM do agente decidirá autonomamente quando usá-la durante a execução de uma tarefa, com base nas instruções da tarefa e na descrição da ferramenta. + +## Criando Ferramentas Personalizadas + +A verdadeira flexibilidade do PraisonAI (e de frameworks como LangChain, que ele integra) reside na facilidade de criar ferramentas personalizadas para atender às necessidades específicas do seu projeto. + +O método mais comum em Python é definir uma função e decorá-la para transformá-la em uma ferramenta que o LLM possa entender. + +**Exemplo Chave: `examples/python/general/example_custom_tools.py`** + +Este arquivo no repositório PraisonAI é uma excelente referência. Ele demonstra o uso do decorator `@tool` (frequentemente vindo de `langchain_core.tools` ou uma utilidade similar fornecida pelo PraisonAI). + +```python +# Adaptado de examples/python/general/example_custom_tools.py +from langchain_core.tools import tool # Ou um decorator similar do PraisonAI +from pydantic import BaseModel, Field # Para definir o esquema dos argumentos + +# Exemplo 1: Ferramenta Simples +@tool +def get_word_length(word: str) -> int: + """Retorna o comprimento de uma palavra.""" + return len(word) + +# Exemplo 2: Ferramenta com descrição mais elaborada e esquema de entrada Pydantic +class CalculatorInput(BaseModel): + a: int = Field(description="Primeiro número") + b: int = Field(description="Segundo número") + +@tool("calculator_tool", args_schema=CalculatorInput) # Nome explícito e esquema +def calculator(a: int, b: int) -> int: + """Calcula a soma de dois números, 'a' e 'b'.""" + return a + b + +# Como usar essas ferramentas com um agente PraisonAI: +# from praisonaiagents import Agent +# +# meu_agente = Agent( +# role="Assistente Inteligente", +# goal="Resolver tarefas usando ferramentas personalizadas.", +# tools=[get_word_length, calculator] # Adiciona as funções decoradas à lista de ferramentas +# ) +# +# resultado_comprimento = meu_agente.start("Qual o comprimento da palavra 'PraisonAI'?") +# print(f"Resultado (comprimento): {resultado_comprimento}") +# +# resultado_soma = meu_agente.start("Some 15 e 27 usando a calculadora.") +# print(f"Resultado (soma): {resultado_soma}") +``` + +**Pontos Cruciais na Criação de Ferramentas Personalizadas:** + +1. **Decorator `@tool`:** + * Este decorator (ou um similar como `@structured_tool` ou utilitários do PraisonAI) é o que registra a função como uma ferramenta utilizável pelo sistema de agentes. + * Ele pode aceitar argumentos, como um nome explícito para a ferramenta ou um `args_schema` para definir a estrutura dos argumentos de entrada de forma mais robusta (usando Pydantic). + +2. **Docstring (Descrição da Ferramenta):** + * **ESSENCIAL!** A docstring da sua função (a string entre aspas triplas ```"..." ``` logo após a definição da função) é usada pelo LLM para entender o que a ferramenta faz. + * Seja claro, conciso e preciso. Explique o propósito, os parâmetros esperados (mesmo que tipados, a descrição ajuda) e o que a ferramenta retorna. + +3. **Type Hints (Anotações de Tipo):** + * Use anotações de tipo do Python (ex: `word: str`, `-> int`). Elas ajudam o LLM (e o Pydantic, se usado) a entender os tipos de dados esperados e retornados, o que é crucial para o "function calling". + +4. **Schema de Argumentos (Pydantic - Opcional, mas Recomendado para Complexidade):** + * Para ferramentas com múltiplos argumentos ou argumentos com descrições específicas, usar um modelo Pydantic (`BaseModel`) para definir o `args_schema` é uma excelente prática. Isso fornece uma estrutura clara e validável para os inputs da ferramenta. + +## O Mecanismo de "Function Calling" / "Tool Using" + +Quando um LLM (como os modelos mais recentes da OpenAI, Gemini, etc.) é informado sobre as ferramentas disponíveis (seus nomes, descrições e esquemas de argumentos), ele pode, durante uma conversa ou ao processar uma tarefa, decidir que precisa de uma ferramenta. Se isso acontecer, o LLM não executa a ferramenta diretamente. Em vez disso, ele: + +1. **Gera uma Solicitação de Chamada de Ferramenta:** O LLM produz uma saída estruturada (geralmente JSON) indicando o nome da ferramenta que ele quer chamar e os valores dos argumentos que ele inferiu do contexto da conversa/tarefa. +2. **Execução pelo Framework:** O framework (PraisonAI, LangChain) intercepta essa solicitação. +3. Ele então chama a função Python real correspondente à ferramenta, passando os argumentos fornecidos pelo LLM. +4. **Resultado da Ferramenta:** A função Python executa sua lógica e retorna um resultado. +5. **Retorno ao LLM:** O framework envia este resultado de volta para o LLM. +6. **Resposta Final:** O LLM agora usa o resultado da ferramenta (junto com o histórico da conversa e o prompt original) para formular sua resposta final ao usuário ou para decidir a próxima ação. + +Este ciclo permite que os LLMs "usem" ferramentas de forma segura e estruturada, sem realmente executar código arbitrário por si mesmos. + +## Ferramentas e o PraisonAI + +O PraisonAI facilita esse processo, seja usando suas ferramentas embutidas ou permitindo a integração suave de ferramentas personalizadas. Ao definir agentes, você simplesmente os equipa com as ferramentas necessárias, e o PraisonAI, em conjunto com o LLM, gerencia a lógica de quando e como essas ferramentas são chamadas. + +A capacidade de estender agentes com ferramentas customizadas é o que permite adaptar o PraisonAI a praticamente qualquer domínio ou caso de uso específico, tornando-o uma plataforma verdadeiramente versátil para a construção de aplicações de IA. diff --git a/docs/06_modelos_llm/00_usando_diferentes_llms.md b/docs/06_modelos_llm/00_usando_diferentes_llms.md new file mode 100644 index 000000000..a940c3e4c --- /dev/null +++ b/docs/06_modelos_llm/00_usando_diferentes_llms.md @@ -0,0 +1,157 @@ +# TODO: Translate this file to English + +# Módulo: Modelos de LLM no PraisonAI + +Um dos pontos fortes do PraisonAI é sua flexibilidade em relação aos Modelos de Linguagem Grande (LLMs). Ele não está restrito a um único provedor e é projetado para suportar uma variedade de LLMs, incluindo modelos da OpenAI, modelos locais via Ollama, inferência rápida com Groq, modelos do Google Gemini, e muitos outros (PraisonAI menciona "100+ LLM Support"). + +Esta flexibilidade permite que você escolha o LLM que melhor se adapta às suas necessidades em termos de custo, performance, capacidades específicas, ou requisitos de privacidade (no caso de modelos locais). + +## Configuração Geral de LLMs + +A forma como você configura um LLM no PraisonAI geralmente envolve duas etapas: + +1. **Configuração do Provedor (Variáveis de Ambiente):** + Muitos provedores de LLM exigem chaves de API e, às vezes, URLs base específicas. Estas são comumente configuradas através de variáveis de ambiente. + +2. **Especificação no Agente:** + Ao definir um [Agente](./../02_conceitos_fundamentais/01_agentes.md), você pode especificar qual modelo ou provedor ele deve usar. Se não especificado, o PraisonAI pode usar um padrão (frequentemente um modelo OpenAI como GPT-3.5 Turbo). + +## Configurando Provedores Comuns + +Vamos ver como configurar alguns dos provedores de LLM mais populares para uso com o PraisonAI: + +### 1. OpenAI (GPT-3.5, GPT-4, etc.) + +* **Variável de Ambiente Principal:** + ```bash + export OPENAI_API_KEY="sua_chave_api_da_openai_aqui" + ``` + (No Windows, use `set` ou `setx` ou a interface gráfica, conforme detalhado no [Guia de Instalação](./../01_instalacao/00_instalacao_windows.md)). +* **Uso:** Esta é geralmente a configuração padrão ou mais direta no PraisonAI. + +### 2. Ollama (Modelos Locais como Llama, Mistral, etc.) + +Ollama permite que você execute LLMs de código aberto localmente na sua máquina. O PraisonAI pode interagir com o servidor Ollama através de uma API compatível com a API da OpenAI. + +* **Pré-requisito:** Ter o Ollama instalado e rodando. (Veja [ollama.com](https://ollama.com/)). Certifique-se de ter baixado os modelos que deseja usar (ex: `ollama pull llama3`). +* **Variáveis de Ambiente:** + ```bash + # URL onde seu servidor Ollama está escutando (padrão) + export OPENAI_BASE_URL="http://localhost:11434/v1" + + # A API do Ollama pode ou não exigir uma chave, mas é comum manter o padrão da API OpenAI. + # Você pode usar um valor fictício se o modelo específico não exigir autenticação. + export OPENAI_API_KEY="ollama" # ou "EMPTY", ou sua chave real se configurou uma no Ollama + + # (Opcional, mas recomendado) Especifique o nome do modelo que o Ollama deve usar por padrão, + # se não for especificado no agente. + # export OPENAI_MODEL_NAME="llama3:latest" + ``` +* **Especificação do Modelo no Agente:** Ao definir um agente, você precisará informar o nome do modelo Ollama que deseja usar (ex: `llama3:latest`, `mistral:latest`). + +### 3. Groq (Inferência Rápida) + +Groq fornece inferência de LLM em alta velocidade usando seus LPUs (Language Processing Units). + +* **Pré-requisito:** Ter uma chave de API do Groq (veja [groq.com](https://groq.com/)). +* **Variáveis de Ambiente:** + ```bash + # URL da API do Groq (compatível com OpenAI) + export OPENAI_BASE_URL="https://api.groq.com/openai/v1" + + # Sua chave de API específica do Groq + export OPENAI_API_KEY="sua_chave_api_do_groq_aqui" + ``` +* **Especificação do Modelo no Agente:** Você usará os nomes dos modelos disponíveis no Groq (ex: `llama3-8b-8192`, `mixtral-8x7b-32768`). + +### 4. Google Gemini + +* **Pré-requisito:** Ter uma chave de API do Google AI Studio ou configurado para usar Gemini via Vertex AI no Google Cloud. +* **Variáveis de Ambiente:** A configuração exata pode variar (ex: `GOOGLE_API_KEY`). O PraisonAI pode ter um manipulador específico para Gemini. +* **Recomendação:** Consulte a documentação oficial do PraisonAI ou exemplos específicos sobre como integrar modelos Gemini, pois pode haver um fluxo de configuração um pouco diferente do padrão `OPENAI_*`. + +### 5. Outros Modelos (Anthropic Claude, Cohere, etc.) + +PraisonAI visa suportar uma ampla gama de modelos. A configuração para cada um pode envolver: +* Variáveis de ambiente específicas (ex: `ANTHROPIC_API_KEY`). +* Uso de URLs base específicas se eles expõem uma API compatível com OpenAI. +* Manipuladores (handlers) ou clientes específicos dentro do PraisonAI para esses modelos. + +> [!IMPORTANT] +> A lista de modelos suportados e seus métodos de configuração exatos podem evoluir. **Sempre consulte a documentação oficial do PraisonAI (`https://docs.praison.ai/models`) para as informações mais atualizadas.** + +## Especificando o Modelo no Agente + +Uma vez que o provedor está configurado através das variáveis de ambiente, você pode (e muitas vezes deve) especificar qual modelo exato um agente deve usar. + +* **Em YAML:** + Dentro da definição de um `role` (agente), você pode adicionar uma seção `llm` ou `model`: + ```yaml + roles: + escritor_rapido: + role: "Escritor Rápido" + goal: "Gerar texto rapidamente para tarefas simples." + # Exemplo para Groq + llm: + provider: groq # Ou openai, ollama, etc. (o nome do provider pode variar) + model: "llama3-8b-8192" + # temperature: 0.6 # Outros parâmetros do LLM + # Exemplo para Ollama (o nome do modelo geralmente inclui o registry/tag) + # llm: + # model: "ollama/llama3:latest" # A sintaxe exata pode variar + # Ou mais simples se OPENAI_BASE_URL e OPENAI_MODEL_NAME estiverem configurados para Ollama: + # llm: + # model: "llama3:latest" # Se o provider é inferido como OpenAI-compatible + # ... + analista_profundo: + role: "Analista Detalhista" + goal: "Realizar análises complexas e profundas." + llm: + provider: openai + model: "gpt-4-turbo-preview" + temperature: 0.3 + # ... + ``` + *A estrutura exata da seção `llm` (ex: `provider`, `model`) pode depender da versão do PraisonAI e do framework subjacente (`praisonai`, `crewai`, `autogen`). Verifique os exemplos YAML no repositório.* + +* **Em Python:** + Ao instanciar um `Agent`, você pode passar um objeto de configuração do LLM ou o nome do modelo. + ```python + from praisonaiagents import Agent + # Supondo que existam classes ou formas de configurar LLMs específicos + # from praisonai.llms import Ollama # Exemplo conceitual + + # Exemplo para OpenAI (muitas vezes o padrão, mas pode ser explícito) + # agente_openai = Agent( + # role="Assistente GPT", + # goal="Usar GPT-4.", + # llm={"model": "gpt-4"} # A forma de passar pode variar + # ) + + # Exemplo para Ollama (conceitual) + # llm_ollama_config = Ollama(model="llama3:latest", base_url="http://localhost:11434") + # agente_ollama = Agent( + # role="Assistente Llama Local", + # goal="Usar Llama 3 localmente via Ollama.", + # llm=llm_ollama_config # Passando o objeto LLM configurado + # ) + + # Outra forma comum, se o PraisonAI usa uma API compatível com OpenAI para Ollama/Groq: + # (Com OPENAI_BASE_URL e OPENAI_API_KEY configurados para Ollama) + agente_ollama_openai_api = Agent( + role="Assistente Local (API OpenAI)", + goal="Usar modelo Ollama através da API compatível.", + llm={"model": "llama3:latest"} # O nome do modelo Ollama + # PraisonAI usaria OPENAI_BASE_URL para direcionar para Ollama + ) + ``` + *A API Python para configurar LLMs específicos pode ser bastante rica. Consulte os exemplos em `examples/python/models/` e a documentação da API `praisonaiagents`.* + +## Considerações + +* **Compatibilidade de Recursos:** Nem todos os LLMs suportam todos os recursos da mesma forma (ex: "function calling"/"tool using", multimodalidade, tamanho da janela de contexto). Escolha o modelo também com base nos recursos que seus agentes precisam. +* **Custos:** Esteja ciente dos custos associados a cada provedor de LLM. Modelos mais poderosos geralmente são mais caros. +* **Desempenho (Latência e Qualidade):** Diferentes modelos têm diferentes características de latência e qualidade de resposta. Teste para encontrar o equilíbrio certo para sua aplicação. +* **Nomes dos Modelos:** Os nomes exatos dos modelos (`gpt-3.5-turbo`, `llama3:latest`, `mixtral-8x7b-32768`, etc.) devem corresponder ao que o provedor espera. + +A capacidade do PraisonAI de se integrar com uma ampla gama de LLMs é uma vantagem significativa, permitindo que você adapte seus agentes às melhores ferramentas de linguagem disponíveis para cada tarefa. diff --git a/docs/07_exemplos_praticos/01_exemplo_analise_de_acoes.md b/docs/07_exemplos_praticos/01_exemplo_analise_de_acoes.md new file mode 100644 index 000000000..909f7ef93 --- /dev/null +++ b/docs/07_exemplos_praticos/01_exemplo_analise_de_acoes.md @@ -0,0 +1,146 @@ +# TODO: Translate this file to English + +# Exemplo Prático: Análise de Ações com Agentes YAML + +Este exemplo prático illustra como você poderia configurar um sistema multi-agente usando PraisonAI e YAML para realizar uma análise básica de uma ação da bolsa de valores. + +**Nota:** O arquivo `examples/cookbooks/yaml/stock_analysis_agents.ipynb` no repositório PraisonAI provavelmente contém uma implementação funcional deste caso de uso. Como não podemos processar o conteúdo de notebooks diretamente aqui, vamos construir um exemplo YAML conceitual que demonstre a abordagem. Recomendamos fortemente que você explore o notebook original para ver a implementação real e o código Python que o acompanha. + +## Problema a Ser Resolvido + +Imagine que você quer automatizar o processo de obter uma visão geral sobre uma determinada ação. Isso poderia envolver: +1. Coletar notícias recentes sobre a empresa. +2. Analisar o sentimento geral dessas notícias. +3. Obter dados financeiros básicos (ex: preço atual, alta/baixa do ano). +4. Gerar um breve resumo com uma recomendação especulativa (comprar, manter, vender), com todos os devidos avisos de que não se trata de aconselhamento financeiro. + +## Agentes Envolvidos (Conceitual) + +Para resolver este problema, poderíamos definir os seguintes agentes (roles): + +1. **`pesquisador_noticias_financeiras`**: + * **Objetivo:** Encontrar as notícias mais recentes e relevantes sobre uma empresa específica. + * **Ferramentas:** Uma ferramenta de busca na web (ex: `tavily_search` ou similar). + +2. **`analista_sentimento_noticias`**: + * **Objetivo:** Analisar um conjunto de notícias e determinar o sentimento geral (positivo, negativo, neutro). + * **Instruções:** Focado em PNL para análise de sentimento. + +3. **`coletor_dados_mercado`**: + * **Objetivo:** Obter dados de mercado atuais para a ação (preço, volume, etc.). + * **Ferramentas:** Uma ferramenta que se conecta a uma API de dados financeiros (ex: Alpha Vantage, Yahoo Finance API - pode ser uma ferramenta customizada). + +4. **`analista_chefe_investimentos`**: + * **Objetivo:** Consolidar todas as informações (notícias, sentimento, dados de mercado) e produzir um resumo final com uma perspectiva (não um conselho financeiro). + * **Instruções:** Enfatizar a natureza especulativa e a necessidade de consultar um profissional. + +## Exemplo de Configuração YAML (`analise_acao.yaml` - Conceitual) + +```yaml +framework: praisonai # Ou crewai, dependendo da preferência de estrutura +topic: "Análise da Ação XYZ" # Pode ser parametrizado ao rodar o `praisonai` CLI + +variables: + nome_empresa: "Nome da Empresa XYZ" + ticker_acao: "XYZ" + +roles: + pesquisador_noticias_financeiras: + role: "Pesquisador de Notícias Financeiras" + goal: "Coletar as 5 notícias mais recentes e relevantes sobre a {nome_empresa} ({ticker_acao})." + backstory: "Você é um especialista em encontrar informações financeiras atualizadas na web." + tools: + - "tavily_search" # Ou outra ferramenta de busca configurada + tasks: + buscar_noticias_recentes: + description: "Use a ferramenta de busca para encontrar as 5 notícias mais importantes sobre a empresa {nome_empresa} ({ticker_acao}) publicadas na última semana. Forneça o título e um breve resumo de cada notícia." + expected_output: "Uma lista contendo 5 itens, cada um com 'titulo' e 'resumo_noticia'." + + analista_sentimento_noticias: + role: "Analista de Sentimento de Notícias" + goal: "Analisar o sentimento geral expresso nas notícias coletadas sobre a {nome_empresa}." + backstory: "Você é um LLM treinado para identificar nuances de sentimento em textos financeiros." + # Este agente não precisa de ferramentas externas, apenas processa o texto. + tasks: + analisar_sentimento_coletado: + description: "Com base na lista de notícias fornecida (títulos e resumos), determine o sentimento geral (Positivo, Negativo ou Neutro) sobre a {nome_empresa}. Justifique brevemente sua análise." + expected_output: "Uma declaração de sentimento (Positivo, Negativo ou Neutro) e uma justificativa de 1-2 frases." + context_tasks: + - buscar_noticias_recentes # Depende da saída do pesquisador + + coletor_dados_mercado: + role: "Coletor de Dados de Mercado" + goal: "Obter os dados de mercado mais recentes para a ação {ticker_acao}." + backstory: "Você se conecta a APIs financeiras para buscar cotações e dados de ações em tempo real." + tools: + - "api_dados_financeiros" # Ferramenta customizada ou embutida que busca dados de uma API + tasks: + buscar_dados_acao: + description: "Use a ferramenta 'api_dados_financeiros' para obter o preço atual, a variação diária (%), o volume negociado, a máxima e mínima das últimas 52 semanas para a ação {ticker_acao}." + expected_output: "Um resumo estruturado contendo: preco_atual, variacao_diaria_percentual, volume, maxima_52s, minima_52s." + + analista_chefe_investimentos: + role: "Analista Chefe de Investimentos (Simulado)" + goal: "Consolidar todas as informações coletadas (notícias, sentimento, dados de mercado) e fornecer um breve panorama e uma perspectiva especulativa sobre a ação {ticker_acao}." + backstory: "Você é um analista experiente que combina diferentes fontes de informação para formar uma visão geral, sempre com uma postura cautelosa e ética." + # Este agente pode precisar de uma ferramenta de cálculo básica, se for fazer projeções simples. + tasks: + compilar_relatorio_acao: + description: | + Com base nas seguintes informações: + 1. Resumos das notícias recentes. + 2. Análise de sentimento das notícias. + 3. Dados de mercado atuais da ação {ticker_acao}. + Elabore um relatório conciso (máximo 300 palavras) que inclua: + - Um breve resumo das notícias e do sentimento. + - Destaque dos principais dados de mercado. + - Uma perspectiva especulativa (ex: 'parece promissor para observação', 'momento de cautela', 'potencial de volatilidade'). + Inclua um AVISO LEGAL claro de que este relatório não constitui aconselhamento financeiro e que decisões de investimento devem ser tomadas com um profissional qualificado. + expected_output: "Um relatório textual de no máximo 300 palavras contendo o panorama da ação {ticker_acao} e o aviso legal." + context_tasks: + - analisar_sentimento_coletado + - buscar_dados_acao + +process: sequential # As tarefas e dependências definem a sequência +# Ou poderia ser hierárquico com o 'analista_chefe_investimentos' como manager. +``` + +## Como Executar (Teórico) + +1. Salve o conteúdo acima como `analise_acao.yaml`. +2. Configure as ferramentas necessárias (ex: `tavily_search` e uma `api_dados_financeiros` que pode ser uma ferramenta customizada que você precisaria criar e registrar no PraisonAI se não for embutida). +3. Execute via CLI: + ```bash + praisonai analise_acao.yaml + ``` + Você também pode passar variáveis via CLI se o PraisonAI suportar overrides para a seção `variables` do YAML, por exemplo: + ```bash + praisonai analise_acao.yaml --vars "nome_empresa='Outra Empresa SA';ticker_acao='OTR4'" + ``` + (A sintaxe exata para override de variáveis dependeria da implementação da CLI do PraisonAI). + +## Resultado Esperado (Conceitual) + +O `analista_chefe_investimentos` produziria um relatório final, algo como: + +> **Panorama da Ação XYZ ({ticker_acao})** +> +> As notícias recentes sobre a Nome da Empresa XYZ indicam um sentimento geralmente [Positivo/Negativo/Neutro], com destaque para [mencionar brevemente um ponto chave das notícias]. Por exemplo, [resumo de uma notícia relevante]. +> +> Atualmente, a ação {ticker_acao} está cotada a [preco_atual], com uma variação diária de [variacao_diaria_percentual]% e volume de [volume]. A máxima das últimas 52 semanas foi de [maxima_52s] e a mínima de [minima_52s]. +> +> **Perspectiva Especulativa:** +> Com base nas informações atuais, o cenário para {ticker_acao} sugere [perspectiva, ex: 'um potencial interessante para acompanhamento devido ao sentimento positivo das notícias, mas a volatilidade do mercado exige cautela.']. +> +> **AVISO LEGAL:** Este relatório é gerado por um sistema de IA para fins ilustrativos e educacionais, baseado em informações publicamente disponíveis e não constitui aconselhamento financeiro. Qualquer decisão de investimento deve ser tomada após consulta a um profissional financeiro qualificado e análise individual. Não nos responsabilizamos por quaisquer perdas ou ganhos decorrentes do uso desta informação. + +## Fundamentos PraisonAI Aplicados + +* **Múltiplos Agentes (`roles`):** Cada agente com sua especialização, `goal`, `backstory` e `tools`. +* **Tarefas (`tasks`):** Descrições claras do que cada agente deve fazer e o `expected_output`. +* **Contexto entre Tarefas (`context_tasks`):** A saída de uma tarefa alimenta a próxima, criando um fluxo de trabalho. +* **Ferramentas (`tools`):** Uso de ferramentas para interagir com o mundo externo (busca na web, APIs financeiras). +* **Configuração YAML:** Definição declarativa de todo o sistema de agentes. +* **Processo Sequencial:** As dependências entre tarefas guiam a ordem de execução. + +Este exemplo, mesmo conceitual, demonstra o poder do PraisonAI para orquestrar múltiplos agentes na resolução de um problema do mundo real. Ao explorar o notebook `stock_analysis_agents.ipynb` original, você poderá ver como esses conceitos são traduzidos em código e configurações YAML reais. diff --git a/docs/07_exemplos_praticos/02_exemplo_geracao_artigos.md b/docs/07_exemplos_praticos/02_exemplo_geracao_artigos.md new file mode 100644 index 000000000..a80df8435 --- /dev/null +++ b/docs/07_exemplos_praticos/02_exemplo_geracao_artigos.md @@ -0,0 +1,128 @@ +# TODO: Translate this file to English + +# Exemplo Prático: Geração de Artigos com Agentes YAML + +Este exemplo demonstra como o PraisonAI pode ser usado para automatizar o processo de criação de um artigo, desde a pesquisa inicial e esboço até a redação final e revisão. Utilizaremos uma abordagem baseada em YAML para definir os agentes e suas tarefas. + +**Nota:** O arquivo `examples/cookbooks/yaml/article_generation_agents.ipynb` no repositório PraisonAI provavelmente contém uma implementação funcional deste caso de uso. Este exemplo é uma representação conceitual. Explore o notebook original para a implementação detalhada. + +## Problema a Ser Resolvido + +Criar um artigo informativo e bem estruturado sobre um tópico específico. O processo envolve: +1. Pesquisar informações relevantes sobre o tópico. +2. Criar um esboço (outline) para o artigo. +3. Escrever o conteúdo do artigo com base no esboço e na pesquisa. +4. Revisar o artigo para clareza, gramática e estilo. + +## Agentes Envolvidos (Conceitual) + +1. **`pesquisador_topicos`**: + * **Objetivo:** Coletar informações e fatos chave sobre o tópico do artigo. + * **Ferramentas:** Ferramenta de busca na web. + +2. **`arquiteto_conteudo`**: + * **Objetivo:** Criar um esboço detalhado e lógico para o artigo, com base na pesquisa. + * **Instruções:** Focado em estruturação de conteúdo. + +3. **`redator_artigos`**: + * **Objetivo:** Escrever o conteúdo completo do artigo, seguindo o esboço e utilizando as informações pesquisadas. + * **Instruções:** Focado em escrita fluida e engajante. + +4. **`revisor_critico`**: + * **Objetivo:** Revisar o artigo escrito, verificando erros, melhorando a clareza e garantindo que o objetivo foi atingido. + * **Instruções:** Focado em análise crítica e sugestões de melhoria. + +## Exemplo de Configuração YAML (`geracao_artigo.yaml` - Conceitual) + +```yaml +framework: praisonai # Ou crewai +topic: "O Impacto da Inteligência Artificial na Educação Superior" + +variables: + titulo_artigo_alvo: "IA na Educação Superior: Uma Revolução no Aprendizado" + publico_alvo: "Educadores, administradores acadêmicos e estudantes universitários" + numero_palavras_alvo: 1200 + +roles: + pesquisador_topicos: + role: "Pesquisador Especialista" + goal: "Coletar informações abrangentes e atuais sobre '{topic}'." + backstory: "Você é um pesquisador meticuloso, capaz de encontrar dados relevantes, estudos de caso e opiniões de especialistas." + tools: + - "tavily_search" + tasks: + pesquisar_informacoes_artigo: + description: "Realize uma pesquisa completa sobre '{topic}'. Colete dados sobre aplicações atuais, benefícios, desafios, e o futuro da IA neste contexto. Priorize fontes acadêmicas e reportagens de tecnologia confiáveis dos últimos 2 anos." + expected_output: "Um documento compilado com os principais pontos de informação, links para fontes, e citações relevantes, organizado por subtemas." + + arquiteto_conteudo: + role: "Arquiteto de Conteúdo" + goal: "Criar um esboço (outline) lógico e detalhado para um artigo sobre '{topic}' com o título '{titulo_artigo_alvo}'." + backstory: "Você é especialista em estruturar informações complexas de forma clara e sequencial para artigos e relatórios." + tasks: + criar_esboco_artigo: + description: "Com base no material de pesquisa fornecido sobre '{topic}', crie um esboço detalhado para um artigo intitulado '{titulo_artigo_alvo}'. O esboço deve incluir: Introdução (com gancho e tese), seções principais (com 3-5 pontos chave cada), subseções se necessário, e Conclusão (com resumo e chamada para ação ou reflexão). O artigo deve ser direcionado para {publico_alvo} e ter aproximadamente {numero_palavras_alvo} palavras." + expected_output: "Um esboço hierárquico completo do artigo, formatado em markdown, pronto para ser usado pelo redator." + context_tasks: + - pesquisar_informacoes_artigo + + redator_artigos: + role: "Redator de Artigos Experiente" + goal: "Escrever um artigo envolvente e informativo sobre '{topic}', seguindo o esboço e usando a pesquisa fornecida." + backstory: "Você transforma esboços e dados de pesquisa em artigos bem escritos, com linguagem clara e adaptada ao público-alvo." + tasks: + escrever_conteudo_artigo: + description: "Utilizando o esboço detalhado e o material de pesquisa sobre '{topic}', escreva o conteúdo completo do artigo '{titulo_artigo_alvo}'. Siga a estrutura do esboço, desenvolva cada ponto com as informações pesquisadas, e mantenha um tom apropriado para {publico_alvo}. O artigo deve ter aproximadamente {numero_palavras_alvo} palavras." + expected_output: "O texto completo do artigo, formatado em markdown." + context_tasks: + - criar_esboco_artigo # Depende do esboço + # Implicitamente também depende de 'pesquisar_informacoes_artigo' via 'criar_esboco_artigo' + + revisor_critico: + role: "Revisor e Editor Crítico" + goal: "Revisar o artigo '{titulo_artigo_alvo}' para garantir alta qualidade, clareza, precisão e coesão, sugerindo melhorias." + backstory: "Você tem um olhar apurado para detalhes, gramática, estilo e lógica argumentativa. Seu objetivo é elevar a qualidade do texto." + tasks: + revisar_artigo_final: + description: | + Revise o artigo fornecido sobre '{topic}' com o título '{titulo_artigo_alvo}'. + Verifique os seguintes aspectos: + 1. Clareza e fluidez do texto. + 2. Correção gramatical e ortográfica. + 3. Coesão e coerência entre as seções. + 4. Se o artigo atinge o objetivo proposto no esboço e se é adequado para o {publico_alvo}. + 5. Se a contagem de palavras está próxima de {numero_palavras_alvo}. + Forneça feedback construtivo detalhado E, se possível, o texto com as correções diretas ou sugestões de reescrita incorporadas. + expected_output: "Um relatório de revisão com feedback detalhado e/ou o texto do artigo com as revisões sugeridas/aplicadas." + context_tasks: + - escrever_conteudo_artigo + +process: sequential +# As dependências (context_tasks) garantem a ordem correta das operações. +``` + +## Como Executar (Teórico) + +1. Salve o conteúdo como `geracao_artigo.yaml`. +2. Certifique-se de que a ferramenta `tavily_search` (ou a que você escolheu) está configurada. +3. Execute via CLI: + ```bash + praisonai geracao_artigo.yaml + ``` + Você pode alterar o `topic` e outras `variables` diretamente no arquivo YAML ou investigar se a sua versão do PraisonAI CLI permite a substituição de variáveis via linha de comando. + +## Resultado Esperado (Conceitual) + +O `revisor_critico` (ou o `redator_artigos` se o revisor apenas fornecer feedback para uma nova iteração do redator) produziria o texto final do artigo, revisado e pronto para publicação, ou um relatório de revisão. + +Por exemplo, a saída da tarefa `escrever_conteudo_artigo` seria o rascunho do artigo. A saída da tarefa `revisar_artigo_final` seria o artigo já com as melhorias ou com comentários para o redator aplicar. + +## Fundamentos PraisonAI Aplicados + +* **Divisão de Trabalho:** Múltiplos agentes, cada um focado em uma etapa do processo de criação do artigo. +* **Workflow Sequencial:** O processo segue uma lógica clara: pesquisa -> esboço -> redação -> revisão. +* **Passagem de Contexto:** A informação gerada por um agente (pesquisa, esboço) é usada como entrada essencial para o próximo. +* **Instruções Detalhadas (`description` e `expected_output`):** Guiam cada agente a produzir o resultado necessário para a etapa seguinte. +* **Variáveis:** Permitem parametrizar o processo para diferentes tópicos ou requisitos de artigo. + +Este exemplo illustra como um processo criativo, como a escrita de um artigo, pode ser decomposto e automatizado com a colaboração de múltiplos agentes especializados no PraisonAI. A qualidade do resultado final dependerá significativamente da clareza dos `goals`, `instructions` e `expected_output` de cada agente e tarefa. diff --git a/docs/07_exemplos_praticos/03_exemplo_analise_geracao_codigo.md b/docs/07_exemplos_praticos/03_exemplo_analise_geracao_codigo.md new file mode 100644 index 000000000..e7107191d --- /dev/null +++ b/docs/07_exemplos_praticos/03_exemplo_analise_geracao_codigo.md @@ -0,0 +1,154 @@ +# TODO: Translate this file to English + +# Exemplo Prático: Análise e Geração Simples de Código com Agentes YAML + +Este exemplo prático demonstra como o PraisonAI pode ser configurado para auxiliar em tarefas relacionadas a código, como explicar um trecho de código existente ou gerar um script simples com base em uma descrição. + +**Nota:** Os exemplos `examples/cookbooks/Code_Analysis_Agent.ipynb` e `examples/cookbooks/yaml/cli_operation_agents.ipynb` no repositório PraisonAI podem conter implementações funcionais e mais detalhadas. Este é um exemplo conceitual para ilustrar a abordagem com YAML. + +## Problema a Ser Resolvido + +Queremos um sistema de agentes que possa: +1. **Explicar um trecho de código:** Dado um código em uma linguagem específica, o agente deve explicar sua funcionalidade, lógica e possíveis usos. +2. **Gerar um script simples:** Dada uma descrição de uma tarefa (ex: "criar um script Python que lista arquivos em um diretório"), o agente deve gerar o código correspondente. + +## Agentes Envolvidos (Conceitual) + +1. **`analista_codigo_fonte`**: + * **Objetivo:** Analisar e explicar trechos de código em várias linguagens. + * **Instruções:** Focado em PNL para "entender" código e descrevê-lo em linguagem natural. + * **Ferramentas:** Poderia opcionalmente usar uma ferramenta de "code interpreter" para testar o código, mas para explicação, o LLM pode ser suficiente. + +2. **`gerador_scripts_python`**: + * **Objetivo:** Gerar scripts Python funcionais com base em descrições de tarefas. + * **Instruções:** Focado em traduzir requisitos em linguagem natural para código Python. + * **Ferramentas:** Opcionalmente, um "code interpreter" para testar o script gerado. + +## Exemplo de Configuração YAML (`codigo_agentes.yaml` - Conceitual) + +```yaml +framework: praisonai +topic: "Análise e Geração de Código Python" + +variables: + linguagem_padrao: "Python" + diretorio_alvo_exemplo: "./minha_pasta" + +roles: + analista_codigo_fonte: + role: "Engenheiro de Software Explicador" + goal: "Analisar e fornecer explicações claras e concisas sobre trechos de código na {linguagem_padrao} ou outra linguagem especificada." + backstory: "Você é um desenvolvedor sênior com vasta experiência em múltiplas linguagens e uma habilidade especial para explicar código complexo de forma simples." + # tools: + # - "code_interpreter" # Opcional, para testes + tasks: + explicar_trecho_codigo: + # Este é um exemplo de tarefa que seria chamada com um input específico. + # O input (o código a ser explicado) viria da execução do 'praisonai' CLI + # ou de outro agente que passa o contexto. + description: "Analise o seguinte trecho de código em {linguagem_padrao} e explique: +1. Qual o seu propósito principal? +2. Como ele funciona (lógica passo a passo)? +3. Em que tipo de situação ele seria útil? + +Código a ser analisado: +```python +{codigo_para_analisar} +```" + expected_output: "Uma explicação textual clara, dividida em propósito, funcionamento e utilidade do código fornecido." + # 'codigo_para_analisar' seria uma variável de input da tarefa. + + gerador_scripts_python: + role: "Desenvolvedor Python Automatizado" + goal: "Gerar scripts Python funcionais e bem documentados com base em descrições de requisitos." + backstory: "Você é um especialista em Python capaz de traduzir rapidamente especificações em scripts eficientes." + # tools: + # - "code_interpreter" # Para testar o script gerado + # - "file_write_tool" # Para salvar o script em um arquivo + tasks: + gerar_script_listar_arquivos: + # Exemplo de tarefa específica. + description: "Crie um script Python que lista todos os arquivos e subdiretórios dentro de um diretório especificado ('{diretorio_alvo_exemplo}' por padrão, mas pode ser sobrescrito). O script deve imprimir os nomes no console." + expected_output: "O código completo do script Python solicitado, pronto para ser executado." + # Poderia ter uma tarefa subsequente para salvar e testar o script. + + gerar_script_customizado: + # Tarefa mais genérica que espera uma descrição do script. + description: "Com base na seguinte solicitação, gere um script Python: '{descricao_script_customizado}'" + expected_output: "O código completo do script Python solicitado." + # 'descricao_script_customizado' seria uma variável de input. + +# Você poderia definir um processo sequencial ou hierárquico se as tarefas +# de análise e geração fossem encadeadas ou gerenciadas. +# Para este exemplo, cada agente pode ser invocado para sua tarefa específica. +``` + +## Como Executar (Teórico) + +A execução dependeria de como você passa os inputs específicos (como `codigo_para_analisar` ou `descricao_script_customizado`) para as tarefas. + +**Opção 1: Foco em uma Tarefa Específica ao Invocar** + +Se a CLI do PraisonAI permitir invocar uma tarefa específica de um agente e passar contexto/variáveis para ela (isso é comum em sistemas como Airflow, mas pode variar no PraisonAI): + +```bash +# Para explicar um código (hipotético, depende da capacidade da CLI) +# Supondo que você possa passar 'codigo_para_analisar' como uma variável de tarefa +praisonai codigo_agentes.yaml --task explicar_trecho_codigo --vars "codigo_para_analisar='def hello(n): + print(f"Hello {n}")'" + +# Para gerar o script padrão de listar arquivos +praisonai codigo_agentes.yaml --task gerar_script_listar_arquivos + +# Para gerar um script customizado +praisonai codigo_agentes.yaml --task gerar_script_customizado --vars "descricao_script_customizado='Um script que lê um arquivo de texto e conta o número de palavras.'" +``` + +**Opção 2: Modificar o YAML para cada Execução** + +Você poderia ter um placeholder no YAML e substituí-lo antes de cada execução, ou ter diferentes arquivos YAML para diferentes códigos/scripts. + +**Opção 3: Agente "Interface com Usuário"** + +Um agente inicial poderia pegar a entrada do usuário (o código a ser analisado ou a descrição do script) e então passar essa informação como contexto para o `analista_codigo_fonte` ou `gerador_scripts_python`. + +## Resultado Esperado (Conceitual) + +* **Para `explicar_trecho_codigo`**: O agente `analista_codigo_fonte` retornaria um texto explicando o código fornecido. + > Exemplo: "O código fornecido define uma função Python chamada `hello` que recebe um argumento `n`. Seu propósito é imprimir uma saudação personalizada no console, incluindo o valor de `n`. Ele funciona usando uma f-string para formatar a mensagem. Seria útil em situações onde você precisa de uma saudação simples ou para demonstrar a passagem de argumentos para funções." + +* **Para `gerar_script_listar_arquivos`**: O agente `gerador_scripts_python` retornaria um bloco de código Python. + ```python + # Resultado esperado (conceitual): + import os + + def listar_arquivos_e_diretorios(caminho_diretorio="."): + """ + Lista todos os arquivos e subdiretórios dentro do caminho_diretorio especificado. + """ + try: + print(f"Conteúdo do diretório: {os.path.abspath(caminho_diretorio)}") + for item in os.listdir(caminho_diretorio): + print(item) + except FileNotFoundError: + print(f"Erro: Diretório não encontrado - {caminho_diretorio}") + except Exception as e: + print(f"Ocorreu um erro: {e}") + + if __name__ == "__main__": + # Por padrão, lista o diretório alvo do YAML, mas pode ser alterado. + diretorio_alvo = "{diretorio_alvo_exemplo}" # Esta variável seria substituída + # ou o script poderia aceitar um argumento de linha de comando. + # listar_arquivos_e_diretorios(diretorio_alvo) + # Para um exemplo funcional direto: + listar_arquivos_e_diretorios() # Lista o diretório atual + ``` + +## Fundamentos PraisonAI Aplicados + +* **Especialização de Agentes:** Agentes distintos para análise e para geração de código. +* **Instruções Claras (`goal`, `instructions`, `description` da tarefa):** Essenciais para que os LLMs entendam a tarefa relacionada a código. +* **Parametrização (`variables`, inputs de tarefa):** Permite reutilizar os agentes para diferentes códigos ou descrições de script. +* **Potencial Uso de Ferramentas:** Embora não detalhado aqui, ferramentas como `code_interpreter` (para executar e testar código) ou `file_write_tool` (para salvar scripts) seriam adições valiosas para tornar os agentes mais autônomos e úteis. O PraisonAI menciona "Code Interpreter Agents" como um recurso. + +Este exemplo mostra como agentes podem ser aplicados a domínios técnicos como programação. A qualidade da explicação ou do código gerado dependerá muito da capacidade do LLM subjacente e da clareza dos prompts e instruções fornecidas aos agentes. diff --git a/docs/08_contribuindo_e_desenvolvimento/00_contribuindo_e_dev_local.md b/docs/08_contribuindo_e_desenvolvimento/00_contribuindo_e_dev_local.md new file mode 100644 index 000000000..b79891693 --- /dev/null +++ b/docs/08_contribuindo_e_desenvolvimento/00_contribuindo_e_dev_local.md @@ -0,0 +1,176 @@ +# TODO: Translate this file to English + +# Módulo: Contribuindo para o PraisonAI e Desenvolvimento Local + +Este módulo é para você que deseja ir além de usar o PraisonAI e quer contribuir para o seu desenvolvimento, ou simplesmente configurar um ambiente local para explorar o código-fonte mais a fundo e talvez fazer suas próprias modificações. + +## Contribuindo para o PraisonAI + +Contribuições da comunidade são essenciais para o crescimento e aprimoramento de projetos de código aberto como o PraisonAI. Se você tem interesse em contribuir, o processo geralmente segue o fluxo padrão do GitHub: + +1. **Faça um Fork do Repositório:** + * Vá até a página do repositório oficial do PraisonAI no GitHub: [https://github.com/MervinPraison/PraisonAI](https://github.com/MervinPraison/PraisonAI) + * Clique no botão "Fork" no canto superior direito. Isso criará uma cópia do repositório na sua conta do GitHub. + +2. **Clone o Seu Fork Localmente:** + * Em seu terminal, clone o repositório que você acabou de "forkar": + ```bash + git clone https://github.com/SEU_USUARIO_GITHUB/PraisonAI.git + cd PraisonAI + ``` + * Substitua `SEU_USUARIO_GITHUB` pelo seu nome de usuário no GitHub. + +3. **Crie uma Nova Branch para Suas Mudanças:** + * É uma boa prática criar uma nova branch para cada funcionalidade ou correção que você for trabalhar. Isso mantém o histórico organizado e facilita a integração. + ```bash + git checkout -b minha-nova-funcionalidade # Escolha um nome descritivo para a branch + ``` + +4. **Faça Suas Alterações:** + * Implemente a nova funcionalidade, corrija um bug, melhore a documentação, etc. + * Certifique-se de seguir as convenções de código e estilo do projeto, se houver. + +5. **Teste Suas Mudanças:** + * Execute os testes existentes para garantir que suas alterações não quebraram nada. (Veja a seção "Executando Testes" abaixo). + * Se estiver adicionando uma nova funcionalidade, considere adicionar novos testes para cobri-la. + +6. **Faça o Commit das Suas Alterações:** + * Adicione os arquivos modificados e faça o commit com uma mensagem clara e descritiva. + ```bash + git add . + git commit -m "feat: Adiciona nova funcionalidade X que faz Y" + # Ou "fix: Corrige bug Z no componente W" + # Siga as convenções de commit do projeto, se houver (ex: Conventional Commits). + ``` + +7. **Envie Suas Alterações para o Seu Fork no GitHub:** + ```bash + git push origin minha-nova-funcionalidade + ``` + +8. **Abra um Pull Request (PR):** + * Vá até a página do seu fork no GitHub. + * Você verá um aviso para criar um Pull Request da sua nova branch para o repositório original do PraisonAI. + * Clique nele, revise suas alterações, escreva uma descrição clara do que seu PR faz e porquê, e envie-o. + +9. **Aguarde o Feedback:** + * Os mantenedores do projeto revisarão seu Pull Request. Eles podem solicitar alterações, fazer perguntas ou aprovar e mesclar suas contribuições. Seja paciente e responsivo ao feedback. + +**Onde mais procurar por informações sobre contribuição:** +* Verifique se há um arquivo `CONTRIBUTING.md` no repositório principal. +* Observe as issues abertas, especialmente aquelas marcadas como "good first issue" ou "help wanted". +* Participe das discussões da comunidade (links geralmente no `README.md` ou na página do GitHub). + +## Configurando o Ambiente de Desenvolvimento Local + +Se você deseja explorar o código, fazer modificações ou contribuir, precisará de um ambiente de desenvolvimento local. + +1. **Pré-requisitos:** + * Python (versão >=3.10, conforme `pyproject.toml`). + * Git. + * Opcional, mas recomendado: `uv` (um instalador Python rápido). + +2. **Clone o Repositório (se ainda não o fez):** + ```bash + git clone https://github.com/MervinPraison/PraisonAI.git # Ou seu fork + cd PraisonAI/src/praisonai # Navegue para a pasta do pacote principal que contém o pyproject.toml + ``` + *Nota: O `pyproject.toml` principal do projeto parece estar em `src/praisonai/`. Verifique a estrutura exata se tiver problemas.* + +3. **Crie e Ative um Ambiente Virtual (Altamente Recomendado):** + Isso isola as dependências do projeto e evita conflitos com outros projetos Python em seu sistema. + ```bash + # Navegue para a pasta que contém o pyproject.toml (ex: src/praisonai) + python -m venv .venv + # No Windows (CMD): + # .venv\Scripts\activate + # No Windows (PowerShell): + # .venv\Scripts\Activate.ps1 + # No macOS/Linux: + # source .venv/bin/activate + ``` + +4. **Instale `uv` (Recomendado pelo Projeto):** + Se ainda não o tiver e quiser seguir as instruções de desenvolvimento do `README.md`: + ```bash + pip install uv + ``` + +5. **Instale as Dependências do Projeto:** + O `README.md` e o `pyproject.toml` do PraisonAI indicam o uso de `uv` para instalar dependências. + * **Instalação básica em modo editável (para desenvolvimento):** + Isto instalará o pacote `PraisonAI` e suas dependências principais. O modo editável (`-e`) significa que as alterações que você fizer no código-fonte local serão refletidas imediatamente ao usar o pacote. + ```bash + # Certifique-se de estar na pasta com o pyproject.toml (ex: src/praisonai) + uv pip install -e . + ``` + * **Instalando com dependências opcionais (extras):** + O PraisonAI usa "extras" para dependências que habilitam funcionalidades específicas (como `crewai`, `autogen`, `ui`, `code`, etc.). Você pode instalá-los conforme necessário. + ```bash + uv pip install -e .[crewai,autogen] + uv pip install -e .[ui,code] + # Para instalar todos os extras, você pode precisar listá-los ou verificar se há um extra "all". + # O pyproject.toml lista os extras disponíveis. + ``` + O `README.md` também menciona: + ```bash + # uv pip install -r pyproject.toml --extra code + # Esta sintaxe também pode funcionar, mas instalar com -e .[extra] é comum para desenvolvimento local. + ``` + A forma mais idiomática, especialmente com `uv` e Poetry (que o `pyproject.toml` usa), seria instalar os grupos de dependência. O `pyproject.toml` define grupos como `[tool.poetry.group.dev.dependencies]`. + Para instalar dependências de desenvolvimento (que incluem testes, docs, etc.): + ```bash + uv pip install --system # Garante que uv use o Python do ambiente virtual ativo + uv pip install -e .[dev] # Se houver um extra 'dev' que agrupe tudo + # Ou, se usando Poetry diretamente (não uv): + # poetry install --with dev + ``` + Dado que o `README.md` foca em `uv pip install -r pyproject.toml --extra ` ou `uv pip install -e .[]`, siga essa orientação. + +## Executando Testes + +O PraisonAI possui uma estrutura de testes abrangente, conforme detalhado em `src/praisonai/tests/TESTING_GUIDE.md`. É crucial executar testes após fazer alterações para garantir que nada foi quebrado. + +**Principais Pontos do Guia de Testes:** + +* **Estrutura:** + * `tests/unit/`: Testes unitários (rápidos, isolados). + * `tests/integration/`: Testes de integração mockados (gratuitos, rápidos, para CI/CD e desenvolvimento). + * `tests/e2e/`: Testes end-to-end reais (podem ter custos com APIs, mais lentos). +* **Como Rodar (Recomendado pelo `TESTING_GUIDE.md`):** + O projeto fornece um `test_runner.py`. + * **Testes Mock (Gratuitos):** + ```bash + # Todos os testes de integração mockados + python tests/test_runner.py --pattern frameworks + + # Testes mock apenas para AutoGen + python tests/test_runner.py --pattern autogen + + # Testes mock apenas para CrewAI + python tests/test_runner.py --pattern crewai + ``` + * **Testes Reais (Podem ter Custo!):** + Requerem configuração de chaves de API (ex: `OPENAI_API_KEY`). + ```bash + # Todos os testes reais (irá pedir confirmação) + python tests/test_runner.py --pattern real + ``` + (Existem mais padrões para testes reais e de execução completa, consulte o `TESTING_GUIDE.md`). +* **Usando `pytest` Diretamente:** + O `pyproject.toml` lista `pytest` como uma dependência de teste. + * **Testes de Integração Mockados:** + ```bash + # Certifique-se de que as dependências de teste estão instaladas no seu ambiente virtual + # (ex: uv pip install -e .[test] ou poetry install --with test) + python -m pytest src/praisonai/tests/integration/ -v + # Ou pytest src/praisonai/tests/integration/ -v (se pytest está no PATH do venv) + ``` + * **Testes Reais (Requer Chaves de API):** + ```bash + python -m pytest src/praisonai/tests/e2e/ -v -m real + ``` + +**Antes de rodar testes reais, sempre leia o `TESTING_GUIDE.md` para entender os custos potenciais e a configuração necessária.** + +Seguindo estas diretrizes, você estará bem equipado para contribuir com o PraisonAI ou para explorá-lo e adaptá-lo às suas necessidades em um ambiente de desenvolvimento local. diff --git a/docs/08_contribuindo_e_desenvolvimento/01_estrutura_do_codigo.md b/docs/08_contribuindo_e_desenvolvimento/01_estrutura_do_codigo.md new file mode 100644 index 000000000..7cb2a8e24 --- /dev/null +++ b/docs/08_contribuindo_e_desenvolvimento/01_estrutura_do_codigo.md @@ -0,0 +1,21 @@ +# TODO: Translate this file to English + +# Entendendo a Estrutura do Código + +Para contribuir ou personalizar o PraisonAI é importante conhecer a organização do diretório `src/`. + +## Principais Pastas + +- **praisonai/**: pacote Python que oferece a CLI `praisonai` e arquivos de configuração de exemplo (`agents.yaml`, `agents-advanced.yaml`, `config.yaml`). É aqui que está o script `cli.py` com as funções de execução e deploy. +- **praisonai-agents/**: biblioteca central `praisonaiagents` contendo as classes `Agent`, `Task`, memórias e ferramentas nativas. +- **praisonai-ts/**: versão em TypeScript/Node.js do framework, destinada a quem prefere trabalhar em JavaScript. + +Dentro de cada pacote há submódulos como `agent`, `task`, `memory`, `tools` e `llm`. Explore esses arquivos para entender como os agentes são implementados. + +### Arquivos de Configuração + +Na pasta `src/praisonai` você encontra exemplos de YAML prontos (citados no módulo [Configurações com YAML](../03_usando_praisonai/06_configuracoes_yaml.md)). Esses arquivos são ótimos pontos de partida para seus experimentos. + +Além disso, o script `inc/config.py` possui a função `generate_config`, utilizada para criar `config.yaml` com parâmetros de treinamento. + +Conhecer essa estrutura ajuda a localizar facilmente onde adicionar novos agentes, ferramentas ou integrações. diff --git a/docs/09_duvidas_frequentes.md b/docs/09_duvidas_frequentes.md new file mode 100644 index 000000000..2e62c069d --- /dev/null +++ b/docs/09_duvidas_frequentes.md @@ -0,0 +1,47 @@ +# TODO: Translate this file to English + +# Dúvidas Frequentes (FAQ) + +Esta seção reúne respostas rápidas para questões comuns ao começar com o PraisonAI. + +## 1. "ModuleNotFoundError: praisonaiagents" +Se, ao executar um exemplo em Python, você receber essa mensagem: +```bash +ModuleNotFoundError: No module named 'praisonaiagents' +``` +Isso indica que o pacote não está instalado no ambiente atual. Execute: +```bash +pip install praisonaiagents +``` +Se estiver usando um clone do repositório, você também pode instalar em modo editável: +```bash +uv pip install -e . +``` +(caso tenha o `uv` instalado) ou +```bash +pip install -e . +``` + +## 2. Como configuro minha `OPENAI_API_KEY`? +A maioria dos exemplos utiliza modelos da OpenAI. Defina a variável de ambiente com: +```bash +export OPENAI_API_KEY="sua-chave-aqui" # Linux ou macOS +set OPENAI_API_KEY="sua-chave-aqui" # Windows CMD +$env:OPENAI_API_KEY="sua-chave-aqui" # PowerShell +``` + +## 3. Preciso de GPU ou conexão constante com a internet? +Para executar os agentes locais que usam modelos via API (como OpenAI), basta ter conexão com a internet. Uma GPU dedicada só é necessária se você planeja rodar modelos locais pesados (ex.: via Ollama ou outros provedores que permitam modelos offline). + +## 4. Onde ficam os exemplos prontos? +Todos os scripts demonstrativos estão em `examples/python/`. A pasta é subdividida em: +- `agents/` – agentes especializados (veja [Modelos de Agentes](03_usando_praisonai/05_modelos_de_agentes.md)). +- `general/` – conceitos isolados como memória, ferramentas e workflows. +- `concepts/` – implementações de RAG, processamento de CSV etc. +- `usecases/` – estudos de caso completos. + +Abra um terminal nesse diretório e execute o arquivo desejado com `python nome_do_exemplo.py`. + +## 5. Como tiro outras dúvidas ou reporto problemas? +Consulte o repositório no GitHub e abra uma *issue* descrevendo o problema ou a sugestão. Se preferir discutir em português, sinta-se à vontade. + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..02fbb0cf2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,31 @@ +# Welcome to the PraisonAI Course! + +This repository is a **fork** of the original project and is maintained by [Habdel-Edenfield](https://github.com/Habdel-Edenfield). The purpose of this initiative is to create a **learning laboratory** about autonomous agents and share knowledge in an accessible and collaborative way. Habdel's motivation is philanthropic, contributing to the community developing technologies for **Open Tibia Server** and other AI projects. + +Browse the modules on the left to start your learning journey. Each section is organized to guide the study step by step, always highlighting practical concepts and real examples. + +## Course Structure + +* **Introduction:** Overview of PraisonAI and this documentation. +* **Learning Methodology:** Scientific guidelines for effective study. +* **Installation:** How to install PraisonAI in your environment. +* **Fundamental Concepts:** The building blocks of PraisonAI. +* **Using PraisonAI:** Practical guides for Python, YAML and JavaScript/TypeScript. +* **Quick Guide: Creating Your First Agent:** Step by step to get an agent running. +* **Agent Models:** Overview of specialized agents available in the examples. +* **[Configurations with YAML](03_usando_praisonai/06_configuracoes_yaml.md):** How to define agents and tasks declaratively. +* **Advanced Workflows:** Explore the capabilities of multiple agents. + * **Multimodal Agents** + * **Code Interpreter Agents** + * **Math Agents** + * **Structured Output** + * **Callback Agents** + * **Mini AI Agents** +* **Tools:** Using and creating tools. +* **LLM Models:** Integrating with various language models. +* **Practical Examples:** Detailed case studies. +* **Contributing and Development:** For those who want to go further. + * **Understanding the Code Structure** +* **Frequently Asked Questions:** Quick answers to common problems. + +Good luck and happy studying! diff --git a/docs/plan.md b/docs/plan.md new file mode 100644 index 000000000..a478d2c2a --- /dev/null +++ b/docs/plan.md @@ -0,0 +1,53 @@ +# PraisonAI Course Content Plan + +This file summarizes the modules already available in `docs/pt-br` and highlights topics that can still be developed. Use it as a guide to track the progress of the material. + +## Current Content + +1. **Introduction** + - How to use this documentation and recommended plugins for Obsidian. + - What PraisonAI is, philosophy and use cases. + - Learning methodology based on the scientific cycle. +2. **Installation** + - Complete installation guide on Windows with environment variables and package verification. +3. **Fundamental Concepts** + - Explanation about agents, tasks, tools, processes, memory and RAG. +4. **Using PraisonAI** + - Usage with Python (`praisonaiagents`). + - Usage with YAML (CLI `praisonai`). + - Usage with JavaScript/TypeScript. + - Quick guide "Creating Your First Agent". + - Catalogue of agent models available in the examples. + - YAML configuration to define agents declaratively. + - Imports and essential functions for creating agents. +5. **Advanced Workflows** + - Collaboration between agents, routing, orchestration, autonomous mode, parallelization and prompt chaining. +6. **Tools** + - Overview and creation of custom tools. +7. **LLM Models** + - Configuration of different providers (OpenAI, Ollama, Groq, etc.). +8. **Practical Examples** + - Case studies demonstrating real applications of the framework. +9. **Contributing and Development** + - Steps to work locally and contribute to the project. + - Understanding the code structure in `src/`. +10. **Frequently Asked Questions (FAQ)** + - Quick answers for common installation and runtime errors. + +## Points to Develop + +- Add installation instructions for Linux and macOS. +- Explore more detailed examples of advanced tools and memories. +- Create additional practical exercises to reinforce the concepts. +- Document specific integrations with other LLM providers (e.g., Gemini, Anthropic). +- Include a debugging guide and best practices for troubleshooting. +- Create sections for features not yet documented: + - (done) Multimodal Agents + - (done) Code Interpreter Agents + - (done) Math Agents + - (done) Agents with Structured Output + - (done) Callback Agents + - (done) Mini AI Agents +- Document the code structure and YAML examples (done) + +This plan should be updated whenever new modules or sections are created. diff --git a/docs_translations/pt-br/00_introducao/00_como_usar_esta_documentacao.md b/docs_translations/pt-br/00_introducao/00_como_usar_esta_documentacao.md new file mode 100644 index 000000000..59ad7559a --- /dev/null +++ b/docs_translations/pt-br/00_introducao/00_como_usar_esta_documentacao.md @@ -0,0 +1,43 @@ +# Como Usar Esta Documentação (E Dicas para Obsidian) + +Esta documentação foi pensada para ser um recurso completo para o seu aprendizado sobre o PraisonAI, com foco especial na utilização através do [Obsidian](https://obsidian.md/). + +## Navegação + +A estrutura de pastas foi organizada em módulos sequenciais. Recomendamos seguir a ordem para um aprendizado progressivo. Utilize os links internos para navegar entre os tópicos relacionados e construir um mapa mental dos conceitos. Para entender como aproveitar melhor cada módulo, consulte também a seção [Metodologia de Aprendizado](03_metodologia_de_aprendizado.md). +Para ver um exemplo completo e rápido de configuração de agentes, consulte [Criando Seu Primeiro Agente](../03_usando_praisonai/04_criando_seu_primeiro_agente.md). Para conhecer os diferentes [Modelos de Agentes](../03_usando_praisonai/05_modelos_de_agentes.md) disponíveis, acesse a seção dedicada. Se quiser personalizar seus próprios arquivos, veja também [Configurações com YAML](../03_usando_praisonai/06_configuracoes_yaml.md). +Caso surjam dúvidas durante seus testes, consulte também a [Dúvidas Frequentes](../09_duvidas_frequentes.md). + +## Plugins Obsidian Sugeridos + +Para a melhor experiência ao visualizar este material no Obsidian, sugerimos instalar os seguintes plugins (se ainda não os tiver): + +1. **Mermaid Tools / Charts / Diagrams:** + * **Utilidade:** Muitos diagramas neste curso são feitos com Mermaid (uma linguagem para gerar diagramas a partir de texto). Este tipo de plugin permite que o Obsidian renderize esses diagramas corretamente. + * **Como usar:** Após instalar, os blocos de código marcados como ```mermaid ... ``` serão transformados em diagramas visuais. + +2. **Advanced Tables:** + * **Utilidade:** Facilita a criação e edição de tabelas formatadas em Markdown. Usaremos tabelas para comparar funcionalidades, listar parâmetros, etc. + * **Como usar:** Oferece uma barra de ferramentas e atalhos para manipular tabelas. + +3. **Callout Manager (ou customização via CSS snippets):** + * **Utilidade:** O Obsidian suporta "callouts" (blocos de destaque) nativamente (ex: \`>[!info] ...\`). Um Callout Manager pode oferecer mais tipos de callouts ou facilitar a customização da aparência deles. Alternativamente, você pode usar CSS snippets para personalizar os callouts padrão. + * **Como usar:** Permite destacar informações como dicas, avisos, exemplos importantes de forma visual. Exemplo de callout: + ```markdown + > [!TIP] Dica Importante + > Esta é uma informação que você não vai querer perder! + ``` + +4. **Excalidraw (Opcional):** + * **Utilidade:** Permite integrar desenhos e diagramas no estilo "quadro branco" diretamente nas suas notas do Obsidian. Pode ser útil se você quiser fazer seus próprios esquemas visuais enquanto estuda. + * **Como usar:** Cria um novo tipo de arquivo (Excalidraw) que pode ser embutido ou linkado em suas notas Markdown. + +## Formato dos Arquivos + +Todos os arquivos são em formato Markdown (`.md`), o que garante portabilidade e fácil edição. + +## Feedback + +Se encontrar erros, tiver sugestões ou dúvidas, sinta-se à vontade para abrir uma issue no repositório original deste curso. + +Aproveite os estudos! diff --git a/docs_translations/pt-br/00_introducao/01_o_que_e_praisonai.md b/docs_translations/pt-br/00_introducao/01_o_que_e_praisonai.md new file mode 100644 index 000000000..6e2f9a7ef --- /dev/null +++ b/docs_translations/pt-br/00_introducao/01_o_que_e_praisonai.md @@ -0,0 +1,156 @@ +# O que é o PraisonAI? + +

+ + + + PraisonAI Logo + +

+ +PraisonAI é um framework de **Múltiplos Agentes de IA (Multi-AI Agents)** pronto para produção e com capacidade de **auto-reflexão**. Ele foi projetado para criar Agentes de IA que automatizam e resolvem problemas, desde tarefas simples até desafios complexos. Ao integrar PraisonAI Agents, AG2 (anteriormente AutoGen) e CrewAI em uma solução de **baixo código (low-code)**, ele simplifica a construção e o gerenciamento de sistemas LLM multi-agentes, enfatizando a simplicidade, personalização e colaboração eficaz entre humanos e agentes. + + + +## Principais Recursos (Key Features) + +O PraisonAI oferece uma vasta gama de funcionalidades para construir agentes poderosos: + +- **Criação Automatizada de Agentes de IA:** Facilidade na definição e instanciação de agentes. +- **Agentes de IA com Auto-Reflexão:** Capacidade dos agentes de analisar e melhorar seu próprio desempenho. +- **Agentes de IA com Raciocínio:** Habilidade de realizar pensamentos lógicos e dedutivos. +- **Agentes de IA Multi Modais:** Suporte para processar diferentes tipos de dados (texto, imagem, etc.). +- **Colaboração Multi-Agente:** Permite que múltiplos agentes trabalhem juntos em tarefas complexas. +- **Workflow de Agentes de IA:** Definição de fluxos de trabalho para orquestrar a interação entre agentes. +- **Adição de Conhecimento Personalizado (RAG):** Integre bases de conhecimento específicas para seus agentes. +- **Agentes com Memória de Curto e Longo Prazo:** Capacidade de reter informações entre interações. +- **Agentes para Conversar com PDF:** Extraia informações e interaja com o conteúdo de arquivos PDF. +- **Agentes Interpretadores de Código:** Permitem que agentes executem código para realizar tarefas. +- **Processamento Assíncrono e Paralelo:** Execução eficiente de tarefas. +- **Auto Agents:** Agentes que podem gerar outros agentes ou modificar a si mesmos. +- **Agentes Matemáticos:** Especializados em resolver problemas matemáticos. +- **Agentes com Saída Estruturada:** Garantem que a resposta do agente siga um formato específico. +- **Agentes Integrados com LangChain:** Aproveite o ecossistema LangChain. +- **Agentes com Callback:** Funções que são chamadas em determinados pontos da execução do agente. +- **Mini Agentes de IA:** Agentes leves para tarefas específicas. +- **Mais de 100 Ferramentas Personalizadas:** Um vasto conjunto de ferramentas prontas para uso. +- **Configuração via YAML:** Defina agentes e workflows de forma declarativa. +- **Suporte a Mais de 100 Modelos de LLM:** Flexibilidade na escolha do modelo de linguagem. + +## Fluxo dos Agentes de IA (AI Agents Flow) + +Este diagrama ilustra um fluxo básico de como os agentes podem interagir em um sistema: + + + +```mermaid +graph LR + Inicio(Inicio) --> Agente1 + Agente1 --> Processo(Processar) + Processo --> Agente2 + Agente2 --> Resultado(Resultado) + Processo -.-> Agente1 + subgraph Agente1["Agente 1"] + Tarefa1(Tarefa) + IconeAgente1("Agente de IA") + Ferramentas1(Ferramentas) + Tarefa1 --- IconeAgente1 + IconeAgente1 --- Ferramentas1 + end + subgraph Agente2["Agente 2"] + Tarefa2(Tarefa) + IconeAgente2("Agente de IA") + Ferramentas2(Ferramentas) + Tarefa2 --- IconeAgente2 + IconeAgente2 --- Ferramentas2 + end + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef tools fill:#2E8B57,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Inicio,Resultado,Tarefa1,Tarefa2 input + class Processo,IconeAgente1,IconeAgente2 process + class Ferramentas1,Ferramentas2 tools + class Agente1,Agente2 transparent +``` + + + + +* **Explicação:** O processo geralmente começa com uma entrada (Início) que é passada para um Agente 1. Este agente, utilizando suas Ferramentas, processa sua Tarefa. O resultado pode ser passado para um Agente 2 para processamento adicional ou pode haver um ciclo onde o processo retorna ao Agente 1. Finalmente, um Resultado é produzido. + +## Agentes de IA com Ferramentas (AI Agents with Tools) + +Os agentes no PraisonAI podem utilizar ferramentas para interagir com sistemas externos e realizar ações: + +```mermaid +flowchart TB + subgraph Ferramentas + direction TB + T3["Busca na Internet"] + T1["Execucao de Codigo"] + T2["Formatacao"] + end + Entrada["Entrada"] ---> Agentes + subgraph Agentes + direction LR + A1["Agente 1"] + A2["Agente 2"] + A3["Agente 3"] + end + Agentes ---> Saida["Saida"] + T3 --> A1 + T1 --> A2 + T2 --> A3 + style Ferramentas fill:#189AB4,color:#fff + style Agentes fill:#8B0000,color:#fff + style Entrada fill:#8B0000,color:#fff + style Saida fill:#8B0000,color:#fff +``` +* **Explicação:** Diferentes agentes (Agente 1, Agente 2, Agente 3) podem ser equipados com diversas ferramentas (Busca na Internet, Execução de Código, Formatação). Com base na Entrada, os agentes utilizam suas ferramentas para processar a informação e gerar uma Saída. + +## Agentes de IA com Memória (AI Agents with Memory) + +A capacidade de memória permite que os agentes mantenham contexto e informação através de múltiplas tarefas: + +```mermaid +flowchart TB + subgraph Memoria ["Memoria"] + direction TB + MCP["Curto Prazo"] + MLP["Longo Prazo"] + end + subgraph Armazenamento ["Armazenamento"] + direction TB + BD["(Vector DB)"] + end + Entrada["Entrada"] ---> Agentes + subgraph Agentes + direction LR + A1["Agente 1"] + A2["Agente 2"] + A3["Agente 3"] + end + Agentes ---> Saida["Saida"] + Memoria <--> Armazenamento + Armazenamento <--> A1 + Armazenamento <--> A2 + Armazenamento <--> A3 + style Memoria fill:#189AB4,color:#fff + style Armazenamento fill:#2E8B57,color:#fff + style Agentes fill:#8B0000,color:#fff + style Entrada fill:#8B0000,color:#fff + style Saida fill:#8B0000,color:#fff +``` +* **Explicação:** Os agentes podem acessar memória de Curto Prazo (para contexto imediato) e de Longo Prazo (para conhecimento persistente). A memória de Longo Prazo é frequentemente implementada utilizando um Banco de Dados Vetorial (Vector DB) para buscas semânticas eficientes. Os agentes interagem com essa memória para informar suas ações e gerar a Saída. + +> [!NOTE] Nota sobre os Logos +> Os logos originais do PraisonAI (light/dark) não estão presentes neste repositório. Se desejar usá-los, você precisará baixá-los do repositório original ou da documentação oficial e colocá-los na pasta \`docs/pt-br/recursos/\`. As referências de imagem neste arquivo foram ajustadas para \`../recursos/logo_light.png\` e \`../recursos/logo_dark.png\`. + +Este arquivo serve como uma introdução geral ao PraisonAI. Nos próximos tópicos, detalharemos cada um desses recursos e conceitos. diff --git a/docs_translations/pt-br/00_introducao/02_filosofia_e_casos_de_uso.md b/docs_translations/pt-br/00_introducao/02_filosofia_e_casos_de_uso.md new file mode 100644 index 000000000..f9e9952d5 --- /dev/null +++ b/docs_translations/pt-br/00_introducao/02_filosofia_e_casos_de_uso.md @@ -0,0 +1,47 @@ +# Filosofia e Casos de Uso do PraisonAI + +## Filosofia do Projeto + +O PraisonAI foi construído com algumas filosofias centrais em mente, que guiam seu desenvolvimento e funcionalidades: + +1. **Pronto para Produção (Production-Ready):** O framework é projetado para ser robusto e confiável o suficiente para ser implantado em aplicações reais e ambientes de produção. +2. **Baixo Código (Low-Code):** Embora ofereça flexibilidade para codificação avançada, o PraisonAI visa simplificar o desenvolvimento de agentes de IA, permitindo que usuários com menos experiência em programação possam construir sistemas complexos, especialmente através da configuração via YAML. +3. **Simplicidade e Customização:** Busca um equilíbrio entre ser fácil de usar para iniciantes e altamente customizável para desenvolvedores experientes que precisam de funcionalidades específicas. +4. **Colaboração Eficaz Humano-Agente:** Enfatiza a criação de sistemas onde humanos e agentes de IA podem colaborar de forma produtiva. Isso inclui mecanismos de feedback, aprovação e monitoramento. +5. **Auto-Reflexão e Melhoria Contínua:** Os agentes são incentivados a ter capacidades de auto-reflexão, permitindo que analisem seus próprios resultados e melhorem seu desempenho ao longo do tempo. +6. **Integração e Ecossistema:** O PraisonAI se integra com outros frameworks populares como CrewAI e AG2 (AutoGen), e suporta uma vasta gama de Modelos de Linguagem (LLMs) e ferramentas, promovendo a interoperabilidade. +7. **Automação de Tarefas Complexas:** O objetivo final é capacitar os usuários a automatizar desde tarefas rotineiras simples até desafios multifacetados que exigem a colaboração de múltiplos agentes especializados. + +## Casos de Uso Comuns + +A flexibilidade do PraisonAI permite sua aplicação em uma ampla variedade de cenários. Alguns casos de uso comuns incluem: + +* **Atendimento ao Cliente Inteligente:** + * **Descrição:** Construção de agentes de suporte que podem entender as perguntas dos clientes, fornecer respostas precisas, resolver problemas e, se necessário, encaminhar para atendentes humanos. + * **Funcionalidades PraisonAI Relevantes:** RAG (para buscar em bases de conhecimento), Memória (para lembrar interações passadas), Integração com Ferramentas (para acessar sistemas de CRM). + +* **Análise de Dados Automatizada:** + * **Descrição:** Criação de agentes que podem processar grandes volumes de dados, identificar padrões, gerar insights e criar relatórios. + * **Funcionalidades PraisonAI Relevantes:** Agentes Interpretadores de Código (para executar scripts de análise), Saída Estruturada (para formatar os resultados), Ferramentas de Visualização de Dados. + +* **Criação de Conteúdo Personalizado:** + * **Descrição:** Desenvolvimento de agentes que podem gerar, editar e otimizar conteúdo para diferentes plataformas (artigos de blog, posts em redes sociais, roteiros de vídeo, etc.), adaptando-se a diferentes estilos e públicos. + * **Funcionalidades PraisonAI Relevantes:** Múltiplos Agentes (para diferentes etapas do processo criativo), Ferramentas de Busca na Web (para pesquisa), Auto-Reflexão (para melhorar a qualidade do conteúdo). + +* **Automação de Processos de Negócios (BPA):** + * **Descrição:** Orquestração de workflows complexos que envolvem múltiplas etapas e sistemas, como processamento de pedidos, integração de novos funcionários (onboarding) ou gerenciamento da cadeia de suprimentos. + * **Funcionalidades PraisonAI Relevantes:** Workflow de Agentes, Colaboração Multi-Agente, Ferramentas de Integração com APIs. + +* **Pesquisa e Coleta de Informações:** + * **Descrição:** Agentes que podem realizar pesquisas extensivas na web, em documentos ou bancos de dados, sumarizar informações e apresentar relatórios concisos. + * **Funcionalidades PraisonAI Relevantes:** RAG, Ferramentas de Busca (Tavily, Crawl4AI), Agentes de Sumarização. + +* **Desenvolvimento e Revisão de Código:** + * **Descrição:** Agentes que auxiliam no desenvolvimento de software, sugerindo código, revisando pull requests, identificando bugs ou explicando trechos de código. + * **Funcionalidades PraisonAI Relevantes:** Agentes Interpretadores de Código, Chat com a Base de Código, Ferramentas de Análise Estática. + +* **Assistentes Pessoais Inteligentes:** + * **Descrição:** Criação de assistentes personalizados que podem gerenciar agendas, responder e-mails, planejar viagens ou realizar tarefas específicas definidas pelo usuário. + * **Funcionalidades PraisonAI Relevantes:** Memória, Ferramentas de Calendário/Email, Capacidade de aprender as preferências do usuário. + +Estes são apenas alguns exemplos. A natureza modular e extensível do PraisonAI permite que ele seja adaptado para muitos outros domínios e desafios. O limite é, em grande parte, a criatividade e a necessidade do desenvolvedor. diff --git a/docs_translations/pt-br/00_introducao/03_metodologia_de_aprendizado.md b/docs_translations/pt-br/00_introducao/03_metodologia_de_aprendizado.md new file mode 100644 index 000000000..3d8dc7540 --- /dev/null +++ b/docs_translations/pt-br/00_introducao/03_metodologia_de_aprendizado.md @@ -0,0 +1,33 @@ +# Metodologia de Aprendizado + +Este curso foi estruturado com base em princípios de ensino científico para que você progrida de forma gradual e tenha segurança ao aplicar o PraisonAI na prática. + +## 1. Ciclo de Aprendizado + +1. **Apresentação do Conceito** + - Cada módulo inicia com uma breve exposição teórica do tema. +2. **Exemplos Guiados** + - Em seguida você encontra exemplos completos para reproduzir no terminal ou em seu editor. +3. **Prática Ativa** + - É recomendável digitar os comandos manualmente para reforçar a memorização. +4. **Reflexão e Revisão** + - Ao final de cada seção, revise o que funcionou e anote dúvidas antes de prosseguir. + +> [!TIP] +> Use a técnica de Feynman: tente explicar o assunto com suas próprias palavras a outra pessoa ou em notas. Se travar em alguma parte, retorne à documentação e revise. + +## 2. Ambiente de Estudos + +- Organize uma pasta dedicada para testar os exemplos. +- Mantenha um terminal aberto para executar os comandos passo a passo. +- Utilize o Obsidian ou outro editor Markdown para registrar suas observações. + +## 3. Aprofundamento Progressivo + +A documentação foi pensada para que cada módulo dependa do anterior. Se algum conceito ainda não estiver claro, volte ao módulo correspondente e refaça os exercícios. Essa repetição espaçada ajuda na fixação a longo prazo. + +## Próximos Passos + +Após dominar esta metodologia, avance para o módulo de **Instalação** e siga a sequência sugerida no README principal. + +Bom estudo! diff --git a/docs_translations/pt-br/01_instalacao/00_instalacao_windows.md b/docs_translations/pt-br/01_instalacao/00_instalacao_windows.md new file mode 100644 index 000000000..5722d8f41 --- /dev/null +++ b/docs_translations/pt-br/01_instalacao/00_instalacao_windows.md @@ -0,0 +1,186 @@ +# Guia de Instalação Local (Windows) + +Este guia detalha como instalar o framework PraisonAI em um ambiente Windows, permitindo que você comece a criar e executar seus próprios agentes de IA. + +## Pré-requisitos + +Antes de começar, garanta que você tenha os seguintes pré-requisitos instalados e configurados em seu sistema Windows: + +1. **Python:** + * **Versão:** É recomendável usar Python 3.8 ou superior. + * **Como verificar:** Abra o Prompt de Comando (CMD) ou PowerShell e digite: + ```bash + python --version + ``` + * **Como instalar:** Se não tiver o Python ou tiver uma versão muito antiga, baixe o instalador mais recente em [python.org](https://www.python.org/downloads/windows/). + > [!IMPORTANT] Durante a Instalação do Python + > Marque a opção **"Add Python to PATH"** (ou "Adicionar Python ao PATH") durante o processo de instalação. Isso facilitará a execução de comandos Python e pip diretamente do terminal. Se você esqueceu de fazer isso, precisará adicionar manualmente os diretórios do Python e Scripts ao PATH do sistema. + +2. **pip (Gerenciador de Pacotes Python):** + * **Como verificar:** O pip geralmente é instalado automaticamente com o Python (a partir da versão 3.4). Verifique com: + ```bash + pip --version + ``` + * **Como atualizar (recomendado):** + ```bash + python -m pip install --upgrade pip + ``` + +3. **Git (Opcional, mas Altamente Recomendado):** + * **Utilidade:** Necessário para clonar o repositório do PraisonAI se você quiser acessar os exemplos mais recentes, contribuir para o projeto ou trabalhar com a versão de desenvolvimento. + * **Como instalar:** Baixe e instale o Git para Windows em [git-scm.com](https://git-scm.com/download/win). + +## Configurando Variáveis de Ambiente + +Para que o PraisonAI funcione corretamente, especialmente ao interagir com modelos de linguagem pagos (como os da OpenAI), você precisará configurar variáveis de ambiente. A mais comum é a `OPENAI_API_KEY`. + +**Opção 1: Temporariamente (para a sessão atual do terminal)** + +Abra o Prompt de Comando ou PowerShell e use o comando `set`: +```bash +set OPENAI_API_KEY=sua_chave_api_aqui +``` +> [!WARNING] Chave Temporária +> Esta configuração será perdida quando você fechar o terminal. + +**Opção 2: Permanentemente (para o usuário atual)** + +Use o comando `setx`. Ele adiciona a variável permanentemente, mas você precisará abrir um **novo** terminal para que as alterações tenham efeito. +```bash +setx OPENAI_API_KEY "sua_chave_api_aqui" +``` +> [!NOTE] Aspas em `setx` +> É uma boa prática usar aspas ao redor do valor da chave com `setx`, especialmente se ela contiver caracteres especiais (embora chaves de API geralmente não contenham). + +**Opção 3: Permanentemente (via Interface Gráfica do Windows)** + +1. Pressione a tecla `Windows`, digite "variáveis de ambiente" e selecione "Editar as variáveis de ambiente do sistema". +2. Na janela "Propriedades do Sistema", clique no botão "Variáveis de Ambiente...". +3. Na seção "Variáveis de usuário para [Seu Nome de Usuário]", clique em "Novo...". + * **Nome da variável:** `OPENAI_API_KEY` + * **Valor da variável:** `sua_chave_api_aqui` +4. Clique "OK" em todas as janelas. Você precisará abrir um novo terminal para que as alterações tenham efeito. + +Outras variáveis de ambiente importantes, como `OPENAI_BASE_URL` (para usar com Ollama ou Groq), podem ser configuradas da mesma forma. + +## Instalação do PraisonAI + +Existem duas formas principais de instalar o PraisonAI: + +### 1. Para Usuários (`praisonaiagents` e `praisonai` CLI) + +Esta é a forma recomendada para a maioria dos usuários que desejam utilizar o PraisonAI para criar e executar agentes. + +* **`praisonaiagents` (Pacote leve para codificação):** + Se você pretende principalmente usar o PraisonAI programaticamente em Python. + ```bash + pip install praisonaiagents + ``` + +* **`praisonai` (Pacote completo com CLI e modo "No Code"):** + Se você quer a experiência completa, incluindo a interface de linha de comando (CLI) para executar arquivos YAML e o modo automático. + ```bash + pip install praisonai + ``` + Este pacote geralmente inclui `praisonaiagents` como dependência. + +### 2. Para Desenvolvedores (Trabalhando com o Código Fonte) + +Se você pretende contribuir para o PraisonAI, modificar seu código-fonte ou usar as versões mais recentes diretamente do repositório. + +1. **Clone o repositório:** + ```bash + git clone https://github.com/MervinPraison/PraisonAI.git + cd PraisonAI + ``` + +2. **Crie e Ative um Ambiente Virtual (Recomendado):** + ```bash + python -m venv .venv + # No CMD: + .venv\Scripts\activate + # No PowerShell: + .venv\Scripts\Activate.ps1 + ``` + +3. **Instale `uv` (um instalador Python rápido):** + O `README.md` do projeto sugere o uso de `uv`. + ```bash + pip install uv + ``` + +4. **Instale as dependências usando `uv`:** + O PraisonAI usa `pyproject.toml` para gerenciar suas dependências. + * Instalação básica: + ```bash + uv pip install -e . + ``` + O `-e .` instala o projeto em modo editável, o que significa que as alterações no código-fonte são refletidas imediatamente. + + * Instalação com extras (para funcionalidades específicas como `code`, `crewai`, `autogen`): + Consulte o arquivo `pyproject.toml` para ver os extras disponíveis. Exemplos: + ```bash + uv pip install -e .[code] + uv pip install -e .[crewai,autogen] + # Para instalar todos os extras, pode haver uma opção como [all] ou você precisará listá-los. + # Verifique o pyproject.toml para a sintaxe correta dos extras. + ``` + Alternativamente, se o `pyproject.toml` estiver configurado para isso, você pode instalar diretamente dele: + ```bash + uv pip install -r pyproject.toml --extra code + ``` + +## Verificando a Instalação + +Após a instalação, você pode verificar se tudo está funcionando corretamente. + +**Se você instalou `praisonaiagents`:** + +Crie um arquivo Python simples (ex: `teste_agente.py`): +```python +from praisonaiagents import Agent + +try: + # Certifique-se de ter sua OPENAI_API_KEY configurada como variável de ambiente + agente_teste = Agent(instructions="Você é um assistente prestativo.") + resposta = agente_teste.start("Escreva uma frase curta sobre IA.") + print("Resposta do Agente:", resposta) +except Exception as e: + print(f"Ocorreu um erro: {e}") + print("Verifique se sua chave OPENAI_API_KEY está configurada corretamente.") +``` +Execute-o: +```bash +python teste_agente.py +``` + +**Se você instalou `praisonai` (com CLI):** + +Verifique a CLI: +```bash +praisonai --version +``` +Tente o modo automático (requer `OPENAI_API_KEY`): +```bash +praisonai --auto "Conte uma piada curta sobre programadores" +``` + +## Solução de Problemas Comuns (Windows) + +* **`pip` ou `python` não é reconhecido como um comando:** + * **Causa:** Python não foi adicionado ao PATH durante a instalação. + * **Solução:** Reinstale o Python marcando "Add Python to PATH" ou adicione manualmente os diretórios `C:\Users\SEU_USUARIO\AppData\Local\Programs\Python\PythonXX` e `C:\Users\SEU_USUARIO\AppData\Local\Programs\Python\PythonXX\Scripts` às Variáveis de Ambiente do sistema. (Substitua `SEU_USUARIO` e `PythonXX` conforme sua instalação). + +* **Erro ao instalar pacotes com `pip` (ex: erros de compilação):** + * **Causa:** Alguns pacotes Python podem ter dependências que requerem ferramentas de compilação C/C++ (Microsoft Visual C++ Build Tools). + * **Solução:** Instale as "Build Tools for Visual Studio" do site da Microsoft. Geralmente, selecionar a carga de trabalho "Desenvolvimento para desktop com C++" é suficiente. + +* **Permissões:** + * **Causa:** Em alguns casos, você pode precisar de permissões de administrador para instalar pacotes globalmente (não recomendado) ou para modificar certas pastas. + * **Solução:** Prefira usar ambientes virtuais. Se realmente precisar, execute o Prompt de Comando ou PowerShell como Administrador. + +* **Conflitos de Pacotes:** + * **Causa:** Versões incompatíveis de pacotes. + * **Solução:** Use ambientes virtuais para isolar as dependências de cada projeto. Comandos como `pip freeze > requirements.txt` e `pip install -r requirements.txt` ajudam a gerenciar dependências. + +Com este guia, você deve ser capaz de instalar o PraisonAI em seu sistema Windows e começar sua jornada no desenvolvimento de agentes de IA! diff --git a/docs_translations/pt-br/02_conceitos_fundamentais/01_agentes.md b/docs_translations/pt-br/02_conceitos_fundamentais/01_agentes.md new file mode 100644 index 000000000..833cd9476 --- /dev/null +++ b/docs_translations/pt-br/02_conceitos_fundamentais/01_agentes.md @@ -0,0 +1,102 @@ +# Conceito Fundamental: Agentes + +No coração do PraisonAI, e de qualquer sistema de Inteligência Artificial baseado em agentes, está o conceito de **Agente**. Vamos explorar o que isso significa. + +## O que é um Agente de IA? + +De forma geral, um **Agente de Inteligência Artificial (Agente de IA)** é uma entidade autônoma que percebe seu ambiente através de sensores (entradas de dados) e atua sobre esse ambiente através de atuadores (saídas ou ações) para atingir objetivos específicos. + +Pense em um agente como um "trabalhador" inteligente que pode: + +1. **Perceber:** Coletar informações sobre o estado atual de uma situação ou sistema. +2. **Pensar/Raciocinar:** Processar essas informações, aplicar lógica, conhecimento e tomar decisões. +3. **Agir:** Executar ações para alcançar uma meta ou realizar uma tarefa. + +**Características comuns de Agentes de IA:** + +* **Autonomia:** Operam sem intervenção humana direta para cada decisão. +* **Reatividade:** Respondem a mudanças no ambiente. +* **Proatividade:** Tomam iniciativa para atingir seus objetivos. +* **Capacidade de Aprendizagem (opcional):** Alguns agentes podem aprender com a experiência e melhorar seu desempenho. +* **Comunicação (opcional):** Podem interagir com outros agentes ou com humanos. + +## Agentes no PraisonAI + +No PraisonAI, um Agente é a unidade fundamental de execução. Ele é tipicamente definido por: + +1. **Instruções (Instructions) / Prompt:** Uma descrição clara do que o agente deve fazer, qual seu papel, personalidade, e quais são seus objetivos. Este é o "cérebro" do agente, guiando seu comportamento. +2. **Modelo de LLM (Opcional, mas comum):** Geralmente, um agente PraisonAI é potencializado por um Modelo de Linguagem Grande (LLM) subjacente (como GPT, Claude, Llama, Gemini, etc.) que interpreta as instruções e gera as respostas ou ações. O PraisonAI permite configurar qual LLM o agente usará. +3. **Ferramentas (Tools - Opcional):** Um conjunto de capacidades ou funções que o agente pode usar para interagir com o mundo exterior (ex: buscar na internet, executar código, ler arquivos). +4. **Memória (Memory - Opcional):** Capacidade de lembrar informações de interações passadas para manter o contexto. +5. **Backstory / Papel (Role):** Define o contexto e a especialização do agente, ajudando o LLM a gerar respostas mais consistentes e relevantes. +6. **Objetivo (Goal):** Uma declaração clara do que o agente deve alcançar. + +### Como o PraisonAI Implementa Agentes + +O PraisonAI simplifica a criação e o gerenciamento desses agentes. Você pode definir agentes de duas formas principais: + +* **Programaticamente (usando Python com `praisonaiagents`):** + Você instancia classes como `Agent` e configura seus atributos (instruções, ferramentas, etc.) diretamente no código. + + *Exemplo (simplificado de `examples/python/agents/single-agent.py`):* + ```python + from praisonaiagents import Agent + + # Supondo que a variável de ambiente OPENAI_API_KEY está configurada + agente_roteirista = Agent( + role="Roteirista Criativo", + goal="Escrever um roteiro de filme envolvente sobre um tema específico.", + backstory="Você é um roteirista renomado, conhecido por sua habilidade em criar narrativas cativantes e diálogos impactantes.", + instructions="Sua tarefa é desenvolver um roteiro completo para um filme sobre robôs explorando Marte. O roteiro deve incluir descrições de cena, diálogos e desenvolvimento de personagens.", + # llm="gpt-4", # Opcional, pode usar o padrão + allow_delegation=False # Este agente não delega tarefas + ) + + # Para iniciar a tarefa principal do agente (definida implicitamente pelo goal e instructions) + # resultado = agente_roteirista.start("Desenvolva o roteiro sobre robôs em Marte.") + # Ou, se o agente tem tarefas explícitas (veremos em "Tarefas"): + # resultado = agente_roteirista.execute_task("Sua primeira tarefa aqui...") + ``` + > Veja o arquivo completo em: [examples/python/agents/single-agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/agents/single-agent.py) (link para o repositório original) + +* **Declarativamente (usando arquivos YAML com `praisonai` CLI):** + Você define as propriedades dos agentes em um arquivo `.yaml`, que o PraisonAI então interpreta para criar e executar os agentes. + + *Exemplo (simplificado de `agents.yaml` no README principal):* + ```yaml + framework: praisonai # Ou crewai, autogen + topic: Inteligência Artificial # Variável que pode ser usada nas descrições + roles: + roteirista: + backstory: "Habilidoso em criar roteiros com diálogos envolventes sobre {topic}." + goal: Criar roteiros a partir de conceitos. + role: Roteirista + # instructions: (Poderia ser definido aqui também) + tasks: + tarefa_escrita_roteiro: + description: "Desenvolver roteiros com personagens cativantes e diálogos sobre {topic}." + expected_output: "Roteiro completo pronto para produção." + # agent: roteirista # Especifica qual agente executa esta tarefa + ``` + > Veja exemplos mais complexos na pasta `examples/cookbooks/yaml/`. + +### Auto-Reflexão em Agentes PraisonAI + +Um dos recursos destacados do PraisonAI é a capacidade de "auto-reflexão". Isso significa que um agente pode ser configurado para: +1. Executar uma tarefa. +2. Analisar seu próprio resultado com base em critérios ou no objetivo original. +3. Se o resultado não for satisfatório, tentar novamente, possivelmente com uma abordagem diferente, até atingir o objetivo ou um limite de tentativas. + +Essa capacidade torna os agentes mais robustos e capazes de lidar com ambiguidades ou produzir resultados de maior qualidade. + +## Fundamentos por Trás + +A ideia de agentes vem de campos como a Inteligência Artificial Distribuída (DAI) e Sistemas Multi-Agentes (MAS). Os fundamentos teóricos incluem: + +* **Arquiteturas de Agentes:** Como BDI (Belief-Desire-Intention), que modela agentes com base em suas crenças sobre o mundo, seus desejos (objetivos) e suas intenções (planos de ação). +* **Teoria da Decisão:** Como os agentes escolhem a melhor ação entre várias alternativas. +* **Comunicação e Coordenação:** Protocolos e estratégias para que múltiplos agentes interajam e trabalhem juntos. + +O PraisonAI abstrai muitos desses detalhes complexos, mas entender os fundamentos pode ajudar a projetar agentes e sistemas de agentes mais eficazes. + +No próximo tópico, veremos como as **Tarefas (Tasks)** se relacionam com os Agentes. diff --git a/docs_translations/pt-br/02_conceitos_fundamentais/02_tarefas.md b/docs_translations/pt-br/02_conceitos_fundamentais/02_tarefas.md new file mode 100644 index 000000000..bc9b9ec23 --- /dev/null +++ b/docs_translations/pt-br/02_conceitos_fundamentais/02_tarefas.md @@ -0,0 +1,109 @@ +# Conceito Fundamental: Tarefas (Tasks) + +Após entendermos o que são [Agentes](./01_agentes.md), o próximo conceito crucial no PraisonAI (e em frameworks similares como CrewAI, do qual o PraisonAI se inspira) é a **Tarefa (Task)**. + +## O que é uma Tarefa? + +Uma Tarefa representa uma unidade de trabalho específica e bem definida que um Agente deve realizar. Se o Agente é o "trabalhador", a Tarefa é a "ordem de serviço" ou a "descrição do trabalho" que ele precisa executar. + +**Características de uma Tarefa:** + +* **Descrição Clara (Description):** Um texto detalhado que explica o que precisa ser feito, quais são os objetivos da tarefa e, possivelmente, o contexto relevante. +* **Resultado Esperado (Expected Output):** Uma descrição do que constitui a conclusão bem-sucedida da tarefa. Isso ajuda o agente (e o sistema) a avaliar se a tarefa foi completada satisfatoriamente. +* **Agente Responsável (Agent):** Especifica qual agente (ou tipo de agente/role) é designado para executar esta tarefa. +* **Contexto/Dependências (Context - Opcional):** Algumas tarefas podem depender dos resultados de tarefas anteriores. O sistema gerencia a passagem desse contexto. +* **Ferramentas (Tools - Opcional):** Pode especificar quais ferramentas o agente deve ou pode usar para realizar a tarefa, ou o agente pode decidir com base em suas ferramentas atribuídas. + +## Tarefas no PraisonAI + +No PraisonAI, as tarefas são o motor que impulsiona os agentes a agir. Elas fornecem o foco e a direção para o trabalho do agente. + +### Como o PraisonAI Implementa Tarefas + +Assim como os Agentes, as Tarefas podem ser definidas: + +* **Programaticamente (usando Python com `praisonaiagents`):** + Você instancia a classe `Task` (ou similar, dependendo da versão e se está usando integrações como CrewAI) e define seus atributos. + + *Exemplo (conceitual, inspirado na estrutura do CrewAI que o PraisonAI integra):* + ```python + from praisonaiagents import Agent # Supondo que Agent e Task venham daqui ou de um módulo integrado + # from crewai import Task # Se estiver usando a sintaxe CrewAI diretamente + + # Definindo um agente (como visto no tópico anterior) + pesquisador = Agent( + role='Pesquisador Sênior', + goal='Descobrir informações de ponta sobre IA e Machine Learning', + backstory='Você é um pesquisador renomado com anos de experiência em vasculhar artigos científicos e notícias de tecnologia.' + ) + + # Definindo uma tarefa para o agente pesquisador + tarefa_pesquisa = { # Em PraisonAI, tarefas podem ser dicionários dentro de uma lista de tarefas do agente ou workflow + 'description': ( + "Pesquise os últimos avanços em modelos de linguagem generativa nos últimos 3 meses. " + "Foque em novas arquiteturas, capacidades emergentes e preocupações éticas." + ), + 'expected_output': ( + "Um relatório resumido de 3-5 parágrafos destacando os principais achados, " + "incluindo links para as fontes primárias (artigos, posts de blog)." + ), + 'agent': pesquisador # Associando a tarefa ao agente + } + + # Em um workflow com múltiplos agentes, você teria uma lista de tarefas + # e o framework orquestraria a execução. + # Exemplo de como um agente poderia executar uma tarefa (pode variar na API exata): + # resultado_tarefa = pesquisador.execute_task(tarefa_pesquisa) + # print(resultado_tarefa) + ``` + > No PraisonAI, a definição de tarefas pode ser mais integrada à configuração do Agente ou do workflow YAML, como veremos abaixo. A API exata para `Task` em Python pode depender se você está usando a camada PraisonAI nativa ou a integração CrewAI/AutoGen. Veja os exemplos em `examples/python/` para a sintaxe precisa. + +* **Declarativamente (usando arquivos YAML com `praisonai` CLI):** + Esta é uma forma muito comum de definir tarefas no PraisonAI, especialmente ao usar múltiplos agentes. + + *Exemplo (do `agents.yaml` no README principal, focado na seção `tasks`):* + ```yaml + framework: praisonai + topic: Inteligência Artificial + roles: + roteirista: # Nome do papel/agente + # ... (backstory, goal, role do agente) ... + tasks: + tarefa_escrita_roteiro: # Nome da tarefa (identificador) + description: "Desenvolver roteiros com personagens cativantes e diálogos sobre {topic}." # O que fazer + expected_output: "Roteiro completo pronto para produção." # O que se espera ao final + # agent: roteirista # Opcional se a tarefa está sob o 'role' que a executa + # Mas útil se um 'manager_agent' distribui tarefas. + # context: # Opcional: especificaria quais tarefas devem ser concluídas antes desta + # - tarefa_ideias_brainstorm + ``` + > No exemplo acima, `tarefa_escrita_roteiro` é uma tarefa atribuída implicitamente ao agente `roteirista`. + > Em cenários mais complexos, você pode ter uma lista global de tarefas e atribuí-las explicitamente aos agentes. + > Consulte os arquivos YAML em `examples/cookbooks/yaml/` para ver diversas formas de estruturar tarefas. Por exemplo, em `examples/cookbooks/yaml/comprehensive_research_report_agents.ipynb` (que usa um YAML), você verá tarefas mais elaboradas. + +### Fluxo de Execução de Tarefas + +1. **Atribuição:** Uma tarefa é atribuída a um agente. +2. **Execução:** O agente usa suas instruções, LLM e ferramentas para trabalhar na tarefa. +3. **Resultado:** O agente produz um resultado. +4. **Avaliação (implícita ou explícita):** O resultado é comparado (pelo agente, por outro agente ou pelo sistema) com o `expected_output`. +5. **Passagem de Contexto:** O resultado da tarefa pode se tornar contexto para tarefas subsequentes. + +### A Importância do "Expected Output" + +O campo `expected_output` é vital. Ele serve como: +* Um guia para o LLM do agente, ajudando-o a entender o formato e o escopo do que precisa ser produzido. +* Um critério para a auto-reflexão do agente ou para agentes avaliadores determinarem se a tarefa foi bem-sucedida. +* Uma forma de garantir que a saída de uma tarefa seja utilizável pela próxima tarefa em um workflow. + +## Fundamentos por Trás + +O conceito de tarefas está ligado a: + +* **Decomposição de Problemas:** Dividir um problema complexo em partes menores e gerenciáveis (as tarefas). +* **Planejamento:** Em sistemas mais avançados, os próprios agentes podem gerar uma sequência de tarefas para atingir um objetivo maior. +* **Gerenciamento de Workflow:** Orquestrar a ordem de execução das tarefas, lidar com dependências e paralelismo. + +Ao definir tarefas claras e com resultados esperados bem descritos, você aumenta significativamente a chance de seus agentes PraisonAI alcançarem os objetivos desejados de forma eficaz. + +A seguir, exploraremos como os **Processos** gerenciam a execução e colaboração entre agentes e suas tarefas. diff --git a/docs_translations/pt-br/02_conceitos_fundamentais/03_processos.md b/docs_translations/pt-br/02_conceitos_fundamentais/03_processos.md new file mode 100644 index 000000000..b0f700184 --- /dev/null +++ b/docs_translations/pt-br/02_conceitos_fundamentais/03_processos.md @@ -0,0 +1,163 @@ +# Conceito Fundamental: Processos (Process) + +Compreendidos os [Agentes](./01_agentes.md) e as [Tarefas](./02_tarefas.md), o próximo elemento essencial na arquitetura do PraisonAI é o **Processo (Process)**. O Processo define como os agentes colaboram e como as tarefas são executadas em um sistema multi-agente. + +## O que é um Processo? + +Em um sistema com múltiplos agentes, o Processo dita a estratégia de coordenação. Ele determina: + +* **A ordem de execução das tarefas:** Se as tarefas são executadas uma após a outra, em paralelo, ou de forma mais complexa. +* **Como os agentes interagem:** Se há um agente gerente, se os agentes passam o trabalho diretamente um para o outro, etc. +* **O fluxo de informação:** Como os resultados de uma tarefa são passados como contexto para a próxima. + +PraisonAI, especialmente através de sua integração com o CrewAI, oferece diferentes tipos de processos para acomodar diversas necessidades de workflows. + +## Tipos de Processos no PraisonAI (e CrewAI) + +O `README.md` principal do PraisonAI já ilustra alguns desses processos. Os mais comuns, inspirados no CrewAI, são: + +1. **Processo Sequencial (Sequential Process):** + * **Descrição:** É a forma mais simples de execução. As tarefas são realizadas uma após a outra, na ordem em que são definidas. O resultado de uma tarefa é automaticamente passado como contexto para a próxima. + * **Ideal para:** Workflows lineares onde cada etapa depende diretamente da anterior. + * **Diagrama:** + ```mermaid + graph LR + Entrada["Entrada"] --> A1 + subgraph Agentes + direction LR + A1["Agente 1 (Tarefa 1)"] --> A2["Agente 2 (Tarefa 2)"] --> A3["Agente 3 (Tarefa 3)"] + end + A3 --> Saida["Saida"] + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Entrada,Saida input + class A1,A2,A3 process + class Agentes transparent + ``` + +2. **Processo Hierárquico (Hierarchical Process):** + * **Descrição:** Utiliza um "agente gerente" (manager agent) para coordenar a execução das tarefas e designar trabalho para "agentes trabalhadores" (worker agents). O gerente recebe o input inicial, decide qual trabalhador (ou sequência de trabalhadores) deve atuar, e pode revisar ou agregar os resultados antes de produzir a saída final. + * **Ideal para:** Tarefas complexas que podem ser decompostas e onde é necessária uma supervisão ou um ponto central de controle e decisão. Permite mais flexibilidade e potencial para otimização. + * **Diagrama:** + ```mermaid + graph TB + Entrada["Entrada"] --> Gerente + subgraph SistemaDeAgentes ["Sistema de Agentes"] + Gerente["Agente Gerente"] + subgraph Trabalhadores ["Agentes Trabalhadores"] + direction LR + T1["Trabalhador 1"] + T2["Trabalhador 2"] + T3["Trabalhador 3"] + end + Gerente --> T1 + Gerente --> T2 + Gerente --> T3 + end + T1 --> Gerente + T2 --> Gerente + T3 --> Gerente + Gerente --> Saida["Saida"] + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Entrada,Saida input + class Gerente,T1,T2,T3 process + class SistemaDeAgentes,Trabalhadores transparent + ``` + * **Observação:** No PraisonAI, o agente gerente pode ter instruções específicas para gerenciar o fluxo, e os trabalhadores são focados em suas tarefas especializadas. O gerente também pode ter a capacidade de solicitar interações humanas (human input) ou aprovações. + +3. **Processo Baseado em Workflow (Workflow Process):** + * **Descrição:** É um tipo de processo mais avançado que suporta relações complexas entre tarefas e execução condicional. Permite construir fluxos de trabalho onde, por exemplo, dependendo do resultado de uma tarefa, diferentes agentes ou sequências de tarefas podem ser ativados. + * **Ideal para:** Lógica de negócios complexa, processos com múltiplos caminhos possíveis, ou quando a automação precisa se adaptar dinamicamente a diferentes cenários. + * **Diagrama (Exemplo com Condição):** + ```mermaid + graph LR + Entrada["Entrada"] --> InicioWorkflow["Inicio do Workflow"] + subgraph Workflow + direction LR + InicioWorkflow --> C1{"Condicao"} + C1 --o|Sim| A1["Agente 1"] + C1 --x|Nao| A2["Agente 2"] + A1 --> Juncao["Juncao"] + A2 --> Juncao + Juncao --> A3["Agente 3"] + end + A3 --> Saida["Saida"] + classDef input fill:#8B0000,stroke:#7C90A0,color:#fff + classDef process fill:#189AB4,stroke:#7C90A0,color:#fff + classDef decision fill:#2E8B57,stroke:#7C90A0,color:#fff + classDef transparent fill:none,stroke:none + class Entrada,Saida input + class InicioWorkflow,A1,A2,A3,Juncao process + class C1 decision + class Workflow transparent + ``` + * **Observação:** O PraisonAI implementa workflows através de sua configuração YAML (ver `agents-advanced.yaml` ou exemplos em `examples/cookbooks/yaml/`) e programaticamente, permitindo definir a ordem, as dependências e as condições para a execução das tarefas. + +## Como Configurar o Processo no PraisonAI + +A escolha e configuração do processo geralmente ocorrem ao definir um "time" de agentes (Crew) ou um sistema multi-agente. + +* **Programaticamente (Python):** + Ao usar a integração CrewAI dentro do PraisonAI, você pode especificar o tipo de processo ao instanciar a classe `Crew`. + ```python + # Exemplo conceitual com CrewAI + from crewai import Crew, Process + # from praisonaiagents import Agent, Task # Supondo que venham do PraisonAI + + # ... (definição de agentes e tarefas) ... + + # Criando um time (Crew) com um processo específico + meu_time = Crew( + agents=[agente1, agente2], + tasks=[tarefa1, tarefa2], + process=Process.sequential # Ou Process.hierarchical + # verbose=True # Para ver o log de execução + ) + + resultado_final = meu_time.kickoff() + ``` + > Consulte os exemplos em `examples/python/general/` como `workflow_example_basic.py` ou `workflow_example_detailed.py` para ver a sintaxe específica do PraisonAI, que pode ter sua própria maneira de definir workflows. + +* **Declarativamente (YAML):** + Nos arquivos YAML do PraisonAI, a estrutura das `roles` (agentes) e `tasks`, e como elas são aninhadas ou referenciadas, implicitamente ou explicitamente definem o processo. Para processos hierárquicos, você pode definir um `manager_agent`. Para workflows complexos, a ordem e as dependências das tarefas são cruciais. + + *Exemplo de estrutura que sugere um processo (pode variar):* + ```yaml + framework: praisonai # ou crewai + # process: sequential # Pode haver uma chave explícita em algumas versões/configurações + + manager_agent: gestor_de_projetos # Sugere um processo hierárquico + + roles: + gestor_de_projetos: + # ... + pesquisador: + # ... + escritor: + # ... + + tasks: + - name: tarefa_pesquisa + agent: pesquisador + # ... + - name: tarefa_escrita + agent: escritor + context_tasks: [tarefa_pesquisa] # Define dependência, implicando ordem + # ... + ``` + > É importante notar que o `framework: crewai` ou `framework: autogen` no YAML pode influenciar como os processos são interpretados, pois o PraisonAI pode delegar a lógica de processo para esses frameworks. + +## Fundamentos por Trás + +Os diferentes tipos de processos em sistemas multi-agentes se baseiam em conceitos de: + +* **Arquiteturas de Software:** Padrões como pipeline (sequencial) ou blackboard (um espaço compartilhado onde agentes leem e escrevem informações, gerenciado por um controlador). +* **Teoria da Computação Distribuída:** Como coordenar múltiplos executores. +* **Gerenciamento de Projetos e Organização de Equipes:** O processo hierárquico espelha estruturas de gerenciamento onde um líder distribui tarefas e consolida resultados. + +A escolha do processo correto depende da natureza do problema a ser resolvido. Problemas simples e lineares se beneficiam de processos sequenciais, enquanto problemas mais complexos e dinâmicos podem exigir abordagens hierárquicas ou baseadas em workflows. + +O próximo conceito a ser explorado são as **Ferramentas (Tools)**, que dão aos agentes suas capacidades de interagir com o mundo. diff --git a/docs_translations/pt-br/02_conceitos_fundamentais/04_ferramentas.md b/docs_translations/pt-br/02_conceitos_fundamentais/04_ferramentas.md new file mode 100644 index 000000000..37742e149 --- /dev/null +++ b/docs_translations/pt-br/02_conceitos_fundamentais/04_ferramentas.md @@ -0,0 +1,114 @@ +# Conceito Fundamental: Ferramentas (Tools) + +Os [Agentes](./01_agentes.md) no PraisonAI, para serem verdadeiramente úteis e interagirem com o mundo além de apenas processar texto, precisam de **Ferramentas (Tools)**. As ferramentas expandem as capacidades dos agentes, permitindo-lhes realizar ações, buscar informações externas e interagir com outros sistemas. + +## O que são Ferramentas? + +No contexto de agentes de IA e LLMs, uma Ferramenta é essencialmente uma **função ou capacidade específica que um agente pode invocar para realizar uma tarefa que vai além das capacidades inerentes do modelo de linguagem**. + +Pense nas ferramentas como os "braços e pernas" do agente, ou como aplicativos especializados que ele pode usar: + +* **Exemplos Comuns:** + * **Busca na Web:** Para encontrar informações atualizadas na internet. + * **Execução de Código:** Para realizar cálculos, manipular dados ou interagir com sistemas via scripts. + * **Leitura/Escrita de Arquivos:** Para acessar ou persistir informações no sistema de arquivos. + * **Interação com APIs:** Para se conectar a serviços externos (ex: previsão do tempo, bancos de dados, redes sociais). + * **Cálculo Matemático:** Para resolver problemas matemáticos complexos. + * **Geração de Imagens:** Para criar imagens a partir de descrições textuais. + +O LLM dentro do agente decide *quando* usar uma ferramenta, *qual* ferramenta usar e com *quais parâmetros* chamá-la, com base na tarefa atual e em suas instruções. + +## Ferramentas no PraisonAI + +PraisonAI possui um rico ecossistema de ferramentas, mencionando "100+ Custom Tools" em sua documentação. Ele permite tanto o uso de ferramentas pré-construídas quanto a criação de ferramentas personalizadas. + +### Como o PraisonAI Implementa Ferramentas + +1. **Definição da Ferramenta:** + Uma ferramenta é tipicamente definida como uma função (em Python, por exemplo) que realiza uma ação específica. Crucialmente, a ferramenta deve ter uma **descrição clara** de seu propósito, argumentos e o que ela retorna. Essa descrição é usada pelo LLM para entender como e quando usar a ferramenta. + +2. **Atribuição ao Agente:** + As ferramentas são disponibilizadas para um agente. O agente, ao processar uma tarefa, pode então "decidir" usar uma de suas ferramentas disponíveis se julgar necessário. + +3. **Invocação pelo Agente (LLM):** + Quando o LLM do agente determina que uma ferramenta é necessária, ele geralmente formata uma "chamada de função" (function call) especificando o nome da ferramenta e os argumentos. O framework (PraisonAI) intercepta essa chamada, executa a função da ferramenta correspondente com os argumentos fornecidos, e retorna o resultado da ferramenta para o LLM. O LLM então usa esse resultado para continuar seu processo de pensamento e gerar a resposta final ou a próxima ação. + +### Usando Ferramentas Embutidas + +PraisonAI facilita o uso de muitas ferramentas comuns. A forma exata de habilitá-las pode variar: + +* **Automaticamente Disponíveis:** Algumas ferramentas básicas podem estar disponíveis por padrão para certos tipos de agentes. +* **Especificadas na Configuração YAML:** + ```yaml + # Exemplo conceitual em YAML + roles: + pesquisador_web: + role: Pesquisador Web + goal: Encontrar informações relevantes na internet. + tools: + - 'tavily_search' # Nome de uma ferramenta de busca na web + - 'web_scraper' # Nome de uma ferramenta para extrair conteúdo de páginas + # ... outras configurações do agente ... + ``` +* **Adicionadas Programaticamente (Python):** + ```python + from praisonaiagents import Agent + # Supondo a existência de ferramentas definidas em algum lugar + # from praisonai.tools import minha_ferramenta_busca, minha_ferramenta_calculo + + # Exemplo conceitual + agente_com_ferramentas = Agent( + role="Assistente Versátil", + goal="Resolver problemas usando informações da web e cálculos.", + # A forma de passar ferramentas pode variar; pode ser uma lista de funções, + # instâncias de classes de ferramentas, ou nomes de ferramentas registradas. + tools=[minha_ferramenta_busca, minha_ferramenta_calculo] + ) + ``` + > Consulte os exemplos em `examples/python/tools/` e `examples/python/general/example_custom_tools.py` para a sintaxe correta de como definir e atribuir ferramentas. O PraisonAI também se integra com ferramentas do LangChain, o que expande enormemente as opções. + +### Criando Ferramentas Personalizadas + +Uma das grandes vantagens do PraisonAI é a facilidade de criar suas próprias ferramentas. + +* **Em Python:** + Geralmente, você define uma função Python e a decora com um decorator específico (fornecido pelo PraisonAI ou pela biblioteca de ferramentas que ele usa, como LangChain) para expô-la como uma ferramenta. A descrição da função (docstring) é crucial, pois é o que o LLM usará para entender a ferramenta. + + *Exemplo (inspirado em `examples/python/general/example_custom_tools.py` e LangChain):* + ```python + from langchain_core.tools import tool # Exemplo usando decorator do LangChain + + @tool + def minha_ferramenta_personalizada(texto: str, numero: int) -> str: + """ + Esta ferramenta recebe um texto e um número. + Ela concatena o texto com o número e retorna a string resultante. + Use esta ferramenta quando precisar combinar uma string com um valor numérico. + """ + return f"{texto} - {numero}" + + # Depois, esta 'minha_ferramenta_personalizada' pode ser adicionada à lista de ferramentas de um agente. + # agente = Agent(tools=[minha_ferramenta_personalizada, ...]) + ``` + > A descrição dentro das aspas triplas (docstring) é fundamental! Ela deve explicar claramente o que a ferramenta faz, quais argumentos ela espera e o que ela retorna. O LLM usa essa informação para decidir se e como usar a ferramenta. + +### O Papel do LLM na Utilização de Ferramentas (Function Calling / Tool Using) + +Modelos de LLM modernos (como os da OpenAI, Gemini, etc.) foram treinados com a capacidade de "function calling" ou "tool using". Isso significa que, dada uma lista de ferramentas disponíveis (com suas descrições e esquemas de argumentos), o LLM pode: + +1. Entender a pergunta do usuário ou a tarefa atual. +2. Determinar se alguma das ferramentas disponíveis pode ajudar a responder à pergunta ou realizar a tarefa. +3. Se sim, gerar uma estrutura de dados (geralmente JSON) que especifica qual ferramenta chamar e com quais argumentos. +4. Receber o resultado da execução da ferramenta e usar essa informação para formular a resposta final. + +O PraisonAI gerencia esse fluxo de interação entre o LLM e as ferramentas. + +## Fundamentos por Trás + +* **Planejamento Automatizado:** A capacidade de um agente de decompor um problema e identificar que precisa de uma capacidade externa (ferramenta) para uma sub-etapa. +* **Integração de Sistemas:** Ferramentas são a ponte entre o mundo abstrato do LLM e sistemas ou fontes de dados concretos. +* **Extensibilidade:** Permitem que o comportamento dos agentes seja estendido dinamicamente sem retreinar o LLM. + +Dominar o uso e a criação de ferramentas é essencial para construir agentes PraisonAI verdadeiramente poderosos e capazes de resolver problemas do mundo real. + +Em seguida, veremos como a **Memória** permite que os agentes mantenham o contexto e aprendam com interações passadas. diff --git a/docs_translations/pt-br/02_conceitos_fundamentais/05_memoria.md b/docs_translations/pt-br/02_conceitos_fundamentais/05_memoria.md new file mode 100644 index 000000000..73b9d5cd8 --- /dev/null +++ b/docs_translations/pt-br/02_conceitos_fundamentais/05_memoria.md @@ -0,0 +1,128 @@ +# Conceito Fundamental: Memória (Memory) + +Para que os [Agentes](./01_agentes.md) do PraisonAI tenham conversas coerentes, aprendam com interações passadas e mantenham o contexto ao longo de [Tarefas](./02_tarefas.md) complexas, eles precisam de **Memória (Memory)**. A memória é um componente crucial que eleva os agentes de simples processadores de comandos para assistentes mais inteligentes e contextuais. + +## O que é Memória para Agentes de IA? + +No contexto de Agentes de IA e LLMs, Memória refere-se à capacidade do sistema de **armazenar, reter e recuperar informações de interações ou experiências passadas**. Sem memória, cada interação com um agente seria isolada, e o agente não teria conhecimento do que foi dito ou feito anteriormente. + +**Tipos Comuns de Memória em Agentes:** + +1. **Memória de Curto Prazo (Short-Term Memory):** + * **Propósito:** Manter o contexto da conversa ou sessão atual. É como a "memória de trabalho" de um humano. + * **Implementação Comum:** Armazenar um histórico das últimas N interações (perguntas e respostas) e fornecê-lo como parte do prompt para o LLM a cada nova interação. Isso é frequentemente chamado de "janela de contexto deslizante" (sliding context window). + * **Limitações:** O tamanho da janela de contexto dos LLMs é finito. Para conversas muito longas, informações mais antigas podem ser perdidas. + +2. **Memória de Longo Prazo (Long-Term Memory):** + * **Propósito:** Permitir que o agente retenha informações importantes, fatos aprendidos, preferências do usuário ou resumos de conversas passadas por um período indefinido. + * **Implementação Comum:** + * **Bancos de Dados Vetoriais (Vector Databases):** Informações textuais são convertidas em embeddings (vetores numéricos) e armazenadas. Quando necessário, a pergunta atual do usuário ou o contexto da tarefa é usado para buscar semanticamente informações relevantes no banco de dados vetorial. O PraisonAI menciona integração com Mem0, que é um exemplo de memória de longo prazo inteligente. + * **Bancos de Dados Tradicionais (SQL, NoSQL):** Para armazenar dados estruturados ou semi-estruturados sobre o usuário ou o domínio. + * **Resumos de Conversas:** Agentes podem ser programados para resumir conversas periodicamente e armazenar esses resumos na memória de longo prazo. + +## Memória no PraisonAI + +PraisonAI enfatiza a importância da memória para seus agentes, listando "Agentes com Memória de Curto e Longo Prazo" como um recurso chave. + +### Como o PraisonAI Implementa a Memória + +A implementação específica pode variar dependendo da configuração e dos componentes usados, mas geralmente envolve: + +* **Gerenciamento Automático de Histórico (Curto Prazo):** O framework provavelmente lida com o histórico da conversa atual, enviando-o ao LLM conforme necessário, dentro dos limites da janela de contexto do modelo. + +* **Integração com Sistemas de Memória Externa (Longo Prazo):** + * **Bancos de Dados Vetoriais:** Para buscas semânticas e recuperação de informações relevantes de um grande corpus de dados ou de conversas passadas. Exemplos de Vector DBs incluem Pinecone, Weaviate, ChromaDB, FAISS. + * **Mem0:** O PraisonAI menciona especificamente a integração com [Mem0](https://mem0.ai/), uma plataforma de memória inteligente como serviço (MaaS) projetada para LLMs, que visa fornecer memória persistente e contextual de forma eficiente. + * **Outras Soluções:** Pode incluir o uso de bancos de dados relacionais ou NoSQL para armazenar perfis de usuário, preferências ou outros dados estruturados que o agente precise lembrar. + +### Configurando e Usando a Memória + +* **Programaticamente (Python):** + Ao definir um agente ou um "crew" (time de agentes), você pode configurar o tipo de memória a ser usado. + ```python + from praisonaiagents import Agent # ou de onde vier a classe Agent + # from praisonai.memory import AlgumModuloDeMemoria # Exemplo conceitual + + # Exemplo conceitual de como a memória poderia ser atribuída + agente_com_memoria = Agent( + role="Assistente Pessoal", + goal="Lembrar minhas preferências e histórico de pedidos.", + # ... + memory=True, # Habilita a memória padrão (curto prazo) + # long_term_memory_handler=MeuHandlerDeMemoriaMem0(), # Exemplo para longo prazo + # vector_database_config={...} # Outra forma de configurar + ) + + # O agente usaria a memória automaticamente ao processar tarefas + # agente_com_memoria.start("Lembre-se que minha cor favorita é azul.") + # agente_com_memoria.start("Qual é a minha cor favorita?") + ``` + > A sintaxe exata e as opções de configuração da memória podem ser encontradas nos exemplos do PraisonAI, como `examples/python/general/memory_example.py` ou `memory_simple.py`, e na documentação da API. + +* **Declarativamente (YAML):** + Em arquivos YAML, pode haver seções ou propriedades para configurar a memória dos agentes ou do workflow. + ```yaml + # Exemplo conceitual em YAML + roles: + assistente_pessoal: + role: Assistente Pessoal + goal: Lembrar preferências e histórico. + memory: + enabled: true + type: mem0 # ou 'vector_db', 'short_term_default' + # config: # Configurações específicas para o tipo de memória + # api_key: "sua_chave_mem0_aqui" + # user_id: "usuario123" + # ... + ``` + +### O Diagrama "AI Agents with Memory" do README + +O `README.md` principal do PraisonAI inclui um diagrama útil: + +```mermaid +flowchart TB + subgraph Memoria ["Memoria"] + direction TB + MCP["Curto Prazo"] + MLP["Longo Prazo"] + end + subgraph Armazenamento ["Armazenamento"] + direction TB + BD["(Vector DB)"] + end + Entrada["Entrada"] ---> Agentes + subgraph Agentes + direction LR + A1["Agente 1"] + A2["Agente 2"] + A3["Agente 3"] + end + Agentes ---> Saida["Saida"] + Memoria <--> Armazenamento + Armazenamento <--> A1 + Armazenamento <--> A2 + Armazenamento <--> A3 + style Memoria fill:#189AB4,color:#fff + style Armazenamento fill:#2E8B57,color:#fff + style Agentes fill:#8B0000,color:#fff + style Entrada fill:#8B0000,color:#fff + style Saida fill:#8B0000,color:#fff +``` +* **Interpretação:** + * Os **Agentes** recebem uma **Entrada**. + * Eles têm acesso à **Memória**, que é dividida em **Curto Prazo** e **Longo Prazo**. + * A **Memória de Longo Prazo** é frequentemente suportada por um **Armazenamento** externo, como um **Banco de Dados Vetorial (Vector DB)**. + * Há uma interação bidirecional entre a Memória e o Armazenamento (dados são salvos e recuperados). + * Os Agentes também interagem bidirecionalmente com o Armazenamento (ou com a camada de Memória que gerencia o armazenamento). + * Com base na entrada e nas informações recuperadas da memória, os Agentes produzem uma **Saída**. + +## Fundamentos por Trás + +* **Psicologia Cognitiva:** Os conceitos de memória de curto e longo prazo em IA são inspirados em modelos da memória humana. +* **Recuperação de Informação (Information Retrieval):** Técnicas para buscar eficientemente dados relevantes em grandes armazenamentos, especialmente buscas semânticas usando embeddings. +* **Gerenciamento de Contexto:** Estratégias para manter o fluxo da conversa e fornecer ao LLM as informações necessárias para gerar respostas relevantes e coerentes. + +Uma memória eficaz é o que permite aos agentes PraisonAI construir relacionamentos de longo prazo com os usuários, aprender com as interações e realizar tarefas complexas que exigem a lembrança de informações ao longo do tempo. + +O próximo conceito fundamental é **Conhecimento (Knowledge)** e como ele se relaciona com RAG (Retrieval Augmented Generation). diff --git a/docs_translations/pt-br/02_conceitos_fundamentais/06_conhecimento_rag.md b/docs_translations/pt-br/02_conceitos_fundamentais/06_conhecimento_rag.md new file mode 100644 index 000000000..a8452ef72 --- /dev/null +++ b/docs_translations/pt-br/02_conceitos_fundamentais/06_conhecimento_rag.md @@ -0,0 +1,127 @@ +# Conceito Fundamental: Conhecimento (Knowledge) e RAG + +Além da [Memória](./05_memoria.md) para conversas e interações, os [Agentes](./01_agentes.md) do PraisonAI frequentemente precisam acessar e utilizar um corpo de **Conhecimento (Knowledge)** específico para realizar suas [Tarefas](./02_tarefas.md) de forma eficaz. Uma técnica poderosa para isso é a **Retrieval Augmented Generation (RAG)**. + +## O que é Conhecimento no Contexto de Agentes de IA? + +Conhecimento, neste contexto, refere-se a um conjunto de informações, dados ou documentos que um agente pode consultar para: + +* Responder a perguntas factuais. +* Obter contexto específico sobre um domínio. +* Basear suas respostas e ações em informações atualizadas ou proprietárias. + +Os Modelos de Linguagem Grande (LLMs) são pré-treinados em vastas quantidades de texto da internet, mas esse conhecimento: + +1. **Não é atualizado em tempo real:** O conhecimento do LLM "congela" na data em que foi treinado. +2. **Não inclui dados privados ou proprietários:** LLMs públicos não conhecem os documentos internos da sua empresa, por exemplo. +3. **Pode "alucinar":** Às vezes, os LLMs podem gerar informações que parecem plausíveis, mas são factualmente incorretas. + +Fornecer aos agentes acesso a uma base de conhecimento externa ajuda a mitigar esses problemas. + +## RAG (Retrieval Augmented Generation) + +**RAG** é uma arquitetura que combina as capacidades de geração de texto dos LLMs com um sistema de recuperação de informação. Em vez de depender apenas do conhecimento interno do LLM, o processo RAG funciona da seguinte forma: + +1. **Pergunta/Consulta do Usuário:** O usuário faz uma pergunta ou atribui uma tarefa ao agente. +2. **Recuperação (Retrieval):** + * A consulta do usuário é usada para buscar informações relevantes em uma base de conhecimento externa (ex: um conjunto de documentos, uma base de dados, artigos da Wikipedia). + * Essa busca é frequentemente realizada usando **embeddings e bancos de dados vetoriais**. A consulta e os documentos na base de conhecimento são convertidos em vetores, e o sistema busca os documentos cujos vetores são mais "próximos" (semanticamente similares) ao vetor da consulta. +3. **Aumento (Augmentation):** + * Os trechos de informação mais relevantes recuperados da base de conhecimento são combinados com o prompt original do usuário. +4. **Geração (Generation):** + * O prompt aumentado (contendo a pergunta original + os dados recuperados) é então enviado ao LLM. + * O LLM utiliza tanto seu conhecimento interno quanto as informações contextuais fornecidas para gerar uma resposta mais precisa, relevante e baseada nos fatos recuperados. + +**Benefícios do RAG:** + +* **Respostas Mais Precisas e Factuais:** Reduz as alucinações, pois as respostas são ancoradas em dados recuperados. +* **Acesso a Conhecimento Atualizado:** A base de conhecimento pode ser atualizada independentemente do LLM. +* **Uso de Dados Proprietários:** Permite que os agentes utilizem informações específicas de um domínio ou organização. +* **Transparência:** É possível (e muitas vezes implementado) citar as fontes de onde a informação foi recuperada, aumentando a confiança na resposta do agente. + +## Conhecimento e RAG no PraisonAI + +PraisonAI destaca "Adicionar Conhecimento Personalizado" e "RAG Agents" como recursos importantes, indicando suporte robusto para essa arquitetura. + +### Como o PraisonAI Implementa Conhecimento e RAG + +A implementação geralmente envolve: + +1. **Preparação da Base de Conhecimento:** + * **Coleta de Documentos:** Reunir os documentos relevantes (PDFs, TXTs, páginas web, etc.). + * **Chunking (Fragmentação):** Dividir documentos longos em pedaços menores (chunks) para processamento e recuperação mais eficientes. + * **Embedding e Indexação:** Gerar embeddings para cada chunk e armazená-los em um banco de dados vetorial (Vector DB) para busca rápida. PraisonAI pode integrar-se com várias soluções de Vector DB. + +2. **Configuração do Agente RAG:** + * O agente é configurado para usar um processo RAG. Isso significa que, ao receber uma consulta, ele primeiro acionará o mecanismo de recuperação antes de chamar o LLM. + * Pode envolver a especificação do Vector DB a ser usado, como as consultas devem ser transformadas em embeddings, e como os resultados recuperados devem ser formatados no prompt para o LLM. + +### Exemplos e Uso + +* **Programaticamente (Python):** + Você provavelmente configuraria um `Retriever` (componente responsável pela busca no Vector DB) e o associaria a um agente ou a uma cadeia (chain) que implementa o fluxo RAG. + ```python + # Exemplo conceitual usando componentes comuns em RAG + from praisonaiagents import Agent + # from langchain.vectorstores import Chroma # Exemplo de Vector DB + # from langchain.embeddings import OpenAIEmbeddings # Exemplo de modelo de embedding + # from langchain.text_splitter import RecursiveCharacterTextSplitter + # from langchain.chains import RetrievalQA + + # 1. Carregar e preparar documentos (splitting, embedding, storing in Vector DB) + # ... (código para popular seu Vector DB com seus documentos) ... + # vector_store = Chroma(persist_directory="./chroma_db", embedding_function=OpenAIEmbeddings()) + # retriever = vector_store.as_retriever() + + # 2. Criar um agente ou cadeia RAG + # agente_rag = Agent( + # role="Especialista em Documentos", + # goal="Responder perguntas com base nos documentos fornecidos.", + # # ... + # # A forma de integrar o retriever pode variar: + # # Pode ser uma ferramenta, um tipo de memória, ou uma configuração específica do agente. + # tools=[meu_retriever_tool], # Onde meu_retriever_tool usa o 'retriever' + # # ou + # # retrieval_config={'retriever': retriever, 'type': 'rag'}, + # ) + + # Ou usando uma cadeia como RetrievalQA do LangChain, que o PraisonAI pode integrar + # qa_chain = RetrievalQA.from_chain_type(llm=meu_llm, chain_type="stuff", retriever=retriever) + # resultado = qa_chain.run("Qual é o principal tópico do documento X?") + ``` + > Veja exemplos como `examples/python/concepts/rag-agents.py` e `examples/python/concepts/knowledge-agents.py` no repositório PraisonAI para implementações concretas. + +* **Declarativamente (YAML):** + Arquivos YAML podem permitir a especificação de fontes de conhecimento, configurações de Vector DBs ou a ativação de um modo RAG para certos agentes. + ```yaml + # Exemplo conceitual em YAML + roles: + especialista_documentos: + role: Especialista em Documentos + goal: Responder perguntas com base em nossa base de conhecimento interna. + knowledge_base: + type: chroma_db # Ou outro tipo de Vector DB + path: "./minha_base_de_conhecimento_vectorial" + embedding_model: "text-embedding-ada-002" # Modelo para gerar embeddings + # ... + tasks: + responder_pergunta_documento: + description: "Com base no documento 'manual_produto_v2.pdf', qual é o procedimento para resetar o dispositivo?" + expected_output: "Uma explicação clara do procedimento de reset, citando a página se possível." + # O agente usaria sua knowledge_base configurada para responder. + ``` + +### "Chat with PDF Agents" + +Este é um caso de uso específico do RAG. O agente é configurado para usar um ou mais arquivos PDF como sua base de conhecimento. O PraisonAI simplifica a criação desses agentes, provavelmente lidando com o parsing do PDF, chunking, embedding e o fluxo RAG nos bastidores. + +## Fundamentos por Trás + +* **Recuperação de Informação (Information Retrieval):** A ciência de buscar informações em grandes coleções de dados. +* **Processamento de Linguagem Natural (PLN):** Técnicas para processar e entender texto, incluindo a geração de embeddings. +* **Bancos de Dados Vetoriais:** Sistemas otimizados para armazenar e pesquisar vetores de alta dimensionalidade. +* **Arquiteturas de LLM:** Compreender como os LLMs processam prompts e como o contexto adicional (dos documentos recuperados) influencia a geração. + +A capacidade de integrar conhecimento externo através de RAG torna os agentes PraisonAI significativamente mais poderosos, permitindo que eles operem com informações específicas do domínio, atualizadas e verificáveis. + +Isso conclui nossa exploração dos conceitos fundamentais! A seguir, veremos como usar o PraisonAI na prática. diff --git a/docs_translations/pt-br/03_usando_praisonai/01_usando_com_python.md b/docs_translations/pt-br/03_usando_praisonai/01_usando_com_python.md new file mode 100644 index 000000000..73c4bff4d --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/01_usando_com_python.md @@ -0,0 +1,150 @@ +# Usando o PraisonAI com Python (`praisonaiagents`) + +A biblioteca `praisonaiagents` é o coração do PraisonAI para quem deseja construir e interagir com agentes de IA usando a linguagem Python. Ela oferece uma interface flexível e poderosa para definir agentes, suas tarefas, ferramentas e como eles colaboram. + +## Configuração Inicial + +Antes de começar, certifique-se de que você tem: +1. O pacote `praisonaiagents` instalado (veja o [Guia de Instalação](./../01_instalacao/00_instalacao_windows.md)). +2. Sua chave de API do OpenAI (ou de outro provedor de LLM suportado) configurada como uma variável de ambiente (ex: `OPENAI_API_KEY`). + +## Criando um Agente Simples (Single Agent) + +Um agente simples é um agente individual designado para realizar uma ou mais tarefas sem necessariamente colaborar com outros agentes. + +O `README.md` principal do PraisonAI fornece um exemplo claro: + +```python +from praisonaiagents import Agent + +# Crie uma instância do Agente +# As instruções (instructions) são o prompt principal que define o comportamento do agente. +agente = Agent(instructions="Você é um assistente de IA prestativo.") + +# Inicie o agente com uma tarefa/pergunta específica +# O método start() envia a string como a primeira tarefa/prompt para o agente. +resultado = agente.start("Escreva um roteiro de filme sobre um robô em Marte.") + +print(resultado) +``` + +**Desmembrando o Código:** + +* `from praisonaiagents import Agent`: Importa a classe `Agent` principal. +* `agente = Agent(instructions="...")`: Cria uma instância do agente. O parâmetro `instructions` é crucial, pois define a persona e o comportamento geral do agente. Você pode (e deve) ser muito mais específico em suas instruções para obter melhores resultados. Outros parâmetros importantes ao criar um `Agent` incluem: + * `role` (str): O papel do agente (ex: "Analista de Marketing"). + * `goal` (str): O objetivo principal do agente. + * `backstory` (str): Uma história de fundo para dar mais contexto ao LLM. + * `llm` (any): Permite especificar o modelo de LLM a ser usado (ex: instâncias de modelos da OpenAI, Ollama, etc.). Se não especificado, usará um padrão (geralmente baseado em OpenAI). + * `tools` (list): Uma lista de [ferramentas](./../02_conceitos_fundamentais/04_ferramentas.md) que o agente pode usar. + * `memory` (bool): Se o agente deve usar [memória](./../02_conceitos_fundamentais/05_memoria.md). + * `max_iter` (int): Número máximo de iterações que o agente pode executar (útil para evitar loops infinitos). + * `max_rpm` (int): Número máximo de requisições por minuto (para controle de custos/limites de API). + * `verbose` (bool): Se deve imprimir logs detalhados da execução do agente. + * `allow_delegation` (bool): Se este agente pode delegar tarefas para outros agentes (relevante em sistemas multi-agente). +* `resultado = agente.start("...")`: Este método inicia a execução do agente com a string fornecida como a primeira solicitação ou tarefa. O agente processará essa solicitação com base em suas instruções e LLM configurado. + +**Exemplo Mais Detalhado (`examples/python/agents/single-agent.py`):** + +O repositório PraisonAI contém exemplos mais elaborados. O arquivo `examples/python/agents/single-agent.py` mostra um agente roteirista: + +```python +# (Conteúdo adaptado de examples/python/agents/single-agent.py) +from praisonaiagents import Agent +from praisonaiagents.common.log_adapter import get_logger + +logger = get_logger(__name__) + +# Supondo que OPENAI_API_KEY está configurada +screenwriter_agent = Agent( + role="Roteirista Criativo", + goal="Escrever um roteiro de filme envolvente sobre um tema específico.", + backstory="Você é um roteirista renomado, conhecido por sua habilidade em criar narrativas cativantes e diálogos impactantes.", + instructions="Sua tarefa é desenvolver um roteiro completo para um filme sobre robôs explorando Marte. O roteiro deve incluir descrições de cena, diálogos e desenvolvimento de personagens.", + # llm="gpt-4", # Você pode especificar o modelo + verbose=True, + allow_delegation=False +) + +# Para executar a tarefa principal conforme definido no 'goal' e 'instructions' +# A string passada para start() pode refinar ou iniciar a tarefa. +final_script = screenwriter_agent.start( + "Desenvolva o roteiro sobre robôs em Marte, focando em um robô que desenvolve autoconsciência." +) + +logger.info(f"Roteiro Final Gerado:\n{final_script}") +``` +> **Para Rodar:** Navegue até a pasta `examples/python/agents/` no seu terminal (após clonar o repositório PraisonAI) e execute `python single-agent.py`. Certifique-se de ter suas credenciais de LLM configuradas. + +## Criando Múltiplos Agentes (Multi Agents) + +A verdadeira força do PraisonAI reside na capacidade de orquestrar múltiplos agentes que colaboram para resolver problemas complexos. + +O `README.md` principal também ilustra isso: + +```python +from praisonaiagents import Agent, PraisonAIAgents # PraisonAIAgents é o orquestrador + +# Agente 1: Pesquisador +agente_pesquisador = Agent( + instructions="Pesquise sobre os últimos avanços em Inteligência Artificial generativa.", + role="Pesquisador de IA", + goal="Coletar informações e artigos recentes sobre IA generativa." + # Você pode adicionar ferramentas de busca web aqui +) + +# Agente 2: Sumarizador +agente_sumarizador = Agent( + instructions="Sumarize as descobertas do agente pesquisador de forma concisa.", + role="Escritor Técnico", + goal="Produzir um resumo claro e informativo baseado na pesquisa fornecida." +) + +# Crie uma instância do orquestrador PraisonAIAgents +# A ordem na lista pode influenciar a execução em processos sequenciais. +sistema_multi_agente = PraisonAIAgents( + agents=[agente_pesquisador, agente_sumarizador] + # Você pode definir 'tasks' aqui também, ou elas podem ser inferidas + # e passadas entre os agentes dependendo do processo. +) + +# Inicie o sistema multi-agente +# O método start() do PraisonAIAgents gerenciará o fluxo entre os agentes. +# Em um processo sequencial padrão, o resultado do agente_pesquisador +# seria passado como entrada para o agente_sumarizador. +resultado_final_colaborativo = sistema_multi_agente.start() + +print(resultado_final_colaborativo) +``` + +**Desmembrando o Código Multi-Agente:** + +* `from praisonaiagents import PraisonAIAgents`: Importa a classe que gerencia um grupo de agentes. +* `agente_pesquisador = Agent(...)`, `agente_sumarizador = Agent(...)`: Define cada agente individualmente, com seus próprios papéis, objetivos e instruções. +* `sistema_multi_agente = PraisonAIAgents(agents=[...])`: Cria o "time" ou sistema de agentes. + * O construtor de `PraisonAIAgents` pode aceitar outros parâmetros importantes, como: + * `tasks` (list): Uma lista de [tarefas](./../02_conceitos_fundamentais/02_tarefas.md) a serem executadas pela equipe. Se não fornecido explicitamente, o sistema pode tentar inferir ou executar um fluxo mais simples. + * `process` (str ou Enum): Define o [processo](./../02_conceitos_fundamentais/03_processos.md) de colaboração (ex: 'sequential', 'hierarchical'). O padrão é geralmente sequencial. + * `manager_llm` (any): Se estiver usando um processo hierárquico, este LLM pode ser usado pelo agente gerente. + * `verbose` (bool): Log detalhado. +* `resultado_final_colaborativo = sistema_multi_agente.start()`: Inicia a colaboração. O `PraisonAIAgents` orquestra a passagem de informação (contexto) entre os agentes conforme o processo definido. + +### Explorando Mais Exemplos Python + +O diretório `examples/python/` no repositório PraisonAI é rico em exemplos que demonstram diversas funcionalidades: + +* **`examples/python/general/`**: Contém exemplos de conceitos como: + * `async_example*.py`: Execução assíncrona de agentes/tarefas. + * `auto_agents_example.py`: Demonstração de "Auto Agents". + * `example_custom_tools.py`: Como definir e usar ferramentas personalizadas. + * `memory_example.py` e `memory_simple.py`: Uso de memória. + * `workflow_example_basic.py` e `workflow_example_detailed.py`: Definição de workflows de agentes. +* **`examples/python/agents/`**: Diferentes tipos de agentes especializados. Consulte [Modelos de Agentes](05_modelos_de_agentes.md) para um resumo de cada um. +* **`examples/python/concepts/`**: Implementações de RAG, processamento de CSV, etc. +* **`examples/python/usecases/`**: Soluções para casos de uso específicos como análise de sentimentos, revisão de código, etc. + +**Recomendação:** +Clone o repositório PraisonAI (`git clone https://github.com/MervinPraison/PraisonAI.git`) e explore esses exemplos. Modifique-os, execute-os e veja como diferentes configurações afetam o comportamento dos agentes. Esta é uma das melhores maneiras de aprofundar seu entendimento prático. +Se surgirem problemas durante os testes, consulte a seção [Dúvidas Frequentes](../09_duvidas_frequentes.md) para possíveis soluções. + +No próximo tópico, veremos como usar o PraisonAI de forma "No-Code" ou "Low-Code" através de arquivos de configuração YAML. Para um resumo rápido dos campos disponíveis, consulte [Configurações com YAML](./06_configuracoes_yaml.md). diff --git a/docs_translations/pt-br/03_usando_praisonai/02_usando_com_yaml.md b/docs_translations/pt-br/03_usando_praisonai/02_usando_com_yaml.md new file mode 100644 index 000000000..70e614132 --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/02_usando_com_yaml.md @@ -0,0 +1,160 @@ +# Usando o PraisonAI com YAML (No-Code / Low-Code) + +Uma das grandes vantagens do PraisonAI é sua capacidade de definir e orquestrar agentes de IA usando arquivos de configuração YAML. Essa abordagem "No-Code" ou "Low-Code" permite que usuários, mesmo sem profundo conhecimento de programação, construam sistemas de agentes complexos de forma declarativa. + +## A Interface de Linha de Comando (CLI) `praisonai` + +Para trabalhar com arquivos YAML, você usará principalmente a interface de linha de comando `praisonai`. Certifique-se de tê-la instalada (geralmente via `pip install praisonai` - veja o [Guia de Instalação](./../01_instalacao/00_instalacao_windows.md)). + +**Comandos Principais:** + +* `praisonai `: Executa a configuração de agentes definida no ``. +* `praisonai --auto "sua tarefa aqui"`: Modo de geração automática onde o PraisonAI tenta criar e executar agentes para a tarefa descrita. +* `praisonai --init "descrição da tarefa"`: Ajuda a inicializar um arquivo `agents.yaml` básico com base na descrição fornecida. +* `praisonai --version`: Mostra a versão instalada. +* `praisonai --help`: Exibe informações de ajuda e outras opções da CLI. + +## Estrutura Básica de um Arquivo YAML (`agents.yaml`) + +Um arquivo YAML para PraisonAI (comumente chamado `agents.yaml`, mas pode ter qualquer nome) define os componentes do seu sistema de agentes. Vamos analisar a estrutura com base nos exemplos do PraisonAI. + +**Exemplo Simples (adaptado do `README.md` principal):** + +```yaml +# framework: Define qual framework de agentes o PraisonAI deve utilizar por baixo dos panos. +# Pode ser 'praisonai' (nativo), 'crewai', ou 'autogen'. +framework: praisonai + +# topic: Uma variável global que pode ser usada dentro de outras strings no YAML +# usando a sintaxe {topic}. Útil para parametrizar seus agentes. +topic: "Inteligência Artificial e o Futuro do Trabalho" + +# roles: Define os diferentes agentes (ou papéis) no seu sistema. +roles: + # 'pesquisador' é um nome/identificador para este agente/papel. + pesquisador: + role: "Pesquisador Especialista em IA" # O nome formal do papel. + goal: "Conduzir pesquisas aprofundadas sobre o impacto da {topic}." + backstory: "Você é um analista de tendências tecnológicas com um olhar crítico e habilidade para encontrar informações relevantes e dados prospectivos sobre {topic}." + # instructions: (Opcional aqui, pode ser mais geral ou focado em tarefas específicas) + # llm: (Opcional) Especifica o modelo LLM para este agente. + # model: "gpt-3.5-turbo" + # temperature: 0.7 + # tools: (Opcional) Lista de ferramentas que este agente pode usar. + # - 'tavily_search' # Exemplo de ferramenta de busca + # memory: (Opcional) Configurações de memória para o agente. + # enabled: true + tasks: + # 'tarefa_coleta_dados' é um nome/identificador para esta tarefa. + tarefa_coleta_dados: + description: "Coletar artigos, estudos e opiniões de especialistas publicados nos últimos 6 meses sobre o impacto da {topic}. Identificar os principais argumentos, previsões e preocupações." + expected_output: "Um relatório compilado contendo um resumo dos principais achados, lista de fontes e trechos relevantes. O relatório deve ter no máximo 1000 palavras." + # agent: pesquisador # Opcional se a tarefa está aninhada sob o 'role' que a executa. + # async_execution: false # Se a tarefa pode ser executada de forma assíncrona. + + # Você pode definir múltiplos 'roles' (agentes) + escritor: + role: "Escritor de Conteúdo Estratégico" + goal: "Produzir um artigo de blog envolvente e informativo baseado na pesquisa sobre {topic}." + backstory: "Você é um escritor talentoso, capaz de traduzir informações complexas em conteúdo acessível e cativante para um público geral interessado em tecnologia." + tasks: + tarefa_redacao_artigo: + description: "Com base no relatório de pesquisa fornecido sobre {topic}, escrever um artigo de blog de aproximadamente 800 palavras. O artigo deve ser bem estruturado, com introdução, desenvolvimento dos pontos principais e conclusão. Usar uma linguagem clara e exemplos práticos." + expected_output: "O texto final do artigo de blog, pronto para publicação, incluindo um título chamativo e sugestões de subtítulos." + context_tasks: # Define que esta tarefa depende do resultado de outra(s). + - tarefa_coleta_dados # O resultado da 'tarefa_coleta_dados' do 'pesquisador' será passado como contexto. + +# tasks: (Opcional) Você também pode definir uma lista global de tarefas +# e atribuí-las aos agentes, especialmente útil para workflows mais complexos +# ou quando um agente gerente distribui tarefas. +# tasks: +# - name: tarefa_global_de_revisao +# agent: revisor # Supondo um agente 'revisor' definido em 'roles' +# description: "Revisar o artigo de blog final quanto à clareza, gramática e precisão." +# expected_output: "Artigo revisado com sugestões de melhoria." +# context_tasks: +# - tarefa_redacao_artigo + +# process: (Opcional) Define o tipo de processo de colaboração. +# Ex: sequential, hierarchical. Se não especificado, um padrão é usado (geralmente sequencial). +# process: sequential + +# manager_agent: (Opcional) Se estiver usando um processo hierárquico, +# especifica qual 'role' atua como o gerente. +# manager_agent: pesquisador # Exemplo +``` + +**Principais Seções do YAML:** + +* `framework` (Obrigatório): Especifica qual backend de agentes usar (`praisonai`, `crewai`, `autogen`). Isso influencia como o YAML é interpretado e quais funcionalidades estão disponíveis. +* `topic` (Opcional): Uma variável global para reutilizar texto. +* `roles` (Obrigatório): Define cada agente. + * `role` (str): O nome do papel do agente. + * `goal` (str): O objetivo principal do agente. + * `backstory` (str): Contexto para o LLM. + * `instructions` (str, Opcional): Instruções gerais para o agente. + * `llm` (dict, Opcional): Configurações do LLM (modelo, temperatura, etc.). + * `tools` (list, Opcional): Ferramentas que o agente pode usar. + * `memory` (dict, Opcional): Configurações de memória. + * `tasks` (dict, Opcional, aninhado sob um `role`): Tarefas específicas para este agente. + * `description` (str): O que a tarefa envolve. + * `expected_output` (str): O resultado esperado. + * `agent` (str, Opcional): Qual agente executa (útil se as tarefas são listadas globalmente). + * `context_tasks` (list, Opcional): Lista de nomes de tarefas das quais esta tarefa depende. O resultado dessas tarefas será passado como contexto. + * `async_execution` (bool, Opcional): Se a tarefa pode ser executada de forma assíncrona. +* `tasks` (list, Opcional, nível raiz): Uma lista global de tarefas. Útil para workflows onde um agente gerente distribui trabalho ou para definir uma sequência explícita. Cada item da lista é um dicionário com as mesmas chaves de uma tarefa aninhada (`name`, `description`, `expected_output`, `agent`, `context_tasks`, etc.). +* `process` (str, Opcional): Tipo de processo de colaboração (ex: `sequential`, `hierarchical`). +* `manager_agent` (str, Opcional): Nome do `role` que atua como gerente em processos hierárquicos. + +## Executando o Arquivo YAML + +1. Salve sua configuração em um arquivo (ex: `meus_agentes.yaml`). +2. Abra seu terminal. +3. Execute: + ```bash + praisonai meus_agentes.yaml + ``` +4. O PraisonAI irá: + * Ler e validar o arquivo YAML. + * Instanciar os agentes e tarefas definidos. + * Orquestrar a execução das tarefas pelos agentes, conforme o processo e as dependências especificadas. + * Imprimir os resultados e logs no console (o nível de detalhe pode depender de configurações `verbose` ou globais). + +## Modo Automático (`--auto`) + +Para tarefas mais simples ou para obter um ponto de partida rápido, você pode usar o modo `--auto`: + +```bash +praisonai --auto "Crie um resumo do livro 'O Pequeno Príncipe' em 3 parágrafos." +``` +O PraisonAI tentará interpretar a solicitação, possivelmente criar agentes e tarefas internamente, e executar o processo para gerar o resultado. + +## Inicializando um YAML (`--init`) + +Se você não tem certeza de como começar seu arquivo YAML, o PraisonAI pode ajudar: + +```bash +praisonai --init "Planejar uma campanha de marketing para um novo aplicativo de fitness" +``` +Isso geralmente cria um arquivo `agents.yaml` básico com uma estrutura inicial baseada na sua descrição, que você pode então refinar. + +## Vantagens da Abordagem YAML + +* **Acessibilidade:** Permite que não-programadores ou programadores com menos experiência em Python construam sistemas de IA. +* **Clareza e Legibilidade:** A estrutura declarativa do YAML pode tornar a configuração do sistema de agentes fácil de entender. +* **Configuração Rápida:** Ideal para prototipagem rápida e experimentação. +* **Reutilização:** Arquivos YAML podem servir como templates para diferentes projetos. + +## Explorando Exemplos YAML + +A pasta `examples/cookbooks/yaml/` no repositório PraisonAI é o melhor lugar para encontrar exemplos práticos e avançados de configurações YAML. Lá você encontrará diversos arquivos `.ipynb` (Jupyter Notebooks) que carregam e executam arquivos YAML para casos de uso como: + +* Geração de artigos +* Resposta automática de e-mails +* Escrita de livros +* Lançamento de produtos +* E muito mais! + +Analise esses exemplos para entender como estruturar seus próprios arquivos YAML para diferentes tipos de problemas e workflows. + +A seguir, veremos como interagir com o PraisonAI usando JavaScript e TypeScript. diff --git a/docs_translations/pt-br/03_usando_praisonai/03_usando_com_js_ts.md b/docs_translations/pt-br/03_usando_praisonai/03_usando_com_js_ts.md new file mode 100644 index 000000000..7ee152597 --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/03_usando_com_js_ts.md @@ -0,0 +1,186 @@ +# Usando o PraisonAI com JavaScript e TypeScript + +PraisonAI também oferece suporte para desenvolvimento de agentes de IA usando JavaScript e TypeScript através do pacote `praisonai` no npm. Isso permite que desenvolvedores front-end e back-end que trabalham com o ecossistema Node.js integrem o poder do PraisonAI em suas aplicações. + +## Configuração Inicial + +1. **Node.js e npm/yarn:** Certifique-se de ter o Node.js instalado. O npm (Node Package Manager) vem com o Node.js. Se preferir, você pode usar o yarn. + * Para verificar: + ```bash + node -v + npm -v + ``` + * Download Node.js: [nodejs.org](https://nodejs.org/) + +2. **Instale o pacote `praisonai`:** + * Com npm: + ```bash + npm install praisonai + ``` + * Com yarn: + ```bash + yarn add praisonai + ``` + +3. **Configure sua Chave de API:** + Assim como na versão Python, você precisará de uma chave de API para o provedor de LLM que pretende usar (ex: OpenAI). Configure-a como uma variável de ambiente: + ```bash + export OPENAI_API_KEY=sua_chave_api_aqui + ``` + Em ambientes de produção Node.js, você pode usar pacotes como `dotenv` para gerenciar variáveis de ambiente a partir de um arquivo `.env`. + +## Usando com JavaScript (CommonJS ou ES Modules) + +O `README.md` principal do PraisonAI mostra um exemplo simples em JavaScript (CommonJS): + +**Exemplo JavaScript (CommonJS - `app.js`):** +```javascript +const { Agent } = require('praisonai'); // Importa a classe Agent + +// Cria uma instância do Agente +const agent = new Agent({ + instructions: 'Você é um assistente de IA prestativo.' + // Você pode adicionar outras configurações aqui, como: + // role: "Escritor Criativo", + // goal: "Escrever uma história curta", + // llm: { provider: "openai", model: "gpt-3.5-turbo" } // Exemplo de configuração de LLM +}); + +// Define a tarefa/prompt e inicia o agente +async function runAgent() { + try { + const result = await agent.start('Escreva um roteiro de filme sobre um robô em Marte.'); + console.log(result); + } catch (error) { + console.error("Erro ao executar o agente:", error); + } +} + +runAgent(); +``` + +**Para executar (CommonJS):** +```bash +node app.js +``` + +Se estiver usando ES Modules em seu projeto Node.js (com `"type": "module"` no seu `package.json` ou usando a extensão `.mjs`): + +**Exemplo JavaScript (ES Modules - `app.mjs`):** +```javascript +import { Agent } from 'praisonai'; // Importa a classe Agent + +const agent = new Agent({ + instructions: 'Você é um assistente de IA prestativo.' +}); + +async function runAgent() { + try { + const result = await agent.start('Escreva um roteiro de filme sobre um robô em Marte.'); + console.log(result); + } catch (error) + console.error("Erro ao executar o agente:", error); + } +} + +runAgent(); +``` + +**Para executar (ES Modules):** +```bash +node app.mjs +``` + +## Usando com TypeScript + +TypeScript adiciona tipagem estática ao JavaScript, o que pode ajudar a pegar erros mais cedo e melhorar a manutenibilidade do código. O PraisonAI também suporta TypeScript. + +1. **Instale o TypeScript e tipos (se necessário):** + ```bash + npm install -D typescript @types/node + # ou + yarn add -D typescript @types/node + ``` + +2. **Crie um arquivo `tsconfig.json` (se não tiver):** + ```bash + npx tsc --init + ``` + Ajuste as configurações no `tsconfig.json` conforme necessário (ex: `target`, `module`, `outDir`). + +**Exemplo TypeScript (`app.ts`):** +```typescript +import { Agent, AgentConfig } from 'praisonai'; // Importa Agent e o tipo de configuração + +const agentConfig: AgentConfig = { + instructions: 'Você é um escritor criativo que escreve contos com emojis.', + role: "Contador de Histórias com Emojis", + goal: "Escrever uma história curta e divertida sobre um tema dado, usando emojis apropriados.", + // llm: { provider: "openai", model: "gpt-4" } // Exemplo +}; + +const agent = new Agent(agentConfig); + +async function runAgent(): Promise { + try { + const storyPrompt: string = "Escreva uma história sobre um viajante do tempo que visita dinossauros."; + const result: string | undefined = await agent.start(storyPrompt); // O resultado pode ser string ou undefined + if (result) { + console.log("História Gerada:"); + console.log(result); + } else { + console.log("O agente não retornou um resultado."); + } + } catch (error) { + console.error("Erro ao executar o agente:", error); + } +} + +runAgent(); +``` + +**Para compilar e executar (TypeScript):** + +1. Compile o código TypeScript para JavaScript: + ```bash + npx tsc + ``` + Isso criará um arquivo `app.js` no seu diretório de saída (ex: `dist/app.js`). + +2. Execute o arquivo JavaScript compilado: + ```bash + node dist/app.js + ``` + + Alternativamente, você pode usar `ts-node` para executar diretamente arquivos TypeScript (ótimo para desenvolvimento): + ```bash + npm install -D ts-node + # ou + yarn add -D ts-node + + npx ts-node app.ts + ``` + +## Funcionalidades e Limitações + +A versão JavaScript/TypeScript do PraisonAI visa espelhar a funcionalidade da versão Python, permitindo: + +* Criação de agentes com instruções, papéis, objetivos. +* Configuração de LLMs. +* Execução de tarefas. +* Potencialmente, uso de ferramentas e memória (verifique a documentação da API JS para detalhes sobre a paridade de recursos com a versão Python). + +**Onde encontrar mais detalhes:** + +* **Repositório PraisonAI (`src/praisonai-ts/`):** A pasta `src/praisonai-ts/` no repositório principal do PraisonAI contém o código-fonte da biblioteca TypeScript. Dentro dela, a subpasta `examples/` é particularmente útil: + * `src/praisonai-ts/examples/simple/`: Contém exemplos básicos. + * `src/praisonai-ts/examples/tools/`: Pode conter exemplos de como usar ferramentas. + * `src/praisonai-ts/examples/concepts/`: Pode ilustrar conceitos como memória ou workflows. +* **Documentação Oficial (`docs.praison.ai`):** Embora a documentação possa focar mais na versão Python e YAML, procure por seções específicas sobre JavaScript/TypeScript ou referências à API JS. + +**Considerações:** + +* **Paridade de Recursos:** É comum que bibliotecas com versões em múltiplas linguagens tenham uma pequena defasagem de recursos entre elas, com a versão principal (neste caso, Python) geralmente sendo a mais completa inicialmente. Sempre verifique a documentação específica da API JavaScript/TypeScript do PraisonAI para confirmar as funcionalidades disponíveis. +* **Ecossistema Node.js:** Ao usar PraisonAI com JavaScript/TypeScript, você pode aproveitar todo o ecossistema Node.js, incluindo seus frameworks web (Express, NestJS), bibliotecas e ferramentas de desenvolvimento. + +Esta introdução deve ajudá-lo a começar a usar o PraisonAI em seus projetos JavaScript e TypeScript. A exploração dos exemplos no repositório é altamente recomendada para entender melhor as capacidades e a API da versão JS/TS. diff --git a/docs_translations/pt-br/03_usando_praisonai/04_criando_seu_primeiro_agente.md b/docs_translations/pt-br/03_usando_praisonai/04_criando_seu_primeiro_agente.md new file mode 100644 index 000000000..263ea7914 --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/04_criando_seu_primeiro_agente.md @@ -0,0 +1,58 @@ +# Criando Seu Primeiro Agente + +Este guia prático mostra passo a passo como colocar um agente PraisonAI em funcionamento usando Python. Se você já instalou o pacote `praisonaiagents`, siga em frente. + +## 1. Configure o Ambiente + +1. Abra um terminal e crie uma pasta para seus testes: + ```bash + mkdir meu_primeiro_agente + cd meu_primeiro_agente + ``` +2. (Opcional) Crie e ative um ambiente virtual: + ```bash + python -m venv .venv + source .venv/bin/activate # No Windows use `.venv\Scripts\activate` + ``` +3. Instale o pacote se ainda não o fez: + ```bash + pip install praisonaiagents + ``` + +## 2. Escreva o Código do Agente + +Crie um arquivo `roteirista.py` com o seguinte conteúdo: + +```python +from praisonaiagents import Agent + +agente = Agent( + instructions="Você é um roteirista de cinema muito criativo.", + role="Roteirista", + goal="Escrever um pequeno roteiro sobre robôs em Marte." +) + +resultado = agente.start("Crie o roteiro com três cenas principais.") +print(resultado) +``` + +## 3. Execute e Analise + +No terminal, rode: +```bash +python roteirista.py +``` + +O PraisonAI conectará ao modelo LLM configurado (por padrão OpenAI) e exibirá o roteiro gerado. + +- Se estiver tudo certo, experimente alterar as instruções, o papel ou o objetivo e observe como o resultado muda. +- Consulte [Usando o PraisonAI com Python](01_usando_com_python.md) para entender todos os parâmetros disponíveis. + +## 4. Próximos Passos + +Depois de dominar este exemplo simples, explore: +- [Criando múltiplos agentes](01_usando_com_python.md#criando-múltiplos-agentes-multi-agents) +- [Definindo agentes via YAML](02_usando_com_yaml.md) +- Os notebooks em `examples/python/` para casos de uso completos. + +Bom aprendizado! diff --git a/docs_translations/pt-br/03_usando_praisonai/05_modelos_de_agentes.md b/docs_translations/pt-br/03_usando_praisonai/05_modelos_de_agentes.md new file mode 100644 index 000000000..efe17bd23 --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/05_modelos_de_agentes.md @@ -0,0 +1,137 @@ +# Modelos de Agentes Disponíveis + +Esta seção apresenta um resumo dos modelos de agentes fornecidos como exemplos no PraisonAI. Eles servem como ponto de partida para criar soluções adaptadas às suas necessidades. + +Cada agente abaixo possui um script dedicado em `examples/python/agents/`. A execução parte do mesmo princípio: instale o pacote `praisonaiagents`, configure sua chave de API do modelo de linguagem e rode o arquivo Python correspondente. + +## Agentes Especializados + +### 1. Agente Analista de Dados +Arquivo: `data-analyst-agent.py` + +Utiliza ferramentas de manipulação de CSV/Excel para ler, filtrar, agrupar e gerar insights de dados. +Execute: +```bash +python data-analyst-agent.py +``` + +### 2. Agente Financeiro +Arquivo: `finance-agent.py` + +Consulta preços, informações e histórico de ações. Útil para análises de mercado básicas. +```bash +python finance-agent.py +``` + +### 3. Agente de Pesquisa +Arquivo: `research-agent.py` + +Realiza buscas na web com `duckduckgo` e retorna resultados resumidos. +```bash +python research-agent.py +``` + +### 4. Agente de Planejamento +Arquivo: `planning-agent.py` + +Ajuda a planejar viagens ou atividades pesquisando informações relevantes on-line. +```bash +python planning-agent.py +``` + +### 5. Agente de Recomendação +Arquivo: `recommendation-agent.py` + +Gera recomendações (como filmes) a partir de buscas na web e de conhecimento prévio do LLM. +```bash +python recommendation-agent.py +``` + +### 6. Agente de Compras +Arquivo: `shopping-agent.py` + +Pesquisa produtos em diferentes sites e organiza os preços em formato de tabela. +```bash +python shopping-agent.py +``` + +### 7. Agente de Programação +Arquivo: `programming-agent.py` + +Contém ferramentas para execução de código, análise, formatação e acesso ao shell. Permite iterar no desenvolvimento de scripts. +```bash +python programming-agent.py +``` + +### 8. Agente de Markdown +Arquivo: `markdown-agent.py` + +Gera ou transforma textos em Markdown. +```bash +python markdown-agent.py +``` + +### 9. Agente de Busca na Web +Arquivo: `websearch-agent.py` + +Focado em pesquisas rápidas na internet. +```bash +python websearch-agent.py +``` + +### 10. Agente Wikipedia +Arquivo: `wikipedia-agent.py` + +Consulta a Wikipedia para reunir informações detalhadas sobre um tópico. +```bash +python wikipedia-agent.py +``` + +### 11. Agente SearxNG +Arquivo: `searxng-agent.py` + +Realiza buscas através de uma instância SearxNG (pode ser container Docker). Necessita do serviço rodando localmente. +```bash +python searxng-agent.py +``` + +### 12. Agente de Imagens +Arquivo: `image-agent.py` + +Aplica análise de imagens, podendo lidar tanto com URLs quanto com arquivos locais. +```bash +python image-agent.py +``` + +### 13. Agente de Imagem para Texto +Arquivo: `image-to-text-agent.py` + +Semelhante ao agente de imagens, mas com foco em descrever conteúdo visual (OCR/descrição). Execute: +```bash +python image-to-text-agent.py +``` + +### 14. Agente de Vídeo +Arquivo: `video-agent.py` + +Permite fornecer arquivos de vídeo para extração de informações e resumo de eventos. +```bash +python video-agent.py +``` + +### 15. Agente "Single" +Arquivo: `single-agent.py` + +Exemplo básico de um agente único com prompt simples. Ótimo ponto de partida. +```bash +python single-agent.py +``` + +## Dicas Gerais + +1. Abra um terminal na pasta `examples/python/agents`. +2. Ative seu ambiente virtual (se usar). +3. Execute o arquivo desejado conforme mostrado acima. +4. Explore e modifique os scripts para entender como cada agente opera. + +Com essas bases, você pode combinar os agentes ou adaptá-los para criar soluções personalizadas no PraisonAI. diff --git a/docs_translations/pt-br/03_usando_praisonai/06_configuracoes_yaml.md b/docs_translations/pt-br/03_usando_praisonai/06_configuracoes_yaml.md new file mode 100644 index 000000000..5e19ae705 --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/06_configuracoes_yaml.md @@ -0,0 +1,46 @@ +# Configurações com YAML + +Os arquivos YAML permitem definir agentes, tarefas e parâmetros do PraisonAI de forma declarativa. Eles são utilizados principalmente pela CLI `praisonai` para iniciar fluxos complexos sem escrever código Python. + +## Estrutura Básica + +Um YAML comum segue o formato visto em `src/praisonai/agents.yaml`: + +```yaml +framework: praisonai +process: sequential +topic: exemplo de topico +memory: false +roles: + pesquisador: + role: Researcher + goal: Obter informações sobre o tema + tasks: + pesquisa: + description: Realizar buscas e resumir resultados + expected_output: Relatório da pesquisa + tools: + - search_tool +dependencies: [] +``` + +### Principais Campos + +- **framework**: define qual biblioteca será usada (“praisonai”, “crewai” ou “autogen”). +- **process**: forma de execução (sequencial, paralelo etc.). +- **topic**: assunto ou objetivo geral dos agentes. +- **memory**: habilita ou não memória. +- **roles**: cada agente é descrito aqui com suas tarefas e ferramentas. +- **dependencies**: lista de tarefas que dependem de outras. + +## Arquivos Avançados + +O `agents-advanced.yaml` demonstra configurações mais complexas, como uso de modelos diferentes para cada agente e escrita de saída em arquivos. + +Explore esses arquivos na pasta `src/praisonai` para entender como adaptar às suas necessidades. Após ajustar o YAML, execute: + +```bash +praisonai caminho/do/arquivo.yaml +``` + +Isso carregará as configurações e iniciará o fluxo definido. diff --git a/docs_translations/pt-br/03_usando_praisonai/07_importes_e_funcoes_essenciais.md b/docs_translations/pt-br/03_usando_praisonai/07_importes_e_funcoes_essenciais.md new file mode 100644 index 000000000..cb3f4b002 --- /dev/null +++ b/docs_translations/pt-br/03_usando_praisonai/07_importes_e_funcoes_essenciais.md @@ -0,0 +1,95 @@ + +# Importações e Funções Essenciais + +Esta lição apresenta as importações mais comuns do PraisonAI para criar agentes e fluxos de trabalho. Use-a como referência rápida ao iniciar seus projetos. + +## Principais Módulos + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents, Tools +from praisonaiagents.utils import get_logger +``` + +- `Agent` define o comportamento de um agente individual. +- `Task` encapsula uma unidade de trabalho executável por um agente. +- `PraisonAIAgents` orquestra múltiplos agentes e tarefas. +- `Tools` dá acesso ao catálogo de ferramentas internas. +- `get_logger` cria um logger padronizado para acompanhar a execução. + +## Exemplo Rápido + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents, Tools +from praisonaiagents.utils import get_logger + +logger = get_logger() + +# Define a tarefa +minha_tarefa = Task( + description="Gerar resumo do texto", + tools=[Tools.SEARCH] +) + +# Define o agente +meu_agente = Agent( + role="Escritor", + goal="Produzir conteúdo de qualidade", + tasks=[minha_tarefa] +) + +# Cria o orquestrador e executa +workflow = PraisonAIAgents(agents=[meu_agente], logger=logger) +workflow.run() +``` + +O código acima demonstra como importar e iniciar rapidamente um fluxo simples com um único agente e uma tarefa. + +# Importações e Funções Essenciais para Desenvolvimento de Agentes + +Esta lição apresenta os principais módulos e utilitários usados ao trabalhar com o PraisonAI em Python. Mantenha este guia à mão como referência rápida dos `imports` mais comuns. + +## Classes Principais + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents +``` + +- `Agent`: cria um agente com instruções e configurações. +- `Task`: representa uma tarefa específica que pode ser atribuída a um agente. +- `PraisonAIAgents`: orquestra múltiplos agentes em um mesmo fluxo. + +### Ferramentas + +```python +from praisonaiagents.tools import Tool +``` + +Utilize a classe `Tool` (ou variações) para criar ferramentas personalizadas que expandem as capacidades do agente. + +### Utilidades + +```python +from praisonaiagents.common.log_adapter import get_logger +``` + +A função `get_logger(__name__)` fornece um logger padronizado para acompanhar a execução dos agentes e depurar eventuais problemas. + +## Exemplo de Uso + +```python +from praisonaiagents import Agent, Task, PraisonAIAgents +from praisonaiagents.tools import Tool +from praisonaiagents.common.log_adapter import get_logger + +logger = get_logger(__name__) + +researcher = Agent(instructions="Pesquise sobre IA") +summarizer = Agent(instructions="Resuma os resultados") +workflow = PraisonAIAgents(agents=[researcher, summarizer]) + +resultado = workflow.start("Inicie a pesquisa sobre agentes autônomos") +logger.info(resultado) +``` + +Este exemplo demonstra como importar as classes básicas e o logger para estruturar um fluxo simples com dois agentes. + diff --git a/docs_translations/pt-br/04_workflows_avancados/01_processos_colaboracao_agentes.md b/docs_translations/pt-br/04_workflows_avancados/01_processos_colaboracao_agentes.md new file mode 100644 index 000000000..b70606464 --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/01_processos_colaboracao_agentes.md @@ -0,0 +1,68 @@ +# Workflows Avançados: Processos de Colaboração entre Agentes + +No módulo de [Conceitos Fundamentais - Processos](./../02_conceitos_fundamentais/03_processos.md), introduzimos os diferentes tipos de processos que o PraisonAI utiliza para orquestrar a colaboração entre agentes: Sequencial, Hierárquico e Baseado em Workflow. Estes processos são a espinha dorsal para a construção de workflows avançados e sofisticados. + +Este tópico revisita esses processos sob a ótica da construção de sistemas multi-agente mais complexos e como eles preparam o terreno para os padrões de workflow "agênticos" que veremos a seguir. + +## Revisitando os Processos Base + +1. **Processo Sequencial (Sequential Process):** + * **Como Funciona:** Tarefas são executadas em uma ordem linear. O output de uma tarefa serve de input para a próxima. + ```mermaid + graph LR + Entrada[Entrada da Tarefa Inicial] --> A1[Agente A +(Tarefa 1)] + A1 -- Resultado 1 --> A2[Agente B +(Tarefa 2)] + A2 -- Resultado 2 --> A3[Agente C +(Tarefa 3)] + A3 -- Resultado Final --> Saida[Saída Final] + ``` + * **Configuração no PraisonAI:** + * **YAML:** Geralmente o padrão se nenhuma configuração de `process` ou `manager_agent` é especificada. A ordem das tarefas na lista (seja global ou sob um agente) e o uso de `context_tasks` definem o fluxo. + * **Python (com CrewAI):** `process=Process.sequential` ao criar a `Crew`. + * **Quando Usar:** Ideal para cadeias de processamento diretas, onde cada etapa é bem definida e depende da anterior. Ex: Ler um arquivo -> Extrair dados -> Formatar dados -> Salvar dados. + * **Limitações:** Pouca flexibilidade para lidar com variações ou decisões complexas no meio do fluxo. + +2. **Processo Hierárquico (Hierarchical Process):** + * **Como Funciona:** Um "Agente Gerente" (Manager Agent) delega tarefas para "Agentes Trabalhadores" (Worker Agents) e, opcionalmente, revisa e consolida seus resultados. + ```mermaid + graph TB + EntradaPrincipal[Entrada Principal] --> Gerente[Agente Gerente] + Gerente -- Delega Tarefa A --> Trabalhador1[Agente Trabalhador A] + Gerente -- Delega Tarefa B --> Trabalhador2[Agente Trabalhador B] + Trabalhador1 -- Resultado A --> Gerente + Trabalhador2 -- Resultado B --> Gerente + Gerente -- Consolida e Processa --> SaidaFinal[Saída Final] + ``` + * **Configuração no PraisonAI:** + * **YAML:** Definir um `manager_agent` na configuração do workflow. O agente gerente terá suas próprias instruções e lógica para delegar e processar. + * **Python (com CrewAI):** `process=Process.hierarchical`. O primeiro agente na lista de `agents` da `Crew` geralmente assume o papel de gerente, ou pode ser explicitamente definido. + * **Quando Usar:** + * Tarefas complexas que podem ser divididas em sub-tarefas especializadas. + * Quando é necessário um ponto central de controle, decisão ou revisão humana (o gerente pode ser configurado para pedir aprovação). + * Para otimizar a alocação de recursos (diferentes LLMs para gerente e trabalhadores). + * **Vantagens:** Maior flexibilidade, capacidade de lidar com erros e re-tentativas de forma mais inteligente (o gerente pode re-delegar). + +3. **Processo Baseado em Workflow (Custom Workflow Process):** + * **Como Funciona:** Permite a definição de fluxos de trabalho mais complexos, com ramificações condicionais, paralelismo e lógicas de execução personalizadas. Não se limita a uma estrutura estritamente sequencial ou hierárquica. + * **Configuração no PraisonAI:** + * **YAML:** Através da estrutura de `tasks`, `context_tasks`, e possivelmente usando a sintaxe específica do framework subjacente (`praisonai`, `crewai`, `autogen`) para definir fluxos condicionais ou paralelos. O arquivo `agents-advanced.yaml` no repositório PraisonAI é um bom exemplo de configurações mais elaboradas. + * **Python:** Construindo a lógica do workflow programaticamente, encadeando chamadas a agentes, processando resultados e tomando decisões sobre o próximo passo. + * **Quando Usar:** Para processos de negócios complexos, simulações, ou qualquer cenário que exija uma orquestração de tarefas e agentes que não se encaixe perfeitamente nos modelos sequencial ou hierárquico simples. + +## A Transição para Workflows "Agênticos" + +Os processos acima são fundamentais, mas o PraisonAI também promove o conceito de **Workflows Agênticos (Agentic Workflows)**, que são padrões mais específicos de interação e processamento de informação, muitas vezes construídos sobre ou combinando esses processos base. + +O `README.md` principal do PraisonAI ilustra vários desses padrões: + +* **Agentic Routing Workflow:** Direciona tarefas para diferentes LLMs ou agentes com base no conteúdo da tarefa. +* **Agentic Orchestrator Worker:** Um orquestrador que distribui trabalho e um sintetizador que reúne os resultados. +* **Agentic Autonomous Workflow:** Agentes que monitoram, agem e se adaptam com base no feedback do ambiente. +* **Agentic Parallelization:** Execução de tarefas em paralelo. +* **Agentic Prompt Chaining:** Encadeamento de prompts onde a saída de um LLM alimenta o próximo. +* **Agentic Evaluator Optimizer:** Um agente gera soluções, outro avalia, e o ciclo se repete. +* **Repetitive Agents:** Agentes que lidam com tarefas repetitivas em loop. + +Nos próximos tópicos deste módulo, detalharemos cada um desses padrões de workflow agêntico, mostrando como eles podem ser implementados ou conceitualizados dentro do PraisonAI, aproveitando os processos de colaboração que revisitamos aqui. Entender bem os processos sequencial, hierárquico e a flexibilidade dos workflows customizados é o primeiro passo para dominar essas técnicas avançadas. diff --git a/docs_translations/pt-br/04_workflows_avancados/02_workflow_roteamento_agentico.md b/docs_translations/pt-br/04_workflows_avancados/02_workflow_roteamento_agentico.md new file mode 100644 index 000000000..0debd51fb --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/02_workflow_roteamento_agentico.md @@ -0,0 +1,108 @@ +# Workflows Avançados: Roteamento Agêntico (Agentic Routing) + +O **Roteamento Agêntico (Agentic Routing Workflow)** é um padrão de workflow avançado onde as tarefas ou consultas são dinamicamente direcionadas para diferentes Modelos de Linguagem (LLMs) ou agentes especializados, com base no conteúdo ou na natureza da entrada. + +Este padrão é particularmente útil quando você tem acesso a múltiplos LLMs, cada um com suas próprias forças (ex: um LLM ótimo para escrita criativa, outro para análise de código, um terceiro mais rápido e barato para tarefas simples), ou quando diferentes agentes são especializados em domínios distintos. + +## Como Funciona o Roteamento Agêntico? + +O fluxo geral é: + +1. **Entrada (Input):** Uma nova tarefa, pergunta ou dado de entrada é recebido pelo sistema. +2. **Roteador (Router):** Um componente central, que pode ser ele mesmo um LLM ou um agente com lógica específica, analisa a entrada. +3. **Decisão de Roteamento:** Com base na análise, o Roteador decide qual LLM ou agente especializado é o mais adequado para processar a entrada. +4. **Delegação:** A entrada é enviada para o LLM ou agente selecionado. +5. **Processamento:** O LLM/agente selecionado processa a entrada e produz um resultado. +6. **Saída (Output):** O resultado é retornado. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada] --> Router[Roteador de Chamadas LLM] + Router -- Rota A --> LLM1[LLM/Agente A (Ex: Criativo)] + Router -- Rota B --> LLM2[LLM/Agente B (Ex: Código)] + Router -- Rota C --> LLM3[LLM/Agente C (Ex: Rápido/Simples)] + LLM1 -- Resultado A --> Out[Saída] + LLM2 -- Resultado B --> Out + LLM3 -- Resultado C --> Out + + style In fill:#8B0000,color:#fff + style Router fill:#2E8B57,color:#fff + style LLM1 fill:#189AB4,color:#fff + style LLM2 fill:#189AB4,color:#fff + style LLM3 fill:#189AB4,color:#fff + style Out fill:#8B0000,color:#fff +``` + +## Casos de Uso + +* **Otimização de Custos e Performance:** Usar LLMs menores e mais rápidos para tarefas simples e LLMs maiores e mais poderosos (e caros) apenas quando necessário. +* **Especialização de Tarefas:** Direcionar consultas sobre programação para um LLM treinado em código, perguntas sobre história para um LLM com vasto conhecimento histórico, etc. +* **Seleção de Agentes Especializados:** Em um sistema com múltiplos agentes PraisonAI, cada um com um `role` e `tools` diferentes, um roteador pode enviar a tarefa para o agente mais qualificado. +* **Tratamento de Linguagem:** Direcionar entradas em diferentes idiomas para LLMs com melhor performance naquele idioma específico. +* **Balanceamento de Carga:** Distribuir requisições entre vários LLMs idênticos para evitar sobrecarga. + +## Implementação no PraisonAI (Conceitual) + +A implementação de um Roteador Agêntico no PraisonAI pode ser feita de algumas maneiras: + +1. **Agente Roteador Dedicado (Manager Agent):** + * Você pode definir um agente PraisonAI específico para atuar como o roteador. + * **Instruções do Agente Roteador:** As instruções para este agente seriam algo como: "Dada uma tarefa, decida qual dos seguintes especialistas (Agente A, Agente B, Agente C) é o mais adequado para resolvê-la. Responda apenas com o nome do especialista." + * **Ferramentas:** Este agente não precisaria de ferramentas externas, apenas da capacidade de escolher entre opções. + * **Lógica de Workflow:** Um processo hierárquico ou um workflow customizado seria construído onde o Agente Roteador recebe a tarefa primeiro, e seu output (o nome do especialista) é usado para direcionar a tarefa para o próximo agente no fluxo. + + **Exemplo YAML Conceitual:** + ```yaml + framework: praisonai + # process: hierarchical # ou um workflow customizado + # manager_agent: roteador_principal + + roles: + roteador_principal: + role: "Coordenador de Tarefas Inteligente" + goal: "Analisar cada tarefa e designá-la ao especialista mais apropriado." + instructions: | + Você receberá uma tarefa. Sua função é decidir qual dos seguintes especialistas deve lidar com ela: + - 'escritor_criativo': Para tarefas que envolvem escrita de histórias, poemas, roteiros. + - 'programador_python': Para tarefas relacionadas a código Python, algoritmos ou scripts. + - 'assistente_geral': Para perguntas factuais simples ou tarefas gerais. + Responda APENAS com o identificador do especialista (ex: 'escritor_criativo'). + # tasks: # O roteador teria uma tarefa implícita de roteamento + + escritor_criativo: + role: "Escritor Criativo" + goal: "Gerar textos criativos e artísticos." + # ... tasks para escrita ... + + programador_python: + role: "Especialista em Python" + goal: "Resolver problemas de programação e gerar código Python." + # ... tasks para programação ... + + assistente_geral: + role: "Assistente Geral" + goal: "Responder a perguntas gerais e realizar tarefas simples." + # ... tasks gerais ... + + # A lógica do workflow (não mostrada aqui) usaria o output do 'roteador_principal' + # para enviar a tarefa original para o 'role' escolhido. + ``` + +2. **Uso de "Router Chains" (se integrado com LangChain):** + * Se o PraisonAI estiver usando LangChain por baixo dos panos, você pode aproveitar as "Router Chains" do LangChain. Essas cadeias são projetadas especificamente para analisar a entrada e direcioná-la para outra cadeia ou LLM. + * Isso envolveria definir as diferentes "rotas" (LLMs ou cadeias de destino) e os prompts que ajudam o LLM roteador a tomar a decisão. + +3. **Lógica Condicional em Workflows Customizados:** + * Em um workflow definido programaticamente (Python), você pode usar um LLM para classificar a intenção da entrada e, em seguida, usar estruturas `if/else` ou `switch` para enviar a tarefa para o agente ou LLM apropriado. + +## Considerações ao Implementar Roteamento Agêntico + +* **Qualidade do Roteamento:** A eficácia do sistema depende da capacidade do Roteador de tomar decisões precisas. Um roteamento ruim pode levar a resultados subótimos ou custos mais altos. +* **Overhead:** A etapa de roteamento adiciona uma chamada LLM (se o roteador for um LLM) ou lógica computacional, o que introduz alguma latência e custo. Isso precisa ser balanceado com os ganhos de usar o LLM/agente especializado correto. +* **Complexidade:** Configurar e manter um sistema de roteamento pode adicionar complexidade ao seu design de agentes. +* **Clareza das Descrições das Rotas:** Se o roteador é um LLM, ele precisa de descrições claras de cada rota/especialista para tomar boas decisões (semelhante a como os agentes usam descrições de ferramentas). + +O Roteamento Agêntico é uma técnica poderosa para construir sistemas de IA mais eficientes, especializados e econômicos. Ao permitir que seu sistema escolha dinamicamente a melhor "ferramenta" (neste caso, o melhor LLM ou agente) para o trabalho, você pode alcançar resultados significativamente melhores. + +A seguir, exploraremos o padrão **Agentic Orchestrator Worker**. diff --git a/docs_translations/pt-br/04_workflows_avancados/03_workflow_orquestrador_trabalhador.md b/docs_translations/pt-br/04_workflows_avancados/03_workflow_orquestrador_trabalhador.md new file mode 100644 index 000000000..7e9f7497f --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/03_workflow_orquestrador_trabalhador.md @@ -0,0 +1,140 @@ +# Workflows Avançados: Orquestrador-Trabalhador Agêntico (Agentic Orchestrator Worker) + +O padrão **Orquestrador-Trabalhador Agêntico (Agentic Orchestrator Worker)** é uma evolução do conceito de [Processo Hierárquico](./01_processos_colaboracao_agentes.md#2-processo-hierárquico-hierarchical-process). Ele envolve um agente **Orquestrador** (semelhante a um gerente) que decompõe uma tarefa complexa, distribui sub-tarefas para múltiplos agentes **Trabalhadores** especializados, e depois um componente (que pode ser o próprio Orquestrador ou um agente **Sintetizador** dedicado) que coleta, analisa e combina os resultados dos trabalhadores para produzir a saída final. + +Este padrão é eficaz para problemas que podem ser paralelizados ou que se beneficiam da combinação de múltiplas perspectivas ou especialidades. + +## Como Funciona o Padrão Orquestrador-Trabalhador? + +1. **Entrada (Input):** Uma tarefa ou problema complexo é apresentado ao Orquestrador. +2. **Decomposição e Delegação (Orquestrador):** + * O Orquestrador analisa a tarefa principal e a divide em sub-tarefas menores e mais gerenciáveis. + * Ele pode usar um [Roteador Agêntico](./02_workflow_roteamento_agentico.md) interno ou sua própria lógica para designar cada sub-tarefa a um agente Trabalhador apropriado (ou a um LLM específico). Múltiplos trabalhadores podem operar em paralelo. +3. **Processamento (Trabalhadores):** + * Cada agente Trabalhador executa sua sub-tarefa designada, possivelmente usando suas próprias ferramentas e conhecimentos especializados. +4. **Coleta e Síntese (Orquestrador ou Sintetizador):** + * Os resultados das sub-tarefas executadas pelos Trabalhadores são retornados. + * O Orquestrador (ou um agente Sintetizador dedicado) coleta esses resultados parciais. + * Ele então analisa, filtra, combina e/ou resume as informações para construir uma resposta coesa e completa para a tarefa original. +5. **Saída (Output):** O resultado final consolidado é apresentado. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada Complexa] --> RouterOrchestrator[Orquestrador / Roteador de Chamadas LLM] + RouterOrchestrator -- Sub-Tarefa A --> LLM_Worker1[LLM/Agente Trabalhador A] + RouterOrchestrator -- Sub-Tarefa B --> LLM_Worker2[LLM/Agente Trabalhador B] + RouterOrchestrator -- Sub-Tarefa C --> LLM_Worker3[LLM/Agente Trabalhador C] + LLM_Worker1 -- Resultado A --> Synthesizer[Sintetizador / Orquestrador] + LLM_Worker2 -- Resultado B --> Synthesizer + LLM_Worker3 -- Resultado C --> Synthesizer + Synthesizer --> Out[Saída Final Consolidada] + + style In fill:#8B0000,color:#fff + style RouterOrchestrator fill:#2E8B57,color:#fff + style LLM_Worker1 fill:#189AB4,color:#fff + style LLM_Worker2 fill:#189AB4,color:#fff + style LLM_Worker3 fill:#189AB4,color:#fff + style Synthesizer fill:#2E8B57,color:#fff + style Out fill:#8B0000,color:#fff +``` +*No diagrama, "Router" e "Orchestrator" podem ser o mesmo agente, e o "Synthesizer" também pode ser uma função do Orquestrador ou um agente separado.* + +## Casos de Uso + +* **Relatórios de Pesquisa Abrangentes:** Um Orquestrador pode designar a diferentes Trabalhadores a tarefa de pesquisar diferentes aspectos de um tópico (ex: histórico, aplicações atuais, implicações éticas, futuro). Um Sintetizador então combina essas seções em um relatório coeso. +* **Análise de Múltiplas Fontes de Dados:** Cada Trabalhador analisa um conjunto de dados diferente; o Sintetizador integra os insights. +* **Desenvolvimento de Software Modular:** O Orquestrador define módulos de um software; diferentes Trabalhadores implementam cada módulo; o Sintetizador (ou o Orquestrador) lida com a integração. +* **Planejamento de Eventos Complexos:** Trabalhadores podem cuidar de diferentes partes do planejamento (local, catering, convidados, entretenimento), e o Orquestrador/Sintetizador monta o plano mestre. +* **Brainstorming e Geração de Ideias:** Múltiplos Trabalhadores geram ideias sobre um problema, e o Sintetizador as agrupa, filtra e prioriza. + +## Implementação no PraisonAI (Conceitual) + +A implementação deste padrão no PraisonAI geralmente envolve um processo hierárquico ou um workflow customizado: + +1. **Agente Orquestrador:** + * **Role/Goal:** "Gerente de Projeto de Pesquisa", "Arquiteto de Soluções". Seu objetivo é decompor o problema, delegar e garantir a qualidade da saída final. + * **Instructions:** Devem incluir como analisar a tarefa principal, como dividi-la, a quem delegar (com base nos `roles` dos trabalhadores disponíveis) e como os resultados devem ser sintetizados. + * **Pode usar ferramentas:** Para ajudar na decomposição ou para chamar os trabalhadores. + +2. **Agentes Trabalhadores:** + * São agentes especializados, cada um com seu `role`, `goal`, `backstory`, `instructions` e `tools` específicos para sua área de especialização. + * Ex: "Pesquisador de Dados Históricos", "Analista Financeiro", "Redator Técnico". + +3. **Agente Sintetizador (Opcional, ou função do Orquestrador):** + * Se for um agente separado: + * **Role/Goal:** "Editor Chefe", "Integrador de Relatórios". Seu objetivo é pegar múltiplos inputs e criar um output unificado e de alta qualidade. + * **Instructions:** Como combinar informações de diferentes fontes, resolver conflitos, garantir consistência e formato. + +**Exemplo YAML Conceitual:** + +```yaml +framework: praisonai +# process: hierarchical # Implícito pela estrutura ou explicitado + +# manager_agent: orquestrador_pesquisa (O Orquestrador é o gerente) + +roles: + orquestrador_pesquisa: + role: "Líder de Pesquisa de Mercado" + goal: "Produzir um relatório de análise de mercado completo sobre um novo produto." + instructions: | + Você recebeu a tarefa de criar um relatório de análise de mercado. + 1. Decomponha a análise em: Análise da Concorrência, Perfil do Público-Alvo, e Análise de Tendências de Mercado. + 2. Delegue cada uma dessas seções para os especialistas apropriados: 'analista_concorrencia', 'especialista_publico', 'analista_tendencias'. + 3. Colete os relatórios parciais de cada especialista. + 4. Sintetize esses relatórios em um documento final coeso, adicionando uma introdução e uma conclusão com recomendações estratégicas. + tasks: + gerenciar_relatorio_mercado: # Tarefa principal do orquestrador + description: "Coordenar a criação do relatório de análise de mercado." + expected_output: "Relatório de análise de mercado finalizado e abrangente." + + analista_concorrencia: + role: "Analista de Concorrência" + goal: "Analisar os principais concorrentes do novo produto." + # ... instructions, tools ... + tasks: + pesquisar_concorrentes: + description: "Identificar 3 principais concorrentes, seus pontos fortes, fracos e participação de mercado." + expected_output: "Relatório detalhado sobre a concorrência." + + especialista_publico: + role: "Especialista em Público-Alvo" + goal: "Definir e analisar o público-alvo do novo produto." + # ... instructions, tools ... + tasks: + definir_personas: + description: "Criar 2-3 personas detalhadas para o público-alvo, incluindo dados demográficos, necessidades e comportamentos." + expected_output: "Documento de personas." + + analista_tendencias: + role: "Analista de Tendências de Mercado" + goal: "Identificar as principais tendências de mercado relevantes para o novo produto." + # ... instructions, tools ... + tasks: + analisar_tendencias: + description: "Pesquisar e resumir as 3 principais tendências de mercado que podem impactar o produto." + expected_output: "Sumário das tendências de mercado." + +# O workflow implícito aqui é que o 'orquestrador_pesquisa' primeiro delega as tarefas +# para os outros três agentes. Depois que eles concluem, o 'orquestrador_pesquisa' +# executa uma etapa final de síntese (que poderia ser uma tarefa separada para ele mesmo, +# usando os resultados dos outros como contexto). +``` + +## Vantagens do Padrão + +* **Paralelização:** Sub-tarefas podem ser executadas em paralelo, acelerando o tempo total de processamento. +* **Especialização:** Permite o uso de agentes ou LLMs altamente especializados para cada sub-tarefa, melhorando a qualidade. +* **Escalabilidade:** Mais trabalhadores podem ser adicionados para lidar com problemas maiores. +* **Modularidade:** O sistema é mais fácil de entender, manter e atualizar, pois os componentes são especializados. + +## Desafios + +* **Decomposição da Tarefa:** A habilidade do Orquestrador em decompor a tarefa principal de forma eficaz é crucial. +* **Síntese dos Resultados:** Combinar os resultados de múltiplos trabalhadores pode ser complexo, especialmente se houver informações conflitantes ou redundantes. O Sintetizador precisa de boas instruções ou lógica para isso. +* **Gerenciamento do Fluxo:** Coordenar múltiplos trabalhadores, lidar com possíveis falhas em sub-tarefas e gerenciar o fluxo de dados pode ser desafiador. + +O padrão Orquestrador-Trabalhador Agêntico é uma abordagem robusta para resolver problemas complexos que se beneficiam de uma abordagem de "dividir para conquistar" com múltiplos especialistas. + +A seguir, exploraremos o **Agentic Autonomous Workflow**, onde os agentes têm mais autonomia para interagir com o ambiente. diff --git a/docs_translations/pt-br/04_workflows_avancados/04_workflow_autonomo_agentico.md b/docs_translations/pt-br/04_workflows_avancados/04_workflow_autonomo_agentico.md new file mode 100644 index 000000000..b52e6568a --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/04_workflow_autonomo_agentico.md @@ -0,0 +1,117 @@ +# Workflows Avançados: Workflow Autônomo Agêntico (Agentic Autonomous Workflow) + +O **Workflow Autônomo Agêntico (Agentic Autonomous Workflow)** representa um padrão onde os agentes de IA têm um grau significativo de autonomia para interagir com um ambiente, monitorar seu estado, tomar decisões e realizar ações para atingir seus objetivos, muitas vezes em um ciclo contínuo de feedback. Este padrão é fundamental para criar sistemas que podem operar com intervenção humana mínima em ambientes dinâmicos. + +Este conceito é a base de muitos sistemas de agentes autônomos, como os popularizados por projetos como Auto-GPT ou BabyAGI, e o PraisonAI fornece os blocos de construção para implementar tais workflows. + +## Como Funciona o Workflow Autônomo? + +O ciclo de operação de um workflow autônomo geralmente envolve: + +1. **Objetivo (Goal):** O agente (ou sistema de agentes) recebe um objetivo de alto nível do usuário. +2. **Planejamento/Raciocínio (LLM):** O agente usa seu LLM para: + * Analisar o objetivo. + * Decompor o objetivo em uma série de tarefas ou etapas menores. + * Priorizar essas tarefas. + * Decidir a próxima ação a ser tomada. +3. **Ação (Action):** O agente executa a ação decidida. Isso pode envolver: + * Usar uma [ferramenta](./../02_conceitos_fundamentais/04_ferramentas.md) (ex: buscar na web, escrever em um arquivo, executar código). + * Interagir com um ambiente simulado ou real. + * Comunicar-se com outro agente. +4. **Observação/Feedback (Environment/LLM):** O agente observa o resultado de sua ação e o feedback do ambiente. + * O ambiente pode ser o resultado de uma pesquisa na web, a saída de um script, uma resposta de uma API, ou uma mudança de estado em um sistema. + * O próprio LLM pode "refletir" sobre o resultado da ação em relação ao objetivo. +5. **Adaptação/Replanejamento (LLM):** Com base na observação e no feedback, o LLM: + * Atualiza seu entendimento do estado atual. + * Avalia o progresso em direção ao objetivo. + * Replaneja as próximas tarefas ou ações, se necessário. + * Pode adicionar novas tarefas, remover tarefas antigas ou re-priorizar. +6. **Ciclo Contínuo:** O processo retorna à etapa de "Ação" (ou "Planejamento/Raciocínio" para a próxima tarefa) e continua até que o objetivo seja alcançado, um critério de parada seja atingido (ex: número máximo de iterações), ou o usuário intervenha. +7. **Intervenção Humana (Opcional):** Em muitos sistemas autônomos, há pontos onde a aprovação ou feedback humano pode ser solicitado, especialmente para ações críticas ou quando o agente está incerto. PraisonAI suporta interação humana. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + Humano[Humano (Define Objetivo Inicial)] <--> LLM_Agente[LLM/Agente (Planeja, Raciocina)] + LLM_Agente -- AÇÃO --> Ambiente[Ambiente (Ferramentas, APIs, Web)] + Ambiente -- FEEDBACK/OBSERVAÇÃO --> LLM_Agente + LLM_Agente -- Decide Próxima Ação ou --> Parar[Parar (Objetivo Atingido / Limite)] + + style Humano fill:#8B0000,color:#fff + style LLM_Agente fill:#2E8B57,color:#fff + style Ambiente fill:#189AB4,color:#fff + style Parar fill:#333,color:#fff +``` + +## Casos de Uso + +* **Pesquisa Autônoma:** Um agente que recebe um tópico de pesquisa e autonomamente busca na web, lê artigos, resume informações e compila um relatório. +* **Gerenciamento de Projetos Simples:** Um agente que acompanha o progresso de tarefas, envia lembretes e atualiza status (com as ferramentas certas). +* **Testes de Software Automatizados:** Agentes que can interagir com uma aplicação, tentar diferentes inputs e relatar bugs. +* **Robôs de Comércio (Trading Bots) Simples:** Agentes que monitoram o mercado (ambiente), tomam decisões de compra/venda com base em regras e executam negociações. +* **Aprendizagem e Exploração:** Agentes que exploram um novo software ou API para aprender suas funcionalidades. + +## Implementação no PraisonAI (Conceitual) + +Construir um workflow verdadeiramente autônomo no PraisonAI geralmente requer uma combinação de: + +1. **Um Agente Principal (ou "Master" Agent):** + * **Role/Goal:** Seu objetivo é o objetivo de alto nível fornecido pelo usuário. + * **Instructions:** Devem ser muito bem elaboradas para guiar o ciclo de planejamento, ação e reflexão. Podem incluir: + * Como decompor o objetivo. + * Como gerar uma lista de tarefas. + * Como priorizar e selecionar a próxima tarefa. + * Como usar ferramentas para executar tarefas. + * Como avaliar o resultado de uma ação. + * Como decidir se o objetivo foi alcançado. + * **Tools:** Um conjunto robusto de ferramentas é essencial (busca na web, escrita de arquivos, execução de código, etc.). + * **Memory:** Memória de curto e longo prazo para manter o controle das tarefas realizadas, informações coletadas e o plano atual. + +2. **Loop de Execução:** + * **Programaticamente (Python):** Você precisaria implementar um loop `while` ou `for` (com um número máximo de iterações) que encapsula o ciclo de: + 1. Agente decide a próxima ação/tarefa. + 2. Agente executa a ação (chama uma ferramenta). + 3. Agente recebe o resultado/feedback. + 4. Agente atualiza sua memória/lista de tarefas. + 5. Verifica a condição de parada. + * **YAML:** A configuração YAML pode definir os agentes e suas capacidades, mas o loop de execução autônomo e a lógica de replanejamento dinâmico podem ser mais complexos de expressar puramente em YAML sem um framework que explicitamente suporte esse modo (como AutoGen, que PraisonAI integra). O PraisonAI com `framework: autogen` pode ser uma via. + +3. **Gerenciamento de Tarefas:** + * O agente precisa manter uma lista de tarefas a fazer, tarefas concluídas e, possivelmente, gerar novas tarefas com base no feedback. + +**Exemplo de Lógica Interna de um Agente Autônomo (Simplificado):** + +1. **Objetivo Inicial:** "Escrever um relatório sobre os benefícios da energia solar para residências." +2. **LLM (Planejamento Inicial):** + * Tarefa 1: Pesquisar "benefícios da energia solar residencial". + * Tarefa 2: Pesquisar "custos de instalação de energia solar residencial". + * Tarefa 3: Pesquisar "incentivos governamentais para energia solar residencial". + * Tarefa 4: Estruturar o relatório (introdução, benefícios, custos, incentivos, conclusão). + * Tarefa 5: Escrever a seção de introdução. + * ... (e assim por diante) ... + * Tarefa N: Revisar o relatório completo. +3. **Ação (Tarefa 1):** Agente usa a ferramenta de busca na web com "benefícios da energia solar residencial". +4. **Observação:** Recebe links e resumos de artigos. +5. **Adaptação/Memória:** Armazena os resultados. Pode decidir que precisa refinar a busca ou que encontrou informação suficiente para essa sub-tarefa. Marca Tarefa 1 como concluída (ou parcialmente). Decide que a próxima tarefa é a Tarefa 2. +6. **Ação (Tarefa 2):** Agente usa a ferramenta de busca na web com "custos de instalação de energia solar residencial". +7. ... (o ciclo continua) ... +8. **Ação (Tarefa 5):** Agente usa uma ferramenta interna (ou apenas seu LLM) para escrever a introdução, usando os dados coletados. +9. ... +10. **Parar:** Quando todas as tarefas são concluídas e o agente (ou um agente revisor) considera o relatório satisfatório. + +## PraisonAI e Integrações (AutoGen, CrewAI) + +* **AutoGen:** O framework AutoGen da Microsoft é projetado especificamente para criar conversas e colaborações entre múltiplos agentes LLM, o que é um componente chave para workflows autônomos. Ao usar `framework: autogen` no PraisonAI, você pode estar aproveitando as capacidades do AutoGen para esse tipo de ciclo de feedback e replanejamento. +* **CrewAI:** Embora mais focado na colaboração estruturada, os agentes CrewAI dentro do PraisonAI podem ser parte de um sistema autônomo maior, onde um "agente mestre" orquestra Crews para diferentes partes do objetivo autônomo. + +## Desafios dos Workflows Autônomos + +* **Manter o Foco:** Agentes podem se desviar do objetivo original ou entrar em loops improdutivos. +* **Custo:** Múltiplas chamadas de LLM para planejamento, reflexão e execução de ferramentas podem ser caras. +* **Confiabilidade das Ferramentas:** A autonomia depende da robustez das ferramentas. +* **Controle e Segurança:** Dar autonomia total a agentes que podem executar código ou interagir com a web requer medidas de segurança cuidadosas (sandboxing, permissões limitadas). +* **Avaliação do Progresso:** É difícil para o agente (e para o desenvolvedor) saber objetivamente se está progredindo em direção a objetivos complexos e de longo prazo. + +O Workflow Autônomo Agêntico é uma das áreas mais excitantes e desafiadoras da IA com LLMs. O PraisonAI, ao fornecer uma plataforma flexível para definir agentes, ferramentas, memória e integrar-se com frameworks como AutoGen, oferece os componentes necessários para experimentar e construir esses sistemas. + +A seguir, veremos o padrão de **Paralelização Agêntica (Agentic Parallelization)**. diff --git a/docs_translations/pt-br/04_workflows_avancados/05_paralelizacao_agentica.md b/docs_translations/pt-br/04_workflows_avancados/05_paralelizacao_agentica.md new file mode 100644 index 000000000..a7cf2252d --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/05_paralelizacao_agentica.md @@ -0,0 +1,137 @@ +# Workflows Avançados: Paralelização Agêntica (Agentic Parallelization) + +A **Paralelização Agêntica (Agentic Parallelization)** é um padrão de workflow onde múltiplas tarefas ou chamadas a Modelos de Linguagem (LLMs)/agentes são executadas simultaneamente, em vez de sequencialmente. O objetivo principal é reduzir o tempo total de processamento para tarefas que podem ser divididas em partes independentes. + +Este padrão é uma forma específica do workflow [Orquestrador-Trabalhador](./03_workflow_orquestrador_trabalhador.md), com uma ênfase na execução concorrente das sub-tarefas. + +## Como Funciona a Paralelização Agêntica? + +1. **Entrada (Input) e Decomposição:** Uma tarefa principal é recebida. Um componente inicial (pode ser um Orquestrador ou um passo de pré-processamento) decompõe a tarefa principal em múltiplas sub-tarefas que podem ser processadas independentemente. +2. **Execução Paralela:** As sub-tarefas são distribuídas para diferentes LLMs ou agentes trabalhadores e são processadas ao mesmo tempo (em paralelo). +3. **Agregação/Sincronização:** Os resultados de todas as sub-tarefas paralelas são coletados por um componente Agregador ou Sincronizador. Este componente espera que todas (ou um número suficiente) das tarefas paralelas sejam concluídas. +4. **Processamento Final (Opcional):** O Agregador pode então processar os resultados combinados (ex: sumarizar, consolidar, filtrar) para produzir a saída final. +5. **Saída (Output):** O resultado final é apresentado. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada Principal] --> Decomposer[Decompositor/Orquestrador] + Decomposer -- Sub-Tarefa A --> LLM1[LLM/Agente A] + Decomposer -- Sub-Tarefa B --> LLM2[LLM/Agente B] + Decomposer -- Sub-Tarefa C --> LLM3[LLM/Agente C] + + LLM1 -- Resultado A --> Aggregator[Agregador/Sincronizador] + LLM2 -- Resultado B --> Aggregator + LLM3 -- Resultado C --> Aggregator + + Aggregator --> Out[Saída Final] + + style In fill:#8B0000,color:#fff + style Decomposer fill:#2E8B57,color:#fff + style LLM1 fill:#189AB4,color:#fff + style LLM2 fill:#189AB4,color:#fff + style LLM3 fill:#189AB4,color:#fff + style Aggregator fill:#7E57C2,color:#fff /* Cor diferente para o agregador */ + style Out fill:#8B0000,color:#fff +``` +*No diagrama, o "Decomposer" pode ser parte do Orquestrador no padrão Orquestrador-Trabalhador.* + +## Casos de Uso + +* **Processamento de Lotes (Batch Processing):** Aplicar a mesma operação a múltiplos itens de dados independentes. Ex: Traduzir vários segmentos de texto, classificar o sentimento de muitos comentários de usuários, gerar descrições para diversos produtos. +* **Coleta de Informações de Diversas Fontes:** Enviar consultas paralelas a diferentes APIs ou ferramentas de busca para coletar dados variados sobre um tópico. +* **Geração de Múltiplas Variantes:** Gerar várias versões de um texto criativo (ex: slogans, parágrafos introdutórios) em paralelo para depois selecionar a melhor. +* **Avaliação de Múltiplos Modelos/Prompts:** Enviar o mesmo prompt para diferentes LLMs (ou o mesmo LLM com diferentes configurações) em paralelo para comparar os resultados. +* **Análise Distribuída:** Dividir um grande conjunto de dados e fazer com que diferentes agentes analisem diferentes partes em paralelo. + +## Implementação no PraisonAI (Conceitual) + +A implementação da paralelização no PraisonAI pode ser alcançada através de: + +1. **Programação Assíncrona em Python:** + * A biblioteca `asyncio` do Python é fundamental para executar operações de I/O (como chamadas de API para LLMs) de forma concorrente. + * Você pode criar múltiplas tarefas `async` que chamam diferentes agentes ou LLMs e depois usar `asyncio.gather()` para esperar que todas sejam concluídas. + * PraisonAI menciona "Async & Parallel Processing" como um recurso, então provavelmente oferece abstrações ou exemplos de como fazer isso. Os arquivos `async_example*.py` em `examples/python/general/` são bons pontos de partida. + + **Exemplo Python Conceitual com `asyncio`:** + ```python + import asyncio + from praisonaiagents import Agent # Supondo que Agent suporta chamadas async + + # Supondo que 'agente_tarefa_a', 'agente_tarefa_b', 'agente_tarefa_c' + # são instâncias de Agent configuradas para suas respectivas sub-tarefas. + + async def executar_agente(agente, input_data): + # Supondo que o método start() ou um similar seja 'async' + return await agente.start(input_data) + + async def main_paralelo(): + input_a = "Dados para tarefa A" + input_b = "Dados para tarefa B" + input_c = "Dados para tarefa C" + + # Cria tarefas asyncio para cada agente + task_a = asyncio.create_task(executar_agente(agente_tarefa_a, input_a)) + task_b = asyncio.create_task(executar_agente(agente_tarefa_b, input_b)) + task_c = asyncio.create_task(executar_agente(agente_tarefa_c, input_c)) + + # Espera todos os resultados + resultados = await asyncio.gather(task_a, task_b, task_c) + + resultado_agregado = f"Resultado A: {resultados[0]}\nResultado B: {resultados[1]}\nResultado C: {resultados[2]}" + print("Resultados Agregados:") + print(resultado_agregado) + return resultado_agregado + + # if __name__ == "__main__": + # # Configurar agentes aqui (agente_tarefa_a, etc.) + # # Exemplo: + # agente_tarefa_a = Agent(instructions="Processar dados do tipo A") + # agente_tarefa_b = Agent(instructions="Processar dados do tipo B") + # agente_tarefa_c = Agent(instructions="Processar dados do tipo C") + # asyncio.run(main_paralelo()) + ``` + +2. **Configuração YAML com Suporte a `async_execution`:** + * Se o framework PraisonAI (ou o backend como CrewAI/AutoGen) suporta, tarefas podem ser marcadas para execução assíncrona no YAML. + * O orquestrador do PraisonAI precisaria então gerenciar o início dessas tarefas e a coleta de seus resultados. + + **Exemplo YAML Conceitual:** + ```yaml + framework: praisonai + # ... + tasks: + - name: sub_tarefa_alpha + agent: trabalhador_alpha + description: "Processar o item Alpha." + expected_output: "Resultado do item Alpha." + async_execution: true # Indica que pode rodar em paralelo + + - name: sub_tarefa_beta + agent: trabalhador_beta + description: "Processar o item Beta." + expected_output: "Resultado do item Beta." + async_execution: true # Indica que pode rodar em paralelo + + - name: tarefa_agregacao + agent: agregador_final + description: "Coletar os resultados de Alpha e Beta e sumarizar." + expected_output: "Sumário final." + context_tasks: [sub_tarefa_alpha, sub_tarefa_beta] # Depende da conclusão das tarefas paralelas + # async_execution: false # Esta geralmente é síncrona após as outras + ``` + *Neste exemplo, `sub_tarefa_alpha` e `sub_tarefa_beta` poderiam ser iniciadas em paralelo. A `tarefa_agregacao` só começaria após ambas serem concluídas.* + +3. **Bibliotecas de Filas de Tarefas (Task Queues):** + * Para sistemas mais robustos e distribuídos, bibliotecas como Celery (com RabbitMQ ou Redis) podem ser usadas para gerenciar a distribuição de tarefas para múltiplos workers que podem estar rodando em diferentes processos ou máquinas. O PraisonAI poderia atuar como o produtor de tarefas para tal sistema. + +## Considerações + +* **Independência das Tarefas:** A paralelização é mais eficaz quando as sub-tarefas são verdadeiramente independentes umas das outras. Se há muitas dependências, o ganho de performance pode ser limitado. +* **Overhead de Gerenciamento:** Iniciar e gerenciar múltiplas tarefas paralelas tem seu próprio overhead. Para tarefas muito pequenas, o overhead pode superar os ganhos. +* **Limites de API e Recursos:** Ao fazer múltiplas chamadas a LLMs em paralelo, esteja ciente dos limites de taxa (rate limits) da API do provedor de LLM e dos recursos computacionais disponíveis. +* **Complexidade da Agregação:** A lógica para agregar os resultados de tarefas paralelas pode ser complexa, especialmente se as tarefas podem falhar ou retornar dados em formatos ligeiramente diferentes. + +A Paralelização Agêntica é uma estratégia valiosa para otimizar a performance de workflows que envolvem múltiplas operações independentes. O suporte a `async` no PraisonAI e Python fornece uma base sólida para implementar este padrão. + +A seguir, exploraremos o **Encadeamento de Prompts Agêntico (Agentic Prompt Chaining)**. diff --git a/docs_translations/pt-br/04_workflows_avancados/06_encadeamento_prompts_agentico.md b/docs_translations/pt-br/04_workflows_avancados/06_encadeamento_prompts_agentico.md new file mode 100644 index 000000000..a9c0b6e2c --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/06_encadeamento_prompts_agentico.md @@ -0,0 +1,174 @@ +# Workflows Avançados: Encadeamento de Prompts Agêntico (Agentic Prompt Chaining) + +O **Encadeamento de Prompts Agêntico (Agentic Prompt Chaining)**, também conhecido como "Prompt Chaining" ou "Sequential Prompting", é uma técnica fundamental na construção de interações mais complexas e sofisticadas com Modelos de Linguagem (LLMs). Em vez de tentar resolver um problema com um único prompt massivo, o problema é decomposto em uma sequência de prompts menores e mais focados, onde a saída de um prompt alimenta a entrada (ou parte do contexto) do próximo. + +Este padrão é uma forma de processo sequencial, mas com ênfase na manipulação e transformação da informação através de múltiplas etapas de interação com o LLM (ou diferentes LLMs/agentes). + +## Como Funciona o Encadeamento de Prompts? + +1. **Entrada Inicial (Input):** O processo começa com uma entrada ou pergunta inicial. +2. **Primeiro LLM/Agente (LLM Call 1):** A entrada é processada pelo primeiro LLM ou agente com um prompt específico. +3. **Saída Intermediária 1:** Este LLM/agente produz uma saída. +4. **Portão/Decisão (Gate - Opcional):** Pode haver uma etapa de decisão ou validação aqui. + * **Passar (Pass):** Se a saída é satisfatória ou cumpre certas condições, ela (ou uma transformação dela) é passada para o próximo LLM/agente. + * **Falhar/Sair (Fail/Exit):** Se a saída não é satisfatória, o processo pode terminar ou seguir um caminho alternativo. +5. **Segundo LLM/Agente (LLM Call 2):** A saída intermediária alimenta o prompt do segundo LLM/agente. +6. **Saída Intermediária 2:** Este LLM/agente produz outra saída. +7. **(Repetir):** O processo pode continuar com mais chamadas LLM/agentes e portões, conforme necessário. +8. **Saída Final (Output):** A saída do último LLM/agente na cadeia é o resultado final do processo. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada Inicial] --> LLM1[LLM/Agente 1 (Prompt 1)] + LLM1 -- Saída 1 --> Gate{Portão/Decisão} + Gate -- Passar --> LLM2[LLM/Agente 2 (Prompt 2)] + LLM2 -- Saída 2 --> LLM3[LLM/Agente 3 (Prompt 3)] + LLM3 -- Saída Final --> Out[Resultado Final] + Gate -- Falhar/Alternativa --> Exit[Sair ou Rota Alternativa] + + style In fill:#8B0000,color:#fff + style LLM1 fill:#189AB4,color:#fff + style Gate fill:#FFCA28,color:#000 /* Amarelo para decisão */ + style LLM2 fill:#189AB4,color:#fff + style LLM3 fill:#189AB4,color:#fff + style Out fill:#8B0000,color:#fff + style Exit fill:#333,color:#fff +``` + +## Casos de Uso + +* **Refinamento Progressivo:** + * Prompt 1: Gerar um rascunho inicial de um texto. + * Prompt 2: Revisar o rascunho para gramática e clareza. + * Prompt 3: Adaptar o tom do texto revisado para um público específico. +* **Extração e Formatação de Dados:** + * Prompt 1: Extrair informações chave de um bloco de texto não estruturado. + * Prompt 2: Formatar as informações extraídas em JSON. +* **Tradução e Adaptação:** + * Prompt 1: Traduzir um texto para outro idioma. + * Prompt 2: Adaptar a tradução para nuances culturais ou um dialeto específico. +* **Geração de Código em Etapas:** + * Prompt 1: Descrever a funcionalidade de alto nível de uma função. + * Prompt 2: Gerar o esqueleto da função em Python com base na descrição. + * Prompt 3: Adicionar tratamento de erros e documentação à função gerada. +* **Resumo Multi-etapas:** + * Prompt 1: Identificar os pontos principais de um documento longo. + * Prompt 2: Gerar um resumo executivo com base nos pontos principais identificados. +* **Simulação de Conversa com Múltiplas Personas:** Cada "turno" da conversa pode ser um prompt, com o histórico da conversa alimentando o contexto do próximo. + +## Implementação no PraisonAI (Conceitual) + +O Encadeamento de Prompts é inerentemente suportado pela estrutura de agentes e tarefas sequenciais do PraisonAI. + +1. **Múltiplos Agentes Sequenciais:** + * Defina uma série de agentes onde cada um é especializado em uma etapa da cadeia. + * O `goal` e `instructions` de cada agente corresponderiam a um prompt específico na cadeia. + * Use o [Processo Sequencial](./01_processos_colaboracao_agentes.md#1-processo-sequencial-sequential-process) para que a saída de um agente seja automaticamente passada como contexto para o próximo. + + **Exemplo YAML Conceitual:** + ```yaml + framework: praisonai # ou crewai + process: sequential + + roles: + extrator_dados: + role: "Especialista em Extração" + goal: "Extrair nome, email e empresa de um texto de cartão de visita." + instructions: "Dado um texto, identifique e extraia o nome da pessoa, seu endereço de e-mail e o nome da empresa. Retorne apenas esses três dados, um por linha." + # tasks: # Tarefa implícita de extração + + formatador_json: + role: "Formatador JSON" + goal: "Converter dados extraídos para o formato JSON." + instructions: "Você receberá três linhas de texto: nome, email, empresa. Transforme essas informações em um objeto JSON com as chaves 'nome', 'email' e 'empresa'." + # tasks: # Tarefa implícita de formatação, usando a saída do 'extrator_dados' como contexto + + # A entrada inicial seria dada ao 'extrator_dados'. + # A saída do 'extrator_dados' seria automaticamente o input para 'formatador_json'. + ``` + +2. **Múltiplas Tarefas para um Único Agente (ou Agentes em um Workflow):** + * Defina um agente e atribua a ele uma série de tarefas sequenciais. + * A descrição de cada tarefa atuaria como um prompt na cadeia. + * Use `context_tasks` para garantir a ordem correta e a passagem de contexto. + + **Exemplo YAML Conceitual com Tarefas Explícitas:** + ```yaml + framework: praisonai + roles: + escritor_multifacetado: + role: "Assistente de Escrita Completo" + goal: "Produzir um artigo de blog bem escrito e otimizado." + # instructions gerais para o agente + + tasks: + - name: gerar_rascunho + agent: escritor_multifacetado + description: "Escreva um rascunho de 500 palavras sobre os benefícios da meditação para a produtividade." + expected_output: "Texto do rascunho inicial." + + - name: revisar_gramatica + agent: escritor_multifacetado + description: "Revise o texto fornecido (resultado do 'gerar_rascunho') para erros de gramática e ortografia. Forneça o texto corrigido." + expected_output: "Texto revisado gramaticalmente." + context_tasks: [gerar_rascunho] + + - name: otimizar_seo + agent: escritor_multifacetado + description: "Analise o texto revisado (resultado do 'revisar_gramatica') e sugira 3 palavras-chave de SEO para incorporar. Reescreva o primeiro parágrafo para incluir uma delas." + expected_output: "Primeiro parágrafo reescrito e lista de 3 palavras-chave." + context_tasks: [revisar_gramatica] + ``` + +3. **Programaticamente (Python):** + * Você pode simplesmente chamar `agente.start()` (ou um método similar) múltiplas vezes, usando a saída de uma chamada como entrada para a próxima. + * Bibliotecas como LangChain (que o PraisonAI integra) têm abstrações específicas para cadeias de prompts (ex: `SequentialChain`, `LLMChain`). + + **Exemplo Python Conceitual:** + ```python + from praisonaiagents import Agent + + # Supondo que OPENAI_API_KEY está configurada + agente_prompt1 = Agent(instructions="Traduza o seguinte texto para o francês: {texto_original}") + agente_prompt2 = Agent(instructions="Explique o significado da seguinte frase em francês em uma sentença simples em português: {frase_frances}") + + texto_ingles = "Hello, how are you today?" + + # Primeira chamada na cadeia + texto_frances = agente_prompt1.start(texto_original=texto_ingles) + # (A API do PraisonAI pode variar na forma de passar inputs nomeados para o prompt) + # Ou, mais diretamente: + # texto_frances = agente_prompt1.start(f"Traduza o seguinte texto para o francês: {texto_ingles}") + + + print(f"Texto em Francês: {texto_frances}") + + # Segunda chamada na cadeia, usando a saída da primeira + explicacao_portugues = agente_prompt2.start(frase_frances=texto_frances) + # Ou: + # explicacao_portugues = agente_prompt2.start(f"Explique o significado da seguinte frase em francês em uma sentença simples em português: {texto_frances}") + + print(f"Explicação em Português: {explicacao_portugues}") + ``` + +## Vantagens do Encadeamento de Prompts + +* **Melhora da Qualidade:** Decompor o problema permite que o LLM foque em uma sub-tarefa específica por vez, geralmente levando a resultados melhores do que um único prompt complexo. +* **Maior Controle:** Permite inspecionar e modificar saídas intermediárias. +* **Redução de Alucinações:** Prompts mais focados podem reduzir a chance de o LLM gerar informações incorretas. +* **Facilidade de Debugging:** Se algo der errado, é mais fácil identificar em qual etapa da cadeia o problema ocorreu. +* **Modularidade:** Cada prompt/agente na cadeia pode ser desenvolvido e testado independentemente. + +## "Gates" (Portões/Decisões) + +A inclusão de "gates" ou etapas de decisão entre as chamadas de LLM adiciona mais poder ao encadeamento. Um "gate" pode ser: +* Uma chamada a uma função Python que valida a saída intermediária. +* Outra chamada LLM que decide se a qualidade é suficiente para prosseguir. +* Uma solicitação de feedback humano. + +Se a saída não passar pelo "gate", o workflow pode terminar, tentar a etapa anterior novamente com um prompt modificado, ou seguir um caminho alternativo. + +O Encadeamento de Prompts Agêntico é uma técnica versátil e poderosa, fundamental para construir aplicações LLM robustas e capazes de realizar tarefas complexas em múltiplas etapas. + +A seguir, exploraremos o padrão **Avaliador-Otimizador Agêntico (Agentic Evaluator Optimizer)**. diff --git a/docs_translations/pt-br/04_workflows_avancados/07_avaliador_otimizador_agentico.md b/docs_translations/pt-br/04_workflows_avancados/07_avaliador_otimizador_agentico.md new file mode 100644 index 000000000..6871c52a5 --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/07_avaliador_otimizador_agentico.md @@ -0,0 +1,160 @@ +# Workflows Avançados: Avaliador-Otimizador Agêntico (Agentic Evaluator Optimizer) + +O padrão **Avaliador-Otimizador Agêntico (Agentic Evaluator Optimizer)**, também conhecido como ciclo Gerador-Avaliador ou Crítico-Executor, é um workflow iterativo projetado para refinar e melhorar progressivamente a qualidade de uma solução ou saída gerada por um Modelo de Linguagem (LLM) ou agente. + +Este padrão envolve pelo menos dois papéis principais (que podem ser desempenhados por diferentes LLMs/agentes ou pelo mesmo LLM com diferentes prompts): + +1. **Gerador (Generator) / Executor:** Responsável por criar uma solução inicial ou uma tentativa de resposta para um dado problema ou tarefa. +2. **Avaliador (Evaluator) / Crítico:** Responsável por analisar a solução gerada pelo Gerador, compará-la com critérios de qualidade ou objetivos, e fornecer feedback construtivo. + +## Como Funciona o Ciclo Avaliador-Otimizador? + +1. **Entrada (Input) / Problema:** O ciclo começa com um problema a ser resolvido ou uma tarefa a ser realizada. +2. **Geração (Generator):** O agente Gerador produz uma primeira versão da solução ou resposta. +3. **Avaliação (Evaluator):** A solução do Gerador é passada para o agente Avaliador. O Avaliador: + * Compara a solução com critérios pré-definidos, exemplos de boas respostas, ou o objetivo original. + * Identifica pontos fortes, fracos, erros, ou áreas para melhoria. + * Gera um feedback detalhado. +4. **Decisão:** Com base no feedback do Avaliador: + * **Aceitar:** Se a solução for considerada boa o suficiente (atinge um certo limiar de qualidade), o ciclo termina e a solução é aceita como saída final. + * **Rejeitar + Feedback (Otimizar):** Se a solução precisa de melhorias, o feedback do Avaliador é fornecido de volta ao Gerador. +5. **Re-Geração / Otimização (Generator):** O Gerador recebe a solução anterior e o feedback do Avaliador. Ele então tenta produzir uma nova versão melhorada da solução, incorporando o feedback. +6. **Loop:** O processo retorna à etapa de Avaliação (3) com a nova solução. Este ciclo iterativo continua até que a solução seja aceita ou um número máximo de iterações seja atingido. + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + In[Entrada/Problema] --> Generator[LLM/Agente Gerador] + Generator -- SOLUÇÃO v1 --> Evaluator[LLM/Agente Avaliador] + Evaluator -- ACEITA --> Out[Saída Final Aceita] + Evaluator -- REJEITADA + FEEDBACK --> Generator + + style In fill:#8B0000,color:#fff + style Generator fill:#189AB4,color:#fff + style Evaluator fill:#FFCA28,color:#000 /* Amarelo para avaliação */ + style Out fill:#8B0000,color:#fff +``` + +## Casos de Uso + +* **Escrita de Textos de Alta Qualidade:** + * Gerador: Escreve um rascunho de um artigo. + * Avaliador: Verifica clareza, coesão, gramática, tom, e se o artigo cumpre os requisitos. Fornece sugestões de reescrita. +* **Geração de Código:** + * Gerador: Escreve uma função em Python. + * Avaliador: Verifica se o código funciona, segue as boas práticas, é eficiente, e tem tratamento de erros. Pode até tentar executar o código e analisar os resultados. +* **Design de Soluções:** + * Gerador: Propõe uma arquitetura para um sistema de software. + * Avaliador: Analisa a proposta quanto a escalabilidade, segurança, custo, e manutenibilidade. +* **Resolução de Problemas Complexos:** + * Gerador: Sugere uma estratégia para resolver um problema de lógica. + * Avaliador: Verifica a validade da estratégia e aponta falhas no raciocínio. +* **Otimização de Prompts:** O próprio feedback pode ser usado para refinar o prompt original que o Gerador está usando. +* **Auto-correção / Auto-reflexão Avançada:** O PraisonAI menciona "Self Reflection AI Agents". O ciclo Avaliador-Otimizador é uma forma poderosa de implementar auto-reflexão, onde o "Avaliador" pode ser o mesmo agente Gerador, mas operando sob um prompt diferente focado na crítica e melhoria. + +## Implementação no PraisonAI (Conceitual) + +Este padrão geralmente requer um workflow que gerencia o ciclo iterativo: + +1. **Agente Gerador:** + * `role`, `goal`, `instructions` focados na criação da solução inicial. + * Pode ter ferramentas específicas para sua tarefa de geração. + +2. **Agente Avaliador:** + * `role`, `goal`, `instructions` focados na análise crítica da solução do Gerador. Suas instruções devem incluir os critérios de avaliação. + * Pode ter ferramentas para ajudar na avaliação (ex: um linter de código, uma ferramenta para verificar fatos). + +3. **Lógica de Orquestração (Pode ser um Agente Gerente ou código Python):** + * Gerencia o loop: envia a tarefa inicial para o Gerador, passa a saída para o Avaliador, passa o feedback de volta para o Gerador. + * Implementa a condição de parada (solução aceita ou máximo de iterações). + +**Exemplo YAML Conceitual (com um Agente Gerente Orquestrando):** +```yaml +framework: praisonai +# process: hierarchical ou custom workflow +# manager_agent: orquestrador_ciclo + +roles: + orquestrador_ciclo: + role: "Orquestrador do Ciclo de Melhoria" + goal: "Gerenciar o processo iterativo de geração e avaliação para produzir um código Python de alta qualidade." + instructions: | + Seu objetivo é obter uma função Python que some dois números. + 1. Delegue a tarefa de escrever a função inicial para o 'programador_junior'. + 2. Receba a função e delegue a tarefa de avaliá-la para o 'revisor_codigo_senior'. + 3. Se o 'revisor_codigo_senior' aprovar (responder com "APROVADO"), a tarefa está concluída. + 4. Se o 'revisor_codigo_senior' fornecer feedback, passe a função original E o feedback para o 'programador_junior' para uma nova tentativa. + 5. Repita os passos 2-4 no máximo 3 vezes. Se não for aprovado em 3 tentativas, encerre com a última versão e o feedback. + # tasks: ... + + programador_junior: + role: "Programador Python Junior" + goal: "Escrever código Python funcional com base nas especificações e feedback." + instructions: "Escreva uma função Python chamada 'soma' que recebe dois argumentos e retorna sua soma. Se receber feedback, use-o para corrigir e melhorar a função." + # tasks: ... + + revisor_codigo_senior: + role: "Revisor de Código Senior" + goal: "Avaliar código Python quanto à funcionalidade, clareza e boas práticas, fornecendo feedback construtivo." + instructions: | + Você receberá uma função Python. Avalie-a com base nos seguintes critérios: + - Funcionalidade: Ela soma dois números corretamente? + - Clareza: O código é fácil de entender? + - Boas Práticas: Segue as convenções do Python (PEP8)? + Se a função estiver boa, responda APENAS com a palavra "APROVADO". + Caso contrário, forneça um feedback específico sobre o que precisa ser melhorado. + # tools: # Poderia ter uma ferramenta para executar o código + # tasks: ... +``` + +**Programaticamente (Python):** +```python +from praisonaiagents import Agent # ou de onde vier Agent + +# Configurar os agentes (gerador, avaliador) +gerador = Agent(instructions="Gere um slogan para uma cafeteria.") +avaliador = Agent(instructions="Avalie o slogan: '{slogan_gerado}'. É curto, memorável e atraente? Se não, sugira melhorias. Se sim, diga 'Perfeito'.") + +slogan_atual = None +feedback = None +max_iteracoes = 3 + +for i in range(max_iteracoes): + prompt_gerador = "Gere um slogan para uma cafeteria." + if feedback: # Se houver feedback, adiciona ao prompt do gerador + prompt_gerador += f" Considere o seguinte feedback para melhoria: {feedback}" + + slogan_atual = gerador.start(prompt_gerador) + print(f"Iteração {i+1} - Slogan Gerado: {slogan_atual}") + + feedback_avaliador = avaliador.start(slogan_gerado=slogan_atual) # Passando o slogan para o prompt do avaliador + print(f"Iteração {i+1} - Feedback do Avaliador: {feedback_avaliador}") + + if "Perfeito" in feedback_avaliador: # Condição de parada + print("Slogan final aceito!") + break + + feedback = feedback_avaliador # Prepara o feedback para a próxima iteração +else: + print("Máximo de iterações atingido. Usando o último slogan gerado.") + +# Resultado final é 'slogan_atual' +``` + +## Vantagens do Padrão + +* **Melhoria da Qualidade:** A natureza iterativa e o feedback explícito geralmente levam a resultados de maior qualidade do que uma única tentativa. +* **Resolução de Problemas Complexos:** Permite abordar problemas que são difíceis de resolver corretamente na primeira tentativa. +* **Simula Processos Humanos:** Espelha como os humanos frequentemente trabalham: criar, obter feedback, refinar. +* **Customização da Avaliação:** Os critérios de avaliação podem ser altamente personalizados para a tarefa em questão. + +## Desafios + +* **Custo e Latência:** Cada iteração envolve pelo menos duas chamadas LLM (uma para o Gerador, uma para o Avaliador), o que pode aumentar o custo e o tempo de execução. +* **Qualidade do Feedback:** A eficácia do ciclo depende muito da qualidade do feedback do Avaliador. Um feedback vago ou ruim não ajudará o Gerador. +* **Convergência:** Não há garantia de que o processo sempre convergirá para uma solução perfeita. É importante ter critérios de parada (ex: número máximo de iterações, tempo limite). +* **Definição dos Critérios de Avaliação:** Criar prompts ou lógica para o Avaliador que reflitam com precisão os critérios de qualidade desejados pode ser desafiador. + +O padrão Avaliador-Otimizador Agêntico é uma técnica poderosa para alcançar resultados de alta qualidade e para tarefas que se beneficiam de um processo de refinamento iterativo. O PraisonAI, com sua capacidade de orquestrar múltiplos agentes e workflows, está bem posicionado para implementar este padrão. + +A seguir, veremos os **Agentes Repetitivos (Repetitive Agents)**. diff --git a/docs_translations/pt-br/04_workflows_avancados/08_agentes_repetitivos.md b/docs_translations/pt-br/04_workflows_avancados/08_agentes_repetitivos.md new file mode 100644 index 000000000..b55178115 --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/08_agentes_repetitivos.md @@ -0,0 +1,124 @@ +# Workflows Avançados: Agentes Repetitivos (Repetitive Agents) + +O padrão de **Agentes Repetitivos (Repetitive Agents)** refere-se a um workflow onde um ou mais agentes são projetados para executar uma tarefa específica (ou um conjunto de tarefas) múltiplas vezes, geralmente sobre diferentes conjuntos de dados de entrada ou até que uma determinada condição seja satisfeita. + +Este padrão é útil para automação de processos que envolvem a aplicação da mesma lógica a vários itens ou para tarefas que requerem monitoramento ou ação contínua. + +## Como Funcionam os Agentes Repetitivos? + +1. **Definição da Tarefa:** Uma tarefa ou um conjunto de tarefas que o agente precisa realizar é claramente definida. +2. **Entrada de Dados (Iterável):** Há uma fonte de dados ou um gatilho que fornece a entrada para cada iteração. Pode ser: + * Uma lista de itens (ex: URLs, nomes de arquivos, registros de um banco de dados). + * Um fluxo de dados contínuo (ex: novos e-mails chegando, atualizações de um feed). + * Um contador ou uma condição de tempo (ex: executar a cada hora). +3. **Loop de Execução:** O agente (ou o sistema que o gerencia) entra em um loop: + * **Obter Entrada:** Pega o próximo item da lista, lê do fluxo, ou verifica a condição de tempo/evento. + * **Executar Tarefa:** O agente executa sua tarefa definida usando a entrada atual. + * **Produzir Saída/Efeito Colateral:** O agente gera um resultado para a iteração atual ou realiza uma ação (ex: salva um arquivo, envia uma notificação). +4. **Condição de Parada:** O loop continua até que: + * Todos os itens da lista tenham sido processados. + * O fluxo de dados termine. + * Uma condição específica de parada seja atingida (ex: um erro crítico, um sinal do usuário, um número máximo de iterações). + +**Diagrama (do `README.md` do PraisonAI):** +```mermaid +flowchart LR + EntradaIteravel[Entrada / Lista de Itens / Gatilho] --> AgenteLoop[("Agente em Loop")] + AgenteLoop -- Processa Item/Evento --> Tarefa[Executa Tarefa Definida] + Tarefa -- Para Próxima Iteração / Item --> AgenteLoop + Tarefa -- Concluído / Condição de Parada --> Saida[Saída Agregada / Fim do Processo] + + style EntradaIteravel fill:#8B0000,color:#fff + style AgenteLoop fill:#2E8B57,color:#fff,shape:circle + style Tarefa fill:#189AB4,color:#fff + style Saida fill:#8B0000,color:#fff +``` + +## Casos de Uso + +* **Processamento em Lote de Arquivos:** + * Agente lê cada arquivo de uma pasta, extrai informações e salva em um banco de dados. +* **Web Scraping de Múltiplas Páginas:** + * Agente recebe uma lista de URLs, visita cada uma, extrai dados específicos e os armazena. +* **Envio de E-mails Personalizados em Massa:** + * Agente percorre uma lista de contatos, personaliza um template de e-mail para cada um e o envia. +* **Monitoramento e Alerta:** + * Agente verifica o status de um sistema a cada X minutos e envia um alerta se detectar um problema. +* **Tradução de Múltiplos Documentos:** + * Agente traduz uma série de documentos de um idioma para outro. +* **Classificação de Dados:** + * Agente analisa uma lista de comentários de clientes e classifica cada um como positivo, negativo ou neutro. + +## Implementação no PraisonAI (Conceitual) + +A implementação de agentes repetitivos no PraisonAI pode ser feita de várias formas: + +1. **Loop de Controle Externo (Python):** + * Você pode escrever um script Python que define um agente PraisonAI e, em seguida, usa um loop `for` ou `while` para chamar o método `start()` (ou similar) do agente repetidamente com diferentes dados de entrada. + + **Exemplo Python Conceitual:** + ```python + from praisonaiagents import Agent + + # Supondo que OPENAI_API_KEY está configurada + tradutor_agente = Agent( + instructions="Traduza o seguinte texto para o espanhol: {texto_para_traduzir}", + role="Tradutor Inglês-Espanhol" + ) + + lista_de_frases_ingles = [ + "Hello, world!", + "How are you?", + "This is a test." + ] + + traducoes_espanhol = [] + + for frase in lista_de_frases_ingles: + # A forma de passar o input pode variar. + # Idealmente, o agente é configurado para esperar uma variável no prompt. + # Se o método start apenas concatena, você faria: + # traducao = tradutor_agente.start(f"Traduza o seguinte texto para o espanhol: {frase}") + # Mas se o Agent suportar substituição de placeholders nas instructions: + traducao = tradutor_agente.start(texto_para_traduzir=frase) + traducoes_espanhol.append(traducao) + print(f"Inglês: {frase} -> Espanhol: {traducao}") + + # print("\nTraduções Finais:", traducoes_espanhol) + ``` + +2. **Agente com Capacidade de Iteração Interna (Menos Comum para LLMs):** + * Seria menos comum que um agente baseado em LLM gerenciasse um loop complexo internamente apenas com prompts, a menos que ele estivesse escrevendo e executando código que implementasse o loop. + * No entanto, um agente poderia ser instruído a processar uma *lista* de itens fornecida em um único prompt, se a lista não for muito grande. Ex: "Traduza as seguintes 3 frases: [frase1, frase2, frase3]". + +3. **Workflows YAML com Gatilhos ou Fontes de Dados Iteráveis:** + * Se o PraisonAI (ou o framework subjacente como AutoGen) suportar gatilhos baseados em tempo (agendamento) ou a capacidade de ler de uma fonte de dados que pode ser iterada (ex: um arquivo CSV, uma fila de mensagens), então o workflow YAML poderia ser configurado para executar repetidamente. + * O `schedule_config.yaml.example` no repositório PraisonAI sugere capacidades de agendamento, o que se alinha com tarefas repetitivas. + + **Exemplo YAML Conceitual (para um agendador hipotético):** + ```yaml + # Supondo uma configuração de agendamento no PraisonAI + schedule: + - name: "verificar_novos_pedidos_a_cada_5_minutos" + cron_expression: "*/5 * * * *" # A cada 5 minutos + workflow_yaml: "workflows/processar_pedido.yaml" # YAML que define o agente e a tarefa de processar um pedido + # input_source: "fila_de_pedidos_api" # De onde pegar o dado do pedido + ``` + +4. **Uso de Ferramentas que Gerenciam Iteração:** + * O agente pode ter uma ferramenta que, quando chamada, processa uma coleção de itens. Por exemplo, uma ferramenta `processar_lista_de_urls(urls: list)` que internamente itera sobre as URLs e realiza uma ação para cada uma. + +## Considerações para Agentes Repetitivos + +* **Gerenciamento de Estado entre Iterações:** Se o agente precisa lembrar informações de iterações anteriores (além do contexto de curto prazo), a [memória](./../02_conceitos_fundamentais/05_memoria.md) persistente é crucial. +* **Tratamento de Erros:** Em um loop longo, é importante ter um bom tratamento de erros. O que acontece se uma iteração falhar? O loop para? A falha é registrada e o loop continua? +* **Eficiência e Custo:** Executar um agente LLM muitas vezes pode ser lento e/ou caro. Para tarefas repetitivas muito simples, pode haver soluções não-LLM mais eficientes. Considere otimizações como: + * Usar LLMs menores e mais rápidos se a tarefa permitir. + * Processamento em lote (batching) de chamadas LLM, se possível. + * Paralelização (se as iterações forem independentes). +* **Limites de Taxa (Rate Limiting):** Cuidado com os limites de taxa das APIs dos LLMs ou outras APIs que suas ferramentas possam estar usando. +* **Idempotência:** Se possível, projete a tarefa do agente para ser idempotente, o que significa que executá-la múltiplas vezes com a mesma entrada produz o mesmo resultado ou não causa efeitos colaterais indesejados. Isso é útil se uma iteração precisar ser re-executada devido a uma falha. + +Os Agentes Repetitivos são um padrão essencial para automatizar tarefas que precisam ser aplicadas a múltiplos conjuntos de dados ou executadas de forma contínua. O PraisonAI fornece a flexibilidade para implementar este padrão, seja através de loops de controle externos em Python ou potencialmente através de configurações de workflow mais avançadas. + +Com este tópico, concluímos a exploração dos principais padrões de Workflows Avançados ilustrados no PraisonAI! diff --git a/docs_translations/pt-br/04_workflows_avancados/09_agentes_multimodais.md b/docs_translations/pt-br/04_workflows_avancados/09_agentes_multimodais.md new file mode 100644 index 000000000..6b04b532f --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/09_agentes_multimodais.md @@ -0,0 +1,13 @@ +# Workflows Avançados: Agentes Multimodais + +Agentes multimodais conseguem lidar com diferentes tipos de dados, como texto e imagens, dentro do mesmo fluxo de trabalho. No PraisonAI, você pode combinar ferramentas de visão computacional com seus agentes tradicionais. + +```python +from praisonaiagents import Agent +from praisonaiagents.tools import image_to_text + +agent = Agent(tools=[image_to_text]) +agent.start("Analyze the image at example.png and summarise it") +``` + +Utilize esse padrão quando precisar de entradas visuais ou de outros formatos além de texto. diff --git a/docs_translations/pt-br/04_workflows_avancados/10_code_interpreter_agents.md b/docs_translations/pt-br/04_workflows_avancados/10_code_interpreter_agents.md new file mode 100644 index 000000000..bb367421d --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/10_code_interpreter_agents.md @@ -0,0 +1,13 @@ +# Workflows Avançados: Code Interpreter Agents + +Esses agentes utilizam a ferramenta `code_interpreter` para executar trechos de código e retornar o resultado. É útil para análises de dados, geração de gráficos ou qualquer tarefa que exija execução dinâmica de scripts. + +```python +from praisonaiagents import Agent +from praisonaiagents.tools import code_interpreter + +agent = Agent(tools=[code_interpreter]) +agent.start("Calculate the factorial of 5") +``` + +A saída do código é repassada para o agente, permitindo ciclos de raciocínio baseados em resultados programáticos. diff --git a/docs_translations/pt-br/04_workflows_avancados/11_math_agents.md b/docs_translations/pt-br/04_workflows_avancados/11_math_agents.md new file mode 100644 index 000000000..3b8cb618f --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/11_math_agents.md @@ -0,0 +1,13 @@ +# Workflows Avançados: Math Agents + +Math Agents são especializados em resolver cálculos e problemas matemáticos. Combinam o raciocínio do modelo de linguagem com ferramentas que efetuam operações precisas. + +```python +from praisonaiagents import Agent +from praisonaiagents.tools import math_tool + +agent = Agent(tools=[math_tool]) +agent.start("Solve the equation 2*x + 3 = 9") +``` + +Esse padrão ajuda a garantir respostas numéricas corretas e detalhadas. diff --git a/docs_translations/pt-br/04_workflows_avancados/12_saida_estruturada.md b/docs_translations/pt-br/04_workflows_avancados/12_saida_estruturada.md new file mode 100644 index 000000000..274e1eb23 --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/12_saida_estruturada.md @@ -0,0 +1,12 @@ +# Workflows Avançados: Structured Output + +Em muitas aplicações, é importante que as respostas sigam um formato fixo, como JSON ou tabelas. Os agentes podem ser configurados com instruções claras para sempre retornarem dados estruturados. + +```python +from praisonaiagents import Agent + +agent = Agent(instructions="Answer using a JSON object with keys 'summary' and 'sources'.") +agent.start("Summarise the benefits of solar energy") +``` + +Definir um esquema de saída torna o pós-processamento muito mais simples. diff --git a/docs_translations/pt-br/04_workflows_avancados/13_callback_agents.md b/docs_translations/pt-br/04_workflows_avancados/13_callback_agents.md new file mode 100644 index 000000000..414d8dc17 --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/13_callback_agents.md @@ -0,0 +1,15 @@ +# Workflows Avançados: Callback Agents + +Callback Agents permitem executar funções específicas em pontos determinados da conversa, como antes ou depois do uso de uma ferramenta. Isso facilita monitoramento e extensões personalizadas. + +```python +from praisonaiagents import Agent + +def log_step(data): + print("Agent step:", data) + +agent = Agent(callbacks=[log_step]) +agent.start("Tell me a joke") +``` + +Use callbacks para registro, métricas ou integrações extras. diff --git a/docs_translations/pt-br/04_workflows_avancados/14_mini_agents.md b/docs_translations/pt-br/04_workflows_avancados/14_mini_agents.md new file mode 100644 index 000000000..e9c96506d --- /dev/null +++ b/docs_translations/pt-br/04_workflows_avancados/14_mini_agents.md @@ -0,0 +1,12 @@ +# Workflows Avançados: Mini AI Agents + +Mini Agents são versões simplificadas focadas em uma tarefa específica. Por serem leves, podem ser executados em paralelo ou incorporados a aplicações maiores com facilidade. + +```python +from praisonaiagents import Agent + +agent = Agent(instructions="Answer only with emoji reactions") +agent.start("How are you?") +``` + +São úteis quando se deseja um comportamento muito pontual sem a complexidade de um workflow completo. diff --git a/docs_translations/pt-br/05_ferramentas/00_visao_geral_ferramentas.md b/docs_translations/pt-br/05_ferramentas/00_visao_geral_ferramentas.md new file mode 100644 index 000000000..cc38e4633 --- /dev/null +++ b/docs_translations/pt-br/05_ferramentas/00_visao_geral_ferramentas.md @@ -0,0 +1,138 @@ +# Módulo: Ferramentas (Tools) no PraisonAI + +As **Ferramentas (Tools)** são um componente essencial que transforma os [Agentes](./../02_conceitos_fundamentais/01_agentes.md) do PraisonAI de meros processadores de linguagem em entidades capazes de interagir com o mundo real, executar ações e acessar informações externas. O PraisonAI destaca o suporte a "Mais de 100 Ferramentas Personalizadas", além da capacidade de criar as suas próprias. + +Este módulo explora como as ferramentas funcionam no PraisonAI, como utilizá-las e como desenvolvê-las. Já introduzimos o conceito básico de ferramentas em [Conceitos Fundamentais - Ferramentas](./../02_conceitos_fundamentais/04_ferramentas.md), aqui vamos aprofundar. + +## A Importância das Ferramentas e Suas Descrições + +Para um Modelo de Linguagem Grande (LLM) utilizar uma ferramenta eficazmente, ele precisa entender: +1. **O que a ferramenta faz:** Qual seu propósito? +2. **Quando usá-la:** Em que situações ou para quais tipos de perguntas/tarefas ela é relevante? +3. **Quais argumentos ela espera:** Que informações de entrada a ferramenta necessita? +4. **O que ela retorna:** Qual o formato e o tipo de saída da ferramenta? + +Essa compreensão é quase inteiramente derivada da **descrição da ferramenta** (geralmente a docstring da função em Python) e do **esquema dos seus argumentos** (tipos e nomes dos parâmetros). + +> [!CRITICAL] Descrições Claras São Cruciais! +> A qualidade da descrição da sua ferramenta impacta diretamente a capacidade do LLM de usá-la corretamente. Descrições vagas ou imprecisas levarão a um uso incorreto ou à não utilização da ferramenta. + +## Usando Ferramentas Embutidas no PraisonAI + +PraisonAI oferece um vasto conjunto de ferramentas prontas para uso. Embora uma lista exaustiva esteja além do escopo deste guia (consulte a documentação oficial do PraisonAI ou explore o código-fonte para detalhes específicos), o uso delas geralmente segue um padrão: + +* **Identificação da Ferramenta:** Você precisa saber o nome ou identificador da ferramenta que deseja usar (ex: `tavily_search`, `web_scraper`, `code_interpreter`, `file_read_tool`). +* **Atribuição ao Agente:** + * **Em YAML:** Na definição de um `role` (agente), você pode listar as ferramentas que ele tem permissão para usar na seção `tools`: + ```yaml + roles: + pesquisador_avancado: + role: "Pesquisador Avançado" + goal: "Encontrar e analisar informações detalhadas sobre tópicos complexos." + tools: + - "tavily_search" # Ferramenta de busca na web (exemplo) + - "web_page_reader" # Ferramenta para ler conteúdo de URLs + # - "nome_outra_ferramenta_embutida" + # ... outras configurações ... + ``` + * **Em Python:** Ao instanciar um `Agent`, você passa uma lista de objetos de ferramenta ou nomes de ferramentas registradas para o parâmetro `tools`. + ```python + from praisonaiagents import Agent + # Supondo que as ferramentas embutidas possam ser importadas ou referenciadas por nome + # from praisonai.tools import TavilySearchTool, WebScraperTool # Exemplo conceitual + + # ferramentas_disponiveis = [TavilySearchTool(), WebScraperTool()] + # OU, se referenciadas por nome: + # ferramentas_disponiveis = ["tavily_search", "web_scraper"] + + # agente = Agent( + # role="Pesquisador", + # goal="Coletar informações da web.", + # tools=ferramentas_disponiveis + # ) + ``` + A forma exata de instanciar/referenciar ferramentas embutidas em Python dependerá de como elas são expostas pela biblioteca `praisonaiagents`. Verifique os exemplos no repositório. + +* **Invocação pelo LLM:** Uma vez que um agente tem uma ferramenta atribuída, o LLM do agente decidirá autonomamente quando usá-la durante a execução de uma tarefa, com base nas instruções da tarefa e na descrição da ferramenta. + +## Criando Ferramentas Personalizadas + +A verdadeira flexibilidade do PraisonAI (e de frameworks como LangChain, que ele integra) reside na facilidade de criar ferramentas personalizadas para atender às necessidades específicas do seu projeto. + +O método mais comum em Python é definir uma função e decorá-la para transformá-la em uma ferramenta que o LLM possa entender. + +**Exemplo Chave: `examples/python/general/example_custom_tools.py`** + +Este arquivo no repositório PraisonAI é uma excelente referência. Ele demonstra o uso do decorator `@tool` (frequentemente vindo de `langchain_core.tools` ou uma utilidade similar fornecida pelo PraisonAI). + +```python +# Adaptado de examples/python/general/example_custom_tools.py +from langchain_core.tools import tool # Ou um decorator similar do PraisonAI +from pydantic import BaseModel, Field # Para definir o esquema dos argumentos + +# Exemplo 1: Ferramenta Simples +@tool +def get_word_length(word: str) -> int: + """Retorna o comprimento de uma palavra.""" + return len(word) + +# Exemplo 2: Ferramenta com descrição mais elaborada e esquema de entrada Pydantic +class CalculatorInput(BaseModel): + a: int = Field(description="Primeiro número") + b: int = Field(description="Segundo número") + +@tool("calculator_tool", args_schema=CalculatorInput) # Nome explícito e esquema +def calculator(a: int, b: int) -> int: + """Calcula a soma de dois números, 'a' e 'b'.""" + return a + b + +# Como usar essas ferramentas com um agente PraisonAI: +# from praisonaiagents import Agent +# +# meu_agente = Agent( +# role="Assistente Inteligente", +# goal="Resolver tarefas usando ferramentas personalizadas.", +# tools=[get_word_length, calculator] # Adiciona as funções decoradas à lista de ferramentas +# ) +# +# resultado_comprimento = meu_agente.start("Qual o comprimento da palavra 'PraisonAI'?") +# print(f"Resultado (comprimento): {resultado_comprimento}") +# +# resultado_soma = meu_agente.start("Some 15 e 27 usando a calculadora.") +# print(f"Resultado (soma): {resultado_soma}") +``` + +**Pontos Cruciais na Criação de Ferramentas Personalizadas:** + +1. **Decorator `@tool`:** + * Este decorator (ou um similar como `@structured_tool` ou utilitários do PraisonAI) é o que registra a função como uma ferramenta utilizável pelo sistema de agentes. + * Ele pode aceitar argumentos, como um nome explícito para a ferramenta ou um `args_schema` para definir a estrutura dos argumentos de entrada de forma mais robusta (usando Pydantic). + +2. **Docstring (Descrição da Ferramenta):** + * **ESSENCIAL!** A docstring da sua função (a string entre aspas triplas ```"..." ``` logo após a definição da função) é usada pelo LLM para entender o que a ferramenta faz. + * Seja claro, conciso e preciso. Explique o propósito, os parâmetros esperados (mesmo que tipados, a descrição ajuda) e o que a ferramenta retorna. + +3. **Type Hints (Anotações de Tipo):** + * Use anotações de tipo do Python (ex: `word: str`, `-> int`). Elas ajudam o LLM (e o Pydantic, se usado) a entender os tipos de dados esperados e retornados, o que é crucial para o "function calling". + +4. **Schema de Argumentos (Pydantic - Opcional, mas Recomendado para Complexidade):** + * Para ferramentas com múltiplos argumentos ou argumentos com descrições específicas, usar um modelo Pydantic (`BaseModel`) para definir o `args_schema` é uma excelente prática. Isso fornece uma estrutura clara e validável para os inputs da ferramenta. + +## O Mecanismo de "Function Calling" / "Tool Using" + +Quando um LLM (como os modelos mais recentes da OpenAI, Gemini, etc.) é informado sobre as ferramentas disponíveis (seus nomes, descrições e esquemas de argumentos), ele pode, durante uma conversa ou ao processar uma tarefa, decidir que precisa de uma ferramenta. Se isso acontecer, o LLM não executa a ferramenta diretamente. Em vez disso, ele: + +1. **Gera uma Solicitação de Chamada de Ferramenta:** O LLM produz uma saída estruturada (geralmente JSON) indicando o nome da ferramenta que ele quer chamar e os valores dos argumentos que ele inferiu do contexto da conversa/tarefa. +2. **Execução pelo Framework:** O framework (PraisonAI, LangChain) intercepta essa solicitação. +3. Ele então chama a função Python real correspondente à ferramenta, passando os argumentos fornecidos pelo LLM. +4. **Resultado da Ferramenta:** A função Python executa sua lógica e retorna um resultado. +5. **Retorno ao LLM:** O framework envia este resultado de volta para o LLM. +6. **Resposta Final:** O LLM agora usa o resultado da ferramenta (junto com o histórico da conversa e o prompt original) para formular sua resposta final ao usuário ou para decidir a próxima ação. + +Este ciclo permite que os LLMs "usem" ferramentas de forma segura e estruturada, sem realmente executar código arbitrário por si mesmos. + +## Ferramentas e o PraisonAI + +O PraisonAI facilita esse processo, seja usando suas ferramentas embutidas ou permitindo a integração suave de ferramentas personalizadas. Ao definir agentes, você simplesmente os equipa com as ferramentas necessárias, e o PraisonAI, em conjunto com o LLM, gerencia a lógica de quando e como essas ferramentas são chamadas. + +A capacidade de estender agentes com ferramentas customizadas é o que permite adaptar o PraisonAI a praticamente qualquer domínio ou caso de uso específico, tornando-o uma plataforma verdadeiramente versátil para a construção de aplicações de IA. diff --git a/docs_translations/pt-br/06_modelos_llm/00_usando_diferentes_llms.md b/docs_translations/pt-br/06_modelos_llm/00_usando_diferentes_llms.md new file mode 100644 index 000000000..51acac5e2 --- /dev/null +++ b/docs_translations/pt-br/06_modelos_llm/00_usando_diferentes_llms.md @@ -0,0 +1,155 @@ +# Módulo: Modelos de LLM no PraisonAI + +Um dos pontos fortes do PraisonAI é sua flexibilidade em relação aos Modelos de Linguagem Grande (LLMs). Ele não está restrito a um único provedor e é projetado para suportar uma variedade de LLMs, incluindo modelos da OpenAI, modelos locais via Ollama, inferência rápida com Groq, modelos do Google Gemini, e muitos outros (PraisonAI menciona "100+ LLM Support"). + +Esta flexibilidade permite que você escolha o LLM que melhor se adapta às suas necessidades em termos de custo, performance, capacidades específicas, ou requisitos de privacidade (no caso de modelos locais). + +## Configuração Geral de LLMs + +A forma como você configura um LLM no PraisonAI geralmente envolve duas etapas: + +1. **Configuração do Provedor (Variáveis de Ambiente):** + Muitos provedores de LLM exigem chaves de API e, às vezes, URLs base específicas. Estas são comumente configuradas através de variáveis de ambiente. + +2. **Especificação no Agente:** + Ao definir um [Agente](./../02_conceitos_fundamentais/01_agentes.md), você pode especificar qual modelo ou provedor ele deve usar. Se não especificado, o PraisonAI pode usar um padrão (frequentemente um modelo OpenAI como GPT-3.5 Turbo). + +## Configurando Provedores Comuns + +Vamos ver como configurar alguns dos provedores de LLM mais populares para uso com o PraisonAI: + +### 1. OpenAI (GPT-3.5, GPT-4, etc.) + +* **Variável de Ambiente Principal:** + ```bash + export OPENAI_API_KEY="sua_chave_api_da_openai_aqui" + ``` + (No Windows, use `set` ou `setx` ou a interface gráfica, conforme detalhado no [Guia de Instalação](./../01_instalacao/00_instalacao_windows.md)). +* **Uso:** Esta é geralmente a configuração padrão ou mais direta no PraisonAI. + +### 2. Ollama (Modelos Locais como Llama, Mistral, etc.) + +Ollama permite que você execute LLMs de código aberto localmente na sua máquina. O PraisonAI pode interagir com o servidor Ollama através de uma API compatível com a API da OpenAI. + +* **Pré-requisito:** Ter o Ollama instalado e rodando. (Veja [ollama.com](https://ollama.com/)). Certifique-se de ter baixado os modelos que deseja usar (ex: `ollama pull llama3`). +* **Variáveis de Ambiente:** + ```bash + # URL onde seu servidor Ollama está escutando (padrão) + export OPENAI_BASE_URL="http://localhost:11434/v1" + + # A API do Ollama pode ou não exigir uma chave, mas é comum manter o padrão da API OpenAI. + # Você pode usar um valor fictício se o modelo específico não exigir autenticação. + export OPENAI_API_KEY="ollama" # ou "EMPTY", ou sua chave real se configurou uma no Ollama + + # (Opcional, mas recomendado) Especifique o nome do modelo que o Ollama deve usar por padrão, + # se não for especificado no agente. + # export OPENAI_MODEL_NAME="llama3:latest" + ``` +* **Especificação do Modelo no Agente:** Ao definir um agente, você precisará informar o nome do modelo Ollama que deseja usar (ex: `llama3:latest`, `mistral:latest`). + +### 3. Groq (Inferência Rápida) + +Groq fornece inferência de LLM em alta velocidade usando seus LPUs (Language Processing Units). + +* **Pré-requisito:** Ter uma chave de API do Groq (veja [groq.com](https://groq.com/)). +* **Variáveis de Ambiente:** + ```bash + # URL da API do Groq (compatível com OpenAI) + export OPENAI_BASE_URL="https://api.groq.com/openai/v1" + + # Sua chave de API específica do Groq + export OPENAI_API_KEY="sua_chave_api_do_groq_aqui" + ``` +* **Especificação do Modelo no Agente:** Você usará os nomes dos modelos disponíveis no Groq (ex: `llama3-8b-8192`, `mixtral-8x7b-32768`). + +### 4. Google Gemini + +* **Pré-requisito:** Ter uma chave de API do Google AI Studio ou configurado para usar Gemini via Vertex AI no Google Cloud. +* **Variáveis de Ambiente:** A configuração exata pode variar (ex: `GOOGLE_API_KEY`). O PraisonAI pode ter um manipulador específico para Gemini. +* **Recomendação:** Consulte a documentação oficial do PraisonAI ou exemplos específicos sobre como integrar modelos Gemini, pois pode haver um fluxo de configuração um pouco diferente do padrão `OPENAI_*`. + +### 5. Outros Modelos (Anthropic Claude, Cohere, etc.) + +PraisonAI visa suportar uma ampla gama de modelos. A configuração para cada um pode envolver: +* Variáveis de ambiente específicas (ex: `ANTHROPIC_API_KEY`). +* Uso de URLs base específicas se eles expõem uma API compatível com OpenAI. +* Manipuladores (handlers) ou clientes específicos dentro do PraisonAI para esses modelos. + +> [!IMPORTANT] +> A lista de modelos suportados e seus métodos de configuração exatos podem evoluir. **Sempre consulte a documentação oficial do PraisonAI (`https://docs.praison.ai/models`) para as informações mais atualizadas.** + +## Especificando o Modelo no Agente + +Uma vez que o provedor está configurado através das variáveis de ambiente, você pode (e muitas vezes deve) especificar qual modelo exato um agente deve usar. + +* **Em YAML:** + Dentro da definição de um `role` (agente), você pode adicionar uma seção `llm` ou `model`: + ```yaml + roles: + escritor_rapido: + role: "Escritor Rápido" + goal: "Gerar texto rapidamente para tarefas simples." + # Exemplo para Groq + llm: + provider: groq # Ou openai, ollama, etc. (o nome do provider pode variar) + model: "llama3-8b-8192" + # temperature: 0.6 # Outros parâmetros do LLM + # Exemplo para Ollama (o nome do modelo geralmente inclui o registry/tag) + # llm: + # model: "ollama/llama3:latest" # A sintaxe exata pode variar + # Ou mais simples se OPENAI_BASE_URL e OPENAI_MODEL_NAME estiverem configurados para Ollama: + # llm: + # model: "llama3:latest" # Se o provider é inferido como OpenAI-compatible + # ... + analista_profundo: + role: "Analista Detalhista" + goal: "Realizar análises complexas e profundas." + llm: + provider: openai + model: "gpt-4-turbo-preview" + temperature: 0.3 + # ... + ``` + *A estrutura exata da seção `llm` (ex: `provider`, `model`) pode depender da versão do PraisonAI e do framework subjacente (`praisonai`, `crewai`, `autogen`). Verifique os exemplos YAML no repositório.* + +* **Em Python:** + Ao instanciar um `Agent`, você pode passar um objeto de configuração do LLM ou o nome do modelo. + ```python + from praisonaiagents import Agent + # Supondo que existam classes ou formas de configurar LLMs específicos + # from praisonai.llms import Ollama # Exemplo conceitual + + # Exemplo para OpenAI (muitas vezes o padrão, mas pode ser explícito) + # agente_openai = Agent( + # role="Assistente GPT", + # goal="Usar GPT-4.", + # llm={"model": "gpt-4"} # A forma de passar pode variar + # ) + + # Exemplo para Ollama (conceitual) + # llm_ollama_config = Ollama(model="llama3:latest", base_url="http://localhost:11434") + # agente_ollama = Agent( + # role="Assistente Llama Local", + # goal="Usar Llama 3 localmente via Ollama.", + # llm=llm_ollama_config # Passando o objeto LLM configurado + # ) + + # Outra forma comum, se o PraisonAI usa uma API compatível com OpenAI para Ollama/Groq: + # (Com OPENAI_BASE_URL e OPENAI_API_KEY configurados para Ollama) + agente_ollama_openai_api = Agent( + role="Assistente Local (API OpenAI)", + goal="Usar modelo Ollama através da API compatível.", + llm={"model": "llama3:latest"} # O nome do modelo Ollama + # PraisonAI usaria OPENAI_BASE_URL para direcionar para Ollama + ) + ``` + *A API Python para configurar LLMs específicos pode ser bastante rica. Consulte os exemplos em `examples/python/models/` e a documentação da API `praisonaiagents`.* + +## Considerações + +* **Compatibilidade de Recursos:** Nem todos os LLMs suportam todos os recursos da mesma forma (ex: "function calling"/"tool using", multimodalidade, tamanho da janela de contexto). Escolha o modelo também com base nos recursos que seus agentes precisam. +* **Custos:** Esteja ciente dos custos associados a cada provedor de LLM. Modelos mais poderosos geralmente são mais caros. +* **Desempenho (Latência e Qualidade):** Diferentes modelos têm diferentes características de latência e qualidade de resposta. Teste para encontrar o equilíbrio certo para sua aplicação. +* **Nomes dos Modelos:** Os nomes exatos dos modelos (`gpt-3.5-turbo`, `llama3:latest`, `mixtral-8x7b-32768`, etc.) devem corresponder ao que o provedor espera. + +A capacidade do PraisonAI de se integrar com uma ampla gama de LLMs é uma vantagem significativa, permitindo que você adapte seus agentes às melhores ferramentas de linguagem disponíveis para cada tarefa. diff --git a/docs_translations/pt-br/07_exemplos_praticos/01_exemplo_analise_de_acoes.md b/docs_translations/pt-br/07_exemplos_praticos/01_exemplo_analise_de_acoes.md new file mode 100644 index 000000000..bc508fd50 --- /dev/null +++ b/docs_translations/pt-br/07_exemplos_praticos/01_exemplo_analise_de_acoes.md @@ -0,0 +1,144 @@ +# Exemplo Prático: Análise de Ações com Agentes YAML + +Este exemplo prático illustra como você poderia configurar um sistema multi-agente usando PraisonAI e YAML para realizar uma análise básica de uma ação da bolsa de valores. + +**Nota:** O arquivo `examples/cookbooks/yaml/stock_analysis_agents.ipynb` no repositório PraisonAI provavelmente contém uma implementação funcional deste caso de uso. Como não podemos processar o conteúdo de notebooks diretamente aqui, vamos construir um exemplo YAML conceitual que demonstre a abordagem. Recomendamos fortemente que você explore o notebook original para ver a implementação real e o código Python que o acompanha. + +## Problema a Ser Resolvido + +Imagine que você quer automatizar o processo de obter uma visão geral sobre uma determinada ação. Isso poderia envolver: +1. Coletar notícias recentes sobre a empresa. +2. Analisar o sentimento geral dessas notícias. +3. Obter dados financeiros básicos (ex: preço atual, alta/baixa do ano). +4. Gerar um breve resumo com uma recomendação especulativa (comprar, manter, vender), com todos os devidos avisos de que não se trata de aconselhamento financeiro. + +## Agentes Envolvidos (Conceitual) + +Para resolver este problema, poderíamos definir os seguintes agentes (roles): + +1. **`pesquisador_noticias_financeiras`**: + * **Objetivo:** Encontrar as notícias mais recentes e relevantes sobre uma empresa específica. + * **Ferramentas:** Uma ferramenta de busca na web (ex: `tavily_search` ou similar). + +2. **`analista_sentimento_noticias`**: + * **Objetivo:** Analisar um conjunto de notícias e determinar o sentimento geral (positivo, negativo, neutro). + * **Instruções:** Focado em PNL para análise de sentimento. + +3. **`coletor_dados_mercado`**: + * **Objetivo:** Obter dados de mercado atuais para a ação (preço, volume, etc.). + * **Ferramentas:** Uma ferramenta que se conecta a uma API de dados financeiros (ex: Alpha Vantage, Yahoo Finance API - pode ser uma ferramenta customizada). + +4. **`analista_chefe_investimentos`**: + * **Objetivo:** Consolidar todas as informações (notícias, sentimento, dados de mercado) e produzir um resumo final com uma perspectiva (não um conselho financeiro). + * **Instruções:** Enfatizar a natureza especulativa e a necessidade de consultar um profissional. + +## Exemplo de Configuração YAML (`analise_acao.yaml` - Conceitual) + +```yaml +framework: praisonai # Ou crewai, dependendo da preferência de estrutura +topic: "Análise da Ação XYZ" # Pode ser parametrizado ao rodar o `praisonai` CLI + +variables: + nome_empresa: "Nome da Empresa XYZ" + ticker_acao: "XYZ" + +roles: + pesquisador_noticias_financeiras: + role: "Pesquisador de Notícias Financeiras" + goal: "Coletar as 5 notícias mais recentes e relevantes sobre a {nome_empresa} ({ticker_acao})." + backstory: "Você é um especialista em encontrar informações financeiras atualizadas na web." + tools: + - "tavily_search" # Ou outra ferramenta de busca configurada + tasks: + buscar_noticias_recentes: + description: "Use a ferramenta de busca para encontrar as 5 notícias mais importantes sobre a empresa {nome_empresa} ({ticker_acao}) publicadas na última semana. Forneça o título e um breve resumo de cada notícia." + expected_output: "Uma lista contendo 5 itens, cada um com 'titulo' e 'resumo_noticia'." + + analista_sentimento_noticias: + role: "Analista de Sentimento de Notícias" + goal: "Analisar o sentimento geral expresso nas notícias coletadas sobre a {nome_empresa}." + backstory: "Você é um LLM treinado para identificar nuances de sentimento em textos financeiros." + # Este agente não precisa de ferramentas externas, apenas processa o texto. + tasks: + analisar_sentimento_coletado: + description: "Com base na lista de notícias fornecida (títulos e resumos), determine o sentimento geral (Positivo, Negativo ou Neutro) sobre a {nome_empresa}. Justifique brevemente sua análise." + expected_output: "Uma declaração de sentimento (Positivo, Negativo ou Neutro) e uma justificativa de 1-2 frases." + context_tasks: + - buscar_noticias_recentes # Depende da saída do pesquisador + + coletor_dados_mercado: + role: "Coletor de Dados de Mercado" + goal: "Obter os dados de mercado mais recentes para a ação {ticker_acao}." + backstory: "Você se conecta a APIs financeiras para buscar cotações e dados de ações em tempo real." + tools: + - "api_dados_financeiros" # Ferramenta customizada ou embutida que busca dados de uma API + tasks: + buscar_dados_acao: + description: "Use a ferramenta 'api_dados_financeiros' para obter o preço atual, a variação diária (%), o volume negociado, a máxima e mínima das últimas 52 semanas para a ação {ticker_acao}." + expected_output: "Um resumo estruturado contendo: preco_atual, variacao_diaria_percentual, volume, maxima_52s, minima_52s." + + analista_chefe_investimentos: + role: "Analista Chefe de Investimentos (Simulado)" + goal: "Consolidar todas as informações coletadas (notícias, sentimento, dados de mercado) e fornecer um breve panorama e uma perspectiva especulativa sobre a ação {ticker_acao}." + backstory: "Você é um analista experiente que combina diferentes fontes de informação para formar uma visão geral, sempre com uma postura cautelosa e ética." + # Este agente pode precisar de uma ferramenta de cálculo básica, se for fazer projeções simples. + tasks: + compilar_relatorio_acao: + description: | + Com base nas seguintes informações: + 1. Resumos das notícias recentes. + 2. Análise de sentimento das notícias. + 3. Dados de mercado atuais da ação {ticker_acao}. + Elabore um relatório conciso (máximo 300 palavras) que inclua: + - Um breve resumo das notícias e do sentimento. + - Destaque dos principais dados de mercado. + - Uma perspectiva especulativa (ex: 'parece promissor para observação', 'momento de cautela', 'potencial de volatilidade'). + Inclua um AVISO LEGAL claro de que este relatório não constitui aconselhamento financeiro e que decisões de investimento devem ser tomadas com um profissional qualificado. + expected_output: "Um relatório textual de no máximo 300 palavras contendo o panorama da ação {ticker_acao} e o aviso legal." + context_tasks: + - analisar_sentimento_coletado + - buscar_dados_acao + +process: sequential # As tarefas e dependências definem a sequência +# Ou poderia ser hierárquico com o 'analista_chefe_investimentos' como manager. +``` + +## Como Executar (Teórico) + +1. Salve o conteúdo acima como `analise_acao.yaml`. +2. Configure as ferramentas necessárias (ex: `tavily_search` e uma `api_dados_financeiros` que pode ser uma ferramenta customizada que você precisaria criar e registrar no PraisonAI se não for embutida). +3. Execute via CLI: + ```bash + praisonai analise_acao.yaml + ``` + Você também pode passar variáveis via CLI se o PraisonAI suportar overrides para a seção `variables` do YAML, por exemplo: + ```bash + praisonai analise_acao.yaml --vars "nome_empresa='Outra Empresa SA';ticker_acao='OTR4'" + ``` + (A sintaxe exata para override de variáveis dependeria da implementação da CLI do PraisonAI). + +## Resultado Esperado (Conceitual) + +O `analista_chefe_investimentos` produziria um relatório final, algo como: + +> **Panorama da Ação XYZ ({ticker_acao})** +> +> As notícias recentes sobre a Nome da Empresa XYZ indicam um sentimento geralmente [Positivo/Negativo/Neutro], com destaque para [mencionar brevemente um ponto chave das notícias]. Por exemplo, [resumo de uma notícia relevante]. +> +> Atualmente, a ação {ticker_acao} está cotada a [preco_atual], com uma variação diária de [variacao_diaria_percentual]% e volume de [volume]. A máxima das últimas 52 semanas foi de [maxima_52s] e a mínima de [minima_52s]. +> +> **Perspectiva Especulativa:** +> Com base nas informações atuais, o cenário para {ticker_acao} sugere [perspectiva, ex: 'um potencial interessante para acompanhamento devido ao sentimento positivo das notícias, mas a volatilidade do mercado exige cautela.']. +> +> **AVISO LEGAL:** Este relatório é gerado por um sistema de IA para fins ilustrativos e educacionais, baseado em informações publicamente disponíveis e não constitui aconselhamento financeiro. Qualquer decisão de investimento deve ser tomada após consulta a um profissional financeiro qualificado e análise individual. Não nos responsabilizamos por quaisquer perdas ou ganhos decorrentes do uso desta informação. + +## Fundamentos PraisonAI Aplicados + +* **Múltiplos Agentes (`roles`):** Cada agente com sua especialização, `goal`, `backstory` e `tools`. +* **Tarefas (`tasks`):** Descrições claras do que cada agente deve fazer e o `expected_output`. +* **Contexto entre Tarefas (`context_tasks`):** A saída de uma tarefa alimenta a próxima, criando um fluxo de trabalho. +* **Ferramentas (`tools`):** Uso de ferramentas para interagir com o mundo externo (busca na web, APIs financeiras). +* **Configuração YAML:** Definição declarativa de todo o sistema de agentes. +* **Processo Sequencial:** As dependências entre tarefas guiam a ordem de execução. + +Este exemplo, mesmo conceitual, demonstra o poder do PraisonAI para orquestrar múltiplos agentes na resolução de um problema do mundo real. Ao explorar o notebook `stock_analysis_agents.ipynb` original, você poderá ver como esses conceitos são traduzidos em código e configurações YAML reais. diff --git a/docs_translations/pt-br/07_exemplos_praticos/02_exemplo_geracao_artigos.md b/docs_translations/pt-br/07_exemplos_praticos/02_exemplo_geracao_artigos.md new file mode 100644 index 000000000..f7c041a41 --- /dev/null +++ b/docs_translations/pt-br/07_exemplos_praticos/02_exemplo_geracao_artigos.md @@ -0,0 +1,126 @@ +# Exemplo Prático: Geração de Artigos com Agentes YAML + +Este exemplo demonstra como o PraisonAI pode ser usado para automatizar o processo de criação de um artigo, desde a pesquisa inicial e esboço até a redação final e revisão. Utilizaremos uma abordagem baseada em YAML para definir os agentes e suas tarefas. + +**Nota:** O arquivo `examples/cookbooks/yaml/article_generation_agents.ipynb` no repositório PraisonAI provavelmente contém uma implementação funcional deste caso de uso. Este exemplo é uma representação conceitual. Explore o notebook original para a implementação detalhada. + +## Problema a Ser Resolvido + +Criar um artigo informativo e bem estruturado sobre um tópico específico. O processo envolve: +1. Pesquisar informações relevantes sobre o tópico. +2. Criar um esboço (outline) para o artigo. +3. Escrever o conteúdo do artigo com base no esboço e na pesquisa. +4. Revisar o artigo para clareza, gramática e estilo. + +## Agentes Envolvidos (Conceitual) + +1. **`pesquisador_topicos`**: + * **Objetivo:** Coletar informações e fatos chave sobre o tópico do artigo. + * **Ferramentas:** Ferramenta de busca na web. + +2. **`arquiteto_conteudo`**: + * **Objetivo:** Criar um esboço detalhado e lógico para o artigo, com base na pesquisa. + * **Instruções:** Focado em estruturação de conteúdo. + +3. **`redator_artigos`**: + * **Objetivo:** Escrever o conteúdo completo do artigo, seguindo o esboço e utilizando as informações pesquisadas. + * **Instruções:** Focado em escrita fluida e engajante. + +4. **`revisor_critico`**: + * **Objetivo:** Revisar o artigo escrito, verificando erros, melhorando a clareza e garantindo que o objetivo foi atingido. + * **Instruções:** Focado em análise crítica e sugestões de melhoria. + +## Exemplo de Configuração YAML (`geracao_artigo.yaml` - Conceitual) + +```yaml +framework: praisonai # Ou crewai +topic: "O Impacto da Inteligência Artificial na Educação Superior" + +variables: + titulo_artigo_alvo: "IA na Educação Superior: Uma Revolução no Aprendizado" + publico_alvo: "Educadores, administradores acadêmicos e estudantes universitários" + numero_palavras_alvo: 1200 + +roles: + pesquisador_topicos: + role: "Pesquisador Especialista" + goal: "Coletar informações abrangentes e atuais sobre '{topic}'." + backstory: "Você é um pesquisador meticuloso, capaz de encontrar dados relevantes, estudos de caso e opiniões de especialistas." + tools: + - "tavily_search" + tasks: + pesquisar_informacoes_artigo: + description: "Realize uma pesquisa completa sobre '{topic}'. Colete dados sobre aplicações atuais, benefícios, desafios, e o futuro da IA neste contexto. Priorize fontes acadêmicas e reportagens de tecnologia confiáveis dos últimos 2 anos." + expected_output: "Um documento compilado com os principais pontos de informação, links para fontes, e citações relevantes, organizado por subtemas." + + arquiteto_conteudo: + role: "Arquiteto de Conteúdo" + goal: "Criar um esboço (outline) lógico e detalhado para um artigo sobre '{topic}' com o título '{titulo_artigo_alvo}'." + backstory: "Você é especialista em estruturar informações complexas de forma clara e sequencial para artigos e relatórios." + tasks: + criar_esboco_artigo: + description: "Com base no material de pesquisa fornecido sobre '{topic}', crie um esboço detalhado para um artigo intitulado '{titulo_artigo_alvo}'. O esboço deve incluir: Introdução (com gancho e tese), seções principais (com 3-5 pontos chave cada), subseções se necessário, e Conclusão (com resumo e chamada para ação ou reflexão). O artigo deve ser direcionado para {publico_alvo} e ter aproximadamente {numero_palavras_alvo} palavras." + expected_output: "Um esboço hierárquico completo do artigo, formatado em markdown, pronto para ser usado pelo redator." + context_tasks: + - pesquisar_informacoes_artigo + + redator_artigos: + role: "Redator de Artigos Experiente" + goal: "Escrever um artigo envolvente e informativo sobre '{topic}', seguindo o esboço e usando a pesquisa fornecida." + backstory: "Você transforma esboços e dados de pesquisa em artigos bem escritos, com linguagem clara e adaptada ao público-alvo." + tasks: + escrever_conteudo_artigo: + description: "Utilizando o esboço detalhado e o material de pesquisa sobre '{topic}', escreva o conteúdo completo do artigo '{titulo_artigo_alvo}'. Siga a estrutura do esboço, desenvolva cada ponto com as informações pesquisadas, e mantenha um tom apropriado para {publico_alvo}. O artigo deve ter aproximadamente {numero_palavras_alvo} palavras." + expected_output: "O texto completo do artigo, formatado em markdown." + context_tasks: + - criar_esboco_artigo # Depende do esboço + # Implicitamente também depende de 'pesquisar_informacoes_artigo' via 'criar_esboco_artigo' + + revisor_critico: + role: "Revisor e Editor Crítico" + goal: "Revisar o artigo '{titulo_artigo_alvo}' para garantir alta qualidade, clareza, precisão e coesão, sugerindo melhorias." + backstory: "Você tem um olhar apurado para detalhes, gramática, estilo e lógica argumentativa. Seu objetivo é elevar a qualidade do texto." + tasks: + revisar_artigo_final: + description: | + Revise o artigo fornecido sobre '{topic}' com o título '{titulo_artigo_alvo}'. + Verifique os seguintes aspectos: + 1. Clareza e fluidez do texto. + 2. Correção gramatical e ortográfica. + 3. Coesão e coerência entre as seções. + 4. Se o artigo atinge o objetivo proposto no esboço e se é adequado para o {publico_alvo}. + 5. Se a contagem de palavras está próxima de {numero_palavras_alvo}. + Forneça feedback construtivo detalhado E, se possível, o texto com as correções diretas ou sugestões de reescrita incorporadas. + expected_output: "Um relatório de revisão com feedback detalhado e/ou o texto do artigo com as revisões sugeridas/aplicadas." + context_tasks: + - escrever_conteudo_artigo + +process: sequential +# As dependências (context_tasks) garantem a ordem correta das operações. +``` + +## Como Executar (Teórico) + +1. Salve o conteúdo como `geracao_artigo.yaml`. +2. Certifique-se de que a ferramenta `tavily_search` (ou a que você escolheu) está configurada. +3. Execute via CLI: + ```bash + praisonai geracao_artigo.yaml + ``` + Você pode alterar o `topic` e outras `variables` diretamente no arquivo YAML ou investigar se a sua versão do PraisonAI CLI permite a substituição de variáveis via linha de comando. + +## Resultado Esperado (Conceitual) + +O `revisor_critico` (ou o `redator_artigos` se o revisor apenas fornecer feedback para uma nova iteração do redator) produziria o texto final do artigo, revisado e pronto para publicação, ou um relatório de revisão. + +Por exemplo, a saída da tarefa `escrever_conteudo_artigo` seria o rascunho do artigo. A saída da tarefa `revisar_artigo_final` seria o artigo já com as melhorias ou com comentários para o redator aplicar. + +## Fundamentos PraisonAI Aplicados + +* **Divisão de Trabalho:** Múltiplos agentes, cada um focado em uma etapa do processo de criação do artigo. +* **Workflow Sequencial:** O processo segue uma lógica clara: pesquisa -> esboço -> redação -> revisão. +* **Passagem de Contexto:** A informação gerada por um agente (pesquisa, esboço) é usada como entrada essencial para o próximo. +* **Instruções Detalhadas (`description` e `expected_output`):** Guiam cada agente a produzir o resultado necessário para a etapa seguinte. +* **Variáveis:** Permitem parametrizar o processo para diferentes tópicos ou requisitos de artigo. + +Este exemplo illustra como um processo criativo, como a escrita de um artigo, pode ser decomposto e automatizado com a colaboração de múltiplos agentes especializados no PraisonAI. A qualidade do resultado final dependerá significativamente da clareza dos `goals`, `instructions` e `expected_output` de cada agente e tarefa. diff --git a/docs_translations/pt-br/07_exemplos_praticos/03_exemplo_analise_geracao_codigo.md b/docs_translations/pt-br/07_exemplos_praticos/03_exemplo_analise_geracao_codigo.md new file mode 100644 index 000000000..2849f3b79 --- /dev/null +++ b/docs_translations/pt-br/07_exemplos_praticos/03_exemplo_analise_geracao_codigo.md @@ -0,0 +1,152 @@ +# Exemplo Prático: Análise e Geração Simples de Código com Agentes YAML + +Este exemplo prático demonstra como o PraisonAI pode ser configurado para auxiliar em tarefas relacionadas a código, como explicar um trecho de código existente ou gerar um script simples com base em uma descrição. + +**Nota:** Os exemplos `examples/cookbooks/Code_Analysis_Agent.ipynb` e `examples/cookbooks/yaml/cli_operation_agents.ipynb` no repositório PraisonAI podem conter implementações funcionais e mais detalhadas. Este é um exemplo conceitual para ilustrar a abordagem com YAML. + +## Problema a Ser Resolvido + +Queremos um sistema de agentes que possa: +1. **Explicar um trecho de código:** Dado um código em uma linguagem específica, o agente deve explicar sua funcionalidade, lógica e possíveis usos. +2. **Gerar um script simples:** Dada uma descrição de uma tarefa (ex: "criar um script Python que lista arquivos em um diretório"), o agente deve gerar o código correspondente. + +## Agentes Envolvidos (Conceitual) + +1. **`analista_codigo_fonte`**: + * **Objetivo:** Analisar e explicar trechos de código em várias linguagens. + * **Instruções:** Focado em PNL para "entender" código e descrevê-lo em linguagem natural. + * **Ferramentas:** Poderia opcionalmente usar uma ferramenta de "code interpreter" para testar o código, mas para explicação, o LLM pode ser suficiente. + +2. **`gerador_scripts_python`**: + * **Objetivo:** Gerar scripts Python funcionais com base em descrições de tarefas. + * **Instruções:** Focado em traduzir requisitos em linguagem natural para código Python. + * **Ferramentas:** Opcionalmente, um "code interpreter" para testar o script gerado. + +## Exemplo de Configuração YAML (`codigo_agentes.yaml` - Conceitual) + +```yaml +framework: praisonai +topic: "Análise e Geração de Código Python" + +variables: + linguagem_padrao: "Python" + diretorio_alvo_exemplo: "./minha_pasta" + +roles: + analista_codigo_fonte: + role: "Engenheiro de Software Explicador" + goal: "Analisar e fornecer explicações claras e concisas sobre trechos de código na {linguagem_padrao} ou outra linguagem especificada." + backstory: "Você é um desenvolvedor sênior com vasta experiência em múltiplas linguagens e uma habilidade especial para explicar código complexo de forma simples." + # tools: + # - "code_interpreter" # Opcional, para testes + tasks: + explicar_trecho_codigo: + # Este é um exemplo de tarefa que seria chamada com um input específico. + # O input (o código a ser explicado) viria da execução do 'praisonai' CLI + # ou de outro agente que passa o contexto. + description: "Analise o seguinte trecho de código em {linguagem_padrao} e explique: +1. Qual o seu propósito principal? +2. Como ele funciona (lógica passo a passo)? +3. Em que tipo de situação ele seria útil? + +Código a ser analisado: +```python +{codigo_para_analisar} +```" + expected_output: "Uma explicação textual clara, dividida em propósito, funcionamento e utilidade do código fornecido." + # 'codigo_para_analisar' seria uma variável de input da tarefa. + + gerador_scripts_python: + role: "Desenvolvedor Python Automatizado" + goal: "Gerar scripts Python funcionais e bem documentados com base em descrições de requisitos." + backstory: "Você é um especialista em Python capaz de traduzir rapidamente especificações em scripts eficientes." + # tools: + # - "code_interpreter" # Para testar o script gerado + # - "file_write_tool" # Para salvar o script em um arquivo + tasks: + gerar_script_listar_arquivos: + # Exemplo de tarefa específica. + description: "Crie um script Python que lista todos os arquivos e subdiretórios dentro de um diretório especificado ('{diretorio_alvo_exemplo}' por padrão, mas pode ser sobrescrito). O script deve imprimir os nomes no console." + expected_output: "O código completo do script Python solicitado, pronto para ser executado." + # Poderia ter uma tarefa subsequente para salvar e testar o script. + + gerar_script_customizado: + # Tarefa mais genérica que espera uma descrição do script. + description: "Com base na seguinte solicitação, gere um script Python: '{descricao_script_customizado}'" + expected_output: "O código completo do script Python solicitado." + # 'descricao_script_customizado' seria uma variável de input. + +# Você poderia definir um processo sequencial ou hierárquico se as tarefas +# de análise e geração fossem encadeadas ou gerenciadas. +# Para este exemplo, cada agente pode ser invocado para sua tarefa específica. +``` + +## Como Executar (Teórico) + +A execução dependeria de como você passa os inputs específicos (como `codigo_para_analisar` ou `descricao_script_customizado`) para as tarefas. + +**Opção 1: Foco em uma Tarefa Específica ao Invocar** + +Se a CLI do PraisonAI permitir invocar uma tarefa específica de um agente e passar contexto/variáveis para ela (isso é comum em sistemas como Airflow, mas pode variar no PraisonAI): + +```bash +# Para explicar um código (hipotético, depende da capacidade da CLI) +# Supondo que você possa passar 'codigo_para_analisar' como uma variável de tarefa +praisonai codigo_agentes.yaml --task explicar_trecho_codigo --vars "codigo_para_analisar='def hello(n): + print(f"Hello {n}")'" + +# Para gerar o script padrão de listar arquivos +praisonai codigo_agentes.yaml --task gerar_script_listar_arquivos + +# Para gerar um script customizado +praisonai codigo_agentes.yaml --task gerar_script_customizado --vars "descricao_script_customizado='Um script que lê um arquivo de texto e conta o número de palavras.'" +``` + +**Opção 2: Modificar o YAML para cada Execução** + +Você poderia ter um placeholder no YAML e substituí-lo antes de cada execução, ou ter diferentes arquivos YAML para diferentes códigos/scripts. + +**Opção 3: Agente "Interface com Usuário"** + +Um agente inicial poderia pegar a entrada do usuário (o código a ser analisado ou a descrição do script) e então passar essa informação como contexto para o `analista_codigo_fonte` ou `gerador_scripts_python`. + +## Resultado Esperado (Conceitual) + +* **Para `explicar_trecho_codigo`**: O agente `analista_codigo_fonte` retornaria um texto explicando o código fornecido. + > Exemplo: "O código fornecido define uma função Python chamada `hello` que recebe um argumento `n`. Seu propósito é imprimir uma saudação personalizada no console, incluindo o valor de `n`. Ele funciona usando uma f-string para formatar a mensagem. Seria útil em situações onde você precisa de uma saudação simples ou para demonstrar a passagem de argumentos para funções." + +* **Para `gerar_script_listar_arquivos`**: O agente `gerador_scripts_python` retornaria um bloco de código Python. + ```python + # Resultado esperado (conceitual): + import os + + def listar_arquivos_e_diretorios(caminho_diretorio="."): + """ + Lista todos os arquivos e subdiretórios dentro do caminho_diretorio especificado. + """ + try: + print(f"Conteúdo do diretório: {os.path.abspath(caminho_diretorio)}") + for item in os.listdir(caminho_diretorio): + print(item) + except FileNotFoundError: + print(f"Erro: Diretório não encontrado - {caminho_diretorio}") + except Exception as e: + print(f"Ocorreu um erro: {e}") + + if __name__ == "__main__": + # Por padrão, lista o diretório alvo do YAML, mas pode ser alterado. + diretorio_alvo = "{diretorio_alvo_exemplo}" # Esta variável seria substituída + # ou o script poderia aceitar um argumento de linha de comando. + # listar_arquivos_e_diretorios(diretorio_alvo) + # Para um exemplo funcional direto: + listar_arquivos_e_diretorios() # Lista o diretório atual + ``` + +## Fundamentos PraisonAI Aplicados + +* **Especialização de Agentes:** Agentes distintos para análise e para geração de código. +* **Instruções Claras (`goal`, `instructions`, `description` da tarefa):** Essenciais para que os LLMs entendam a tarefa relacionada a código. +* **Parametrização (`variables`, inputs de tarefa):** Permite reutilizar os agentes para diferentes códigos ou descrições de script. +* **Potencial Uso de Ferramentas:** Embora não detalhado aqui, ferramentas como `code_interpreter` (para executar e testar código) ou `file_write_tool` (para salvar scripts) seriam adições valiosas para tornar os agentes mais autônomos e úteis. O PraisonAI menciona "Code Interpreter Agents" como um recurso. + +Este exemplo mostra como agentes podem ser aplicados a domínios técnicos como programação. A qualidade da explicação ou do código gerado dependerá muito da capacidade do LLM subjacente e da clareza dos prompts e instruções fornecidas aos agentes. diff --git a/docs_translations/pt-br/08_contribuindo_e_desenvolvimento/00_contribuindo_e_dev_local.md b/docs_translations/pt-br/08_contribuindo_e_desenvolvimento/00_contribuindo_e_dev_local.md new file mode 100644 index 000000000..821de7a67 --- /dev/null +++ b/docs_translations/pt-br/08_contribuindo_e_desenvolvimento/00_contribuindo_e_dev_local.md @@ -0,0 +1,174 @@ +# Módulo: Contribuindo para o PraisonAI e Desenvolvimento Local + +Este módulo é para você que deseja ir além de usar o PraisonAI e quer contribuir para o seu desenvolvimento, ou simplesmente configurar um ambiente local para explorar o código-fonte mais a fundo e talvez fazer suas próprias modificações. + +## Contribuindo para o PraisonAI + +Contribuições da comunidade são essenciais para o crescimento e aprimoramento de projetos de código aberto como o PraisonAI. Se você tem interesse em contribuir, o processo geralmente segue o fluxo padrão do GitHub: + +1. **Faça um Fork do Repositório:** + * Vá até a página do repositório oficial do PraisonAI no GitHub: [https://github.com/MervinPraison/PraisonAI](https://github.com/MervinPraison/PraisonAI) + * Clique no botão "Fork" no canto superior direito. Isso criará uma cópia do repositório na sua conta do GitHub. + +2. **Clone o Seu Fork Localmente:** + * Em seu terminal, clone o repositório que você acabou de "forkar": + ```bash + git clone https://github.com/SEU_USUARIO_GITHUB/PraisonAI.git + cd PraisonAI + ``` + * Substitua `SEU_USUARIO_GITHUB` pelo seu nome de usuário no GitHub. + +3. **Crie uma Nova Branch para Suas Mudanças:** + * É uma boa prática criar uma nova branch para cada funcionalidade ou correção que você for trabalhar. Isso mantém o histórico organizado e facilita a integração. + ```bash + git checkout -b minha-nova-funcionalidade # Escolha um nome descritivo para a branch + ``` + +4. **Faça Suas Alterações:** + * Implemente a nova funcionalidade, corrija um bug, melhore a documentação, etc. + * Certifique-se de seguir as convenções de código e estilo do projeto, se houver. + +5. **Teste Suas Mudanças:** + * Execute os testes existentes para garantir que suas alterações não quebraram nada. (Veja a seção "Executando Testes" abaixo). + * Se estiver adicionando uma nova funcionalidade, considere adicionar novos testes para cobri-la. + +6. **Faça o Commit das Suas Alterações:** + * Adicione os arquivos modificados e faça o commit com uma mensagem clara e descritiva. + ```bash + git add . + git commit -m "feat: Adiciona nova funcionalidade X que faz Y" + # Ou "fix: Corrige bug Z no componente W" + # Siga as convenções de commit do projeto, se houver (ex: Conventional Commits). + ``` + +7. **Envie Suas Alterações para o Seu Fork no GitHub:** + ```bash + git push origin minha-nova-funcionalidade + ``` + +8. **Abra um Pull Request (PR):** + * Vá até a página do seu fork no GitHub. + * Você verá um aviso para criar um Pull Request da sua nova branch para o repositório original do PraisonAI. + * Clique nele, revise suas alterações, escreva uma descrição clara do que seu PR faz e porquê, e envie-o. + +9. **Aguarde o Feedback:** + * Os mantenedores do projeto revisarão seu Pull Request. Eles podem solicitar alterações, fazer perguntas ou aprovar e mesclar suas contribuições. Seja paciente e responsivo ao feedback. + +**Onde mais procurar por informações sobre contribuição:** +* Verifique se há um arquivo `CONTRIBUTING.md` no repositório principal. +* Observe as issues abertas, especialmente aquelas marcadas como "good first issue" ou "help wanted". +* Participe das discussões da comunidade (links geralmente no `README.md` ou na página do GitHub). + +## Configurando o Ambiente de Desenvolvimento Local + +Se você deseja explorar o código, fazer modificações ou contribuir, precisará de um ambiente de desenvolvimento local. + +1. **Pré-requisitos:** + * Python (versão >=3.10, conforme `pyproject.toml`). + * Git. + * Opcional, mas recomendado: `uv` (um instalador Python rápido). + +2. **Clone o Repositório (se ainda não o fez):** + ```bash + git clone https://github.com/MervinPraison/PraisonAI.git # Ou seu fork + cd PraisonAI/src/praisonai # Navegue para a pasta do pacote principal que contém o pyproject.toml + ``` + *Nota: O `pyproject.toml` principal do projeto parece estar em `src/praisonai/`. Verifique a estrutura exata se tiver problemas.* + +3. **Crie e Ative um Ambiente Virtual (Altamente Recomendado):** + Isso isola as dependências do projeto e evita conflitos com outros projetos Python em seu sistema. + ```bash + # Navegue para a pasta que contém o pyproject.toml (ex: src/praisonai) + python -m venv .venv + # No Windows (CMD): + # .venv\Scripts\activate + # No Windows (PowerShell): + # .venv\Scripts\Activate.ps1 + # No macOS/Linux: + # source .venv/bin/activate + ``` + +4. **Instale `uv` (Recomendado pelo Projeto):** + Se ainda não o tiver e quiser seguir as instruções de desenvolvimento do `README.md`: + ```bash + pip install uv + ``` + +5. **Instale as Dependências do Projeto:** + O `README.md` e o `pyproject.toml` do PraisonAI indicam o uso de `uv` para instalar dependências. + * **Instalação básica em modo editável (para desenvolvimento):** + Isto instalará o pacote `PraisonAI` e suas dependências principais. O modo editável (`-e`) significa que as alterações que você fizer no código-fonte local serão refletidas imediatamente ao usar o pacote. + ```bash + # Certifique-se de estar na pasta com o pyproject.toml (ex: src/praisonai) + uv pip install -e . + ``` + * **Instalando com dependências opcionais (extras):** + O PraisonAI usa "extras" para dependências que habilitam funcionalidades específicas (como `crewai`, `autogen`, `ui`, `code`, etc.). Você pode instalá-los conforme necessário. + ```bash + uv pip install -e .[crewai,autogen] + uv pip install -e .[ui,code] + # Para instalar todos os extras, você pode precisar listá-los ou verificar se há um extra "all". + # O pyproject.toml lista os extras disponíveis. + ``` + O `README.md` também menciona: + ```bash + # uv pip install -r pyproject.toml --extra code + # Esta sintaxe também pode funcionar, mas instalar com -e .[extra] é comum para desenvolvimento local. + ``` + A forma mais idiomática, especialmente com `uv` e Poetry (que o `pyproject.toml` usa), seria instalar os grupos de dependência. O `pyproject.toml` define grupos como `[tool.poetry.group.dev.dependencies]`. + Para instalar dependências de desenvolvimento (que incluem testes, docs, etc.): + ```bash + uv pip install --system # Garante que uv use o Python do ambiente virtual ativo + uv pip install -e .[dev] # Se houver um extra 'dev' que agrupe tudo + # Ou, se usando Poetry diretamente (não uv): + # poetry install --with dev + ``` + Dado que o `README.md` foca em `uv pip install -r pyproject.toml --extra ` ou `uv pip install -e .[]`, siga essa orientação. + +## Executando Testes + +O PraisonAI possui uma estrutura de testes abrangente, conforme detalhado em `src/praisonai/tests/TESTING_GUIDE.md`. É crucial executar testes após fazer alterações para garantir que nada foi quebrado. + +**Principais Pontos do Guia de Testes:** + +* **Estrutura:** + * `tests/unit/`: Testes unitários (rápidos, isolados). + * `tests/integration/`: Testes de integração mockados (gratuitos, rápidos, para CI/CD e desenvolvimento). + * `tests/e2e/`: Testes end-to-end reais (podem ter custos com APIs, mais lentos). +* **Como Rodar (Recomendado pelo `TESTING_GUIDE.md`):** + O projeto fornece um `test_runner.py`. + * **Testes Mock (Gratuitos):** + ```bash + # Todos os testes de integração mockados + python tests/test_runner.py --pattern frameworks + + # Testes mock apenas para AutoGen + python tests/test_runner.py --pattern autogen + + # Testes mock apenas para CrewAI + python tests/test_runner.py --pattern crewai + ``` + * **Testes Reais (Podem ter Custo!):** + Requerem configuração de chaves de API (ex: `OPENAI_API_KEY`). + ```bash + # Todos os testes reais (irá pedir confirmação) + python tests/test_runner.py --pattern real + ``` + (Existem mais padrões para testes reais e de execução completa, consulte o `TESTING_GUIDE.md`). +* **Usando `pytest` Diretamente:** + O `pyproject.toml` lista `pytest` como uma dependência de teste. + * **Testes de Integração Mockados:** + ```bash + # Certifique-se de que as dependências de teste estão instaladas no seu ambiente virtual + # (ex: uv pip install -e .[test] ou poetry install --with test) + python -m pytest src/praisonai/tests/integration/ -v + # Ou pytest src/praisonai/tests/integration/ -v (se pytest está no PATH do venv) + ``` + * **Testes Reais (Requer Chaves de API):** + ```bash + python -m pytest src/praisonai/tests/e2e/ -v -m real + ``` + +**Antes de rodar testes reais, sempre leia o `TESTING_GUIDE.md` para entender os custos potenciais e a configuração necessária.** + +Seguindo estas diretrizes, você estará bem equipado para contribuir com o PraisonAI ou para explorá-lo e adaptá-lo às suas necessidades em um ambiente de desenvolvimento local. diff --git a/docs_translations/pt-br/08_contribuindo_e_desenvolvimento/01_estrutura_do_codigo.md b/docs_translations/pt-br/08_contribuindo_e_desenvolvimento/01_estrutura_do_codigo.md new file mode 100644 index 000000000..d91582e99 --- /dev/null +++ b/docs_translations/pt-br/08_contribuindo_e_desenvolvimento/01_estrutura_do_codigo.md @@ -0,0 +1,19 @@ +# Entendendo a Estrutura do Código + +Para contribuir ou personalizar o PraisonAI é importante conhecer a organização do diretório `src/`. + +## Principais Pastas + +- **praisonai/**: pacote Python que oferece a CLI `praisonai` e arquivos de configuração de exemplo (`agents.yaml`, `agents-advanced.yaml`, `config.yaml`). É aqui que está o script `cli.py` com as funções de execução e deploy. +- **praisonai-agents/**: biblioteca central `praisonaiagents` contendo as classes `Agent`, `Task`, memórias e ferramentas nativas. +- **praisonai-ts/**: versão em TypeScript/Node.js do framework, destinada a quem prefere trabalhar em JavaScript. + +Dentro de cada pacote há submódulos como `agent`, `task`, `memory`, `tools` e `llm`. Explore esses arquivos para entender como os agentes são implementados. + +### Arquivos de Configuração + +Na pasta `src/praisonai` você encontra exemplos de YAML prontos (citados no módulo [Configurações com YAML](../03_usando_praisonai/06_configuracoes_yaml.md)). Esses arquivos são ótimos pontos de partida para seus experimentos. + +Além disso, o script `inc/config.py` possui a função `generate_config`, utilizada para criar `config.yaml` com parâmetros de treinamento. + +Conhecer essa estrutura ajuda a localizar facilmente onde adicionar novos agentes, ferramentas ou integrações. diff --git a/docs_translations/pt-br/09_duvidas_frequentes.md b/docs_translations/pt-br/09_duvidas_frequentes.md new file mode 100644 index 000000000..a025b9883 --- /dev/null +++ b/docs_translations/pt-br/09_duvidas_frequentes.md @@ -0,0 +1,45 @@ +# Dúvidas Frequentes (FAQ) + +Esta seção reúne respostas rápidas para questões comuns ao começar com o PraisonAI. + +## 1. "ModuleNotFoundError: praisonaiagents" +Se, ao executar um exemplo em Python, você receber essa mensagem: +```bash +ModuleNotFoundError: No module named 'praisonaiagents' +``` +Isso indica que o pacote não está instalado no ambiente atual. Execute: +```bash +pip install praisonaiagents +``` +Se estiver usando um clone do repositório, você também pode instalar em modo editável: +```bash +uv pip install -e . +``` +(caso tenha o `uv` instalado) ou +```bash +pip install -e . +``` + +## 2. Como configuro minha `OPENAI_API_KEY`? +A maioria dos exemplos utiliza modelos da OpenAI. Defina a variável de ambiente com: +```bash +export OPENAI_API_KEY="sua-chave-aqui" # Linux ou macOS +set OPENAI_API_KEY="sua-chave-aqui" # Windows CMD +$env:OPENAI_API_KEY="sua-chave-aqui" # PowerShell +``` + +## 3. Preciso de GPU ou conexão constante com a internet? +Para executar os agentes locais que usam modelos via API (como OpenAI), basta ter conexão com a internet. Uma GPU dedicada só é necessária se você planeja rodar modelos locais pesados (ex.: via Ollama ou outros provedores que permitam modelos offline). + +## 4. Onde ficam os exemplos prontos? +Todos os scripts demonstrativos estão em `examples/python/`. A pasta é subdividida em: +- `agents/` – agentes especializados (veja [Modelos de Agentes](03_usando_praisonai/05_modelos_de_agentes.md)). +- `general/` – conceitos isolados como memória, ferramentas e workflows. +- `concepts/` – implementações de RAG, processamento de CSV etc. +- `usecases/` – estudos de caso completos. + +Abra um terminal nesse diretório e execute o arquivo desejado com `python nome_do_exemplo.py`. + +## 5. Como tiro outras dúvidas ou reporto problemas? +Consulte o repositório no GitHub e abra uma *issue* descrevendo o problema ou a sugestão. Se preferir discutir em português, sinta-se à vontade. + diff --git a/docs_translations/pt-br/README.md b/docs_translations/pt-br/README.md new file mode 100644 index 000000000..8c3e346d7 --- /dev/null +++ b/docs_translations/pt-br/README.md @@ -0,0 +1,31 @@ +# Bem-vindo ao Curso PraisonAI! + +Este repositório é um **fork** do projeto original e é mantido por [Habdel-Edenfield](https://github.com/Habdel-Edenfield). O propósito desta iniciativa é criar um **laboratório de aprendizado** sobre agentes autônomos e compartilhar conhecimento de forma acessível e colaborativa. A motivação de Habdel é filantrópica, contribuindo com a comunidade de desenvolvimento de tecnologias aplicadas ao **Open Tibia Server** e a outros projetos de IA. + +Navegue pelos módulos à esquerda para começar sua jornada de aprendizado. Cada seção foi organizada para conduzir o estudo passo a passo, sempre destacando conceitos práticos e exemplos reais. + +## Estrutura do Curso + +* **Introdução:** Visão geral do PraisonAI e desta documentação. +* **Metodologia de Aprendizado:** Orientações científicas para estudar com eficiência. +* **Instalação:** Como instalar o PraisonAI em seu ambiente. +* **Conceitos Fundamentais:** Os blocos de construção do PraisonAI. +* **Usando o PraisonAI:** Guias práticos para Python, YAML e JavaScript/TypeScript. +* **Guia Rápido: Criando Seu Primeiro Agente:** Passo a passo para colocar um agente em funcionamento. +* **Modelos de Agentes:** Visão geral dos agentes especializados disponíveis nos exemplos. +* **[Configurações com YAML](03_usando_praisonai/06_configuracoes_yaml.md):** Como definir agentes e tarefas de forma declarativa. +* **Workflows Avançados:** Explore as capacidades de múltiplos agentes. + * **Agentes Multimodais** + * **Code Interpreter Agents** + * **Math Agents** + * **Saída Estruturada** + * **Callback Agents** + * **Mini AI Agents** +* **Ferramentas:** Utilizando e criando ferramentas. +* **Modelos LLM:** Integrando com diversos modelos de linguagem. +* **Exemplos Práticos:** Estudos de caso detalhados. +* **Contribuindo e Desenvolvimento:** Para quem quer ir além. + * **Entendendo a Estrutura do Código** +* **Dúvidas Frequentes:** Respostas rápidas para problemas comuns. + +Boa sorte e bons estudos! \ No newline at end of file diff --git a/docs_translations/pt-br/plan.md b/docs_translations/pt-br/plan.md new file mode 100644 index 000000000..42725eaed --- /dev/null +++ b/docs_translations/pt-br/plan.md @@ -0,0 +1,54 @@ +# Plano de Conteúdo do Curso PraisonAI + +Este arquivo resume os módulos já existentes na documentação em `docs/pt-br` e aponta temas que ainda podem ser desenvolvidos. Use-o como guia para acompanhar o progresso do material. + +## Conteúdo Atual + +1. **Introdução** + - Como usar esta documentação e plugins recomendados para Obsidian. + - O que é o PraisonAI, filosofia e casos de uso. + - Metodologia de aprendizado baseada em ciclo científico. +2. **Instalação** + - Guia completo de instalação no Windows com variáveis de ambiente e verificação do pacote. +3. **Conceitos Fundamentais** + - Explicação sobre agentes, tarefas, ferramentas, processos, memória e RAG. +4. **Usando o PraisonAI** + - Uso com Python (`praisonaiagents`). + - Uso com YAML (CLI `praisonai`). + - Uso com JavaScript/TypeScript. + - Guia rápido "Criando Seu Primeiro Agente". + - Catálogo de modelos de agentes disponíveis nos exemplos. + - Configurações com YAML para definir agentes de forma declarativa. + - Importações e funções essenciais para criação de agentes. +5. **Workflows Avançados** + - Colaboração entre agentes, roteamento, orquestração, modo autônomo, paralelização e encadeamento de prompts. +6. **Ferramentas** + - Visão geral e criação de ferramentas personalizadas. +7. **Modelos LLM** + - Configuração de diferentes provedores (OpenAI, Ollama, Groq, etc.). +8. **Exemplos Práticos** + - Estudos de caso demonstrando aplicações reais do framework. +9. **Contribuindo e Desenvolvimento** + - Passos para trabalhar localmente e contribuir com o projeto. + - Entendendo a estrutura do código em `src/`. +10. **Dúvidas Frequentes (FAQ)** + - Respostas rápidas para erros comuns de instalação e execução. + +## Pontos a Desenvolver + +- Adicionar instruções de instalação para Linux e macOS. +- Explorar exemplos mais detalhados de ferramentas e memórias avançadas. +- Criar exercícios práticos adicionais para fixação dos conceitos. +- Documentar integrações específicas com outros provedores de LLM (ex.: Gemini, Anthropic). +- Incluir guia de depuração e boas práticas para resolução de problemas. +- Criar seções para recursos ainda não documentados: +- - (concluído) Agentes Multimodais +- - (concluído) Code Interpreter Agents +- - (concluído) Math Agents +- - (concluído) Agentes com Saída Estruturada +- - (concluído) Callback Agents +- - (concluído) Mini AI Agents +- Documentar a estrutura do código e exemplos de YAML (concluído) + + +Este plano deve ser atualizado sempre que novos módulos ou seções forem criados. \ No newline at end of file diff --git a/src/praisonai/tests/unit/agent/test_mini_agents_fix.py b/src/praisonai/tests/unit/agent/test_mini_agents_fix.py index 0873ede5b..58a9a4747 100644 --- a/src/praisonai/tests/unit/agent/test_mini_agents_fix.py +++ b/src/praisonai/tests/unit/agent/test_mini_agents_fix.py @@ -6,14 +6,12 @@ import sys import os +import pytest + sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src')) -try: - from praisonaiagents import Agent, Agents - print("✅ Successfully imported PraisonAI Agents") -except ImportError as e: - print(f"❌ Failed to import: {e}") - sys.exit(1) +pytest.importorskip("praisonaiagents") +from praisonaiagents import Agent, Agents def test_context_processing(): """Test the context processing logic without running actual agents"""