Instructivos de Framework de agentes

Cómo comenzar a usar un notebook

Comienza a usar el Framework de agentes con un agente de "Hello World" en un notebook.

Agentes de muestra

Para explorar el código de ejemplo de los agentes de muestra, descarga el archivo .zip de esta carpeta de Google Drive a tu entorno de desarrollo local.

En el directorio de muestras, se encuentran los agentes de demostración. Instala las dependencias en el archivo requirements.txt para un agente de demostración específico:

pip install  -r samples/anthropic_demo/requirements.txt

Ejecuta los siguientes comandos:

af web samples

af run samples/hello_world

Instructivos

En esta página, se proporcionan instructivos paso a paso para tareas comunes cuando se trabaja con el Agente Framework. Elige un instructivo para comenzar.

Instructivo: Integra tus propios datos en un agente

En este instructivo, se abordan diferentes métodos para proporcionar tus propios datos, conocimiento o documentos a tu agente. El mejor enfoque depende del tamaño y el tipo de tus datos, y del equilibrio deseado entre latencia y precisión.

Proporciona tus propios datos

Existen varias formas de proporcionar tus propios datos, conocimientos o documentos al agente, según el tamaño y el tipo de datos, y las compensaciones de latencia y precisión deseadas.

Tipo Importe pequeño Importe elevado
Texto sin formato Incorporación en la instrucción o en la RAG RAG
Documentos Incorporación en la instrucción o en la RAG RAG
Otro contenido multimedia
(imágenes, audios, videos, etcétera)		 Trabajo en curso Trabajo en curso

En los siguientes instructivos, encontrarás más información sobre cada enfoque.

Cómo incorporar datos en las instrucciones

Una forma sencilla de proporcionar una pequeña cantidad de documentos al agente es incorporarlos en las instrucciones.

Los archivos PDF y otros archivos de texto se pueden convertir a texto sin formato y, luego, incorporarlos en las instrucciones.

Consideraciones

  • El contenido de los archivos se enviará al modelo, por lo que, cuanto más grande sea el archivo, mayor será la latencia y el costo.

  • El contenido se enviará al modelo para todas las solicitudes, independientemente de si la consulta del usuario no tiene nada que ver con el contenido.

  • Puedes usar texto sin formato o cualquier formato de texto legible, p.ej., Markdown para tu archivo.

Riesgos de seguridad

  • La incorporación de contenido de esta manera tiene algunos riesgos de seguridad, ya que el servidor puede tratar el contenido de los documentos incorporados como sus propias instrucciones.

  • Este riesgo de seguridad se puede mitigar hasta cierto punto si se marca claramente el comienzo y el final del contenido incorporado, como se muestra en el siguiente ejemplo.

  • Debido a este riesgo, no incorpores contenido en el que no confíes, p.ej., contenido generado por usuarios.

Ejemplo

Para que las instrucciones sean legibles, un enfoque común es cargar el archivo y insertarlo en las instrucciones con la sintaxis de cadena f de Python.

Ten en cuenta que usa etiquetas XML para separar el contenido del archivo del resto de las instrucciones. También puedes usar otras formas de separación, siempre que sea clara para el modelo. P.ej., etiquetas como BEGIN_USER_GUIDE o END_USER_GUIDE.

def read_file(filename):
  file_path = os.path.join(os.path.dirname(__file__), filename)
  with open(file_path, 'r') as f:
    return f.read()

