Notas prácticas: ZQ Intelligence: Agentes especializados en orquestación para finanzas
Guía paso a paso operativa de las notas prácticas: ZQ Intelligence: Agentes especializados en orquestación para finanzas: contratos, cheques y espacios de código adicionales para los equipos que implementan este patrón.
Úselo como una versión reestructurada dirigida a los operadores de las ideas presentadas en “ZQ Intelligence: Orchestrator-Specialist Agents for Financial Analysis in Snowflake”: etapas claras, espacios ordenados para el código y notas de recuperación que perduran tras la transferencia de tareas. La etapa de Resumen funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben estar en un único lugar al que los operadores puedan auditar sin tener que leer todo el sistema.
ZQ Model as a Service: Cómo impulsa la inteligencia de Snowflake
Para el modelo ZQ como etapa, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.
Por qué agentes especializados: lógica de línea de montaje
En la fase de Asamblea de Agentes Especializados en el “Porqué”, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluya la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Arquitectura de un vistazo
En la fase de “Arquitectura a primera vista”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de “Arquitectura a primera vista”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin necesidad de leer todo el código.
Caso de uso 1: Agente ZQ Macro
Al trabajar en la etapa ZQ del Caso de uso 1, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
- Retrieve evidence for a query
CALL TESTING.ZQ_CB_AGENT.ZQ_AGENT_RETRIEVE_EVIDENCE(
OBJECT_CONSTRUCT('QUERY', 'inflation outlook', 'CENTRAL_BANK', 'federal_reserve_system', 'K', 25)
);
- Run full analysis (retrieval + stance + uncertainty + forward-looking)
CALL TESTING.ZQ_CB_AGENT.ZQ_AGENT_RUN_FULL_ANALYSIS(
OBJECT_CONSTRUCT('QUERY', 'unemployment', 'CENTRAL_BANK', 'federal_reserve_system', 'K', 25)
);
Caso de uso 2: Agente ZQ Equity
Al trabajar en la etapa Use Case 2 ZQ, primero anote el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Análisis basado en evidencias: cómo lo aplica ZQ
Al trabajar en la fase de Análisis Basado en Evidencias How ZQ, primero escribe el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considera esta fase como un contrato entre los insumos y los resultados validados. Nombra los artefactos, define las verificaciones de éxito y evita completaciones parciales silenciosas. Haz puntos de control después de pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la fase de Análisis Basado en Evidencias How ZQ, primero escribe el contrato: los insumos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantén la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
Código: Configuración de la herramienta del agente
La etapa de Configuración de la herramienta del agente funciona mejor cuando se trata como una superficie medible. Capture una transcripción de éxito, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
# ZQ Macro Agent: tool definitions (agent_spec.py)
tools:
- tool_spec:
type: "generic"
name: "retrieve_evidence"
description: "Retrieves central bank sentences via Cortex Search and persists for NLP classification. Returns REQUEST_ID for classifier tools."
input_schema:
type: "object"
properties:
QUERY: { type: "string", description: "Search query for central bank communications" }
CENTRAL_BANK: { type: "string", description: "Filter by central bank. NULL for all." }
K: { type: "number", description: "Number of evidence sentences (default 25, max 200)." }
required: [QUERY]
- tool_spec:
type: "generic"
name: "classify_stance"
description: "Classifies retrieved evidence by monetary policy stance (Hawkish/Dovish/Neutral). Requires REQUEST_ID from retrieve_evidence."
input_schema:
type: "object"
properties:
REQUEST_ID: { type: "string", description: "REQUEST_ID from retrieve_evidence" }
required: [REQUEST_ID]
Código: Búsqueda en Cortex y persistencia de pruebas
La función de búsqueda y etapas de Code Cortex funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el error debe apuntar a una única responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
- Cortex Search service over CB sentences
CREATE OR REPLACE CORTEX SEARCH SERVICE TESTING.CB_AI.SENTENCE_SEARCH_SVC
ON TEXT
ATTRIBUTES CENTRAL_BANK, YEAR, DOCUMENT_TYPE
WAREHOUSE = CB_AGENT_WAREHOUSE
AS
SELECT ID, TEXT, CENTRAL_BANK, YEAR, DOCUMENT_TYPE, RELEASE_DATE, …
FROM TESTING.CB_AI.SENTENCE_SEARCH_VW;
- Evidence and labels tables for traceability
CREATE TABLE TESTING.CB_AI.EVIDENCE_HITS (
request_id STRING, hit_id STRING, rank INT,
document_id STRING, sentence_id STRING, text STRING, …
);
CREATE TABLE TESTING.CB_AI.MODEL_LABELS (
request_id STRING, model_id STRING, hit_id STRING,
prediction STRING, confidence DOUBLE, …
);
El proceso: Recuperación → Clasificación → Agregación
La etapa de Clasificación y Recuperación del Pipeline funciona mejor cuando se trata como una superficie medible. Capture un transcripto ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Separe la política de fragmentación de la política de recuperación. Cambiar una no debe obligar a reescribir la otra cuando cambian las métricas de calidad. La etapa de Clasificación y Recuperación del Pipeline funciona mejor cuando se trata como una superficie medible. Capture un transcripto ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
Conclusión
En la fase de conclusión, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Referencias
En la fase de Referencias, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluya la aprobación humana en aquellas tareas que implican gastos o modificaciones en datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Lista de verificación operativa
Al trabajar en la fase de la Lista de verificación operativa, primero escriba el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista garantiza que los cambios posteriores en el código sean transparentes.
Registra los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos.
Se debe crear un punto de control después de los pasos costosos. La reanudación no debería volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Fija las versiones de dependencias y registra el resumen de la imagen que ejecutó la demostración. La reproducibilidad es mejor que el conocimiento basado en prácticas internas.
Mantén la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un único lugar que los operadores puedan auditar sin tener que leer todo el grafo.
Se debe crear un punto de control después de los pasos costosos. La reanudación no debería volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.
Nota para el lote b3ca06f8cc84: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: Cómo construí un pipeline RAG en documentos legales y financieros — Guía paso a paso de las Notas prácticas: Cómo construí un pipeline RAG en documentos legales y financieros, incluyendo contratos, verificaciones y espacios para código listo para usar en equipos que implementen este patrón.