DEV Community: Rockerfeler

Más allá del Prompt: Cómo ATDF y la Ingeniería de Contexto Transforman tus Flujos de IA

Rockerfeler — Fri, 11 Jul 2025 13:42:36 +0000

En el desarrollo de agentes conversacionales y sistemas basados en LLM, la ingeniería de contexto y los estándares de descripción de herramientas juegan un papel esencial para garantizar respuestas coherentes, fiables, escalables y fácilmente mantenibles. Este artículo explora en profundidad cómo ATDF (Agent Tool Description Format) se integra de forma natural en un flujo de ingeniería de contexto, utilizando un ejemplo representativo de validación de rangos de fechas.

¿Qué es ATDF?

ATDF es un formato estructurado, agnóstico y estandarizado para describir las interfaces funcionales de herramientas que un agente puede invocar, independientemente de la plataforma subyacente, motor de ejecución o lenguaje de programación utilizado:

Schema de entrada (input): especificación formal de los parámetros requeridos, con sus tipos, formatos y descripciones claras.
Schemas de salida (output): estructuras detalladas para las respuestas esperadas en caso de éxito y de error, validadas mediante JSON Schema.
Ejemplos (examples): casos de uso documentados que sirven como guía para el modelo, facilitando pruebas, debugging y generación automática de instrucciones.

Al definir explícitamente la interfaz de cada herramienta, ATDF permite:

Validación automática de los datos antes y después de invocar la herramienta.
Autodocumentación contextual integrada en el prompt, de forma que el modelo entienda de forma clara cómo interactuar con la herramienta.
Manejo de errores estructurado mediante plantillas predictibles que pueden ser analizadas y reutilizadas por el agente de manera programática.
Reusabilidad de herramientas en distintos agentes o flujos, sin necesidad de modificaciones específicas.

Fundamentos de la Ingeniería de Contexto

La ingeniería de contexto diseña y organiza todos los elementos que conforman el entorno informativo en el que opera el modelo de lenguaje. Esta disciplina actúa como el puente entre el modelo base y su comportamiento adaptado a casos de uso específicos. Incluye:

Recuperación de datos: extracción dinámica de información relevante desde bases de conocimiento, APIs externas o documentos (técnicas como RAG).
Gestión de memoria: uso de scratchpads, historiales y memorias a largo plazo para almacenar interacciones, estados, preferencias y datos temporales del usuario.
Compresión, chunking y tokenización: técnicas para dividir, resumir o estructurar grandes volúmenes de texto para adaptarse a los límites de tokens del modelo.
Orquestación de herramientas: lógica condicional y modular que determina cuándo, cómo y en qué secuencia se deben invocar herramientas externas.

Estas capas no solo permiten que el modelo interactúe con el entorno, sino que también aseguran que lo haga de forma eficiente, precisa y contextualizada.

Ejemplo Genérico: Validación de Rango de Fechas

Este ejemplo muestra un patrón común en flujos de procesamiento automático: validar que una fecha de inicio (Start) y una fecha de fin (End) sean válidas, estén en el futuro con respecto al momento actual y que Start ocurra antes que End.

Diagrama Lógico del Flujo

Entrada de parámetros: el agente recibe los valores Start y End como parte del contexto del usuario.
Evaluación de condiciones: se aplican dos comparaciones sobre objetos tipo dateTime:

now < Start (inicio en el futuro)
Start < End (inicio antes que fin)
1. Respuesta exitosa: si ambas condiciones se cumplen, la herramienta devuelve un JSON estructurado como:

{
  "status": "success",
  "data": {
    "text": "'Start' es anterior a 'End' y ambas son posteriores a 'Ahora'"
  },
  "meta": {
    "timestamp": "2025-07-11T14:25:00Z"
  }
}

Respuesta con error: si alguna condición falla, se devuelve una estructura informativa que detalla el fallo:

{
  "status": "error",
  "data": {
    "code": "400",
    "text": "Error en fechas de inicio y fin. La fecha de inicio 2025-07-10T09:00:00Z y/o la fecha de fin 2025-07-10T08:00:00Z son iguales o anteriores a 2025-07-11T14:23:45Z",
    "details": { "field": "start: 2025-07-10T09:00:00Z, end: 2025-07-10T08:00:00Z" },
    "expected": "start: cualquier fecha y hora posterior a 2025-07-11T14:23:45Z, end: cualquier fecha y hora posterior a 'start'",
    "solution": "Asegúrate que ambos valores son fechas válidas y posteriores a 2025-07-11T14:23:45Z"
  },
  "meta": {
    "timestamp": "2025-07-11T14:23:45Z"
  }
}

