Un Agente simple para realizar resumen del contenido de sitios web con Embabel

La AI (Artificial Intelligence) esta por todos lados y ha llego para quedarse.

Un gran uso de la AI para nosotros como Desarrolladores de Software es la creación de Agentes Inteligentes que, con ayuda de Large Language Models (LLM’s), puedan resolver problemas que serían complejos o imposibles de abordar mediante programación tradicional.

Hace unas semanas me entere de la existencia de un nuevo framework en el que Rod Johnson (creador del framework Spring) y otras personas están trabajando llamado Embabel

Embabel es un framework para crear flujos de agentes en la JVM haciendo una mezcla de interacciones con LLM’s via prompts y código con modelos de dominio (clases Java/Kotlin). El framework esta construido sobre Spring AI

El framework es relativamente nuevo y aun en desarrollo, aun no existe documentación oficial y es posible que algunas cosas que aquí explico cambien en un futuro (aunque no creo que radicalmente).

El código de este ejemplo lo encuentran en mi repositorio de Github en la dirección: abadongutierrez/basic-embabel-agent

Caso de Uso: Resumen de sitios web

Casi todos hemos usado LLM’s para realizar algún resumen de algún texto, de hecho, hacer resumen es uno de los grandes usos de LLM’s, y en el ejemplo de hoy usaremos Embabel para crear un Agente que extraiga el contenido de los sitios que le digamos y que haga un resumen del texto de los mismos.

En general usaremos Embabel para construir un agente que: 1. Reciba una entrada de texto libre por parte del usuario (via Spring Shell). 2. Extraiga los enlaces web mencionados por el usuario. 3. Visite cada sitio, obtenga su contenido en forma de texto libre de etiquetas HTML. 4. Genere un resumen del contenido de cada sitio.

Para visitar cada liga y extraer el contenido de ese sitio web usaremos la biblioteca JSoup. Con esta biblioteca podemos fácilmente conectarnos a un sitio web y extraer solo el texto sin etiquetas HTML de la siguiente forma:

// Conectarse y obtener el documento HTML
Document doc = Jsoup.connect("https://en.wikipedia.org/").get();
// Extraer solo el texto
doc.text();

¿Cómo se crea un Agente?

Para definir un Agente tenemos que crear una clase y anotarla con @Agent. Esto es muy similar al uso @Component y las anotaciones derivadas que existen en el Framework de Spring. De hecho @Agent también deriva de @Component por lo que se maneja como un Bean y, por lo mismo, podemos aprovechar la inyección de dependencias.

@Agent(description = "Agent to summarize content of web pages")  
public class SummarizingAgent {
    @Action  
    public WebPageLinks extractWebPagesLinks(UserInput userInput) { ... }

    @Action
    public SummarizedPages summarizeWebPages(WebPageLinks webPageLinks, OperationContext operationContext) { ... }

    @AchievesGoal(description = "Show summarized content of the web pages to the user")  
    @Action  
    public SummarizedPages showSummarization(SummarizedPages summarizedPages) { ... }
}

Es importante asignar una buena descripción al agente, ya que cuando se interactúa con ellos a través de Spring Shell, un LLM es el encargado de seleccionar qué agente responderá a la solicitud del usuario. Esta selección se basa en un análisis de la intención del usuario y en la correspondencia con el agente más adecuado para atenderla.

Cada método que represente un paso en el flujo del agente debe anotarse con @Action. El método que representa el objetivo final del agente también se anota con @AchievesGoal.

Cuando interactuamos con Agentes via la interfaz de Spring Shell, generalmente el primer paso es el método @Action que recibe como argumento un UserInput. Esto lo menciono porque usar los Agentes via Spring Shell no es la única forma de interactuar con ellos también se puede con otros mecanismos que tratare de explorar en futuras publicaciones.

El flujo del Agente

No existe una forma de especificar el flujo del Agente programáticamente. El framework, como lo dice en la pagina de inicio, trata de ir mas allá de simplemente especificar un flujo a través de una maquina de estados y aplica una planeación inteligente al inicio del flujo y después de la ejecución de cada paso. El flujo lo detecta el framework a través de la relación que hay entre los métodos inspeccionando los tipos de datos en de “entradas” (argumentos de los métodos) y “salidas” (el tipo de retorno).

SummarizingAgent

En este tutorial creamos el SummarizingAgent que como primer paso extrae las URLs de la entrada de usuario. Para lograr esto hacemos uso de un LLM debido a que como las instrucciones del usuario es texto libre y sin formato, los LLM son buenos analizando texto y extrayendo información que nosotros le indiquemos. Esto esta implementado en el método extractWebPagesLinks.

