Lab Walkthrough Build Personal Assistant Agent

Time to bring everything together and build a simple personal assistant agent from starter files. This hands-on lab demonstrates an agent loop that calls tools, maintains conversation memory, and handles errors. You will work with two starter files, implement three mock tools, and create an agent loop that executes tool calls and returns natural language responses. This guide assumes a Python 3.11+ virtual environment is active and the starter files exist at /root/code/tools_starter.py and /root/code/agent_starter.py. Copy each starter file to its working name and implement the TODOs inside.

A retro pixel-art poster with the headline "BUILD A PERSONAL ASSISTANT AGENT." It highlights components like "Agent Loop," "Tools," "Memory," and "Error Handling" and notes "Python 3.11 + venv active" with starter file names.

What you’ll build

A small agent loop that can call tools and integrate tool output into the conversation.
Three deterministic, mocked tools: check_calendar, search_web, and get_user_preferences.
A dispatcher to run tools and return results to the model.
Error handling and a bounded iteration loop to avoid runaway calls.

Files and components

Item	Purpose	Path / Example
Starter files	Templates to copy and implement	`/root/code/tools_starter.py`, `/root/code/agent_starter.py`
Tools list	Tool metadata exposed to the model	`TOOLS` in `tools.py` (`function` schema)
Tool handlers	Mock implementations used by `execute_tool`	`check_calendar`, `search_web`, `get_user_preferences`
Agent loop	Calls model, executes tools, and assembles final response	`run_agent()` in `agent.py`

Tip: Keep the tool metadata (TOOLS) and the Python handler names in sync. The model requests a function by name, and your execute_tool must map that exact name to the corresponding Python function.

Step 1 — Tools: create `tools.py`

Copy tools_starter.py to tools.py.
Add three tool definitions into the TOOLS list:
- check_calendar — returns events for a date (YYYY-MM-DD) or today’s events if no date provided.
- search_web — returns a short summary for a search query.
- get_user_preferences — returns stored user preferences for a given category.

Each tool entry follows a function-schema pattern: a type plus a function object containing name, description, and parameters.

Implement simple handler functions that return mocked, deterministic responses, and implement an execute_tool dispatcher to map tool names to their Python functions and invoke them with parsed arguments.

Example tools.py (copy into /root/code/tools.py and fill in as shown):

# tools.py
import json
from typing import Any, Dict, Optional

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "check_calendar",
            "description": "Check calendar events for a given date (YYYY-MM-DD). If no date provided, return today's events.",
            "parameters": {
                "type": "object",
                "properties": {
                    "date": {"type": "string", "description": "Date in YYYY-MM-DD format (optional)"}
                }
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_web",
            "description": "Search the web for a query and return a short summary of the top result.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query string"}
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_user_preferences",
            "description": "Return stored user preferences for a given category.",
            "parameters": {
                "type": "object",
                "properties": {
                    "category": {"type": "string", "description": "Preferences category, e.g., 'news' or 'music'"}
                },
                "required": ["category"]
            }
        }
    }
]


def check_calendar(date: Optional[str] = None) -> str:
    """
    Mock implementation: in a real agent this would query a calendar API.
    """
    # For demo purposes we return a hard-coded schedule.
    return "10am: Standup, 2pm: Dentist"


def search_web(query: str) -> str:
    """
    Mock implementation that returns a pretend top result.
    """
    return f"[search_web] Top result for '{query}': AI agents are software that act autonomously."


def get_user_preferences(category: str) -> str:
    """
    Mock implementation: return stored preferences for a category.
    """
    return f"[get_user_preferences] Preferences for {category}: none set"


def execute_tool(name: str, args: Optional[Dict[str, Any]]) -> str:
    """
    Dispatch helper: call the matching function with args as kwargs.
    Returns the tool's result (string). Handles missing tool and call errors.
    """
    funcs = {
        "check_calendar": check_calendar,
        "search_web": search_web,
        "get_user_preferences": get_user_preferences,
    }

    func = funcs.get(name)
    if func is None:
        return f"Error: unknown tool '{name}'"

    if args is None:
        args = {}

    try:
        # Ensure args is a dict before expanding into kwargs
        if isinstance(args, str):
            # If the tool system passed a JSON string, try to decode it
            args = json.loads(args)
        if not isinstance(args, dict):
            return "Error: tool arguments must be an object"
        return func(**args)
    except TypeError as e:
        return f"Error: invalid arguments for tool '{name}': {e}"
    except Exception as e:
        return f"Error: tool '{name}' failed with exception: {e}"

