Welcome! Today, we’ll learn how to design a Todo API agent — a software agent that interacts with a Todo API for you. In modern systems, especially those using multi-agent setups, it’s common to delegate tasks to agents. For example, you might want an agent to manage your to-do list by reading tasks from an external service.

The goal: understand how to structure the code, define data models, and ensure all API interactions go through the agent. By the end, you’ll know how to build an agent that reads tasks from a Todo API and responds to user prompts in natural language.

Let’s break down the main components of our Todo API agent. In a multi-agent system, each agent handles a specific domain. Here, our agent manages to-do tasks.

Key components:

• Agent: Receives user prompts and decides what to do.
• Tool: Wraps specific functionality (like calling an API) for the agent.
• API Interaction: Handles communication with the external Todo API.

Why this structure? Think of the agent as a team member who knows how to use certain tools (like the Todo API) to get things done. This makes the system modular and easier to maintain.

Here’s how a user interacts with the agent:

Notice: the user never calls the API directly. They interact with the agent, which uses its tools to fulfill the request.

For context, here is a simple implementation of ask_agent function we can use:

To make our agent reliable, we define clear data models and possible actions. Pydantic models and enums help here. Enums define allowed actions. We only support reading tasks for now:

This makes supported actions explicit. To add more actions later, just extend the enum.

Pydantic’s BaseModel defines the structure of a to-do item:

This ensures every task has a consistent structure, making validation and serialization easy.

This model defines the arguments needed for an action:

Using these models ensures the agent only receives valid, well-structured data.

The TodoAPI class contains all logic for interacting with the external Todo API. This keeps API logic separate from the agent’s decisions.

• get_tasks: Fetches all tasks from the API and returns them as TodoItem objects.
• handle_request: Decides what to do based on the action. For now, only GET is supported.
• run_function: Parses the arguments, calls the API handler, and returns the result as JSON.

This design makes it easy to add more actions later.

Now, let’s connect the API logic to the agent using a tool. The tool bridges the agent and the API. We use a FunctionTool to wrap the API:

• name: The tool’s name.
• description: What the tool does.
• params_json_schema: The expected input structure, from our Pydantic model.
• on_invoke_tool: The function to call when the tool is used.

The agent is created with a name, instructions, and a list of tools:

Instructions tell the agent how to behave and which tool to use.

As a user, you should never call the API directly. Always use the agent interface.

Here’s how to ask the agent to list your tasks:

• The user gives a natural language prompt.
• ask_agent sends this prompt to the agent.
• The agent uses its todos_api tool to fetch tasks.
• The agent returns the result.

This keeps your code clean and ensures all API interactions are managed by the agent, making it easier to add features and handle errors.

You learned how to design a Todo API agent that interacts with an external API through a clear interface. We covered structuring code with agents, tools, and data models, and encapsulating API logic in a class. Most importantly, all API interactions should go through the agent, not directly from your code.

Now it’s your turn! Next, you’ll get hands-on experience building and using your own Todo API agent. You’ll practice defining models, implementing API logic, and interacting with the agent using natural language prompts. This will help solidify your understanding and prepare you for more advanced multi-agent designs.