Difficult to Follow the Code Along with the Book Chapter 4

[MrDataPsycho]

Hi,
After you read the issue feel free to close the it. My goal to read the book was to read the book and code as well my self. But the code snippet is incomplete in the book and evolved in the git repository. Which made it difficult to follow along with the book. I do not mind the book being large. Even if that is the case that it was required to make the book small then the code repository should have been tagged with versions. For example first chapter with tag v0.0.1 ... Just giving an example. I start reading agent First agent base class section 4.2.2 BaseAgent Listing 4.3 and 4.4 with the following code:

“class BaseAgent(ABC):
    """Abstract base class defining the core agent interface."""

    def __init__(
        self,
        name: str,
        instructions: str,
        model_client: 'BaseChatCompletionClient',
        tools: Optional[List] = None,
        memory: Optional['BaseMemory'] = None,
        context: Optional['AgentContext'] = None,
        middleware: Optional[List] = None,
        max_iterations: int = 10
    ):
        self.name = name
        self.instructions = instructions
        self.model_client = model_client

        # Process optional components with defaults
        self.tools = self._process_tools(tools or [])
        self.memory = memory
        self.context = context or AgentContext()
        self.middleware_chain = MiddlewareChain(
            middleware or []
        )
        ...

There is no import of ABC, abstractmethod, I do not know where AgentContext() , MiddlewareChain(middleware or []) comes from.
IN the listing 4.6 when creating BaseChatCompletionClient created ABC and abstractmethod imported correctly.

When I checked the code repo _base.py It looks so different than actual base agent code from the book.

Am I reading the book wrong way. I am not interested to import code from pico agent and run it by My goal was to understand how pico agent is being created and how can I create one. But for now I do not see my goal will be reached by continuing to read this book.

Please provide any recommendation you have how best this book should be read or it is required to make some update to this book. This is the foundation chapter, If someone loose interest after reading this chapter probably won't continue to read the rest. The book is still excellent but I would like to see it as one of the top best.

Also something about the flow of the chapter 4. Agent depends on Chat Client, Messages Tools and other stuff then They should be build first and then when agent requirements are fullfilled then we should initialise the base agent. Middleware and other minor stuff could be left for later but the major dependency of agent should be created first then Agent base should be created that's my opinion.

Thanks

[victordibia]

Hi @MrDataPsycho,

First of all, thank you, this is great feedback.

While writing, I had to make some tradeoffs. For example, I could add a really simplistic version that is easier to read but fails to illustrate the true complexity of what the agentic loop looks like, while still not filling pages with too much code. On the other hand, as you mention, the goal is also to make it easy for the reader to create their own agentic loop rather than simply import and use picoagent. I think this goal is important, and I will work on a revision that attempts to achieve it.

Regarding concept presentation, the intended learning experience is:

• Present the shell/structure of the agent class (e.g., there is a stub for the Agent class—it will need a model, tools, middleware, etc., which we will attach later)
• Iteratively expand it with implementation details (e.g., implement the model client, then add it)

Perhaps some writing improvements can be done to make this clearer.
I will update this thread as I make progress on this revision

Thanks again for the feedback, much appreciated.

Btw, is a reading experience like this closer to what you were expecting from the book?
The Agent Execution Loop: How to Build an AI Agent From Scratch

[ShahriyarR]

As this issue also was dedicated for the feedback loop for the book, I would like also share few observations.
From my learning experience, the books are powerful in the term of they force my brain to read and manually type the code portions sequentially, also to go back and force to absorb more useful information. So it gives clear progress on each page.
But also, most successful teaching platforms are based on RPG-style learning experience, with clear steps and final outcomes at the end of each unit, chapter.

I am not telling the book chapter should give a diamond at each successful run :) What I am trying to emphasize how this book can be more helpful on learning something completely new and most valuable nowadays - Building AI Agents.

Let's for example take Chapter 6: Building Multi-Agent Workflows - from the name the intention is - at the end of the chapter I will have simple, running, ready to use Multi-Agent Workflow - as I don't know yet wth is this, I would assume the guidance, until the end.

Listing 6.1 Worfklow building blocks: types, functions, and steps - now my cognitive load starts to increase.

• Where to put this code? in which file? main.py? domain.py? models.py?
• How I should structure my project? it should be located in src/models/domain.py?
• To which file this listing code belongs in the book repo?

Listing 6.2 Workflow composition and execution with streaming - again some code portions.

• The same questions above + how to successfully run it?

This is about how the coding examples can be structured effectively.
Let's also talk about how to be sure that we have managed to finish the milestone inside the chapter? - I would expect a reward, why now? Because: "When you run this example," after listing 6.2, is a trigger.

How, I would make more interactive book experience?
Multiple ways can be organized together or separately.
The best experience of course to have special CLI command to run our code against predefined tests either locally or against the server or the github(fetches from raw content, runs against chapter 6 code that we typed from)

So codes are organized by chapters, each Listing has its own test, or within the chapter 6.1 + 6.2 is already working solution, so "Note: run this CLI command to validate the results"

Even better experience the book acts like a community of the agent builders. The book has a web page, working server, when CLI command succeeds its unlocks the ranking, unlocking the next level etc. So basically, I have some kind of clear progress - to some final big boss - to some final big project.