Step 2 — Agent: create `agent.py`

Copy agent_starter.py to agent.py.
Implement run_agent(user_message: str, history: list | None = None) -> str:

Key responsibilities of run_agent:

Build the initial messages list, starting with the system prompt.
Append optional conversation history, then the user’s message.
Run a bounded loop (use MAX_ITERATIONS) that calls the model until:
- the model returns a final assistant message (finish reason stop), or
- the model requests tool calls (finish reason like tool_call or tool_calls).
When the model requests tools:
- Parse tool arguments (handle both dict and JSON string forms).
- Call execute_tool and append the tool’s output as a role: "tool" message.
- Continue the loop so the model can return a final answer that incorporates tool outputs.
Provide defensive handling for different SDK shapes (object vs dict) and unknown finish reasons.

Example agent.py:

# agent.py
import os
import json
from openai import OpenAI
from tools import TOOLS, execute_tool

MAX_ITERATIONS = 10
SYSTEM_PROMPT = "You are a helpful assistant."
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_API_BASE")
)


def run_agent(user_message: str, history: list | None = None) -> str:
    """
    Run the agent loop: keep calling the model until it either returns a final
    assistant message (finish reason 'stop') or we hit MAX_ITERATIONS.

    The model may request tool calls. When it does, this function executes those
    tools and appends results back into the conversation so the model can continue.
    """
    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
    if history:
        messages.extend(history)
    messages.append({"role": "user", "content": user_message})

    for _ in range(MAX_ITERATIONS):
        # Call the model. We pass TOOLS so the model can request tool calls.
        response = client.chat.completions.create(
            model="openai/gpt-4.1-mini",
            messages=messages,
            tools=TOOLS,
        )

        choice = response.choices[0]
        # Depending on SDK shape, assistant message may be at choice.message
        assistant_message = getattr(choice, "message", None) or choice.get("message", {})
        finish_reason = getattr(choice, "finish_reason", None) or choice.get("finish_reason")

        # If the model requested tool calls, run them and append tool results
        # Accept either "tool_call" or "tool_calls" as finish reason depending on SDK/version.
        if finish_reason in ("tool_call", "tool_calls"):
            # Append the assistant message that contains the tool call(s)
            messages.append({"role": "assistant", "content": assistant_message.content if hasattr(assistant_message, "content") else assistant_message.get("content", "")})

            # Extract tool calls from the assistant message. Different SDKs may expose this differently.
            tool_calls = []
            if hasattr(assistant_message, "tool_calls"):
                tool_calls = assistant_message.tool_calls
            elif isinstance(assistant_message, dict) and "tool_calls" in assistant_message:
                tool_calls = assistant_message["tool_calls"]

            # Execute each requested tool call and append its result back into messages.
            for tc in tool_calls:
                # tc may be an object with .id, .function.name, .function.arguments ...
                try:
                    # Support both object and dict shapes
                    function_info = getattr(tc, "function", None) or tc.get("function", {})
                    tool_name = getattr(function_info, "name", None) or function_info.get("name")
                    raw_args = getattr(function_info, "arguments", None) or function_info.get("arguments", "{}")
                    # arguments may already be a dict or a JSON string
                    if isinstance(raw_args, str):
                        args = json.loads(raw_args) if raw_args.strip() else {}
                    else:
                        args = raw_args or {}
                    result = execute_tool(tool_name, args)
                except Exception as e:
                    result = f"Error: {e}"

                # Append tool result as a tool role message
                tool_call_id = getattr(tc, "id", None) or tc.get("id")
                messages.append({
                    "role": "tool",
                    "name": tool_name,
                    "tool_call_id": tool_call_id,
                    "content": result
                })

            # Loop again so the model can incorporate tool results and produce the final answer
            continue

        # If the model finished normally, return the assistant's content
        elif finish_reason == "stop":
            # assistant_message may be an object or dict
            content = ""
            if hasattr(assistant_message, "content"):
                content = assistant_message.content
            elif isinstance(assistant_message, dict):
                content = assistant_message.get("content", "")
            return content

        # Unknown finish reason: append whatever assistant produced and continue, or break
        else:
            # Attempt to append assistant message and continue
            if assistant_message:
                if hasattr(assistant_message, "content"):
                    messages.append({"role": "assistant", "content": assistant_message.content})
                elif isinstance(assistant_message, dict) and "content" in assistant_message:
                    messages.append({"role": "assistant", "content": assistant_message["content"]})
            # As a safety, break to avoid infinite loop if finish reason is unexpected
            break

    return "Error: reached max iterations without a final response."

