{"id":29715612,"url":"https://github.com/rodolfo-code/agent-template","last_synced_at":"2025-08-24T03:38:37.900Z","repository":{"id":305413163,"uuid":"1022801518","full_name":"rodolfo-code/agent-template","owner":"rodolfo-code","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-20T00:35:40.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-20T00:55:27.070Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rodolfo-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T21:25:21.000Z","updated_at":"2025-07-20T00:35:43.000Z","dependencies_parsed_at":"2025-07-20T01:08:12.398Z","dependency_job_id":null,"html_url":"https://github.com/rodolfo-code/agent-template","commit_stats":null,"previous_names":["rodolfo-code/agent-template"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rodolfo-code/agent-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodolfo-code%2Fagent-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodolfo-code%2Fagent-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodolfo-code%2Fagent-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodolfo-code%2Fagent-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rodolfo-code","download_url":"https://codeload.github.com/rodolfo-code/agent-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodolfo-code%2Fagent-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266796972,"owners_count":23985515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-24T05:37:39.415Z","updated_at":"2025-07-24T05:37:40.857Z","avatar_url":"https://github.com/rodolfo-code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Template Cookiecutter para Micro-Agentes Python\n\nUm template Cookiecutter robusto para criar micro-agentes Python especializados usando Clean Architecture, FastAPI, LangGraph, LangChain e OpenAI, otimizado para integração com Kestra.\n\n## 🌟 Características Principais\n\n- **🏗️ Clean Architecture**: Separação clara de responsabilidades em camadas\n- **🤖 LangGraph**: Workflow de agentes com nós interconectados e decision routing\n- **⚡ FastAPI**: API REST moderna com documentação automática\n- **🔗 LangChain**: Integração nativa com LLMs e ferramentas\n- **🧠 OpenAI**: Suporte para GPT-4o, GPT-4o-mini e outros modelos\n- **🔄 Reflexão Automática**: Sistema de auto-avaliação e melhoria iterativa\n- **📊 LangSmith**: Monitoramento e debugging opcional\n- **🐳 Docker Ready**: Containerização completa com Docker e Docker Compose\n- **📦 uv**: Gerenciamento de dependências ultrarrápido\n- **🔌 Kestra Integration**: Pronto para integração com workflows Kestra\n- **📝 Logging Estruturado**: Logs JSON com structlog\n- **🛡️ Configuração Robusta**: Validação de configuração com Pydantic Settings\n\n## 🚀 Início Rápido\n\n### Pré-requisitos\n\n```bash\n# Python 3.12+\npython --version\n\n# Cookiecutter\npip install cookiecutter\n\n# uv (recomendado)\npip install uv\n```\n\n### 1. Gerar Projeto\n\n```bash\n# Use o template\ncookiecutter https://github.com/seu-usuario/agent-template\n\n# Ou localmente\ncookiecutter .\n```\n\n### 2. Configurar Projeto\n\n```bash\n# Entre no diretório gerado\ncd meu-novo-agente\n\n# Configure variáveis de ambiente\ncp ENV_VARS.md .env\n# Edite o .env com suas chaves da API\n\n# Instale dependências\nuv sync\n\n# Execute o agente\nuv run uvicorn main:app --reload\n```\n\n### 3. Testar API\n\n```bash\n# Health check\ncurl http://localhost:8000/health\n\n# Documentação automática\nopen http://localhost:8000/docs\n```\n\n## 📁 Estrutura Gerada\n\n```\nmeu-novo-agente/\n├── app/\n│   ├── presentation/           # 🌐 Camada de Apresentação (FastAPI)\n│   │   └── domain_router.py    # Endpoints REST\n│   ├── application/            # 📋 Camada de Aplicação\n│   │   ├── agent/              # 🤖 Agentes LangGraph\n│   │   │   └── AgentName/\n│   │   │       ├── agent_builder/     # Construtor do grafo\n│   │   │       └── node_functions/    # Nós do workflow\n│   │   │           ├── main_node/     # Nó principal\n│   │   │           ├── reflect_node/  # Nó de reflexão\n│   │   │           └── adjust_node/   # Nó de ajuste\n│   │   ├── interfaces/         # 🔌 Contratos/Protocolos\n│   │   └── services/           # ⚙️ Serviços de aplicação\n│   ├── domain/                 # 🏢 Camada de Domínio\n│   │   ├── entities/           # Entidades de negócio\n│   │   └── state/              # Estados do LangGraph\n│   └── infrastructure/         # 🔧 Camada de Infraestrutura\n│       ├── config/             # Configurações\n│       └── llm/                # Serviços LLM\n├── main.py                     # 🚪 Ponto de entrada\n├── pyproject.toml             # 📦 Configuração do projeto\n├── Dockerfile                 # 🐳 Container Docker\n├── docker-compose.yml         # 🐙 Orchestração\n└── README.md                  # 📖 Documentação\n```\n\n## 🎯 Workflow do Agente (LangGraph)\n\n```mermaid\ngraph TD\n    A[main_processing] --\u003e B{decision_router}\n    B --\u003e|reflect| C[reflection]\n    B --\u003e|adjust| D[adjust_processing]\n    B --\u003e|end| E[__end__]\n    C --\u003e F{decision_router}\n    F --\u003e|adjust| D\n    F --\u003e|end| E\n    D --\u003e A\n```\n\n### Nós Implementados\n\n1. **🎯 main_processing**: Processamento principal usando LLM\n2. **🔍 reflection**: Avaliação da qualidade do resultado\n3. **⚙️ adjust_processing**: Ajustes baseados na reflexão\n4. **🧭 decision_router**: Roteamento inteligente entre nós\n\n## 🛠️ Configuração Avançada\n\n### Variáveis de Ambiente\n\n```bash\n# OpenAI (Obrigatório)\nOPENAI_API_KEY=sua_chave_aqui\nOPENAI_MODEL=gpt-4o-mini\n\n# LangSmith (Opcional)\nLANGCHAIN_TRACING_V2=true\nLANGCHAIN_API_KEY=sua_chave_langsmith\n\n# Configuração do Agente\nAGENT_MAX_RETRIES=3\nAGENT_TIMEOUT=30\nAGENT_ENABLE_REFLECTION=true\n```\n\n### Personalização\n\n#### 1. Modificar Prompts\n\nEdite os arquivos `node.py` em cada nó para customizar os prompts:\n\n```python\n# app/application/agent/AgentName/node_functions/main_node/node.py\nsystem_prompt = \"\"\"Seu prompt customizado aqui...\"\"\"\n```\n\n#### 2. Adicionar Novos Nós\n\n```bash\n# 1. Crie o diretório do nó\nmkdir app/application/agent/AgentName/node_functions/novo_node\n\n# 2. Implemente a função do nó\n# 3. Adicione no agent_builder.py\n# 4. Atualize o decision_router.py\n```\n\n#### 3. Configurar Novos Endpoints\n\n```python\n# app/presentation/domain_router.py\n@router.post(\"/novo-endpoint\")\nasync def novo_endpoint(request: NovoRequest):\n    # Implementação\n```\n\n## 🐳 Deploy\n\n### Docker\n\n```bash\n# Build e execução\ndocker build -t meu-agente .\ndocker run -p 8000:8000 --env-file .env meu-agente\n```\n\n### Docker Compose\n\n```bash\n# Desenvolvimento\ndocker-compose up --build\n\n# Produção\ndocker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n```\n\n### Kubernetes\n\n```yaml\n# Exemplo de deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: meu-agente\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: meu-agente\n  template:\n    spec:\n      containers:\n        - name: agent\n          image: meu-agente:latest\n          ports:\n            - containerPort: 8000\n```\n\n## 🔗 Integração com Kestra\n\n### Exemplo de Flow\n\n```yaml\nid: agent-workflow\nnamespace: ai.agents\n\ntasks:\n  - id: process-content\n    type: io.kestra.plugin.core.http.Request\n    uri: http://meu-agente:8000/domain/process\n    method: POST\n    body: |\n      {\n        \"content\": \"{{ inputs.content }}\",\n        \"options\": {\"enable_reflection\": true}\n      }\n```\n\n## 📊 Monitoramento\n\n### Métricas Incluídas\n\n- ⏱️ Tempo de execução por nó\n- 🎯 Taxa de sucesso/erro\n- 💰 Uso de tokens OpenAI\n- 📈 Scores de confiança\n- 🔄 Número de iterações\n\n### Health Checks\n\n```bash\n# Status da aplicação\ncurl http://localhost:8000/health\n\n# Status específico do agente\ncurl http://localhost:8000/domain/health\n\n# Schema do workflow\ncurl http://localhost:8000/domain/schema\n```\n\n## 🧪 Testes\n\n### Teste Automatizado\n\n```bash\n# Execute o script de teste\npython test_template.py\n```\n\n### Testes Manuais\n\n```bash\n# Teste básico\ncurl -X POST http://localhost:8000/domain/process \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"texto para processar\"}'\n\n# Teste com reflexão\ncurl -X POST http://localhost:8000/domain/process-with-reflection \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"texto complexo\", \"options\": {\"enable_reflection\": true}}'\n```\n\n## 📚 Exemplos Práticos\n\n- **[Análise de Sentimentos](EXEMPLO_USO.md)**: Agente especializado em análise de sentimentos\n- **Sumarização**: Agente para sumarização de textos\n- **Classificação**: Agente para classificação de documentos\n- **Extração de Entidades**: Agente para NER (Named Entity Recognition)\n\n## 🛡️ Boas Práticas\n\n### Segurança\n\n- ✅ Nunca commitar chaves de API\n- ✅ Usar variáveis de ambiente para configuração\n- ✅ Implementar rate limiting em produção\n- ✅ Validar entrada rigorosamente\n\n### Performance\n\n- ✅ Configurar timeouts apropriados\n- ✅ Implementar cache quando necessário\n- ✅ Monitorar uso de tokens\n- ✅ Usar modelos apropriados (GPT-4o-mini para tarefas simples)\n\n### Desenvolvimento\n\n- ✅ Seguir Clean Architecture\n- ✅ Implementar testes unitários\n- ✅ Usar logging estruturado\n- ✅ Documentar APIs com FastAPI\n\n## 🤝 Contribuição\n\n1. Fork o projeto\n2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)\n3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)\n4. Push para a branch (`git push origin feature/AmazingFeature`)\n5. Abra um Pull Request\n\n## 📄 Licença\n\nEste projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.\n\n## 🆘 Suporte\n\n- 📖 [Documentação Completa](COMO_USAR_TEMPLATE.md)\n- 💡 [Exemplo Prático](EXEMPLO_USO.md)\n- 🧪 [Scripts de Teste](test_template.py)\n- 🐛 [Reportar Issues](https://github.com/seu-usuario/agent-template/issues)\n\n## 🗺️ Roadmap\n\n- [ ] Suporte a múltiplos LLM providers (Anthropic, Google, etc.)\n- [ ] Templates especializados por domínio\n- [ ] Dashboard de monitoramento integrado\n- [ ] Suporte a streaming de respostas\n- [ ] Integração com bancos vetoriais\n- [ ] Ferramentas de debugging visuais\n- [ ] CI/CD templates\n\n---\n\n**Criado com ❤️ para acelerar o desenvolvimento de micro-agentes Python de alta qualidade.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodolfo-code%2Fagent-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frodolfo-code%2Fagent-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodolfo-code%2Fagent-template/lists"}