agent_framework_bot = Agent(
    # ...
    instruction=f"""You are an agent that answers user's questions about the Agent Framework.

You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)

Usa RAG

La generación mejorada por recuperación es un patrón común para mejorar las respuestas del modelo con tus propios datos. Es particularmente útil para grandes cantidades de datos, ya que funciona indexando los datos y solo recupera una pequeña parte de datos relevantes para la consulta.

El framework de agentes proporciona algunas formas de integrarse con varios sistemas de RAG diferentes.

Situaciones Recomendaciones
Demos / Prototipos FilesRetrieval
Pequeña cantidad de datos
(unos pocos documentos)		 FilesRetrieval
Solución RAG completamente administrada VertexRagRetrieval
Soluciones de bricolaje o de otro tipo de RAG LlamaIndexRetrieval

FilesRetrieval

FilesRetrieval compilará un almacén de vectores en la memoria cuando se inicie tu agente. Agrega latencia y se limita a la memoria y el rendimiento del entorno de alojamiento de la API. Por lo tanto, esta opción solo es adecuada para demostraciones o prototipos, o para la producción con una cantidad muy pequeña de documentos.

FilesRetrieval se compila sobre LlamaIndex. Debes configurarlo según la documentación de LlamaIndex.

Una vez que esté configurada, puedes colocar tus documentos en una carpeta y crear una herramienta de recuperación de la siguiente manera:

company_policies_retrieval = FilesRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)

root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

VertexRagRetrieval

Vertex RAG Engine es un servicio completamente administrado que controla la transferencia, transformación, incorporación, indexación y recuperación de datos.

Para usarlo, sigue la guía de inicio rápido para configurar tu corpus y transferir documentos. Luego, agrega la herramienta a tu agente.

company_policies_retrieval = VertexRagRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

Si usa la Búsqueda de Google, tu agente podrá acceder a conocimiento del mundo real en tiempo real y usar la Búsqueda de Google para investigar preguntas.

Notas

  • La Fundamentación con la Búsqueda de Google puede generar cargos adicionales.
  • Para Gemini 1.5:
    • Cuando agregas la herramienta de la Búsqueda de Google a un agente, no puedes tener otras herramientas para ese agente.
    • La herramienta de la Búsqueda de Google siempre se ejecuta, independientemente de si la búsqueda necesita la Búsqueda de Google o no.
  • Para Gemini 2.0 y versiones posteriores:
    • Puedes tener otras herramientas mientras usas la herramienta de la Búsqueda de Google.
    • La herramienta de Búsqueda de Google se ejecuta solo cuando el modelo considera que es necesario.
  • Los modelos de terceros no son compatibles con las herramientas de la Búsqueda de Google.
  • Para usar la herramienta de la Búsqueda de Google, debes seguir los lineamientos que se indican en Cómo usar las sugerencias de la Búsqueda de Google, lo que incluye mostrar siempre un banner para mostrar las búsquedas relacionadas de la Búsqueda de Google. Nuestra IU para desarrolladores también sigue estas reglas.

Ejemplo

Habilitar la herramienta de la Búsqueda de Google es muy sencillo. Solo debes agregar google_search a tu lista de herramientas.

from agents.tools import google_search

root_agent = Agent(
    # ...
    tools=[google_search],
)

Instructivo: Evalúa el rendimiento de tu agente

Evaluar a tu agente es fundamental para garantizar que funcione según lo esperado y cumpla con tus estándares de calidad. El framework de agentes proporciona varias formas de evaluar el rendimiento del agente con archivos de prueba y criterios de evaluación.

Cómo funciona la evaluación

Cada archivo de prueba contiene una lista de consultas, trayectorias de herramientas esperadas y respuestas de referencia. Los archivos de prueba se pueden organizar en carpetas. De manera opcional, una carpeta puede incluir un archivo test_config.json que especifique los criterios de evaluación.

Archivo de prueba de ejemplo

Un archivo de prueba contiene una sesión con consultas, el uso esperado de la herramienta y respuestas de referencia. A continuación, se muestra un ejemplo:

[
  {
    "query": "hi",
    "expected_tool_use": [],
    "reference": "Hello! What can I do for you?\n"
  },
  {
    "query": "roll a die for me",
    "expected_tool_use": [
      {
        "tool_name": "roll_die",
        "tool_input": {
          "sides": 6
        }
      }
    ]
  },
  {
    "query": "what's the time now?",
    "expected_tool_use": [],
    "reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
  }
]

Criterios de evaluación

Los criterios de evaluación en test_config.json definen cómo se medirá el rendimiento del agente:

  • tool_trajectory_avg_score: Evalúa las trayectorias de las herramientas.
  • response_match_score: Evalúa las respuestas.

Si no se proporcionan criterios de evaluación, se aplicará una configuración predeterminada.

Ejemplo de criterios de evaluación (test_config.json)

Este es un ejemplo de un archivo test_config.json que especifica criterios de evaluación personalizados:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}
  • tool_trajectory_avg_score: Se establece en 1.0, lo que significa que se espera un uso perfecto de la trayectoria de la herramienta.
  • response_match_score: Se establece en 0.8, lo que permite un pequeño margen de error en las respuestas del agente.

Formas de ejecutar la evaluación

1. af web: Ejecuta evaluaciones a través de la IU web

Puedes evaluar a los agentes de forma interactiva con nuestra IU basada en la Web.

Pasos:
  1. Para iniciar el servidor web, ejecuta lo siguiente: bash af web
  2. En la interfaz web, haz lo siguiente:
    • Selecciona un agente.
    • Haz clic en "Guardar sesión como archivo de prueba" para guardar una sesión como archivo de prueba.
    • Haz clic en "Run test file" para mostrar una ventana emergente con archivos de prueba en la carpeta del agente.
Archivos de prueba:

Los archivos de prueba se almacenan en la misma carpeta que el agente. Puedes actualizar manualmente o agregar archivos de prueba según sea necesario.

2. af test: Ejecuta pruebas a través de la línea de comandos.

Puedes ejecutar todos los archivos de prueba en una carpeta especificada con el comando af test. La carpeta debe contener la definición del agente y los archivos de prueba.

Ejemplo:
af test samples/agent_folder

Este comando ubicará y ejecutará todos los archivos de prueba (*.test.json) en la carpeta especificada.

3. pytest: Ejecuta pruebas de manera programática

También puedes usar pytest para ejecutar archivos de prueba como parte de tus pruebas de integración.

Comando de ejemplo:
pytest tests/integrations/
Ejemplo de código de prueba:

Este es un ejemplo de un caso de prueba de pytest que ejecuta un solo archivo de prueba:

def test_with_single_test_file():
    """Test the agent's basic ability via a session file."""
    AgentEvaluator.evaluate(
        "tests.integration.fixture.home_automation_agent",
        "tests/integration/fixture/home_automation_agent/simple_test.test.json",
    )

Este enfoque te permite integrar las evaluaciones de agentes en tus canalizaciones de CI/CD o en paquetes de pruebas más grandes.