Definición de la herramienta en formato ATDF

Con base en este flujo, se define la herramienta validar_rango_de_fechas utilizando el estándar ATDF:

tool:
  name: validar_rango_de_fechas
  description: Valida que Start y End sean posteriores a ahora, y que Start < End.
  input:
    type: object
    properties:
      Start:
        type: string
        format: date-time
        description: Fecha y hora de inicio.
      End:
        type: string
        format: date-time
        description: Fecha y hora de fin.
    required: [Start, End]

  output:
    success:
      type: object
      properties:
        status: { const: "success" }
        data:
          type: object
          properties:
            text:
              type: string
              description: Mensaje confirmando el resultado exitoso.
        meta:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
      required: [status, data, meta]

    error:
      type: object
      properties:
        status: { const: "error" }
        data:
          type: object
          properties:
            code:
              type: string
              description: Código de error (p. ej. "400").
            text:
              type: string
              description: Mensaje legible explicando el error.
            details:
              type: object
              description: Campos o valores que causaron el fallo.
            expected:
              type: string
              description: Lo que el sistema esperaba recibir.
            solution:
              type: string
              description: Instrucciones para corregir el error.
        meta:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
      required: [status, data, meta]

  examples:
    - input:
        Start: "2025-07-12T10:00:00Z"
        End:   "2025-07-12T12:00:00Z"
      output:
        status: "success"
        data:
          text: "'Start' es anterior a 'End' y ambas son posteriores a 'Ahora'"
        meta:
          timestamp: "2025-07-11T14:25:00Z"
    - input:
        Start: "2025-07-10T09:00:00Z"
        End:   "2025-07-10T08:00:00Z"
      output:
        status: "error"
        data:
          code: "400"
          text: "Error en fechas de inicio y fin..."
          details: { field: "start:…, end:…" }
          expected: "start: posterior a ahora, end: posterior a start"
          solution: "Asegúrate de valores válidos"
        meta:
          timestamp: "2025-07-11T14:23:45Z"

Orquestación y Contextualización Dinámica

La herramienta definida se puede usar de manera flexible dentro de un flujo más amplio de orquestación contextual:

Inyección de especificaciones: durante la inicialización de sesión, el modelo recibe una sección TOOLS con toda la definición ATDF correspondiente.
Construcción del prompt: el sistema de contexto construye automáticamente el payload correcto para invocar validar_rango_de_fechas.
Evaluación del resultado:

Si el resultado es success, el flujo avanza al siguiente paso del proceso (por ejemplo, confirmación de cita, reserva, etc.).
Si el resultado es error, el agente presenta el mensaje de error, sugiere soluciones claras, y conserva los detalles técnicos para debugging o retrys.
1. Persistencia de estado:
Guarda el timestamp del intento y los valores fallidos para evitar loops.
Almacena preferencias temporales o patrones de errores frecuentes en la memoria del agente.

Conclusión

Este ejemplo demuestra con claridad cómo ATDF proporciona un marco claro, modular y reutilizable para definir interfaces de herramientas de forma agnóstica, y cómo la ingeniería de contexto convierte estas definiciones estáticas en experiencias conversacionales dinámicas, seguras y eficaces. Integrando ambas prácticas, es posible construir agentes inteligentes que razonan, validan y corrigen su comportamiento de manera autónoma, precisa y alineada con las necesidades reales del usuario.

Interoperability Between ATDF and MCP

Rockerfeler — Fri, 09 May 2025 06:00:31 +0000

The Agent Tool Description Format (ATDF) is an open standard based on JSON/YAML for describing tools functionally—what a tool does, when to use it, and how to use it. In contrast, the Model Context Protocol (MCP) by Anthropic is an open protocol (using JSON-RPC 2.0) that standardizes how AI assistants (LLMs) discover and invoke external tools and data sources. While ATDF is a static format for tool descriptions, MCP defines a two-way mechanism ("hosts" and "clients") for listing and invoking tools at runtime.

