Skip to content

Latest commit

 

History

History
375 lines (335 loc) · 9.72 KB

dev-guide.md

File metadata and controls

375 lines (335 loc) · 9.72 KB

Guia do Desenvolvedor - Criando Componentes archflow

Introdução

Este guia explica como criar componentes para o archflow, permitindo estender as funcionalidades do framework e criar integrações com o LangChain4j.

1. Entendendo os Tipos de Componentes

1.1 Assistants (AIAssistant)

  • Propósito: Fornecer interfaces conversacionais especializadas
  • Características:
    • Focados em interação e resposta
    • Mantêm contexto da conversa
    • Podem usar diferentes modelos de linguagem
  • Exemplo de Uso: Assistente de atendimento, assistente técnico

1.2 Agents (AIAgent)

  • Propósito: Executar tarefas autônomas e tomar decisões
  • Características:
    • Podem usar múltiplas ferramentas
    • Planejam ações
    • Tomam decisões baseadas em objetivos
  • Exemplo de Uso: Agente de pesquisa, agente de análise de dados

1.3 Tools (Tool)

  • Propósito: Executar operações específicas
  • Características:
    • Focadas em uma função específica
    • Recebem parâmetros bem definidos
    • Retornam resultados estruturados
  • Exemplo de Uso: Calculadora, processador de documentos

2. Estrutura de Metadados

2.1 ComponentDescriptor

@ComponentDescriptor(
    id = "my-component",          // ID único do componente
    name = "My Component",        // Nome amigável
    description = "...",          // Descrição detalhada
    type = ComponentType.TOOL,    // Tipo do componente
    version = "1.0.0",           // Versão
    properties = { ... },         // Propriedades configuráveis
    operations = { ... }          // Operações disponíveis
)

2.2 Operation

@Operation(
    id = "execute",              // ID da operação
    name = "Execute Task",       // Nome amigável
    description = "...",         // Descrição
    inputs = { ... },           // Parâmetros de entrada
    outputs = { ... }           // Parâmetros de saída
)

2.3 Property

@Property(
    id = "param1",              // ID da propriedade
    name = "Parameter 1",       // Nome amigável
    description = "...",        // Descrição
    type = "string",           // Tipo (string, number, boolean, etc)
    required = true,           // Se é obrigatório
    defaultValue = "",         // Valor padrão
    group = "basic"            // Grupo na UI
)

3. Exemplos Práticos

3.1 Assistant de Suporte Técnico

@ComponentDescriptor(
    id = "tech-support-assistant",
    name = "Tech Support Assistant",
    description = "Assists with technical support queries",
    type = ComponentType.ASSISTANT,
    version = "1.0.0",
    properties = {
        @Property(
            id = "knowledgeBase",
            name = "Knowledge Base",
            description = "Technical documentation to use",
            type = "string",
            required = true
        ),
        @Property(
            id = "maxTokens",
            name = "Max Response Length",
            type = "number",
            defaultValue = "1000"
        )
    },
    operations = {
        @Operation(
            id = "assist",
            name = "Assist User",
            inputs = {
                @Property(
                    id = "query",
                    name = "User Query",
                    type = "string",
                    required = true
                )
            },
            outputs = {
                @Property(
                    id = "response",
                    name = "Assistant Response",
                    type = "string"
                ),
                @Property(
                    id = "confidence",
                    name = "Confidence Score",
                    type = "number"
                )
            }
        )
    }
)
public class TechSupportAssistant implements AIAssistant {
    private ChatLanguageModel model;
    private Document knowledgeBase;
    
    @Override
    public void initialize(Map<String, Object> config) {
        // Inicialização
    }
    
    @Override
    public Analysis analyzeRequest(String input, ExecutionContext context) {
        // Análise da requisição
    }
    
    @Override
    public Response generateResponse(Analysis analysis, ExecutionContext context) {
        // Geração de resposta
    }
}

3.2 Agente de Pesquisa

@ComponentDescriptor(
    id = "research-agent",
    name = "Research Agent",
    description = "Conducts research on given topics",
    type = ComponentType.AGENT,
    version = "1.0.0",
    properties = {
        @Property(
            id = "searchDepth",
            name = "Search Depth",
            type = "number",
            defaultValue = "3"
        ),
        @Property(
            id = "sources",
            name = "Research Sources",
            type = "array",
            description = "List of sources to use"
        )
    },
    operations = {
        @Operation(
            id = "research",
            name = "Research Topic",
            inputs = {
                @Property(
                    id = "topic",
                    name = "Research Topic",
                    type = "string",
                    required = true
                ),
                @Property(
                    id = "format",
                    name = "Output Format",
                    type = "string",
                    defaultValue = "summary"
                )
            },
            outputs = {
                @Property(
                    id = "findings",
                    name = "Research Findings",
                    type = "object"
                )
            }
        )
    }
)
public class ResearchAgent implements AIAgent {
    @Override
    public Result executeTask(Task task, ExecutionContext context) {
        // Execução da pesquisa
    }
    