Important: Never hard-code your API key. Set OPENAI_API_KEY and any OPENAI_API_BASE in your environment, and avoid committing keys to source control.

Step 3 — Run the agent

From the project directory (for example /root/code) run:

python3 agent.py

Add a small __main__ block to agent.py if it’s not present, to test single-step and multi-step interactions:

if __name__ == "__main__":
    # Single-step: ask about today's calendar
    response = run_agent("What's on my calendar today?")
    print(response)

Example console output for the calendar query (mocked tool response):

root@controlplane ~/code via 🐍 v3.12.3 (venv) cd /root/code && python3 agent.py
You have a team standup at 10am and a dentist appointment at 2pm today.
root@controlplane ~/code via 🐍 v3.12.3 (venv)

The agent requested the check_calendar tool, received the mock schedule, and returned a natural language summary.

Step 4 — Multi-step task example

Test a multi-step query that requires the agent to call multiple tools in sequence. The agent will:

Call search_web to summarize information about AI agents.
Call check_calendar to check availability after 2 PM.
Combine the results into a final assistant response.

Add or run this test in agent.py:

if __name__ == "__main__":
    response = run_agent("Find info about AI agents and check if I'm free after 2pm.")
    print(response)

Example console output (mocked):

root@controlplane ~/code via 🐍 v3.12.3 (venv) cd /root/code && python3 agent.py
[search_web] Top result for 'AI agents': AI agents are software that act autonomously.
[check_calendar] 10am: Standup, 2pm: Dentist
AI agents are software that act autonomously.
You're free after 2pm - your last event is a dentist at 2pm.
root@controlplane ~/code via 🐍 v3.12.3 (venv)

No extra orchestration code is required beyond the agent loop: the agent handles tool calling, executing results via execute_tool, and incorporating tool outputs back into the conversation.

Troubleshooting & tips

If the model never returns a final stop finish reason, the loop will eventually exit with the MAX_ITERATIONS guard to prevent infinite loops.
Ensure the TOOLS metadata is valid JSON-like structure (the function schema) — mismatches between declared parameters and the actual handler signature can produce TypeError.
Tool argument payloads may arrive as dicts or JSON strings; execute_tool should defensively handle both.

Links and further reading

This lab demonstrates a simple production-like architecture: one agent, multiple tools, conversation memory, and basic error handling — a pattern you can extend with real APIs, authentication, and richer tool behavior.

LLM Fundamentals

Tools and Workflows

Building AI Agents

Introduction

Production & OpenClaw

Lab Walkthrough Build Personal Assistant Agent

What you’ll build

Files and components

Step 1 — Tools: create `tools.py`

Step 2 — Agent: create `agent.py`

Step 3 — Run the agent

Step 4 — Multi-step task example

Troubleshooting & tips

Links and further reading

Watch Video

​What you’ll build

​Files and components

​Step 1 — Tools: create tools.py

​Step 2 — Agent: create agent.py

​Step 3 — Run the agent

​Step 4 — Multi-step task example

​Troubleshooting & tips

​Links and further reading

Watch Video

What you’ll build

Files and components

Step 1 — Tools: create `tools.py`

Step 2 — Agent: create `agent.py`

Step 3 — Run the agent

Step 4 — Multi-step task example

Troubleshooting & tips

Links and further reading