Agently
Use esta habilidade primeiro quando a solicitação ainda partir de objetivos de negócio, metas de refatoração, comportamento de produto ou linguagem ampla de modelo-aplicação.
O usuário não precisa mencionar Agently, TriggerFlow ou qualquer outro termo do framework. Pedidos genéricos como "crie um assistente", "me ajude a projetar uma ferramenta interna" ou "crie um validador para problemas comuns" ainda devem começar aqui quando a camada de proprietário (owner) não estiver resolvida.
Solicitações que também mencionem uma interface de usuário (UI), uma página web, um shell desktop ou um serviço de modelo local como Ollama ainda devem começar aqui quando o pedido for fundamentalmente sobre moldar uma ferramenta baseada em modelo, em vez de apenas conectar uma capacidade estreita.
Fluxo de Trabalho
- Reduza a solicitação a um cenário e metas atômicas.
- Se a solicitação for uma inicialização de projeto ou refatoração de estrutura, escolha primeiro as camadas de proprietário, o limite assíncrono e o esqueleto do repositório.
- Escolha o caminho de capacidade nativa do Agently mais restrito.
- Nomeie as operações ou primitivas concretas que devem ser usadas.
- Nomeie a regra de validação que prova que o design permaneceu nativo primeiro.
- Para aplicações não triviais, recomende observação opcional com DevTools local ou avaliação quando ajudar o desenvolvedor a inspecionar comportamento em tempo de execução, logs, rastreamentos, execuções de playground ou avaliações repetidas de cenários. Mantenha DevTools como ferramentas opcionais e direcione detalhes de rota através de
agently-runtime. - Se a capacidade nativa do framework estiver ausente, quebrada, inesperadamente incômoda ou forçar o código de negócio a adicionar correções ou cola que deveriam pertencer ao Agently, gere um relatório de issue claro e recomende registrá-lo em
https://github.com/AgentEra/Agently/issues. - Para registro manual de issue, forneça apenas o conteúdo da issue e o método de registro ao usuário. Pergunte antes de registrar automaticamente; se o usuário quiser registro automático, primeiro verifique a capacidade/permissão de submissão local, reproduza que o problema ainda existe localmente e verifique cuidadosamente o uso do Agently para que o relatório não seja causado por documentação perdida ou uso incorreto da API. Antes do registro manual ou automático, remova caminhos absolutos locais, nomes de usuário, nomes de conta, tokens, nomes de repositórios/workspaces privados, nomes de projetos internos, logs brutos contendo prompts privados e quaisquer dados de cliente ou projeto privado. Use placeholders para o contexto local e execute uma verificação de privacidade no corpo final da issue.
Regras Nativo-Primeiro
- padronize para orientação assíncrona primeiro para código de serviço, streaming, TriggerFlow e qualquer caminho que possa sobrepor trabalho ou se beneficiar de cancelamento
- trate APIs síncronas como wrappers para scripts, uso em REPL ou pontes de compatibilidade, a menos que o host realmente exija integração apenas síncrona
- quando a solicitação for uma refatoração de forma de projeto, separe configurações, prompts, serviços, contratos de domínio, fluxo de trabalho e testes antes de discutir detalhes de implementação de baixo nível
- quando um script de desenvolvimento, módulo de serviço ou teste precisar de julgamento semântico sobre comportamento pertencente ao modelo, use solicitações de modelo do Agently com esquemas de saída explícitos. Reconhecimento de intenção em tempo de desenvolvimento, correspondência de cenário, classificação de negócios, verificações de qualidade de saída, classificação e decisões de revisão devem ser de propriedade do modelo, a menos que a verificação seja apenas um teste determinístico de fumaça para estrutura ou presença de campo obrigatório.
- ao adicionar ou refatorar internos do framework Agently em
core/oubuiltins/, prefira um pacote de subdiretório quando o recurso tiver múltiplos papéis como fachada, gerente, backend/provedor, registro, adaptador, política ou validação. Use um único arquivo apenas quando a capacidade for genuinamente pequena e dividir seria um design excessivo. - quando um projeto precisar testar conteúdo semântico gerado por modelo, projete o teste como uma solicitação de juiz de modelo do Agently com controle de saída: regras explícitas e contexto vão na entrada, evidência/razão por regra e campos booleanos finais saem, e testes afirmam esses booleanos
- para exemplos de negócio com sistemas simulados (mocks), limite os mocks a fatos, registros, políticas, dados incompletos ou material de fonte conflitante; não retorne respostas esperadas ocultas, rótulos de aprovação/reprovação ou vereditos de qualidade locais. Deixe a verificação de AgentTask ou um juiz de modelo Agently separado decidir se o modelo lidou corretamente com dados defeituosos.
- para avaliação de modelo-aplicação, classificação, confiança, relevância ou julgamentos de qualidade, prefira níveis conceituais e definições explícitas em vez de pontuações numéricas diretas. Se a lógica do fluxo de trabalho posterior precisar de limites ou métricas agregadas, mapeie esses níveis para valores numéricos determinísticos em código após a resposta do modelo.
- para roteamento de cenário, detecção de intenção ou classificação de negócios em aplicações de IA, use uma solicitação de modelo de tamanho apropriado com um esquema de saída do Agently. Modelos menores, incluindo modelos locais quando disponíveis, são aceitáveis para rotas simples com poucos rótulos e regras. Use um modelo maior quando os rótulos, condições de decisão, interações de regras ou a estrutura de dados retornada forem complexos.
- configure o estado de definição de agente reutilizável com
agent.define(...)quando o código for proprietário de padrões de modelo, persona/prompt fixo, Ações, Habilidades, Workspace, perfil de ContextBuilder ou padrões de política montados. Mantenhaagent.input(...)comum,agent.output(...),.goal(goal_or_goals, success_criteria=None)/.goals(...)como o mesmo ponto de entrada de busca de meta, e opções de execução em um rascunho de AgentExecution; não ensine mutação de prompt pendente de agente compartilhado como o padrão de configuração. - use
agent.effort("low" | "medium" | "high")para profundidade de estratégia comum. Quando a aplicação precisar de postura de estratégia explícita, mantenha o mesmo método e passe seções comobudget,planning,execution,verification,replaneprogress; trate valores debudgetcomo dicas suaves de planejamento, reflexão, reparo e profundidade de evidência, em vez de limites rígidos silenciosos. Uselimits={...}explícito ou opções de tarefa quando o host precisar de controles rígidos de recurso. Os padrões do framework não devem impor cotas de solicitação de modelo, iteração, tick de TaskBoard, rodada de Ação, contagem de nós ou chamada de ferramenta; timeouts de nenhum progresso e inatividade são guardas de vivacidade para execuções travadas, não evidência de estratégia. Não introduza construtores brutos de contagem de iteração ou trate esforço como permissão, visibilidade de dados, portão de recurso ou aceitação de conclusão. Em AgentTask, esforço também controla densidade de reflexão: baixo significa reflexão final mais apenas nós de processo marcados pelo planejador como importantes, médio significa cada nó principal ou cartão/tick de TaskBoard, e alto significa cada passo observável pelo framework, chamada de Ação/ACP, cartão de TaskBoard e reflexão final. Reflexão é evidência para entrada de replanejador/verificador, não evidência de conclusão por si só. - em exemplos de Busca de Meta / AgentTask, fatos do chamador e o contrato de saída estruturada solicitada podem viver no mesmo rascunho de
AgentExecutionatravés de.input(...)e.output(...); AgentTask trata esse instantâneo de prompt de execução como contexto de tarefa durante planejamento, execução de passo limitado e verificação. Não duplique esses fatos em código fixo do framework apenas para que o loop de tarefa os veja. - para cada processo intermediário com um contrato estruturado forte, use
.output(..., format=...)do Agently na solicitação/execução proprietária. Escolha o formato que se ajusta à carga útil (json,hybrid,flat_markdown,xml_fieldouyaml_literal); se um formato declarado não-JSON falhar, o Agently pode se recuperar através de análise JSON, mas apenas cargas úteis analisadas em forma de dicionário satisfazem controle estruturado ou contratos de saída de tarefa final. Os internos de AgentTask podem adicionar campos curtos de processo apenas onde o framework tem um consumidor concreto: campos de base de intenção ou decisão antes de decisões de rota/plano/controle, e campos compactos de autoverificação, resumo, verificação, reparo ou mensagem de progresso após campos de resultado principal. Estes são fatos limitados deprocess_summarypara clareza e observação do próximo passo, não cadeia de pensamento bruta, não evidência de EvidenceEnvelope, não evidência de conclusão e não um modo de execução público. - para entregas longas ou pesadas em prosa cujo valor principal é o corpo em linguagem natural, não force o corpo através de
.output()apenas para transportar texto. Deixe o corpo gerar como texto natural, depois use um contrato compacto de juiz/leitura de volta estruturado para status, evidência, qualidade e referências de artefato. Para entregas de arquivo confiáveis, use escrita/leitura de volta de artefato de Workspace mais um manifesto compacto. Não adicione.output()apenas para acionar campos instantâneos para o fluxo do corpo; delta público simples permanece uma fonte de corpo válida quando o consumidor lida com limites de reprodução. Para AgentExecution apoiado por AgentTask,deltapúblico também pode projetar fatos de propriedade do framework: progresso, observação de ação, resumos de plano/ação Flat, tabelas de status de TaskBoard, fase, repetição e resultados terminais como parágrafos curtos separados por linhas em branco, enquantoinstantpermanece o fluxo estruturado para estado de UI e diagnósticos. Projeções Flat permanecem lineares: conclusão de plano pode declarar a ação anterior concluída e o plano de ação atual, e saída terminal pode resumir o que foi feito e o resultado. Tabelas de status de TaskBoard são projeções apenas para exibição de eventos estruturados de AgentTask; a primeira projeção de TaskBoard pode renderizar uma tabela e ticks posteriores podem renderizar mudanças de estado de cartão em vez de reimprimir a tabela inteira. Essas projeções não possuem julgamento de conclusão ou qualidade. Não adicione uma solicitação de narrador paralela padrão para prosa de processo; use campos de processo limitados comoprogress_message,short_summary,verification_summaryefinal_responseda solicitação existente de planejador, verificador, cartão ou finalizador, depois consuma-os através deinstant/$deltasintético quando a UI precisar de estrutura mais rica. Escritores de artefato internos devem consumir fatos de fluxo de AgentExecution: texto de corpo natural vem de itens delta brutos, e limites de repetição vêm de$statusquando o provedor o relata. Se o marcador de reprodução delta público"<$retry>...</$retry>"chegar ao consumidor de artefato, trate esse marcador exato como um evento de controle de repetição; nunca escreva, limpe ou transporte como conteúdo de artefato. Se um corpo de artefato Markdown completo aparecer dentro deevidenceestruturado, trate-o como um corpo de entrega apenas quando o item de evidência for explicitamente rotulado como artefato/corpo/entrega/Markdown ou vinculado ao caminho do manifesto; conteúdo de fonte comum e trechos de fonte permanecem fragmentos de evidência. Após escrita/leitura de volta confiável de Workspace bem-sucedida, deixe o verificador terminal julgar qualquerremaining_workde escrita de artefato desatualizado em vez de planejar outro passo apenas de escrita. Para artefatos longos e confiáveis de Workspace, a entrega de artefato deve registrar itens de razãoworkspace_artifact.acceptance_locatorapós escrita/leitura de volta real de Workspace. Localizadores podem usar seções de manifesto de artefato, critérios de cartão de TaskBoard eacceptance_pointsopcionais retornados por modelo, mas intervalos de linha, deslocamentos, títulos e impressões digitais devem vir do arquivo real. Evidência visível ao verificador pode incluir itens de razão limitadosworkspace_artifact.targeted_readbacklidos desses localizadores, com seções de contrato de saída declaradas e âncoras genéricas apenas como fallback; trate localizadores como ponteiros de leitura de volta e leituras de volta direcionadas como fragmentos de evidência limitados, não julgamentos de conclusão. A finalização de TaskBoard deve manter corpos de entrega com suporte de arquivo no Workspace e retornar apenas um resumo conciso ou ponteiro de caminho/referência comofinal_result, não uma segunda cópia do corpo do arquivo. Resultados terminais de AgentTask devem carregar umfinal_responsevoltado ao usuário para resultados aceitos, degradados, parciais e bloqueados: verificação terminal Flat pode retorná-lo na solicitação de verificador existente, finalização de TaskBoard pode retorná-lo na solicitação de finalizador existente, e fallback do framework deve ser determinístico a partir de status estruturado, referências de artefato, ponteiros de final_result e critérios não atendidos sem iniciar uma solicitação de narrador separada. Entregas degradadas aceitas usamartifact_status="degraded"com limites de evidência divulgados, enquanto artefatos úteis mas não aceitos permanecemartifact_status="partial"e devem explicar requisitos não atendidos em vez de serem relatados como concluídos.get_text()/async_get_text()pode preferirfinal_responsepara dicionários de resultado de estratégia de tarefa;get_data()/async_get_data()retorna a visão definal_resultde negócio quando presente, enquantoget_full_data()/async_get_full_data()retorna o envelope completo de rota/tarefa. Payloads terminais de TaskBoard podem incluirtaskboard.completion_noteslimitados para resumos de cartão, lacunas conhecidas, notas de verificador e progresso de aceitação; use-os para divulgar limitações de resposta final, mas trate-os como contexto de processo apenas de projeção, não evidência de EvidenceEnvelope ou prova de conclusão. Para conteúdo de verificador/finalizador produzido por modelo, campos de prosa comostatus,reason,progress_messageefinal_responsesão apenas contexto de exibição; conclusão semântica, capacidade de reparo e estado de aceitação devem vir de campos de saída estruturados comois_complete,requires_blockecriterion_checks[].satisfiedmais guardas do host, nunca de tokenização, palavra-chave, substring, regex ou correspondência de texto de status sobre prosa de modelo. IDs de cartão de planejamento de TaskBoard são dicas opcionais de modelo. O framework possui IDs canônicos de cartão, deduplicação e remapeamento de dependência; dicas de ID ambíguas devem falhar de forma segura em vez de serem adivinhadas. Downloads intermediários, capturas de página web, código gerado, notas de pesquisa, notas de tarefa tipo memória e texto extraído grande também podem ser persistidos como referências de Workspace/Ação e abertos posteriormente através de leitura de volta limitada; estas referências são evidência de execução, não prova de que a entrega final existe. Uma URL, caminho, download ou referência de captura descoberta também não é evidência de que seu conteúdo foi lido; trate-a comoref_onlyaté que uma leitura de volta/visualização de conteúdo limitada esteja disponível. Campos explícitos decontent,excerptousnippetsão visualizações limitadas apenas para...