@Action  
public WebPageLinks extractWebPagesLinks(UserInput userInput) {  
    String prompt = String.format("""  
            Extracts the urls from the provided user input.

            <user-input>  
            %s
            </user-input>

            Extract only the links mentioned in the user input, dont add any other links.  
            """.trim(), userInput.getContent());  
    return PromptRunner.usingLlm().createObjectIfPossible(prompt, WebPageLinks.class);  
}

El segundo paso en el flujo es extraer el contenido en texto de cada sitio web y aquí nos apoyarnos nuevamente de un LLM para obtener un resumen de ese contenido. Esto esta implementado en el método summarizeWebPages. Este método tiene 2 formas de actuar y esto depende de la bandera app.useOpenAI definida en el application.properties. Esta pequeña aplicación esta pensada para usar Ollama y los modelos locales llama3.2 y all-minilm pero también se puede hacer uso de OpenAI asignando la bandera app.useOpenAI en true, esto implica que se necesita especificar la variable de ambiente OPENAI_API_KEY para que la aplicación funcione correctamente.

El método summarizeWebPages lo implemente de 2 formas debido a que llama3.2 no es un modelo tan poderoso como los modelos de OpenAI y tuve muchas complicaciones usando el mismo prompt. Por lo que para cuando se usa llama3.2 use un prompt distinto y ademas una alternativa en caso de que el primer prompt fallara.

...
@Value("${app.useOpenAI:false}") boolean useOpenAI

...

@Action  
public SummarizedPages summarizeWebPages(WebPageLinks webPageLinks, OperationContext operationContext) {  
    if (this.useOpenAI) {  
        return getSummarizedPagesUsingOpenAI(webPageLinks);  
    }  
    return getSummarizedPagesUsingLocalModels(webPageLinks, operationContext);  
}

El ultimo paso en el flujo es simplemente devolver el conjunta de paginas y su resumen para que el framework lo imprima en la consola de Spring Shell. Esto implementado en el método showSummarization que ademas tiene que estar marcado con la anotación @AchievesGoal debido a que una vez ejecutando este método el objetivo del agente se habra logrado.

@AchievesGoal(description = "Show summarized content of the web pages to the user")  
@Action  
public SummarizedPages showSummarization(SummarizedPages summarizedPages) {  
    return summarizedPages;  
}

Interacción con LLMs

El framework tiene el concepto de PromptRunner‘s que como su nombre lo indica ejecutan un prompt a un LLM.

Un PromptRunner tiene métodos para ejecutar un prompt y convertir la salida del prompt a un objeto de dominio con métodos como createObjectIfPossible o createObject. Esto da la ventaja de aplicar tipado fuerte en nuestros programas y así poder hacer uso de técnicas de refactoring mas fácilmente.

El framework define ciertos LLM que los programas utilizaran por default. En nuestro caso estamos usando modelos locales con Ollama por lo que en el archivo application.properties podemos encontrar las siguientes propiedades que indican que modelos se estarán usando por default:

embabel.models.default-llm=llama3.2:latest  
embabel.models.default-embedding-model=all-minilm:latest  
embabel.models.embedding-services.best=all-minilm:latest  
embabel.models.embedding-services.cheapest=all-minilm:latest  
embabel.models.llms.best=llama3.2:latest  
embabel.models.llms.cheapest=llama3.2:latest  

embabel.agent-platform.ranking.llm=llama3.2:latest

Cuando se realizan operaciones con LLM una de las principales cosas que se deben especificar son los prompts pero los PromptRunner‘s también dan la facilidad de especificar los “Tools” que deseamos utilizar como parte de la ejecución de un prompt. En esta pequeña aplicación estamos especificando y haciendo use de JSoup como “Tool” para extraer el texto de un sitio web.

Las “Tools” se pueden especificar haciendo uso de la anotación de Spring AI @Tool y esto se puede ver implemetado en la clase JSoupTool que ademas es un Bean de spring que fácilmente inyectamos al Agente.

@Component  
public class JSoupTool {
    ...