    @Override
    public List<Action> planActions(Goal goal, ExecutionContext context) {
        // Planejamento de ações
    }
}

3.3 Ferramenta de Análise de Documentos

@ComponentDescriptor(
    id = "document-analyzer",
    name = "Document Analyzer",
    description = "Analyzes documents for key information",
    type = ComponentType.TOOL,
    version = "1.0.0",
    properties = {
        @Property(
            id = "language",
            name = "Document Language",
            type = "string",
            defaultValue = "en"
        )
    },
    operations = {
        @Operation(
            id = "analyze",
            name = "Analyze Document",
            inputs = {
                @Property(
                    id = "document",
                    name = "Document Text",
                    type = "string",
                    required = true
                ),
                @Property(
                    id = "extractors",
                    name = "Information Extractors",
                    type = "array"
                )
            },
            outputs = {
                @Property(
                    id = "analysis",
                    name = "Analysis Results",
                    type = "object"
                )
            }
        )
    }
)
public class DocumentAnalyzerTool implements Tool {
    @Override
    public Result execute(Map<String, Object> params, ExecutionContext context) {
        // Análise do documento
    }
}

4. Boas Práticas

4.1 Metadados

  • Use IDs únicos e descritivos
  • Forneça descrições claras
  • Agrupe propriedades logicamente
  • Defina tipos adequados
  • Documente valores padrão

4.2 Operações

  • Mantenha operações focadas
  • Valide inputs adequadamente
  • Forneça outputs consistentes
  • Documente erros possíveis
  • Use nomes intuitivos

4.3 Implementação

  • Siga o princípio de responsabilidade única
  • Gerencie recursos adequadamente
  • Implemente tratamento de erros
  • Forneça logs adequados
  • Considere performance

4.4 Integração

  • Use adaptadores LangChain4j
  • Mantenha estado corretamente
  • Respeite limites de contexto
  • Considere custos de API
  • Implemente retry policies

5. Ideias para Novos Componentes

5.1 Assistants

  • Email Writing Assistant
  • Code Review Assistant
  • Meeting Summary Assistant
  • Language Learning Assistant
  • Customer Service Assistant

5.2 Agents

  • Data Analysis Agent
  • Project Management Agent
  • Content Creation Agent
  • Market Research Agent
  • Scheduling Agent

5.3 Tools

  • PDF Processor
  • Image Analyzer
  • Translation Tool
  • Sentiment Analyzer
  • Data Validation Tool

6. Validação e Testes

6.1 Checklist de Validação

  1. Metadados completos e corretos
  2. Operações bem definidas
  3. Propriedades adequadas
  4. Tratamento de erros
  5. Logs apropriados

6.2 Testes Recomendados

  1. Testes unitários
  2. Testes de integração
  3. Testes de carga
  4. Testes de usabilidade
  5. Validação de metadados

7. Dicas de Desenvolvimento

7.1 Começando

  1. Identifique o tipo de componente
  2. Defina metadados básicos
  3. Implemente operações core
  4. Adicione propriedades
  5. Teste e valide

7.2 Evite

  • Operações muito complexas
  • Propriedades desnecessárias
  • Dependências excessivas
  • Estado global
  • Hardcoding de valores

7.3 Recomendado

  • Documentação clara
  • Logs informativos
  • Tratamento de erros robusto
  • Testes abrangentes
  • Feedback visual adequado

8. Contribuindo

8.1 Processo

  1. Fork do repositório
  2. Crie branch para feature
  3. Implemente componente
  4. Adicione testes
  5. Submeta PR

8.2 Documentação

  • README detalhado
  • Exemplos de uso
  • Configurações possíveis
  • Casos de uso
  • Limitações conhecidas

Conclusão

O archflow oferece uma estrutura robusta para criação de componentes de IA. Seguindo este guia, você pode criar componentes reutilizáveis que se integram perfeitamente ao ecossistema.

Para mais informações ou dúvidas:

  • Consulte a documentação oficial
  • Participe do fórum da comunidade
  • Verifique exemplos existentes
  • Entre em contato com a equipe