Documentação Técnica
Guia completo para instalação, configuração e uso do Capellaris, incluindo exemplos de código e referências de API.
Navegação Rápida
Instalação
Requisitos e passos para instalação
Configuração
Opções e parâmetros de configuração
Referência de API
Documentação completa da API
Criação de Agentes
Como criar e personalizar agentes
Gerenciamento de Squads
Formação e coordenação de equipes
Integração com Chat
Configuração de Slack e Teams
Instalação
Requisitos do Sistema
Requisitos Mínimos:
- Python 3.10 ou superior
- PostgreSQL 13 ou superior
- MongoDB 5.0 ou superior
- Redis 6.0 ou superior
- 8GB de RAM
- 50GB de espaço em disco
- Conexão com internet
Instalação via pip
# Criar ambiente virtual python -m venv venv source venv/bin/activate # Linux/Mac # ou venv\Scripts\activate # Windows # Instalar o pacote pip install gerenciador-agentes-ia # Verificar instalação gerenciador-agentes-ia --version
Instalação a partir do código-fonte
# Clonar o repositório git clone https://github.com/empresa/gerenciador-agentes-ia.git cd gerenciador-agentes-ia # Criar ambiente virtual python -m venv venv source venv/bin/activate # Linux/Mac # ou venv\Scripts\activate # Windows # Instalar dependências pip install -e . # Verificar instalação gerenciador-agentes-ia --version
Instalação com Docker
# Baixar a imagem docker pull empresa/gerenciador-agentes-ia:latest # Executar o contêiner docker run -d \ --name gerenciador-agentes \ -p 8000:8000 \ -v /caminho/para/config:/app/config \ -v /caminho/para/data:/app/data \ empresa/gerenciador-agentes-ia:latest # Verificar logs docker logs gerenciador-agentes
Configuração
O Capellaris pode ser configurado através de um arquivo de configuração em formato YAML ou através de variáveis de ambiente. Abaixo estão as principais opções de configuração disponíveis.
Arquivo de Configuração
# config.yaml sistema: nome: "Capellaris" versao: "1.0.0" modo_debug: false log_level: "info" banco_dados: postgres: host: "localhost" porta: 5432 usuario: "postgres" senha: "senha_segura" banco: "gerenciador_agentes" mongodb: uri: "mongodb://localhost:27017" banco: "gerenciador_agentes" redis: host: "localhost" porta: 6379 senha: null db: 0 api: host: "0.0.0.0" porta: 8000 workers: 4 timeout: 60 cors_origins: ["*"] seguranca: chave_secreta: "sua_chave_secreta_aqui" algoritmo_jwt: "HS256" expiracao_token: 86400 # 24 horas integracao: slack: token: "xoxb-seu-token-aqui" signing_secret: "seu-signing-secret-aqui" canais_permitidos: ["general", "marketing", "desenvolvimento"] teams: app_id: "seu-app-id-aqui" app_password: "seu-app-password-aqui" tenant_id: "seu-tenant-id-aqui" agentes: modelos: default: "gpt-4" fallback: "gpt-3.5-turbo" timeout_resposta: 30 max_tokens: 2000 temperatura: 0.7 aprendizado: armazenar_interacoes: true analisar_padroes: true otimizar_prompts: true intervalo_analise: 3600 # 1 hora
Variáveis de Ambiente
Todas as configurações também podem ser definidas através de variáveis de ambiente,
seguindo o padrão GERENCIADOR_SECAO_CHAVE
.
Exemplos:
GERENCIADOR_SISTEMA_NOME
- Nome do sistemaGERENCIADOR_BANCO_DADOS_POSTGRES_HOST
- Host do PostgreSQLGERENCIADOR_API_PORTA
- Porta da APIGERENCIADOR_INTEGRACAO_SLACK_TOKEN
- Token do Slack
Inicialização do Sistema
# Iniciar com arquivo de configuração gerenciador-agentes-ia start --config /caminho/para/config.yaml # Iniciar com variáveis de ambiente export GERENCIADOR_SISTEMA_NOME="Meu Sistema de Agentes" export GERENCIADOR_API_PORTA=9000 gerenciador-agentes-ia start # Iniciar em modo de desenvolvimento gerenciador-agentes-ia start --dev # Iniciar com configurações específicas gerenciador-agentes-ia start --host 0.0.0.0 --porta 8080 --workers 8
Referência de API
O Capellaris expõe uma API RESTful completa para interação programática com o sistema. Abaixo estão os principais endpoints disponíveis.
Autenticação
A API utiliza autenticação JWT (JSON Web Token). Para obter um token, faça uma requisição POST
para o endpoint /api/auth/token
com as credenciais de usuário.
Todas as requisições subsequentes devem incluir o token no cabeçalho Authorization
no formato Bearer {token}
.
# Obter token de autenticação POST /api/auth/token Content-Type: application/json { "username": "admin", "password": "senha_segura" } # Resposta { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer", "expires_in": 86400 }
Endpoints de Agentes
Listar Agentes
GET /api/agents
Retorna a lista de todos os agentes disponíveis no sistema.
Obter Agente
GET /api/agents/{agent_id}
Retorna os detalhes de um agente específico.
Criar Agente
POST /api/agents
Cria um novo agente com as configurações especificadas.
Atualizar Agente
PUT /api/agents/{agent_id}
Atualiza as configurações de um agente existente.
Excluir Agente
DELETE /api/agents/{agent_id}
Remove um agente do sistema.
Enviar Mensagem para Agente
POST /api/agents/{agent_id}/message
Envia uma mensagem para um agente e recebe a resposta.
Endpoints de Squads
Listar Squads
GET /api/squads
Retorna a lista de todos os squads disponíveis no sistema.
Obter Squad
GET /api/squads/{squad_id}
Retorna os detalhes de um squad específico.
Criar Squad
POST /api/squads
Cria um novo squad com os agentes especificados.
Atualizar Squad
PUT /api/squads/{squad_id}
Atualiza a composição e configurações de um squad existente.
Excluir Squad
DELETE /api/squads/{squad_id}
Remove um squad do sistema.
Enviar Tarefa para Squad
POST /api/squads/{squad_id}/task
Envia uma tarefa para um squad e recebe o resultado.
Exemplo de Uso da API
import requests import json # Configuração base API_URL = "http://localhost:8000/api" USERNAME = "admin" PASSWORD = "senha_segura" # Obter token de autenticação def get_token(): response = requests.post( f"{API_URL}/auth/token", json={"username": USERNAME, "password": PASSWORD} ) data = response.json() return data["access_token"] # Configurar cabeçalhos com token token = get_token() headers = { "Authorization": f"Bearer {token}", "Content-Type": "application/json" } # Listar agentes disponíveis def list_agents(): response = requests.get(f"{API_URL}/agents", headers=headers) return response.json() # Enviar mensagem para um agente def send_message_to_agent(agent_id, message): response = requests.post( f"{API_URL}/agents/{agent_id}/message", headers=headers, json={"message": message} ) return response.json() # Criar um novo squad def create_squad(name, description, agent_ids): response = requests.post( f"{API_URL}/squads", headers=headers, json={ "name": name, "description": description, "agent_ids": agent_ids } ) return response.json() # Enviar tarefa para um squad def send_task_to_squad(squad_id, task): response = requests.post( f"{API_URL}/squads/{squad_id}/task", headers=headers, json={"task": task} ) return response.json() # Exemplo de uso if __name__ == "__main__": # Listar agentes agents = list_agents() print(f"Agentes disponíveis: {json.dumps(agents, indent=2)}") # Enviar mensagem para o agente de marketing marketing_agent_id = "agent_marketing_1" response = send_message_to_agent( marketing_agent_id, "Analise os resultados da nossa campanha de email marketing do último trimestre." ) print(f"Resposta do agente: {json.dumps(response, indent=2)}") # Criar um squad para análise de mercado squad = create_squad( name="Squad de Análise de Mercado", description="Squad para análise completa de mercado e concorrência", agent_ids=["agent_marketing_1", "agent_financial_1", "agent_sales_1"] ) print(f"Squad criado: {json.dumps(squad, indent=2)}") # Enviar tarefa para o squad task_response = send_task_to_squad( squad["id"], "Realize uma análise completa do mercado de software de gestão empresarial, incluindo análise de concorrentes, tendências e oportunidades." ) print(f"Resposta da tarefa: {json.dumps(task_response, indent=2)}")
Criação de Agentes
O Capellaris permite criar agentes personalizados para diferentes áreas de especialidade. Abaixo estão as etapas e exemplos para criar e configurar agentes.
Estrutura de um Agente
Um agente é composto pelos seguintes elementos:
- ID: Identificador único do agente
- Nome: Nome amigável do agente
- Descrição: Descrição das capacidades e propósito do agente
- Especialidade: Área de especialidade do agente (marketing, financeiro, etc.)
- Prompt Base: Instruções base que definem o comportamento do agente
- Ferramentas: Ferramentas e recursos que o agente pode utilizar
- Configurações: Parâmetros específicos do agente
Criação via API
# Exemplo de criação de um agente de marketing via API POST /api/agents Content-Type: application/json Authorization: Bearer {token} { "id": "agent_marketing_custom", "name": "Agente de Marketing Personalizado", "description": "Especialista em análise de campanhas de marketing digital e estratégias de conteúdo", "specialty": "marketing", "base_prompt": "Você é um especialista em marketing digital com foco em análise de campanhas e estratégias de conteúdo. Você deve fornecer análises detalhadas, baseadas em dados, e recomendações práticas que possam ser implementadas. Sempre considere o público-alvo, os objetivos da campanha e as métricas relevantes em suas análises.", "tools": [ "analytics_access", "content_analysis", "competitor_research", "trend_analysis" ], "config": { "model": "gpt-4", "temperature": 0.5, "max_tokens": 2000, "response_format": "structured" } }
Criação via Código
from gerenciador_agentes_ia.core import AgentManager from gerenciador_agentes_ia.agents import Agent # Inicializar o gerenciador de agentes agent_manager = AgentManager() # Criar um agente de desenvolvimento dev_agent = Agent( id="agent_development_custom", name="Agente de Desenvolvimento Personalizado", description="Especialista em revisão de código, arquitetura de software e boas práticas de desenvolvimento", specialty="development", base_prompt=""" Você é um especialista em desenvolvimento de software com ampla experiência em múltiplas linguagens de programação, arquitetura de software e boas práticas de desenvolvimento. Seu objetivo é ajudar a melhorar a qualidade do código, identificar problemas potenciais e sugerir melhorias. Ao revisar código, você deve considerar: 1. Legibilidade e manutenibilidade 2. Eficiência e desempenho 3. Segurança e tratamento de erros 4. Padrões de design e arquitetura 5. Testes e cobertura Forneça sempre exemplos concretos e explicações claras para suas sugestões. """, tools=[ "code_review", "static_analysis", "architecture_review", "test_coverage_analysis" ], config={ "model": "gpt-4", "temperature": 0.3, "max_tokens": 2500, "supported_languages": ["python", "javascript", "java", "csharp", "go"] } ) # Registrar o agente no sistema agent_manager.register_agent(dev_agent) # Verificar se o agente foi registrado corretamente registered_agent = agent_manager.get_agent("agent_development_custom") print(f"Agente registrado: {registered_agent.name}")
Personalização de Prompts
A personalização eficaz do prompt base é crucial para o desempenho do agente. Um bom prompt deve:
- Definir claramente o papel e especialidade do agente
- Estabelecer o tom e estilo de comunicação
- Especificar o formato e estrutura das respostas
- Incluir diretrizes para tratamento de casos específicos
- Definir limitações e comportamentos a evitar
Exemplo de Prompt para Agente Financeiro
""" Você é um especialista financeiro com vasta experiência em análise financeira, planejamento orçamentário, previsões financeiras e análise de investimentos. Seu objetivo é fornecer análises precisas, recomendações baseadas em dados e orientações claras sobre questões financeiras. Ao responder a consultas, você deve: 1. ANÁLISE: - Analisar os dados financeiros fornecidos de forma objetiva e imparcial - Identificar tendências, padrões e anomalias relevantes - Considerar o contexto específico da empresa ou situação 2. RECOMENDAÇÕES: - Fornecer recomendações práticas e acionáveis - Basear suas recomendações em princípios financeiros sólidos e melhores práticas - Apresentar múltiplas opções quando apropriado, com prós e contras 3. COMUNICAÇÃO: - Usar linguagem clara e precisa, evitando jargão desnecessário - Explicar conceitos financeiros complexos de forma acessível - Estruturar suas respostas de forma lógica e organizada 4. LIMITAÇÕES: - Reconhecer quando informações adicionais são necessárias para uma análise completa - Não fazer previsões específicas sobre mercados ou investimentos sem ressalvas apropriadas - Evitar conselhos que possam ser interpretados como consultoria financeira regulamentada Ao analisar demonstrações financeiras, você deve considerar: - Balanço patrimonial: liquidez, alavancagem, estrutura de capital - Demonstração de resultados: margens, crescimento, eficiência operacional - Fluxo de caixa: geração de caixa operacional, investimentos, financiamentos - Indicadores-chave: ROI, ROE, EBITDA, índices de liquidez, ciclo operacional Ao fazer projeções financeiras, você deve: - Basear-se em premissas claras e justificáveis - Considerar múltiplos cenários (otimista, realista, pessimista) - Incluir análises de sensibilidade para variáveis críticas - Apresentar os resultados com intervalos de confiança apropriados Formato de resposta preferido: 1. Resumo executivo (2-3 frases) 2. Análise detalhada (estruturada por tópicos relevantes) 3. Recomendações específicas 4. Próximos passos sugeridos 5. Considerações adicionais ou limitações da análise """
Gerenciamento de Squads
Os squads são equipes temporárias de agentes que colaboram para resolver tarefas complexas que exigem múltiplas especialidades. Esta seção explica como criar, configurar e gerenciar squads.
Estrutura de um Squad
Um squad é composto pelos seguintes elementos:
- ID: Identificador único do squad
- Nome: Nome amigável do squad
- Descrição: Descrição do propósito e capacidades do squad
- Agentes: Lista de agentes que compõem o squad
- Líder: Agente designado como líder do squad
- Fluxo de Trabalho: Definição de como os agentes colaboram
- Configurações: Parâmetros específicos do squad
Criação via API
# Exemplo de criação de um squad de lançamento de produto via API POST /api/squads Content-Type: application/json Authorization: Bearer {token} { "id": "squad_product_launch", "name": "Squad de Lançamento de Produto", "description": "Equipe especializada em planejar e executar lançamentos de produtos", "agents": [ { "id": "agent_marketing_1", "role": "marketing_specialist" }, { "id": "agent_financial_1", "role": "financial_analyst" }, { "id": "agent_sales_1", "role": "sales_strategist" }, { "id": "agent_operations_1", "role": "operations_coordinator" } ], "leader_id": "agent_marketing_1", "workflow": { "type": "sequential", "steps": [ { "agent_id": "agent_marketing_1", "task": "market_analysis", "description": "Analisar o mercado e definir estratégia de posicionamento" }, { "agent_id": "agent_financial_1", "task": "financial_planning", "description": "Desenvolver orçamento e previsões financeiras" }, { "agent_id": "agent_sales_1", "task": "sales_strategy", "description": "Definir estratégia de vendas e canais de distribuição" }, { "agent_id": "agent_operations_1", "task": "logistics_planning", "description": "Planejar logística e operações de lançamento" }, { "agent_id": "agent_marketing_1", "task": "consolidation", "description": "Consolidar os resultados e finalizar o plano de lançamento" } ] }, "config": { "max_execution_time": 3600, "intermediate_results": true, "approval_required": true } }
Criação via Código
from gerenciador_agentes_ia.core import SquadManager from gerenciador_agentes_ia.agents import AgentManager from gerenciador_agentes_ia.squads import Squad, WorkflowStep, WorkflowType # Inicializar os gerenciadores agent_manager = AgentManager() squad_manager = SquadManager(agent_manager) # Definir os passos do fluxo de trabalho workflow_steps = [ WorkflowStep( agent_id="agent_development_1", task="architecture_design", description="Projetar a arquitetura do sistema" ), WorkflowStep( agent_id="agent_financial_1", task="cost_estimation", description="Estimar custos de desenvolvimento e infraestrutura" ), WorkflowStep( agent_id="agent_operations_1", task="resource_planning", description="Planejar recursos e cronograma" ), WorkflowStep( agent_id="agent_development_1", task="consolidation", description="Consolidar os resultados e finalizar o plano de projeto" ) ] # Criar um squad de projeto de software project_squad = Squad( id="squad_software_project", name="Squad de Projeto de Software", description="Equipe especializada em planejamento e execução de projetos de software", agents=[ {"id": "agent_development_1", "role": "architect"}, {"id": "agent_financial_1", "role": "cost_analyst"}, {"id": "agent_operations_1", "role": "project_manager"} ], leader_id="agent_development_1", workflow={ "type": WorkflowType.SEQUENTIAL, "steps": workflow_steps }, config={ "max_execution_time": 7200, "intermediate_results": True, "approval_required": True } ) # Registrar o squad no sistema squad_manager.register_squad(project_squad) # Verificar se o squad foi registrado corretamente registered_squad = squad_manager.get_squad("squad_software_project") print(f"Squad registrado: {registered_squad.name}")
Tipos de Fluxo de Trabalho
Sequencial
Os agentes trabalham em sequência, cada um executando sua tarefa após a conclusão da anterior.
Ideal para: Processos lineares onde cada etapa depende da anterior.
Paralelo
Os agentes trabalham simultaneamente em tarefas independentes.
Ideal para: Tarefas que podem ser executadas independentemente.
Colaborativo
Os agentes trabalham juntos, compartilhando informações e contribuindo para um resultado comum.
Ideal para: Problemas complexos que requerem múltiplas perspectivas.
Hierárquico
Um agente líder coordena o trabalho de agentes subordinados, delegando tarefas e consolidando resultados.
Ideal para: Tarefas que requerem coordenação central e especialização.
Exemplo de Uso de Squad
from gerenciador_agentes_ia.core import SquadManager # Inicializar o gerenciador de squads squad_manager = SquadManager() # Obter um squad existente market_analysis_squad = squad_manager.get_squad("squad_market_analysis") # Enviar uma tarefa para o squad task_result = squad_manager.execute_task( squad_id="squad_market_analysis", task="Realize uma análise completa do mercado de software de gestão empresarial, incluindo análise de concorrentes, tendências e oportunidades.", context={ "target_market": "Pequenas e médias empresas", "geographic_focus": "Brasil", "industry_sectors": ["Varejo", "Serviços", "Manufatura"], "time_horizon": "12 meses" }, requester="user@company.com" ) # Verificar o status da tarefa task_id = task_result["task_id"] task_status = squad_manager.get_task_status(task_id) print(f"Status da tarefa: {task_status['status']}") print(f"Progresso: {task_status['progress']}%") # Se a tarefa estiver concluída, obter o resultado if task_status["status"] == "completed": task_result = squad_manager.get_task_result(task_id) print(f"Resultado da tarefa: {task_result['summary']}") # Acessar resultados detalhados por agente for agent_result in task_result["agent_results"]: print(f"Resultado do agente {agent_result['agent_id']}:") print(agent_result["content"])
Integração com Chat
A integração com plataformas de chat permite que os usuários interajam com os agentes através de interfaces familiares como Slack e Microsoft Teams. Esta seção explica como configurar e personalizar essas integrações.
Configuração do Slack
Pré-requisitos:
- Conta de administrador no workspace do Slack
- Acesso à plataforma de desenvolvedores do Slack
Passos:
- Criar um novo aplicativo na plataforma de desenvolvedores do Slack
- Configurar permissões e escopos (chat:write, channels:read, etc.)
- Obter o token de API e signing secret
- Configurar endpoints de eventos e interatividade
- Instalar o aplicativo no workspace
# Configuração do Slack no arquivo config.yaml integracao: slack: token: "xoxb-seu-token-aqui" signing_secret: "seu-signing-secret-aqui" canais_permitidos: ["general", "marketing", "desenvolvimento", "financeiro"] notificacoes: conclusao_tarefa: true solicitacao_aprovacao: true erros: true formatacao: usar_blocos: true usar_attachments: true max_comprimento_texto: 3000 comandos: - nome: "/agente" descricao: "Interagir com um agente específico" - nome: "/squad"ß descricao: "Interagir com um squad específico" - nome: "/ajuda" descricao: "Exibir ajuda sobre os agentes disponíveis"
Configuração do Microsoft Teams
Pré-requisitos:
- Conta de administrador no Microsoft 365
- Acesso ao Azure Active Directory
- Acesso ao Bot Framework
Passos:
- Registrar um aplicativo no Azure Active Directory
- Criar um bot no Bot Framework
- Configurar permissões e escopos
- Obter o app ID e app password
- Configurar endpoints de mensagens
- Criar o pacote de aplicativo do Teams
- Instalar o aplicativo no Teams
# Configuração do Teams no arquivo config.yaml integracao: teams: app_id: "seu-app-id-aqui" app_password: "seu-app-password-aqui" tenant_id: "seu-tenant-id-aqui" teams_permitidos: ["Marketing", "Desenvolvimento", "Financeiro"] notificacoes: conclusao_tarefa: true solicitacao_aprovacao: true erros: true formatacao: usar_cards_adaptativos: true usar_hero_cards: true max_comprimento_texto: 2000 comandos: - nome: "agente" descricao: "Interagir com um agente específico" - nome: "squad" descricao: "Interagir com um squad específico" - nome: "ajuda" descricao: "Exibir ajuda sobre os agentes disponíveis"
Personalização de Mensagens
from gerenciador_agentes_ia.communication import MessageFormatter from gerenciador_agentes_ia.chat_integration import SlackConnector # Criar um formatador de mensagens personalizado para o Slack class CustomSlackFormatter(MessageFormatter): def format_agent_response(self, agent_id, response, context=None): """ Formata a resposta de um agente para o Slack. Args: agent_id (str): ID do agente response (str): Resposta do agente context (dict, optional): Contexto adicional Returns: dict: Mensagem formatada para o Slack """ # Obter informações do agente agent_info = self.agent_manager.get_agent(agent_id) # Criar blocos para a mensagem blocks = [ { "type": "header", "text": { "type": "plain_text", "text": f"Resposta de {agent_info.name}", "emoji": True } }, { "type": "section", "text": { "type": "mrkdwn", "text": response } }, { "type": "context", "elements": [ { "type": "mrkdwn", "text": f"*Especialidade:* {agent_info.specialty} | *Confiança:* Alta" } ] }, { "type": "actions", "elements": [ { "type": "button", "text": { "type": "plain_text", "text": "👍 Útil", "emoji": True }, "value": f"feedback_positive_{agent_id}" }, { "type": "button", "text": { "type": "plain_text", "text": "👎 Não útil", "emoji": True }, "value": f"feedback_negative_{agent_id}" }, { "type": "button", "text": { "type": "plain_text", "text": "🔄 Reformular", "emoji": True }, "value": f"reformulate_{agent_id}" } ] } ] return { "blocks": blocks, "text": f"Resposta de {agent_info.name}: {response[:100]}..." } def format_approval_request(self, request_id, task_description, agent_id): """ Formata uma solicitação de aprovação para o Slack. Args: request_id (str): ID da solicitação task_description (str): Descrição da tarefa agent_id (str): ID do agente Returns: dict: Mensagem formatada para o Slack """ # Obter informações do agente agent_info = self.agent_manager.get_agent(agent_id) # Criar blocos para a mensagem blocks = [ { "type": "header", "text": { "type": "plain_text", "text": "Solicitação de Aprovação", "emoji": True } }, { "type": "section", "text": { "type": "mrkdwn", "text": f"O agente *{agent_info.name}* gostaria de executar a seguinte tarefa:" } }, { "type": "section", "text": { "type": "mrkdwn", "text": f"```{task_description}```" } }, { "type": "actions", "elements": [ { "type": "button", "text": { "type": "plain_text", "text": "✅ Aprovar", "emoji": True }, "style": "primary", "value": f"approve_{request_id}" }, { "type": "button", "text": { "type": "plain_text", "text": "❌ Rejeitar", "emoji": True }, "style": "danger", "value": f"reject_{request_id}" }, { "type": "button", "text": { "type": "plain_text", "text": "❓ Mais informações", "emoji": True }, "value": f"more_info_{request_id}" } ] } ] return { "blocks": blocks, "text": f"Solicitação de aprovação para tarefa: {task_description[:100]}..." } # Registrar o formatador personalizado slack_connector = SlackConnector(config["integracao"]["slack"]) slack_connector.set_message_formatter(CustomSlackFormatter())