Tool-Using Assistant Architecture Profile

Propósito y convención editorial

Este Architecture Profile reúne decisiones para un asistente que interpreta solicitudes y utiliza capacidades externas bajo control de la aplicación. Su escenario es consultar y reprogramar una entrega. El modelo puede proponer herramientas y argumentos; la autoridad para ejecutarlos se conserva en una frontera explícita.

tool-use explica el patrón y tool-calling el mecanismo de invocación. El perfil añade identidad, estado, políticas, efectos y recuperación. Tampoco es un Agent Profile: describe una arquitectura de aplicación, no la configuración de un especialista dentro de un harness.

La guía de tool use de Anthropic, consultada el 2026-11-09, distingue herramientas ejecutadas por la aplicación de herramientas alojadas por el proveedor. Es un ejemplo de implementación: este perfil se centra en herramientas propias que acceden a servicios de negocio y no presupone que todo código se ejecute dentro del modelo.

Responsabilidades y recorrido

flowchart LR
    U[Usuario] --> A[API e identidad]
    A --> C[Contexto y control del turno]
    C --> M[Modelo propone respuesta o llamada]
    M -->|Llamada| G[Validacion y autorizacion]
    G -->|Autorizado| E[Ejecutor y servicio de negocio]
    G -->|Requiere aprobacion| H[Confirmacion de propuesta]
    H --> G
    E --> R[Resultado observado]
    R --> C
    M -->|Respuesta| O[Salida revisada]
    O --> U

El diagrama representa una composición posible. La API identifica al solicitante y delimita la sesión; el controlador del turno prepara contexto, capacidades y condiciones de terminación. El modelo propone un paso y un gate comprueba estructura, recurso, permisos y condiciones antes de ejecutar. Los resultados vuelven como observaciones, sin adquirir autoridad para cambiar las reglas del encargo.

La vía hacia una respuesta final también necesita los controles de salida pertinentes. Una frase generada como «entrega reprogramada» debe apoyarse en el resultado real del servicio, no solamente en la intención de llamar a una herramienta.

La selección puede estar conducida por un workflow fijo o por un ciclo agentic delimitado. El trabajo Building effective agents, de 2024, distingue esos esquemas y utiliza feedback del entorno y condiciones de parada. Su taxonomía orienta la comparación; no obliga a introducir autonomía o frameworks.

Decisiones del perfil

Eje	Decisión y cuestiones que quedan abiertas
Decomposition	Distinguir conversación, propuesta, policy gate, ejecución y servicios de dominio; no exigir procesos separados.
Dependency structure	Exponer capacidades acotadas mediante contratos de aplicación; evitar convertir una descripción textual en acceso general a sistemas internos.
Communication	Schemas y resultados tipados, con errores diferenciados de transporte, autorización y negocio.
Data ownership	El servicio de negocio conserva la verdad sobre la entrega; la conversación y la propuesta no sustituyen su estado.
Tenancy e isolation	Identidad y alcance se propagan desde el caller confiable; cada herramienta limita recursos y datos accesibles.
Coordination	Relacionar propuesta, aprobación, ejecución y resultado; contemplar reintentos y efectos de resultado incierto.
Execution model	Declarar límites de iteraciones, tiempo, llamadas y gasto; decidir cómo observar trabajo que exceda un turno.
Deployment y scaling	Mantener una unidad simple mientras permita proteger fronteras y operar la carga; separar workers si el lifecycle lo requiere.

La arquitectura puede usar model-routing o ai-gateway sin delegarles toda la política del dominio. model-context-protocol puede implementar la conexión con algunas capacidades, pero el protocolo no decide qué usuario puede modificar una entrega.

De intención a operación autorizada

Una solicitud como «pasalo al martes» puede dejar abierta fecha, zona horaria, entrega o condiciones comerciales. El asistente debe aclarar lo necesario antes de proponer un efecto. El servidor obtiene al usuario autenticado y comprueba que el recurso solicitado le corresponde; no confía en que el modelo elija el identificador correcto.

Para una acción que requiere confirmación, representar una propuesta con identidad, recurso, argumentos normalizados y condiciones. La aprobación debe corresponder a esa propuesta concreta y a un actor autorizado. Cambiar la fecha o el destinatario después de aprobar puede exigir otra decisión. Autorización actual y vigencia deben revisarse cuando se ejecuta el efecto.

human-in-the-loop conserva el patrón de intervención y agent-permissions-and-approval-boundaries distingue aprobación y capacidad técnica. No toda consulta necesita una confirmación, pero una política de bajo riesgo para lecturas no debería extenderse implícitamente a escrituras o divulgación de datos.

Un JSON conforme al schema sigue pudiendo referir al recurso equivocado. structured-generation ayuda a interpretar la propuesta; la política del dominio y least-privilege-for-agents limitan lo que puede ejecutarse.

Efectos, repetición e incertidumbre

El executor envía la operación al servicio responsable y registra evidencia suficiente para correlacionar el resultado. Si se pierde la respuesta, pueden haberse producido cambios aunque el caller observe un timeout. Reenviar una escritura sin estrategia puede duplicar el efecto.

idempotency y retry aportan condiciones para repetir trabajo. La identidad usada para deduplicar debe relacionarse con una operación de negocio definida; cambiar silenciosamente sus argumentos mientras se reutiliza la misma identidad necesita tratamiento explícito. Un retry de la inferencia y un retry de la acción no son la misma operación.

Si el estado de la entrega cambió después de preparar la propuesta, un control de concurrencia o una nueva validación puede rechazarla. El asistente debe comunicar el resultado observado o pedir otra decisión, en lugar de conservar una confirmación desactualizada como permiso indefinido.

Fallos y pruebas pertinentes

Escenario	Evidencia a buscar
Herramienta desconocida o argumentos inválidos	Rechazo antes del efecto y error observable, sin fallback silencioso a una capacidad más amplia.
Operación sobre un recurso ajeno	Denegación por la aplicación aunque la estructura sea válida.
Usuario rechaza o cancela	Ausencia de ejecución posterior atribuible a esa propuesta.
Timeout después del envío	Reconciliación o estado incierto explícito; no una confirmación inventada.
Herramienta devuelve una instrucción maliciosa	Conservación de trust-boundaries y del encargo autorizado.
El ciclo no progresa	Terminación según presupuesto o escalación con evidencia, sin repetición ilimitada.

Probar el gate y executor con propuestas deterministas permite aislar controles de la variabilidad del modelo. Luego evaluar selección de herramientas, argumentos y finalización en tareas representativas mediante agent-evaluation. Un happy path no basta para demostrar seguridad o fiabilidad.

Las trazas deben correlacionar propuesta y efecto, evitando secretos o payloads sensibles innecesarios. agent-tracing, ai-llm-observability y agent-execution-and-human-review-cost aportan perspectivas distintas sobre observación y costo, sin convertir telemetría en prueba automática de corrección.

Composición y límites

Una herramienta de búsqueda documental puede seguir rag-application-architecture. Ambos perfiles se componen: uno organiza evidencia para generación y el otro el control sobre capacidades y efectos. Pueden funcionar dentro de una aplicación monolítica o distribuida según los drivers.

Si una operación ya tiene entradas claras y una secuencia estable, evaluar si un workflow convencional satisface la necesidad. Este perfil introduce flexibilidad y también nuevas decisiones de validación, operación y aceptación. No es una escala de madurez ni una garantía otorgada por el nombre assistant. architecture-profiles y ai-assisted-software-engineering permiten recorrer estas relaciones.