# Scripts Utilitários para TESS e MCP Este diretório contém scripts utilitários para interação com o TESS, MCP e outros serviços relacionados. ## TESS API CLI (`tess_api_cli.py`) Uma ferramenta de linha de comando para interagir diretamente com a API TESS, facilitando a listagem, consulta e execução de agentes TESS. ### Recursos - Listar todos os agentes TESS disponíveis - Consultar informações detalhadas sobre um agente específico - Listar modelos disponíveis com recomendações - Executar agentes TESS com parâmetros personalizados - Suporte para Claude 3.7 Sonnet com Extended Thinking - Suporte a diferentes formatos de saída (texto, JSON, formatado) - Carregar parâmetros de arquivos JSON - Tratamento de erros específicos da API TESS ### Pré-requisitos - Python 3.6+ - Bibliotecas: requests, dotenv - API Key TESS válida ### Instalação Não é necessário instalar. Certifique-se apenas de que o script tenha permissão de execução: ```bash chmod +x tess_api_cli.py ``` ### Uso #### Listar agentes disponíveis: ```bash ./tess_api_cli.py listar ``` #### Obter informações detalhadas sobre um agente específico: ```bash ./tess_api_cli.py info 45 # onde 45 é o ID do agente ``` #### Listar modelos disponíveis: ```bash ./tess_api_cli.py modelos ``` #### Executar um agente com parâmetros em linha de comando: ```bash ./tess_api_cli.py executar 45 \ --nome-da-empresa "Café Aroma" \ --descrio "Cafeteria gourmet com café de origem única" \ --diferenciais "Café de origem única, torrefação artesanal" \ --call-to-action "Visite-nos hoje" \ --temperature "0.75" \ --language "Portuguese (Brazil)" \ --maxlength 140 ``` #### Executar um agente com Claude 3.7 Sonnet e Extended Thinking: ```bash ./tess_api_cli.py executar 45 \ --nome-da-empresa "Café Aroma" \ --descrio "Cafeteria gourmet com café de origem única" \ --diferenciais "Café de origem única, torrefação artesanal" \ --call-to-action "Visite-nos hoje" \ --model "claude-3-7-sonnet@20250219" \ --extended_thinking True ``` #### Executar um agente com parâmetros de um arquivo JSON: ```bash ./tess_api_cli.py executar 45 --parametros exemplo_anuncios_cafe.json ``` #### Escolher o formato de saída: ```bash ./tess_api_cli.py executar 45 --parametros exemplo_anuncios_cafe.json --formato-saida json ``` ### Exemplo de arquivo de parâmetros (JSON) Veja o exemplo em `exemplo_anuncios_cafe.json`: ```json { "nome-da-empresa": "Café Aroma", "descrio": "Cafeteria gourmet com café de origem única e torrefação artesanal.", "diferenciais": "Café de origem única, torrefação artesanal, experiência premium para amantes de café", "call-to-action": "Visite-nos hoje", "temperature": "0.75", "model": "gpt-4o", "maxlength": 140, "language": "Portuguese (Brazil)" } ``` Outro exemplo disponível é `exemplo_anuncios_mkt.json`, para agência de marketing digital: ```json { "nome-da-empresa": "Marketing Digital Pro", "descrio": "Agência especializada em marketing digital com foco em resultados e ROI. Oferecemos serviços completos de SEO, redes sociais, Google Ads e marketing de conteúdo para pequenas e médias empresas que querem aumentar sua presença online e gerar mais leads qualificados.", "diferenciais": "Estratégias personalizadas, métricas em tempo real, especialistas certificados em Google Ads e Meta, metodologia comprovada, atendimento personalizado, relatórios transparentes mensais, retorno sobre investimento garantido", "call-to-action": "Agende uma consulta gratuita", "temperature": "0.75", "model": "gpt-4o", "maxlength": 140, "language": "Portuguese (Brazil)" } ``` E para corretora de seguros, veja o exemplo em `exemplo_anuncios_seguros.json`: ```json { "nome-da-empresa": "Seguros Confiança", "descrio": "Corretora de seguros especializada em planos personalizados para vida, auto, residencial e empresarial. Oferecemos as melhores coberturas do mercado com preços competitivos e atendimento 24/7.", "diferenciais": "Atendimento 24/7, sinistro resolvido em até 48h, planos personalizados, melhor preço garantido, especialistas em cada modalidade de seguro, assistência completa", "call-to-action": "Solicite uma cotação grátis", "temperature": "0.75", "model": "gpt-4o", "maxlength": 140, "language": "Portuguese (Brazil)" } ``` ### Modelos recomendados Os seguintes modelos são recomendados para uso com a API TESS: 1. **GPT-4o** (`gpt-4o`): Modelo padrão recomendado, com excelente performance para geração de texto e processamento de contexto. Versão avançada do GPT-4 com recursos multimodais. 2. **Claude 3.5 Sonnet** (`claude-3-5-sonnet-20240620`): Bom balanceamento entre velocidade e qualidade. Recomendado para tarefas que exigem raciocínio mais complexo. 3. **GPT-4o mini** (`gpt-4o-mini`): Versão mais rápida e econômica do GPT-4o, ideal para tarefas que não exigem máxima qualidade. > **Nota:** O modelo Claude 3.7 Sonnet com Extended Thinking não está disponível diretamente na API TESS. O script foi configurado para usar GPT-4o como modelo padrão, que oferece ótima qualidade e compatibilidade com a API. ### Extended Thinking O recurso **Extended Thinking** está disponível para o modelo Claude 3.7 Sonnet e permite um raciocínio mais detalhado, passo a passo, em problemas complexos. Este modo faz com que o modelo: - Divida problemas complexos em etapas menores - Raciocine de forma mais aprofundada, considerando múltiplas alternativas - Forneça explicações mais detalhadas para suas decisões - Avalie criticamente seu próprio raciocínio Para habilitar este recurso, use o parâmetro `extended_thinking`: ```bash ./tess_api_cli.py executar 45 --model "claude-3-7-sonnet@20250219" --extended_thinking True ``` ### Vantagens sobre o comando `test_api_tess` O `tess_api_cli.py` oferece várias vantagens em relação ao comando `test_api_tess`: 1. **Parâmetros completos**: Envia automaticamente todos os parâmetros necessários para cada agente 2. **Validação simples**: Exibe mensagens de erro mais descritivas 3. **Formatos de saída**: Suporta diferentes formatos de saída, incluindo JSON e formatado 4. **Flexibilidade**: Aceita parâmetros tanto de linha de comando quanto de arquivo JSON 5. **Documentação completa**: Exibe informações detalhadas sobre cada agente e seus parâmetros 6. **Suporte a modelos avançados**: Configurado para usar o GPT-4o por padrão, garantindo melhor compatibilidade ## Outros Scripts - `setup_arcee_cli.sh`: Script para instalação do Arcee CLI - `start_streamlit.sh`: Inicia a aplicação Streamlit - `iniciar_tess_mcp_dev.sh`: Inicia o ambiente de desenvolvimento TESS MCP - `iniciar_tess_mcp_prod.sh`: Inicia o ambiente de produção TESS MCP - `find_tools_usage.py`: Utilitário para localizar uso de ferramentas - `migrate_tools.py`: Script para migração de ferramentas ## Dicas Práticas para o uso do `tess_api_cli.py` Baseado em nossa experiência com o uso intensivo da ferramenta, compartilhamos algumas dicas práticas: ### Otimizando os Resultados 1. **Consulte o agente antes de executar**: Use `./tess_api_cli.py info ` para ver exatamente quais parâmetros o agente espera antes de tentar executá-lo. 2. **Verifique os modelos disponíveis**: Use `./tess_api_cli.py modelos` para listar os modelos disponíveis e evitar erros 422 relacionados a modelos inválidos. 3. **Formate corretamente os valores**: Alguns parâmetros como `temperature` precisam ser enviados como string (ex: "0.75") e não como números. 4. **Preferência por arquivos JSON**: Para execuções frequentes ou parâmetros complexos, prefira usar arquivos JSON em vez de parâmetros na linha de comando. ### Solução de Problemas Comuns 1. **Erro 422 (Unprocessable Entity)**: - Verifique se todos os parâmetros obrigatórios estão presentes - Confirme se está usando um modelo válido (use `modelos` para listar) - Verifique o formato dos parâmetros (especialmente `temperature` como string) 2. **Erro com modelo Claude 3.7 Sonnet**: - Atualmente, o Claude 3.7 Sonnet com Extended Thinking não está disponível na API TESS - Use GPT-4o como alternativa recomendada 3. **Respostas incompletas ou incorretas**: - Tente aumentar o valor de `maxlength` para obter respostas mais completas - Ajuste o valor de `temperature` para equilibrar criatividade vs. precisão - Forneça descrições mais detalhadas nos parâmetros de entrada ### Comparação entre Arquivos de Exemplo Após testar com diferentes tipos de negócio, observamos que: | Exemplo | Detalhamento | Especificidade | Qualidade dos Anúncios | |---------|--------------|----------------|------------------------| | Café Aroma | Alto | Muito específico | Excelente | | Marketing Digital | Alto | Específico para serviços | Muito boa | | Seguros | Médio | Abrange múltiplos produtos | Boa, mas mais genérica | Quanto mais detalhada e específica a descrição do negócio e seus diferenciais, melhores são os resultados obtidos. Para dicas mais detalhadas sobre como criar parâmetros eficazes para diferentes tipos de negócio, consulte o arquivo [usando_api_tess_dicas.md](usando_api_tess_dicas.md) com exemplos e práticas recomendadas.