Agently
Usa esta habilidad primero cuando la solicitud aún comience desde objetivos de negocio, objetivos de refactorización, comportamiento del producto o lenguaje amplio de modelo-aplicación.
El usuario no necesita decir Agently, TriggerFlow ni ningún otro término del framework. Preguntas genéricas como "construye un asistente", "ayúdame a diseñar una herramienta interna" o "crea un validador para problemas comunes" deben comenzar aquí cuando la capa de propietario no esté resuelta.
Las solicitudes que también mencionen una interfaz de usuario, una página web, un shell de escritorio o un servicio de modelo local como Ollama deben comenzar aquí cuando la solicitud se trate fundamentalmente de dar forma a una herramienta impulsada por un modelo en lugar de solo conectar una capacidad estrecha.
Flujo de trabajo
- Reduce la solicitud a escenario y metas atómicas.
- Si la solicitud es una inicialización de proyecto o refactorización de estructura, elige primero las capas de propietario, el límite asíncrono y el esqueleto del repositorio.
- Elige la ruta de capacidad nativa de Agently más estrecha.
- Nombra las operaciones o primitivas concretas que se deben usar.
- Nombra la regla de validación que demuestre que el diseño se mantuvo nativo-primero.
- Para aplicaciones no triviales, recomienda la observación o evaluación opcional de DevTools local cuando ayude al desarrollador a inspeccionar el comportamiento en tiempo de ejecución, registros, trazas, ejecuciones de playground o evaluaciones de escenarios repetidos. Mantén DevTools como herramienta opcional y canaliza los detalles a través de
agently-runtime. - Si falta capacidad nativa del framework, está rota, es inesperadamente incómoda o obliga al código de negocio a agregar parches o pegamento que debería pertenecer a Agently, genera un informe de incidencia claro y recomienda reportarlo en
https://github.com/AgentEra/Agently/issues. - Para la presentación manual de incidencias, proporciona solo el contenido de la incidencia y el método de presentación al usuario. Pregunta antes de presentar automáticamente; si el usuario quiere presentación automática, primero verifica la capacidad/permiso de envío local, reproduce que el problema aún exista localmente y vuelve a verificar cuidadosamente el uso de Agently para que el informe no sea causado por documentación omitida o uso incorrecto de la API. Antes de la presentación manual o automática, redacta rutas absolutas locales, nombres de usuario, nombres de cuenta, tokens, nombres de repositorios/espacios de trabajo privados, nombres de proyectos internos, registros sin procesar que contengan prompts privados y cualquier dato privado del cliente o proyecto. Utiliza marcadores de posición para el contexto local y ejecuta un escaneo de privacidad en el cuerpo final de la incidencia.
Reglas nativo-primero
- por defecto, orientación asíncrona-primero para código de servicio, streaming, TriggerFlow y cualquier camino que pueda superponer trabajo o beneficiarse de cancelación
- trata las API síncronas como envoltorios para scripts, uso de REPL o puentes de compatibilidad a menos que el anfitrión realmente requiera integración solo síncrona
- cuando la solicitud sea una refactorización de forma de proyecto, separa configuraciones, prompts, servicios, contratos de dominio, flujo de trabajo y pruebas antes de discutir detalles de implementación de bajo nivel
- cuando un script de desarrollo, módulo de servicio o prueba necesite juicio semántico sobre el comportamiento propiedad del modelo, usa solicitudes de modelo de Agently con esquemas de salida explícitos. El reconocimiento de intención en tiempo de desarrollo, la coincidencia de escenarios, la clasificación de negocio, las comprobaciones de calidad de salida, la calificación y las decisiones de revisión deben ser propiedad del modelo a menos que la comprobación sea solo una compuerta de humo determinista para estructura o presencia de campos obligatorios.
- al agregar o refactorizar internos del framework de Agently bajo
core/obuiltins/, prefiere un paquete de subdirectorio cuando la característica tenga múltiples roles como fachada, gestor, backend/proveedor, registro, adaptador, política o validación. Usa un solo archivo solo cuando la capacidad sea genuinamente pequeña y dividir sería un sobrediseño. - cuando un proyecto deba probar contenido semántico generado por modelo, diseña la prueba como una solicitud de juez de modelo de Agently con control de salida: las reglas explícitas y el contexto entran, la evidencia/razón por regla y los campos booleanos finales salen, y las pruebas afirman esos booleanos
- para ejemplos de negocio con sistemas simulados, mantén las simulaciones limitadas a hechos, registros, políticas, datos incompletos o material de fuente conflictivo; no devuelvas respuestas esperadas ocultas, etiquetas de aprobado/fallo o veredictos de calidad local. Deja que la verificación de AgentTask o un juez de modelo de Agently separado decida si el modelo manejó correctamente los datos defectuosos.
- para evaluación de aplicaciones de modelo, calificación, confianza, relevancia o juicios de calidad, prefiere niveles conceptuales y definiciones explícitos sobre puntuaciones numéricas directas. Si la lógica del flujo de trabajo posterior necesita umbrales o métricas agregadas, mapea esos niveles a valores numéricos deterministas en el código después de la respuesta del modelo.
- para enrutamiento de escenarios, detección de intención o clasificación de negocio en aplicaciones de IA, usa una solicitud de modelo de tamaño apropiado con un esquema de salida de Agently. Los modelos más pequeños, incluidos los modelos locales cuando estén disponibles, son aceptables para rutas simples con pocas etiquetas y reglas. Usa un modelo más grande cuando las etiquetas, las condiciones de decisión, las interacciones de reglas o la estructura de datos devuelta sean complejas.
- configura el estado de definición de agente reutilizable con
agent.define(...)cuando el código posea valores predeterminados de modelo, persona/prompt fijo, Acciones montadas, Habilidades, Espacio de trabajo, perfil de ContextBuilder o valores predeterminados de política. Manténagent.input(...),agent.output(...),.goal(goal_or_goals, success_criteria=None)/.goals(...)como el mismo punto de entrada de búsqueda de objetivos, y las opciones de ejecución en un borrador de AgentExecution; no enseñes la mutación de prompt pendiente de agente compartido como el patrón de configuración predeterminado. - usa
agent.effort("low" | "medium" | "high")para profundidad de estrategia ordinaria. Cuando la aplicación necesite una postura de estrategia explícita, mantén el mismo método y pasa secciones comobudget,planning,execution,verification,replanyprogress; trata los valores debudgetcomo sugerencias suaves de planificación, reflexión, reparación y profundidad de evidencia en lugar de límites duros silenciosos. Usalimits={...}explícito u opciones de tarea cuando el anfitrión necesite controles de recursos duros. Los valores predeterminados del framework no deben imponer cuotas de solicitud de modelo, iteración, tick de TaskBoard, ronda de Acción, conteo de nodos o llamada a herramienta; los tiempos de espera de sin progreso e inactivo son guardias de actividad para ejecuciones atascadas, no evidencia de estrategia. No introduzcas constructores de conteo de iteraciones brutas ni trates el esfuerzo como permiso, visibilidad de datos, control de recursos o aceptación de finalización. En AgentTask, el esfuerzo también controla la densidad de reflexión: bajo significa reflexión final más solo nodos de proceso marcados como importantes por el planificador, medio significa cada nodo principal o tarjeta/tick de TaskBoard, y alto significa cada paso enmarcado-observable, llamada de Acción/ACP, tarjeta de TaskBoard y reflexión final. La reflexión es evidencia para la entrada del replanificador/verificador, no evidencia de finalización por sí misma. - en ejemplos de Búsqueda de Objetivos / AgentTask, los hechos de la persona que llama y el contrato de salida estructurada solicitado pueden residir en el mismo borrador de
AgentExecutiona través de.input(...)y.output(...); AgentTask trata esa instantánea de prompt de ejecución como contexto de tarea durante la planificación, ejecución de pasos acotados y verificación. No dupliques esos hechos en el código duro del framework solo para que el bucle de tarea los vea. - para cada proceso intermedio con un contrato estructurado fuerte, usa
.output(..., format=...)de Agently en la solicitud/ejecución propietaria. Elige el formato que se ajuste a la carga útil (json,hybrid,flat_markdown,xml_fieldoyaml_literal); si un formato declarado que no sea JSON falla, Agently puede recuperarse a través del análisis JSON, pero solo las cargas útiles analizadas con forma de diccionario satisfacen el control estructurado o los contratos de salida de tarea final. Los internos de AgentTask pueden agregar campos de proceso cortos solo donde el framework tenga un consumidor concreto: campos de intención o base de decisión antes de decisiones de ruta/plan/control, y campos compactos de autocomprobación, resumen, verificación, reparación o mensaje de progreso después de los campos de resultado principal. Estos son hechos acotados deprocess_summarypara claridad y observación del siguiente paso, no cadena de pensamiento bruta, no evidencia de EvidenceEnvelope, no evidencia de finalización y no un modo de tiempo de ejecución público. - para entregables largos o con mucho texto cuyo valor principal es el cuerpo en lenguaje natural, no fuerces el cuerpo a través de
.output()solo para transportar texto. Deja que el cuerpo se genere como texto natural, luego usa un contrato estructurado compacto de juez/lectura para estado, evidencia, calidad y referencias de artefacto. Para entregables de archivo confiables, usa escritura/lectura de artefacto de Workspace más un manifiesto compacto. No agregues.output()únicamente para activar campos instantáneos para el flujo del cuerpo; el delta público sin procesar sigue siendo una fuente de cuerpo válida cuando el consumidor maneja límites de reproducción. Para AgentExecution respaldado por AgentTask, eldeltapúblico también puede proyectar hechos propiedad del framework como progreso, observación de acción, resúmenes de plan/acción Flat, tablas de estado de TaskBoard, fase, reintento y resultados terminales como párrafos cortos separados por líneas en blanco, mientras queinstantsigue siendo el flujo estructurado para estado de UI y diagnósticos. Las proyecciones Flat se mantienen lineales: la finalización del plan puede declarar la acción completada anterior y el plan de acción actual, y la salida terminal puede resumir lo que se hizo y el resultado. Las tablas de estado de TaskBoard son proyecciones solo de visualización a partir de eventos estructurados de AgentTask; la primera proyección de TaskBoard puede renderizar una tabla y los ticks posteriores pueden renderizar cambios de estado de tarjeta en lugar de reimprimir toda la tabla. Estas proyecciones no poseen juicio de finalización o calidad. No agregues una solicitud de narrador paralelo predeterminada para texto de proceso; usa campos de proceso acotados comoprogress_message,short_summary,verification_summaryyfinal_responsede la solicitud existente del planificador, verificador, tarjeta o finalizador, luego consúmelos a través deinstant/$deltasintético cuando la UI necesite una estructura más rica. Los escritores de artefactos internos deben consumir hechos del flujo de AgentExecution: el texto del cuerpo natural proviene de elementos delta sin procesar, y los límites de reintento provienen de$statuscuando el proveedor lo informa. Si el marcador de reproducción delta público"<$retry>...</$retry>"llega al consumidor de artefacto, trata ese marcador exacto como un evento de control de reintento; nunca lo escribas, limpies ni transportes como contenido de artefacto. Si aparece un cuerpo de artefacto Markdown completo dentro deevidenceestructurado, trátalo como un cuerpo entregable solo cuando el elemento de evidencia esté explícitamente etiquetado como artifact/body/deliverable/Markdown o vinculado a la ruta del manifiesto; el contenido fuente ordinario y los extractos fuente siguen siendo fragmentos de evidencia. Después de que la escritura/lectura de Workspace confiable tenga éxito, deja que el verificador terminal juzgue cualquierremaining_workde escritura de artefacto obsoleto en lugar de planificar otro paso de solo escritura. Para artefactos largos de Workspace confiables, la entrega de artefactos debe registrar elementos de libro mayor deworkspace_artifact.acceptance_locatordespués de la escritura/lectura real de Workspace. Los localizadores pueden usar secciones de manifiesto de artefacto, criterios de tarjeta de TaskBoard e intención opcional deacceptance_pointsdevuelta por el modelo, pero los rangos de línea, desplazamientos, encabezados y huellas digitales deben provenir del archivo real. La evidencia visible para el verificador puede incluir elementos de libro mayor deworkspace_artifact.targeted_readbackleídos de esos localizadores, con secciones de contrato de salida declaradas y anclajes genéricos solo como respaldo; trata los localizadores como punteros de lectura y las lecturas dirigidas como fragmentos de evidencia acotados, no juicios de finalización. La finalización de TaskBoard debe mantener los cuerpos entregables respaldados por archivos en Workspace y devolver solo un resumen conciso o un puntero de ruta/referencia comofinal_result, no una segunda copia del cuerpo del archivo. Los resultados terminales de AgentTask deben llevar unfinal_responseorientado al usuario para resultados aceptados, degradados, parciales y bloqueados: la verificación terminal Flat puede devolverlo en la solicitud de verificador existente, la finalización de TaskBoard puede devolverlo en la solicitud de finalizador existente, y el respaldo del framework debe ser determinista a partir del estado estructurado, referencias de artefacto, punteros definal_resulty criterios no cumplidos sin iniciar una solicitud de narrador separada. Las entregas degradadas aceptadas usanartifact_status="degraded"con límites de evidencia divulgados, mientras que los artefactos útiles pero no aceptados permanecen comoartifact_status="partial"y deben explicar los requisitos no cumplidos en lugar de ser informados como completados.get_text()/async_get_text()puede preferirfinal_responsepara dictados de resultado de estrategia de tarea;get_data()/async_get_data()devuelven la vista definal_resultde negocio cuando está presente, mientras queget_full_data()/async_get_full_data()devuelven el sobre completo de ruta/tarea. Las cargas útiles terminales de TaskBoard pueden incluirtaskboard.completion_notesacotados para resúmenes de tarjeta, brechas conocidas, notas de verificador y progreso de aceptación; úsalos para divulgar limitaciones de respuesta final, pero trátalos como contexto de proceso solo de proyección, no como evidencia de EvidenceEnvelope o prueba de finalización. Para contenido de verificador/finalizador producido por modelo, los campos de texto comostatus,reason,progress_messageyfinal_responseson solo contexto de visualización; el estado semántico de finalización, reparabilidad y aceptación debe provenir de campos de salida estructurados comois_complete,requires_blockycriterion_checks[].satisfiedmás guardias del anfitrión, nunca de tokenización, palabra clave, subcadena, expresión regular o coincidencia de texto de estado sobre texto de modelo. Los IDs de tarjeta de planificación de TaskBoard son sugerencias de modelo opcionales. El framework posee IDs de tarjeta canónicos, deduplicación y reasignación de dependencias; las sugerencias de ID ambiguas deben fallar cerradas en lugar de ser adivinadas. Las descargas intermedias, instantáneas de página web, código generado, notas de búsqueda, notas de tarea similares a memoria y texto extraído grande también pueden persistirse como referencias de Workspace/Acción y abrirse más tarde a través de lectura acotada; estas referencias son evidencia de ejecución, no prueba de que el entregable final exista. Una URL, ruta, descarga o referencia de instantánea descubierta tampoco es evidencia de que su contenido haya sido leído; trátala comoref_onlyhasta que haya una lectura/vista previa de contenido acotada disponible. Los campos explícitoscontent,excerptosnippetson vistas previas acotadas solo para