Conceptos Fundamentales de ATDF

馃幆 驴Qu茅 es ATDF?

El Agent Tool Description Format (ATDF) es un est谩ndar para describir herramientas de agentes de IA y manejar respuestas de error de manera estandarizada. ATDF proporciona un formato JSON consistente que funciona independientemente del lenguaje de programaci贸n o framework utilizado.

馃専 Conceptos Clave

1. Herramienta (Tool)

Una herramienta es una funci贸n o servicio que un agente de IA puede ejecutar. Cada herramienta tiene:

Ejemplo:

{
  "name": "hotel_reservation",
  "description": "Make a hotel reservation with validation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "guest_name": {"type": "string"},
      "email": {"type": "string", "format": "email"},
      "check_in": {"type": "string", "format": "date-time"}
    }
  }
}

2. Esquema de Entrada (Input Schema)

El esquema de entrada define la estructura y validaci贸n de los datos que una herramienta acepta. Utiliza JSON Schema para:

Ejemplo:

{
  "type": "object",
  "properties": {
    "guest_name": {
      "type": "string",
      "description": "Full name of the guest",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Guest email address"
    },
    "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "description": "Number of guests"
    }
  },
  "required": ["guest_name", "email", "guests"]
}

3. Respuesta de Error ATDF

Una respuesta de error ATDF es un formato estandarizado para comunicar errores con contexto enriquecido. Incluye:

Ejemplo:

{
  "errors": [
    {
      "type": "https://api.example.com/errors/invalid-date",
      "title": "Invalid Check-in Date",
      "detail": "Check-in date cannot be in the past",
      "instance": "/api/errors/e62aa61e-d844-4761-82c3-531a070fb139",
      "tool_name": "hotel_reservation",
      "parameter_name": "check_in",
      "suggested_value": "2025-01-15T12:00:17.148869",
      "context": {
        "current_time": "2025-01-15T12:00:17.148869",
        "provided_date": "2025-01-14T10:00:00Z"
      }
    }
  ]
}

4. Tipo de Error (Error Type)

El tipo de error es una URI que identifica categ贸ricamente el tipo de problema. Los tipos est谩ndar incluyen:

5. Contexto (Context)

El contexto proporciona informaci贸n adicional que ayuda a entender y resolver el error. Puede incluir:

馃攧 Flujo de Trabajo ATDF

1. Descubrimiento de Herramientas

flowchart LR
    A[Agente de IA] --> B[GET /tools]
    B --> C[Descripci贸n de Herramientas]
    C --> D[Esquemas de Entrada]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e8
    style D fill:#f3e5f5

Proceso:

  1. El agente consulta el endpoint /tools
  2. Recibe la lista de herramientas disponibles
  3. Analiza los esquemas de entrada
  4. Determina qu茅 herramientas puede usar

2. Ejecuci贸n de Herramientas

flowchart LR
    A[Agente] --> B[POST /api/tool/execute]
    B --> C[Validaci贸n de Entrada]
    C --> D[L贸gica de Negocio]
    D --> E[Respuesta]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#f3e5f5

Proceso:

  1. El agente env铆a datos al endpoint de la herramienta
  2. Se valida la entrada contra el esquema
  3. Se ejecuta la l贸gica de negocio
  4. Se devuelve el resultado o error

3. Manejo de Errores

flowchart LR
    A[Error Ocurre] --> B[Formato ATDF]
    B --> C[Contexto Enriquecido]
    C --> D[Correcci贸n Autom谩tica]
    D --> E[Reintento]
    
    style A fill:#ffebee
    style B fill:#fff3e0
    style C fill:#e8f5e8
    style D fill:#e3f2fd
    style E fill:#f3e5f5

馃幆 Beneficios de ATDF

Para Agentes de IA

Para Desarrolladores

Para Sistemas

馃敡 Componentes de una Implementaci贸n ATDF

1. Tool Registry

class ToolRegistry:
    def __init__(self):
        self.tools = {}
    
    def register_tool(self, name: str, description: str, schema: dict):
        self.tools[name] = {
            "name": name,
            "description": description,
            "inputSchema": schema
        }
    
    def get_tools(self):
        return list(self.tools.values())

2. Error Handler

class ATDFErrorHandler:
    def create_error(self, type_uri: str, title: str, detail: str,
                    tool_name: str, parameter_name: str,
                    suggested_value: str = None, context: dict = None):
        return {
            "errors": [{
                "type": type_uri,
                "title": title,
                "detail": detail,
                "instance": f"/api/errors/{uuid.uuid4()}",
                "tool_name": tool_name,
                "parameter_name": parameter_name,
                "suggested_value": suggested_value,
                "context": context or {}
            }]
        }

3. Validator

class ATDFValidator:
    def validate_request(self, tool_name: str, data: dict):
        # Validar esquema JSON
        # Validar reglas de negocio
        # Retornar errores ATDF si es necesario
        pass

馃搳 Tipos de Herramientas Comunes

1. Herramientas de Informaci贸n

2. Herramientas de Acci贸n

3. Herramientas de Validaci贸n

4. Herramientas de Transformaci贸n

馃帹 Patrones de Dise帽o ATDF

1. Factory Pattern

class ToolFactory:
    @staticmethod
    def create_tool(tool_type: str, config: dict):
        if tool_type == "hotel_reservation":
            return HotelReservationTool(config)
        elif tool_type == "flight_booking":
            return FlightBookingTool(config)
        # ...

2. Strategy Pattern

class ValidationStrategy:
    def validate(self, data: dict) -> list[ATDFError]:
        pass

class DateValidationStrategy(ValidationStrategy):
    def validate(self, data: dict) -> list[ATDFError]:
        # Validar fechas
        pass

class EmailValidationStrategy(ValidationStrategy):
    def validate(self, data: dict) -> list[ATDFError]:
        # Validar emails
        pass

3. Observer Pattern

class ToolExecutionObserver:
    def on_tool_executed(self, tool_name: str, result: dict):
        # Logging, m茅tricas, etc.
        pass

class ATDFLogger(ToolExecutionObserver):
    def on_tool_executed(self, tool_name: str, result: dict):
        logger.info(f"Tool {tool_name} executed successfully")

馃攧 Ciclo de Vida de una Herramienta ATDF

1. Dise帽o

2. Implementaci贸n

3. Registro

4. Uso

5. Mantenimiento

馃摎 Pr贸ximos Pasos

  1. Leer la Especificaci贸n ATDF para entender todos los detalles
  2. Revisar la Gu铆a de Implementaci贸n para comenzar a implementar
  3. Explorar los Ejemplos para ver implementaciones reales
  4. Consultar las Mejores Pr谩cticas para recomendaciones

驴Listo para comenzar? Ve a la Gu铆a de Implementaci贸n para crear tu primera herramienta ATDF.

Documentaci贸n: https://mauricioperera.github.io/agent-tool-description-format/