Note: MCP is officially called Model Context Protocol (not "Multimodal Callable Procedures"), though its design inherently supports "multimodal" calls.

Describing MCP Tools in ATDF

In MCP, each tool is defined as a JSON object with fields like name, description, inputSchema (parameter definitions in JSON Schema), and optional annotations (usage hints). For example, Anthropic’s official "fetch" server exposes a fetch tool with parameters:

url (required string)
raw (optional boolean).

To describe this in ATDF, map these fields to:

tool_id: Unique identifier (e.g., "fetch").
description: Brief explanation (e.g., "Retrieves and processes content from a URL").
when_to_use: Contextual usage (e.g., "When needing to fetch or analyze a webpage").
how_to_use.inputs: List of parameters with name, type, and description.
how_to_use.outputs: Success/failure messages (ATDF-specific; MCP does not define these explicitly).

Example ATDF Description for `fetch`:

{
  "tool_id": "fetch",
  "description": "Retrieves and extracts content from a webpage given its URL",
  "when_to_use": "Use when you need to obtain or process content from a website",
  "how_to_use": {
    "inputs": [
      { "name": "url", "type": "string", "description": "The URL of the page to retrieve" },
      { "name": "raw", "type": "boolean", "description": "If true, returns raw HTML (default: false)" }
    ],
    "outputs": {
      "success": "Web content retrieved successfully",
      "failure": [
        { "code": "invalid_url", "description": "The provided URL is invalid or inaccessible" },
        { "code": "fetch_error", "description": "Error retrieving content" }
      ]
    }
  }
}

Key Similarities and Differences

Aspect	ATDF	MCP
Nature	Static JSON/YAML format for tool descriptions	Dynamic JSON-RPC protocol for tool discovery/invocation
Identifier	`tool_id` (unique string)	`name` (unique string)
Description	`description` + `when_to_use` explain functionality and context	`description` (optional free text); uses `annotations` for usage hints (e.g., readOnly)
Parameters	List in `how_to_use.inputs` (name, type, description)	Defined in `inputSchema` (JSON Schema object)
Outputs	`success`/`failure` messages in `how_to_use.outputs`	Free-form results returned during `tools/call`; no standardized output schema
Usage Context	Explicit `when_to_use` field	Relies on agent logic or annotations; no dedicated field
Communication	N/A (static specification only)	Uses `tools/list` and `tools/call` endpoints (JSON-RPC)
Metadata	Supports multilingual descriptions, versioning, tags (v0.2.0)	No built-in multilingual metadata in the base protocol
Design Focus	Descriptive and functional; model-agnostic	Integration-focused; orchestrates workflows between agents and external servers

Examples, Documentation, and Community

There are no official integrations between ATDF and MCP yet, but both have standalone resources:

ATDF: GitHub repository with formal specs, JSON schemas, and examples.
MCP: Official documentation and examples (e.g., fetch, analyze_csv, github_create_issue).

Community efforts include:

AutoGen: Integrates MCP via McpToolAdapter (converts tools to BaseTool objects).
Víctor Dibia: Demonstrated MCP integration with AutoGen agents (e.g., fetch server).

No public codebases automate MCP-to-ATDF conversion yet. Manual mapping or ad-hoc scripts are required.

Approaches for Translating MCP to ATDF

1. Manual Mapping or Custom Scripts

Write a script (e.g., Python) to:

Map MCP fields to ATDF:
- name → tool_id
- description → description
- Parse inputSchema.properties to populate how_to_use.inputs.
Validate with ATDF’s official Python SDK (pip install agent-tool-description-format).

2. Leverage SDKs

MCP SDK: Use Python/TypeScript SDKs to dynamically fetch tools via tools/list.
ATDF SDK: Serialize MCP data into ATDF using the Python SDK for validation.

3. Agent Frameworks (e.g., AutoGen)

AutoGen’s McpToolAdapter converts MCP tools into executable objects. Extend this to serialize metadata into ATDF.

4. Validation and Refinement

Validate generated ATDF with JSON schemas. Enhance fields like when_to_use or add multilingual metadata (ATDF v0.2.0).

Conclusion

While ATDF and MCP serve different purposes—ATDF for static tool descriptions and MCP for runtime communication—they can complement each other. By mapping fields like name → tool_id and inputSchema → how_to_use.inputs, developers can create interoperable systems where agents dynamically invoke tools described in ATDF.