    @Tool(name = "jsoup", description = "A tool to extract text from web pages using JSoup")  
    public String getPageTextTool(String url) {  
        ...
    }

Los PromptRunner‘s hacen uso de los LLM especificados por default o usando LlmOptions se puede indicar modelos distintos. En el caso de esta aplicación usamos esta funcionalidad para especificar el modelo de OpenAI a utilizar cuando la bandera app.useOpenAI esta activa.

String prompt = " ... ";
BuildableLlmOptions llmOptions = LlmOptions.fromCriteria(  
        ModelSelectionCriteria.byName("gpt-4.1-mini")  
);  
return PromptRunner  
        .usingLlm(llmOptions)  
        .withToolObject(jSoupTool)  
        .createObjectIfPossible(prompt, SummarizedPages.class);

Ejecución

Esta aplicación esta configurada para correr usando como interfaz Spring Shell y eso lo podemos notar por la anotación @EnableAgentShell en la clase donde se encuentra el método main.

@SpringBootApplication  
@EnableAgents(  
       loggingTheme = LoggingThemes.STAR_WARS,  
       localModels = {LocalModels.OLLAMA}  
)  
@EnableAgentShell
public class BasicEmbabelAgentApplication {  
    public static void main(String[] args) {  
       SpringApplication.run(BasicEmbabelAgentApplication.class, args);  
    }  
}

También como se puede notar esta configurada para buscar y usar LLM’s locales usando Ollama.

Una vez ejecutada la aplicación aparece el prompt de Spring Shell donde podemos usar el comando x (execute) para indicar el “user input” y hacer que la plataforma de agentes de Embabel busque y seleccione el agente adecuado para atender la petición del usuario:

...
21:05:55.957 [main] INFO  DelegatingAgentScanningBeanPostProcessor - All deferred beans were post-processed.
21:05:55.958 [main] INFO  BasicEmbabelAgentApplication - Started BasicEmbabelAgentApplication in 1.834 seconds (process running for 2.074)
Fear is the path to the dark side.
starwars> x "summarize the content of the following page https://en.wikipedia.org/wiki/Alan_Turing"

salida:

You asked: UserInput(content=summarize the content of the following page https://en.wikipedia.org/wiki/Alan_Turing, timestamp=2025-07-08T03:15:04.089557Z)

{
  "summarizedPages" : [ {
    "url" : "https://en.wikipedia.org/wiki/Alan_Turing",
    "summary" : "Alan Turing (1912-1954) was a British mathematician, computer scientist, logician, philosopher, and cryptographer who made significant contributions to the development of computer science, artificial intelligence, and cryptography.\n\n**Early Life and Education**\n\nTuring was born on June 23, 1912, in London, England. He studied mathematics at King's College, Cambridge, where he graduated with a First Class Honours degree in Mathematics. During World War II, Turing worked at the Government Code and Cypher School (GC&CS) at Bletchley Park, where he played a crucial role in cracking the German Enigma code.\n\n**Contributions to Computing**\n\nTuring is considered one of the founders of computer science. He proposed the theoretical foundations of modern computer science, including:\n\n1. **The Turing Machine**: a mathematical model for a computer's central processing unit (CPU).\n2. **The Universal Turing Machine**: a machine that could simulate any other machine.\n3. **Computability Theory**: the study of what can be computed by a machine.\n\n**Codebreaking and Cryptography**\n\nAt Bletchley Park, Turing worked with a team to crack the Enigma code, which was used by the German military during World War II. His work significantly contributed to the Allied victory.\n\n**Personal Life and Later Years**\n\nTuring's personal life was marked by tragedy. In 1952, he was convicted of gross indecency for his relationship with a man, which led to his chemical castration and eventual death in 1954 at the age of 41.\n\n**Legacy**\n\nTuring's legacy is profound:\n\n1. **Computer Science**: Turing's work laid the foundation for modern computer science.\n2. **Artificial Intelligence**: His ideas on machine intelligence and computation have influenced AI research.\n3. **Cryptography**: Turing's contributions to codebreaking and cryptography have had a lasting impact on national security.\n\n**Recognition**\n\nIn 2009, the British government officially apologized for Turing's treatment and posthumously pardoned him. In 2017, he was featured on the £50 note, making him the first openly gay person to be featured on a British banknote.\n\nTuring's life and work serve as a testament to his innovative spirit and contributions to science and society. His legacy continues to inspire new generations of computer scientists, mathematicians, and thinkers."
  } ]
}

Si analizan con atención los “logs” que imprime la aplicación al ejecutar notaran los pasos que toma Embabel para seleccionar el Agente a ejecutar, los action/goals que contiene el Agente y la planeacion que hace de la ejecución de los “actions” después de la ejecución de cada paso.

Conclusion

Aunque Embabel aún se encuentra en una etapa de desarrollo, ya demuestra ser una propuesta prometedora para los desarrolladores que trabajamos sobre la JVM. Embabel esta desarrollado en Kotlin pero, Rod Johnson lo ha mencionado en entrevistas, este debe poder usarse de manera natural en Java como se puede ver en el código de este ejemplo.

Su enfoque declarativo permite crear agentes inteligentes usando anotaciones, sin definir flujos de forma explícita. En su lugar, un algoritmo de IA (sin usar LLMs) infiere el plan de ejecución según el contexto del agente y después de ejecutar cada paso. Además, se integra de forma nativa con tecnologías conocidas como Spring y Spring AI, lo que facilita su adopción. También incluye soporte para pruebas unitarias y de integración, lo que lo hace apto para proyectos serios desde el inicio.