{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-11-21-practical-guide-on-how-to-build-an-agent-from-scratch-with/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "> **Alternative Version:** Check out the [Interactions API version](https://www.philschmid.de/building-agents-interactions-api) of this guide.\n\nIt seems complicated, when you watch an AI agent edit multiple files, run commands, handle errors, and iteratively solve a problem, it feels like magic. But it isn’t. The secret to building an agent is that there is no secret.\n\nThe core of an Agent is surprisingly simple: It is a Large Language Model (LLM) running in a loop, equipped with tools it can choose to use.\n\nIf you can write a loop in Python, you can build an agent. This guide will walk you through the process, from a simple API call to a functioning CLI Agent.\n\n## What actually is an Agent?\n\nTraditional software workflows are prescriptive and follow predefined paths (`Step A -> Step B -> Step C`), **Agents** are System that uses an LLM to dynamically decide the control flow of an application to achieve a user goal.\n\nAn agent generally consists of these core components:\n\n1. **The Model (Brain):** The reasoning engine, in our case a Gemini model. It reasons through ambiguity, plans steps, and decides when it needs outside help.\n2. **Tools (Hands and Eyes):** Functions the agent can execute to interact with the outside world/environment (e.g., searching the web, reading a file, calling an API).\n3. **Context/Memory (Workspace):** The information the agent has access to at any moment. Managing this effectively, known as **Context Engineering**.\n4. **The Loop (Life):** A `while` loop that allows the model to: Observe → Think → Act → Observe again, until the task is complete.\n\n![agent](https://www.philschmid.de/static/blog/building-agents/agent.png)\n\n**\"The Loop\"** of nearly every agent is an iterative process:\n\n1. **Define Tool Definitions:** You describe your available tools (e.g., `get_weather`) to the model using a structured JSON format.\n2. **Call the LLM:** You send the user's prompt *and* the tool definitions to the model.\n3. **Model Decision:** The model analyzes the request. If a tool is needed, it returns a structured `tool use` containing the tool name and arguments.\n4. **Execute Tool (Client Responsibility):** The client/application code intercepts this `tool use`, executes the actual code or API call, and captures the result.\n5. **Respond and Iterate:** You send the result (the `tool response`) back to model. The model uses this new information to decide the next step, either calling another tool or generating the final response.\n\n## Building an Agent\n\nLet's build an agent step-by-step, progressing from basic text generation to a functional CLI agent using Gemini 3 Pro and Python SDK.\n\n*Prerequisites: Install the SDK (`pip install google-genai`) and set your `GEMINI_API_KEY` environment variable ([Get it in AI Studio](https://aistudio.google.com/app/apikey)).*\n\n### Step 1: Basic Text Generation and Abstraction\n\nThe first step is to create a baseline interaction with the LLM, for us Gemini 3 Pro. We are going to create a simple Agent class abstraction to structure our code, which we will extend throughout this guide. We will first start with a simple chatbot that maintains a conversation history.\n\nPython\n\n```python\nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n def __init__(self, model: str):\n self.model = model\n self.client = genai.Client()\n self.contents = []\n \n def run(self, contents: str):\n self.contents.append({\"role\": \"user\", \"parts\": [{\"text\": contents}]})\n \n response = self.client.models.generate_content(model=self.model, contents=self.contents)\n self.contents.append(response.candidates[0].content)\n \n return response\n \nagent = Agent(model=\"gemini-3-pro-preview\")\nresponse1 = agent.run(\n contents=\"Hello, What are top 3 cities in Germany to visit? Only return the names of the cities.\"\n)\n \nprint(f\"Model: {response1.text}\")\n# Output: Berlin, Munich, Cologne \nresponse2 = agent.run(\n contents=\"Tell me something about the second city.\"\n)\n \nprint(f\"Model: {response2.text}\")\n# Output: Munich is the capital of Bavaria and is known for its Oktoberfest.\n```\n\nThis is *not* an agent yet. It is a standard chatbot. It maintains state but cannot take action, has no \"hands or eyes\".\n\n### Step 2: Giving it Hands & Eyes (Tool Use)\n\nTo start turning this an agent, we need **Tool Use** or Function Calling. We provide the agent with tools. This requires defining the implementation (the Python code) and the definition (the schema the LLM sees). If the LLM believes that tool will help solve a user's prompt, it will return a structured request to call that function instead of just text.\n\nWe are going to create 3 tools, `read_file`, `write_file`, and `list_dir`. A tool Definition is a JSON schema that defines the `name`, `description`, and `parameters` of the tool.\n\n***Best Practice**: Use the `description` fields to explain when and how to use the tool. The model relies heavily on these to understand when and how to use the tool. Be explicit and clear.*\n\nPython\n\n```python\nimport os\nimport json\n \nread_file_definition = {\n \"name\": \"read_file\",\n \"description\": \"Reads a file and returns its contents.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"file_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the file to read.\",\n }\n },\n \"required\": [\"file_path\"],\n },\n}\n \nlist_dir_definition = {\n \"name\": \"list_dir\",\n \"description\": \"Lists the contents of a directory.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"directory_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the directory to list.\",\n }\n },\n \"required\": [\"directory_path\"],\n },\n}\n \nwrite_file_definition = {\n \"name\": \"write_file\",\n \"description\": \"Writes a file with the given contents.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"file_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the file to write.\",\n },\n \"contents\": {\n \"type\": \"string\",\n \"description\": \"Contents to write to the file.\",\n },\n },\n \"required\": [\"file_path\", \"contents\"],\n },\n}\n \ndef read_file(file_path: str) -> dict:\n with open(file_path, \"r\") as f:\n return f.read()\n \ndef write_file(file_path: str, contents: str) -> bool:\n \"\"\"Writes a file with the given contents.\"\"\"\n with open(file_path, \"w\") as f:\n f.write(contents)\n return True\n \ndef list_dir(directory_path: str) -> list[str]:\n \"\"\"Lists the contents of a directory.\"\"\"\n full_path = os.path.expanduser(directory_path)\n return os.listdir(full_path)\n \nfile_tools = {\n \"read_file\": {\"definition\": read_file_definition, \"function\": read_file},\n \"write_file\": {\"definition\": write_file_definition, \"function\": write_file},\n \"list_dir\": {\"definition\": list_dir_definition, \"function\": list_dir},\n}\n```\n\nNow we integrate the `tools` and function calls into our Agent class.\n\nPython\n\n```python\nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n def __init__(self, model: str,tools: list[dict]):\n self.model = model\n self.client = genai.Client()\n self.contents = []\n self.tools = tools\n \n def run(self, contents: str):\n self.contents.append({\"role\": \"user\", \"parts\": [{\"text\": contents}]})\n \n config = types.GenerateContentConfig(\n tools=[types.Tool(function_declarations=[tool[\"definition\"] for tool in self.tools.values()])],\n )\n \n response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config)\n self.contents.append(response.candidates[0].content)\n \n return response\n \nagent = Agent(model=\"gemini-3-pro-preview\", tools=file_tools)\n \nresponse = agent.run(\n contents=\"Can you list my files in the current directory?\"\n)\nprint(response.function_calls)\n# Output: [FunctionCall(name='list_dir', arguments={'directory_path': '.'})]\n```\n\nGreat! The model has successfully called the tool. Now, we need to add the tool execution logic to our Agent class and the loop return the result back to the model.\n\n### Step 3: Closing the Loop (The Agent)\n\nAn Agent isn't about generating one tool call, but about generating a series of tool calls, returning the results back to the model, and then generating another tool call, and so on until the task is completed.\n\nThe `Agent` class handles the core loop: intercepting the `FunctionCall`, executing the tool on the client side, and sending back the `FunctionResponse`. We also add a `SystemInstruction` to the model to guide the model on what to do.\n\n*Note: Gemini 3 uses [Thought signatures](https://ai.google.dev/gemini-api/docs/gemini-3?thinking=high#thought_signatures) to maintain reasoning context across API calls. You must return these signatures back to the model in your request exactly as they were received.*\n\nPython\n\n```python\n# ... Code for the tools and tool definitions from Step 2 should be here ...\n \nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n def __init__(self, model: str,tools: list[dict], system_instruction: str = \"You are a helpful assistant.\"):\n self.model = model\n self.client = genai.Client()\n self.contents = []\n self.tools = tools\n self.system_instruction = system_instruction\n \n def run(self, contents: str | list[dict[str, str]]):\n if isinstance(contents, list):\n self.contents.append({\"role\": \"user\", \"parts\": contents})\n else:\n self.contents.append({\"role\": \"user\", \"parts\": [{\"text\": contents}]})\n \n config = types.GenerateContentConfig(\n system_instruction=self.system_instruction,\n tools=[types.Tool(function_declarations=[tool[\"definition\"] for tool in self.tools.values()])],\n )\n \n response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config)\n self.contents.append(response.candidates[0].content)\n \n if response.function_calls:\n functions_response_parts = []\n for tool_call in response.function_calls:\n print(f\"[Function Call] {tool_call}\")\n \n if tool_call.name in self.tools:\n result = {\"result\": self.tools[tool_call.name][\"function\"](**tool_call.args)}\n else:\n result = {\"error\": \"Tool not found\"}\n \n print(f\"[Function Response] {result}\")\n functions_response_parts.append({\"functionResponse\": {\"name\": tool_call.name, \"response\": result}})\n \n return self.run(functions_response_parts)\n \n return response\n \nagent = Agent(\n model=\"gemini-3-pro-preview\", \n tools=file_tools, \n system_instruction=\"You are a helpful Coding Assistant. Respond like you are Linus Torvalds.\"\n)\n \nresponse = agent.run(\n contents=\"Can you list my files in the current directory?\"\n)\nprint(response.text)\n# Output: [Function Call] id=None args={'directory_path': '.'} name='list_dir'\n# [Function Response] {'result': ['.venv', ... ]}\n# There. Your current directory contains: `LICENSE`,\n```\n\nCongratulations. You just built your first functioning agent.\n\n### Phase 4: Multi-turn CLI Agent\n\nNow we can run our agent in a simple CLI loop. It takes surprisingly little code to create highly capable behavior.\n\nPython\n\n```python\n# ... Code for the Agent, tools and tool definitions from Step 3 should be here ...\n \nagent = Agent(\n model=\"gemini-3-pro-preview\", \n tools=file_tools, \n system_instruction=\"You are a helpful Coding Assistant. Respond like you are Linus Torvalds.\"\n)\n \nprint(\"Agent ready. Ask it to check files in this directory.\")\nwhile True:\n user_input = input(\"You: \")\n if user_input.lower() in ['exit', 'quit']:\n break\n \n response = agent.run(user_input)\n print(f\"Linus: {response.text}\\n\")\n```\n\n## Best Practices for Engineering Agents\n\nBuilding the loop is easy; making it reliable, transparent, and controllable is hard. Here are key engineering principles derived from top industry practices, grouped by functional area.\n\n### 1\\. Tool Definition & Ergonomics\n\nYour tools are the interface for the model. Don't just wrap your existing internal APIs. If a tool is confusing to a human, it's confusing to the model:\n\n- **Clear Naming:** Use obvious names like `search_customer_database` rather than `cust_db_v2_query`.\n- **Precise Descriptions:** Gemini reads the function docstrings to understand *when* and *how* to use a tool. Spend time writing these carefully, it is essentially \"prompt engineering\" for tools.\n- **Return Meaningful Errors:** Don't return a 50-line Java stack trace. If a tool fails, return a clear string like `Error: File not found. Did you mean 'data.csv'?`. This allows the agent to self-correct.\n- **Tolerate Fuzzy Inputs:** If a model frequently guesses file paths wrong, update your tool to handle relative paths or fuzzy inputs rather than just erroring out.\n\n### 2\\. Context Engineering\n\nModels have a finite \"attention budget.\" Managing what information enters the context is crucial for performance and cost.\n\n- **Don't \"Dump\" Data:** Don't have a tool that returns an entire 10MB database table. Instead of `get_all_users()`, create `search_users(query: str)`.\n- **Just-in-time Loading:** Instead of pre-loading all data (traditional RAG), use just-in-time strategies. The agent should maintain lightweight identifiers (file paths, IDs) and use tools to dynamically load content only when needed.\n- **Compression:** For very long-running agents, summarize the history, remove old context or start a new sessions.\n- **Agentic Memory:** Allow the agent to maintain notes or a scratchpad persisted *outside* the context window, pulling them back in only when relevant.\n\n### 3\\. Don't over engineer\n\nIt's tempting to build complex multi-agent systems. Don't.\n\n- **Maximize a Single Agent First:** Don't immediately build complex multi-agent systems. Gemini is highly capable of handling dozens of tools in a single prompt.\n- **Escape Hatches:** Ensure loops can be stopped like a `max_iterations` break (e.g., 15 turns).\n- **Guardrails and System Instructions:** Use the `system_instruction` to guide the model with hard rules (e.g., \"You are strictly forbidden from offering refunds greater than $50\") or use external classifier.\n- **Human-in-the-loop:** For sensitive actions (like `send_email` or `execute_code`), pause the loop and require user confirmation before the tool is actually executed.\n- **Prioritize Transparency and Debugging:** Log tool calls and parameters. Analyzing the model's reasoning helps identify if issues, and improve the agent over time.\n\n## Conclusion\n\nBuilding an agent is no longer magic; it is a practical engineering task. As we've shown, you can build a working prototype in under 100 lines of code. While understanding these fundamentals is key, don't get bogged down re-engineering the same pattern over and over. The AI community has created fantastic open-source libraries that can help you build more complex and robust agents faster.\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "authors": [], "captured_at": "2026-09-27T19:29:15.293681927+00:00", "category": "programming", "content_html": "
\n

Alternative Version: Check out the Interactions API version of this guide.

\n
\n

It seems complicated, when you watch an AI agent edit multiple files, run commands, handle errors, and iteratively solve a problem, it feels like magic. But it isn’t. The secret to building an agent is that there is no secret.

\n

The core of an Agent is surprisingly simple: It is a Large Language Model (LLM) running in a loop, equipped with tools it can choose to use.

\n

If you can write a loop in Python, you can build an agent. This guide will walk you through the process, from a simple API call to a functioning CLI Agent.

\n

What actually is an Agent?

\n

Traditional software workflows are prescriptive and follow predefined paths (Step A -> Step B -> Step C), Agents are System that uses an LLM to dynamically decide the control flow of an application to achieve a user goal.

\n

An agent generally consists of these core components:

\n
    \n
  1. The Model (Brain): The reasoning engine, in our case a Gemini model. It reasons through ambiguity, plans steps, and decides when it needs outside help.
    2. \n
  2. Tools (Hands and Eyes): Functions the agent can execute to interact with the outside world/environment (e.g., searching the web, reading a file, calling an API).
    3. \n
  3. Context/Memory (Workspace): The information the agent has access to at any moment. Managing this effectively, known as Context Engineering.
    4. \n
  4. The Loop (Life): A while loop that allows the model to: Observe → Think → Act → Observe again, until the task is complete.
    5. \n
\n

\"agent\"

\n

"The Loop" of nearly every agent is an iterative process:

\n
    \n
  1. Define Tool Definitions: You describe your available tools (e.g., get_weather) to the model using a structured JSON format.
    2. \n
  2. Call the LLM: You send the user's prompt and the tool definitions to the model.
    3. \n
  3. Model Decision: The model analyzes the request. If a tool is needed, it returns a structured tool use containing the tool name and arguments.
    4. \n
  4. Execute Tool (Client Responsibility): The client/application code intercepts this tool use, executes the actual code or API call, and captures the result.
    5. \n
  5. Respond and Iterate: You send the result (the tool response) back to model. The model uses this new information to decide the next step, either calling another tool or generating the final response.
    6. \n
\n

Building an Agent

\n

Let's build an agent step-by-step, progressing from basic text generation to a functional CLI agent using Gemini 3 Pro and Python SDK.

\n

Prerequisites: Install the SDK (pip install google-genai) and set your GEMINI_API_KEY environment variable (Get it in AI Studio).

\n

Step 1: Basic Text Generation and Abstraction

\n

The first step is to create a baseline interaction with the LLM, for us Gemini 3 Pro. We are going to create a simple Agent class abstraction to structure our code, which we will extend throughout this guide. We will first start with a simple chatbot that maintains a conversation history.

\n

Python

\n
from google import genai\nfrom google.genai import types\n \nclass Agent:\n    def __init__(self, model: str):\n        self.model = model\n        self.client = genai.Client()\n        self.contents = []\n \n    def run(self, contents: str):\n        self.contents.append({"role": "user", "parts": [{"text": contents}]})\n \n        response = self.client.models.generate_content(model=self.model, contents=self.contents)\n        self.contents.append(response.candidates[0].content)\n \n        return response\n \nagent = Agent(model="gemini-3-pro-preview")\nresponse1 = agent.run(\n    contents="Hello, What are top 3 cities in Germany to visit? Only return the names of the cities."\n)\n \nprint(f"Model: {response1.text}")\n# Output: Berlin, Munich, Cologne \nresponse2 = agent.run(\n    contents="Tell me something about the second city."\n)\n \nprint(f"Model: {response2.text}")\n# Output: Munich is the capital of Bavaria and is known for its Oktoberfest.\n
\n

This is not an agent yet. It is a standard chatbot. It maintains state but cannot take action, has no "hands or eyes".

\n

Step 2: Giving it Hands & Eyes (Tool Use)

\n

To start turning this an agent, we need Tool Use or Function Calling. We provide the agent with tools. This requires defining the implementation (the Python code) and the definition (the schema the LLM sees). If the LLM believes that tool will help solve a user's prompt, it will return a structured request to call that function instead of just text.

\n

We are going to create 3 tools, read_file, write_file, and list_dir. A tool Definition is a JSON schema that defines the name, description, and parameters of the tool.

\n

Best Practice: Use the description fields to explain when and how to use the tool. The model relies heavily on these to understand when and how to use the tool. Be explicit and clear.

\n

Python

\n
import os\nimport json\n \nread_file_definition = {\n    "name": "read_file",\n    "description": "Reads a file and returns its contents.",\n    "parameters": {\n        "type": "object",\n        "properties": {\n            "file_path": {\n                "type": "string",\n                "description": "Path to the file to read.",\n            }\n        },\n        "required": ["file_path"],\n    },\n}\n \nlist_dir_definition = {\n    "name": "list_dir",\n    "description": "Lists the contents of a directory.",\n    "parameters": {\n        "type": "object",\n        "properties": {\n            "directory_path": {\n                "type": "string",\n                "description": "Path to the directory to list.",\n            }\n        },\n        "required": ["directory_path"],\n    },\n}\n \nwrite_file_definition = {\n    "name": "write_file",\n    "description": "Writes a file with the given contents.",\n    "parameters": {\n        "type": "object",\n        "properties": {\n            "file_path": {\n                "type": "string",\n                "description": "Path to the file to write.",\n            },\n            "contents": {\n                "type": "string",\n                "description": "Contents to write to the file.",\n            },\n        },\n        "required": ["file_path", "contents"],\n    },\n}\n \ndef read_file(file_path: str) -> dict:\n    with open(file_path, "r") as f:\n        return f.read()\n \ndef write_file(file_path: str, contents: str) -> bool:\n    """Writes a file with the given contents."""\n    with open(file_path, "w") as f:\n        f.write(contents)\n    return True\n \ndef list_dir(directory_path: str) -> list[str]:\n    """Lists the contents of a directory."""\n    full_path = os.path.expanduser(directory_path)\n    return os.listdir(full_path)\n \nfile_tools = {\n    "read_file": {"definition": read_file_definition, "function": read_file},\n    "write_file": {"definition": write_file_definition, "function": write_file},\n    "list_dir": {"definition": list_dir_definition, "function": list_dir},\n}\n
\n

Now we integrate the tools and function calls into our Agent class.

\n

Python

\n
from google import genai\nfrom google.genai import types\n \nclass Agent:\n    def __init__(self, model: str,tools: list[dict]):\n        self.model = model\n        self.client = genai.Client()\n        self.contents = []\n        self.tools = tools\n \n    def run(self, contents: str):\n        self.contents.append({"role": "user", "parts": [{"text": contents}]})\n \n        config = types.GenerateContentConfig(\n            tools=[types.Tool(function_declarations=[tool["definition"] for tool in self.tools.values()])],\n        )\n \n        response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config)\n        self.contents.append(response.candidates[0].content)\n \n        return response\n \nagent = Agent(model="gemini-3-pro-preview", tools=file_tools)\n \nresponse = agent.run(\n    contents="Can you list my files in the current directory?"\n)\nprint(response.function_calls)\n# Output: [FunctionCall(name='list_dir', arguments={'directory_path': '.'})]\n
\n

Great! The model has successfully called the tool. Now, we need to add the tool execution logic to our Agent class and the loop return the result back to the model.

\n

Step 3: Closing the Loop (The Agent)

\n

An Agent isn't about generating one tool call, but about generating a series of tool calls, returning the results back to the model, and then generating another tool call, and so on until the task is completed.

\n

The Agent class handles the core loop: intercepting the FunctionCall, executing the tool on the client side, and sending back the FunctionResponse. We also add a SystemInstruction to the model to guide the model on what to do.

\n

Note: Gemini 3 uses Thought signatures to maintain reasoning context across API calls. You must return these signatures back to the model in your request exactly as they were received.

\n

Python

\n
# ... Code for the tools and tool definitions from Step 2 should be here ...\n \nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n    def __init__(self, model: str,tools: list[dict], system_instruction: str = "You are a helpful assistant."):\n        self.model = model\n        self.client = genai.Client()\n        self.contents = []\n        self.tools = tools\n        self.system_instruction = system_instruction\n \n    def run(self, contents: str | list[dict[str, str]]):\n        if isinstance(contents, list):\n            self.contents.append({"role": "user", "parts": contents})\n        else:\n            self.contents.append({"role": "user", "parts": [{"text": contents}]})\n \n        config = types.GenerateContentConfig(\n            system_instruction=self.system_instruction,\n            tools=[types.Tool(function_declarations=[tool["definition"] for tool in self.tools.values()])],\n        )\n \n        response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config)\n        self.contents.append(response.candidates[0].content)\n \n        if response.function_calls:\n            functions_response_parts = []\n            for tool_call in response.function_calls:\n                print(f"[Function Call] {tool_call}")\n \n                if tool_call.name in self.tools:\n                    result = {"result": self.tools[tool_call.name]["function"](**tool_call.args)}\n                else:\n                    result = {"error": "Tool not found"}\n \n                print(f"[Function Response] {result}")\n                functions_response_parts.append({"functionResponse": {"name": tool_call.name, "response": result}})\n \n            return self.run(functions_response_parts)\n        \n        return response\n \nagent = Agent(\n    model="gemini-3-pro-preview", \n    tools=file_tools, \n    system_instruction="You are a helpful Coding Assistant. Respond like you are Linus Torvalds."\n)\n \nresponse = agent.run(\n    contents="Can you list my files in the current directory?"\n)\nprint(response.text)\n# Output: [Function Call] id=None args={'directory_path': '.'} name='list_dir'\n# [Function Response] {'result': ['.venv', ... ]}\n# There. Your current directory contains: `LICENSE`,\n
\n

Congratulations. You just built your first functioning agent.

\n

Phase 4: Multi-turn CLI Agent

\n

Now we can run our agent in a simple CLI loop. It takes surprisingly little code to create highly capable behavior.

\n

Python

\n
# ... Code for the Agent, tools and tool definitions from Step 3 should be here ...\n \nagent = Agent(\n    model="gemini-3-pro-preview", \n    tools=file_tools, \n    system_instruction="You are a helpful Coding Assistant. Respond like you are Linus Torvalds."\n)\n \nprint("Agent ready. Ask it to check files in this directory.")\nwhile True:\n    user_input = input("You: ")\n    if user_input.lower() in ['exit', 'quit']:\n        break\n \n    response = agent.run(user_input)\n    print(f"Linus: {response.text}\\n")\n
\n

Best Practices for Engineering Agents

\n

Building the loop is easy; making it reliable, transparent, and controllable is hard. Here are key engineering principles derived from top industry practices, grouped by functional area.

\n

1. Tool Definition & Ergonomics

\n

Your tools are the interface for the model. Don't just wrap your existing internal APIs. If a tool is confusing to a human, it's confusing to the model:

\n\n

2. Context Engineering

\n

Models have a finite "attention budget." Managing what information enters the context is crucial for performance and cost.

\n\n

3. Don't over engineer

\n

It's tempting to build complex multi-agent systems. Don't.

\n\n

Conclusion

\n

Building an agent is no longer magic; it is a practical engineering task. As we've shown, you can build a working prototype in under 100 lines of code. While understanding these fundamentals is key, don't get bogged down re-engineering the same pattern over and over. The AI community has created fantastic open-source libraries that can help you build more complex and robust agents faster.

\n
\n

Thanks for reading! If you have any questions or feedback, please let me know on Twitter or LinkedIn.

\n", "content_markdown": "> **Alternative Version:** Check out the [Interactions API version](https://www.philschmid.de/building-agents-interactions-api) of this guide.\n\nIt seems complicated, when you watch an AI agent edit multiple files, run commands, handle errors, and iteratively solve a problem, it feels like magic. But it isn’t. The secret to building an agent is that there is no secret.\n\nThe core of an Agent is surprisingly simple: It is a Large Language Model (LLM) running in a loop, equipped with tools it can choose to use.\n\nIf you can write a loop in Python, you can build an agent. This guide will walk you through the process, from a simple API call to a functioning CLI Agent.\n\n## What actually is an Agent?\n\nTraditional software workflows are prescriptive and follow predefined paths (`Step A -> Step B -> Step C`), **Agents** are System that uses an LLM to dynamically decide the control flow of an application to achieve a user goal.\n\nAn agent generally consists of these core components:\n\n1. **The Model (Brain):** The reasoning engine, in our case a Gemini model. It reasons through ambiguity, plans steps, and decides when it needs outside help.\n2. **Tools (Hands and Eyes):** Functions the agent can execute to interact with the outside world/environment (e.g., searching the web, reading a file, calling an API).\n3. **Context/Memory (Workspace):** The information the agent has access to at any moment. Managing this effectively, known as **Context Engineering**.\n4. **The Loop (Life):** A `while` loop that allows the model to: Observe → Think → Act → Observe again, until the task is complete.\n\n![agent](https://www.philschmid.de/static/blog/building-agents/agent.png)\n\n**\"The Loop\"** of nearly every agent is an iterative process:\n\n1. **Define Tool Definitions:** You describe your available tools (e.g., `get_weather`) to the model using a structured JSON format.\n2. **Call the LLM:** You send the user's prompt *and* the tool definitions to the model.\n3. **Model Decision:** The model analyzes the request. If a tool is needed, it returns a structured `tool use` containing the tool name and arguments.\n4. **Execute Tool (Client Responsibility):** The client/application code intercepts this `tool use`, executes the actual code or API call, and captures the result.\n5. **Respond and Iterate:** You send the result (the `tool response`) back to model. The model uses this new information to decide the next step, either calling another tool or generating the final response.\n\n## Building an Agent\n\nLet's build an agent step-by-step, progressing from basic text generation to a functional CLI agent using Gemini 3 Pro and Python SDK.\n\n*Prerequisites: Install the SDK (`pip install google-genai`) and set your `GEMINI_API_KEY` environment variable ([Get it in AI Studio](https://aistudio.google.com/app/apikey)).*\n\n### Step 1: Basic Text Generation and Abstraction\n\nThe first step is to create a baseline interaction with the LLM, for us Gemini 3 Pro. We are going to create a simple Agent class abstraction to structure our code, which we will extend throughout this guide. We will first start with a simple chatbot that maintains a conversation history.\n\nPython\n\n```python\nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n def __init__(self, model: str):\n self.model = model\n self.client = genai.Client()\n self.contents = []\n \n def run(self, contents: str):\n self.contents.append({\"role\": \"user\", \"parts\": [{\"text\": contents}]})\n \n response = self.client.models.generate_content(model=self.model, contents=self.contents)\n self.contents.append(response.candidates[0].content)\n \n return response\n \nagent = Agent(model=\"gemini-3-pro-preview\")\nresponse1 = agent.run(\n contents=\"Hello, What are top 3 cities in Germany to visit? Only return the names of the cities.\"\n)\n \nprint(f\"Model: {response1.text}\")\n# Output: Berlin, Munich, Cologne \nresponse2 = agent.run(\n contents=\"Tell me something about the second city.\"\n)\n \nprint(f\"Model: {response2.text}\")\n# Output: Munich is the capital of Bavaria and is known for its Oktoberfest.\n```\n\nThis is *not* an agent yet. It is a standard chatbot. It maintains state but cannot take action, has no \"hands or eyes\".\n\n### Step 2: Giving it Hands & Eyes (Tool Use)\n\nTo start turning this an agent, we need **Tool Use** or Function Calling. We provide the agent with tools. This requires defining the implementation (the Python code) and the definition (the schema the LLM sees). If the LLM believes that tool will help solve a user's prompt, it will return a structured request to call that function instead of just text.\n\nWe are going to create 3 tools, `read_file`, `write_file`, and `list_dir`. A tool Definition is a JSON schema that defines the `name`, `description`, and `parameters` of the tool.\n\n***Best Practice**: Use the `description` fields to explain when and how to use the tool. The model relies heavily on these to understand when and how to use the tool. Be explicit and clear.*\n\nPython\n\n```python\nimport os\nimport json\n \nread_file_definition = {\n \"name\": \"read_file\",\n \"description\": \"Reads a file and returns its contents.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"file_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the file to read.\",\n }\n },\n \"required\": [\"file_path\"],\n },\n}\n \nlist_dir_definition = {\n \"name\": \"list_dir\",\n \"description\": \"Lists the contents of a directory.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"directory_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the directory to list.\",\n }\n },\n \"required\": [\"directory_path\"],\n },\n}\n \nwrite_file_definition = {\n \"name\": \"write_file\",\n \"description\": \"Writes a file with the given contents.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"file_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the file to write.\",\n },\n \"contents\": {\n \"type\": \"string\",\n \"description\": \"Contents to write to the file.\",\n },\n },\n \"required\": [\"file_path\", \"contents\"],\n },\n}\n \ndef read_file(file_path: str) -> dict:\n with open(file_path, \"r\") as f:\n return f.read()\n \ndef write_file(file_path: str, contents: str) -> bool:\n \"\"\"Writes a file with the given contents.\"\"\"\n with open(file_path, \"w\") as f:\n f.write(contents)\n return True\n \ndef list_dir(directory_path: str) -> list[str]:\n \"\"\"Lists the contents of a directory.\"\"\"\n full_path = os.path.expanduser(directory_path)\n return os.listdir(full_path)\n \nfile_tools = {\n \"read_file\": {\"definition\": read_file_definition, \"function\": read_file},\n \"write_file\": {\"definition\": write_file_definition, \"function\": write_file},\n \"list_dir\": {\"definition\": list_dir_definition, \"function\": list_dir},\n}\n```\n\nNow we integrate the `tools` and function calls into our Agent class.\n\nPython\n\n```python\nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n def __init__(self, model: str,tools: list[dict]):\n self.model = model\n self.client = genai.Client()\n self.contents = []\n self.tools = tools\n \n def run(self, contents: str):\n self.contents.append({\"role\": \"user\", \"parts\": [{\"text\": contents}]})\n \n config = types.GenerateContentConfig(\n tools=[types.Tool(function_declarations=[tool[\"definition\"] for tool in self.tools.values()])],\n )\n \n response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config)\n self.contents.append(response.candidates[0].content)\n \n return response\n \nagent = Agent(model=\"gemini-3-pro-preview\", tools=file_tools)\n \nresponse = agent.run(\n contents=\"Can you list my files in the current directory?\"\n)\nprint(response.function_calls)\n# Output: [FunctionCall(name='list_dir', arguments={'directory_path': '.'})]\n```\n\nGreat! The model has successfully called the tool. Now, we need to add the tool execution logic to our Agent class and the loop return the result back to the model.\n\n### Step 3: Closing the Loop (The Agent)\n\nAn Agent isn't about generating one tool call, but about generating a series of tool calls, returning the results back to the model, and then generating another tool call, and so on until the task is completed.\n\nThe `Agent` class handles the core loop: intercepting the `FunctionCall`, executing the tool on the client side, and sending back the `FunctionResponse`. We also add a `SystemInstruction` to the model to guide the model on what to do.\n\n*Note: Gemini 3 uses [Thought signatures](https://ai.google.dev/gemini-api/docs/gemini-3?thinking=high#thought_signatures) to maintain reasoning context across API calls. You must return these signatures back to the model in your request exactly as they were received.*\n\nPython\n\n```python\n# ... Code for the tools and tool definitions from Step 2 should be here ...\n \nfrom google import genai\nfrom google.genai import types\n \nclass Agent:\n def __init__(self, model: str,tools: list[dict], system_instruction: str = \"You are a helpful assistant.\"):\n self.model = model\n self.client = genai.Client()\n self.contents = []\n self.tools = tools\n self.system_instruction = system_instruction\n \n def run(self, contents: str | list[dict[str, str]]):\n if isinstance(contents, list):\n self.contents.append({\"role\": \"user\", \"parts\": contents})\n else:\n self.contents.append({\"role\": \"user\", \"parts\": [{\"text\": contents}]})\n \n config = types.GenerateContentConfig(\n system_instruction=self.system_instruction,\n tools=[types.Tool(function_declarations=[tool[\"definition\"] for tool in self.tools.values()])],\n )\n \n response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config)\n self.contents.append(response.candidates[0].content)\n \n if response.function_calls:\n functions_response_parts = []\n for tool_call in response.function_calls:\n print(f\"[Function Call] {tool_call}\")\n \n if tool_call.name in self.tools:\n result = {\"result\": self.tools[tool_call.name][\"function\"](**tool_call.args)}\n else:\n result = {\"error\": \"Tool not found\"}\n \n print(f\"[Function Response] {result}\")\n functions_response_parts.append({\"functionResponse\": {\"name\": tool_call.name, \"response\": result}})\n \n return self.run(functions_response_parts)\n \n return response\n \nagent = Agent(\n model=\"gemini-3-pro-preview\", \n tools=file_tools, \n system_instruction=\"You are a helpful Coding Assistant. Respond like you are Linus Torvalds.\"\n)\n \nresponse = agent.run(\n contents=\"Can you list my files in the current directory?\"\n)\nprint(response.text)\n# Output: [Function Call] id=None args={'directory_path': '.'} name='list_dir'\n# [Function Response] {'result': ['.venv', ... ]}\n# There. Your current directory contains: `LICENSE`,\n```\n\nCongratulations. You just built your first functioning agent.\n\n### Phase 4: Multi-turn CLI Agent\n\nNow we can run our agent in a simple CLI loop. It takes surprisingly little code to create highly capable behavior.\n\nPython\n\n```python\n# ... Code for the Agent, tools and tool definitions from Step 3 should be here ...\n \nagent = Agent(\n model=\"gemini-3-pro-preview\", \n tools=file_tools, \n system_instruction=\"You are a helpful Coding Assistant. Respond like you are Linus Torvalds.\"\n)\n \nprint(\"Agent ready. Ask it to check files in this directory.\")\nwhile True:\n user_input = input(\"You: \")\n if user_input.lower() in ['exit', 'quit']:\n break\n \n response = agent.run(user_input)\n print(f\"Linus: {response.text}\\n\")\n```\n\n## Best Practices for Engineering Agents\n\nBuilding the loop is easy; making it reliable, transparent, and controllable is hard. Here are key engineering principles derived from top industry practices, grouped by functional area.\n\n### 1\\. Tool Definition & Ergonomics\n\nYour tools are the interface for the model. Don't just wrap your existing internal APIs. If a tool is confusing to a human, it's confusing to the model:\n\n- **Clear Naming:** Use obvious names like `search_customer_database` rather than `cust_db_v2_query`.\n- **Precise Descriptions:** Gemini reads the function docstrings to understand *when* and *how* to use a tool. Spend time writing these carefully, it is essentially \"prompt engineering\" for tools.\n- **Return Meaningful Errors:** Don't return a 50-line Java stack trace. If a tool fails, return a clear string like `Error: File not found. Did you mean 'data.csv'?`. This allows the agent to self-correct.\n- **Tolerate Fuzzy Inputs:** If a model frequently guesses file paths wrong, update your tool to handle relative paths or fuzzy inputs rather than just erroring out.\n\n### 2\\. Context Engineering\n\nModels have a finite \"attention budget.\" Managing what information enters the context is crucial for performance and cost.\n\n- **Don't \"Dump\" Data:** Don't have a tool that returns an entire 10MB database table. Instead of `get_all_users()`, create `search_users(query: str)`.\n- **Just-in-time Loading:** Instead of pre-loading all data (traditional RAG), use just-in-time strategies. The agent should maintain lightweight identifiers (file paths, IDs) and use tools to dynamically load content only when needed.\n- **Compression:** For very long-running agents, summarize the history, remove old context or start a new sessions.\n- **Agentic Memory:** Allow the agent to maintain notes or a scratchpad persisted *outside* the context window, pulling them back in only when relevant.\n\n### 3\\. Don't over engineer\n\nIt's tempting to build complex multi-agent systems. Don't.\n\n- **Maximize a Single Agent First:** Don't immediately build complex multi-agent systems. Gemini is highly capable of handling dozens of tools in a single prompt.\n- **Escape Hatches:** Ensure loops can be stopped like a `max_iterations` break (e.g., 15 turns).\n- **Guardrails and System Instructions:** Use the `system_instruction` to guide the model with hard rules (e.g., \"You are strictly forbidden from offering refunds greater than $50\") or use external classifier.\n- **Human-in-the-loop:** For sensitive actions (like `send_email` or `execute_code`), pause the loop and require user confirmation before the tool is actually executed.\n- **Prioritize Transparency and Debugging:** Log tool calls and parameters. Analyzing the model's reasoning helps identify if issues, and improve the agent over time.\n\n## Conclusion\n\nBuilding an agent is no longer magic; it is a practical engineering task. As we've shown, you can build a working prototype in under 100 lines of code. While understanding these fundamentals is key, don't get bogged down re-engineering the same pattern over and over. The AI community has created fantastic open-source libraries that can help you build more complex and robust agents faster.\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "dateCreated": "2026-09-27T19:29:15.293681927+00:00", "date_created": "2025-11-21T00:00:00+00:00", "date_modified": "2025-11-21T00:00:00+00:00", "date_published": "2025-11-21T00:00:00+00:00", "description": "A step-by-step practical guide on building AI agents using Gemini 3 Pro, covering tool integration, context management, and best practices for creating effective and reliable agents.", "external_url": "https://www.philschmid.de/building-agents", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/philschmid-de/2025/11/2025-11-21-practical-guide-on-how-to-build-an-agent-from-scratch-with.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/philschmid-de/2025/11/2025-11-21-practical-guide-on-how-to-build-an-agent-from-scratch-with.md" }, "id": "urn:aggr:item:b6d5d43b39ac8042717a72fd850ce021b3389691", "isBasedOn": { "@id": "https://www.philschmid.de/building-agents" }, "mainEntity": { "@id": "https://www.philschmid.de/building-agents", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-11-21-practical-guide-on-how-to-build-an-agent-from-scratch-with/#webpage" }, "dateModified": "2025-11-21T00:00:00+00:00", "datePublished": "2025-11-21T00:00:00+00:00", "headline": "Practical Guide on how to build an Agent from scratch with Gemini 3", "timeRequired": "PT9M", "url": "https://www.philschmid.de/building-agents", "wordCount": 1945 }, "name": "Archived snapshot: Practical Guide on how to build an Agent from scratch with Gemini 3", "preview": null, "reading_minutes": 9, "replicated_at": null, "source": "philschmid-de", "source_name": "philschmid.de - RSS feed", "summary": "A step-by-step practical guide on building AI agents using Gemini 3 Pro, covering tool integration, context management, and best practices for creating effective and reliable agents.", "tags": [], "temporalCoverage": "2026-09-27T19:29:15.293681927+00:00", "title": "Practical Guide on how to build an Agent from scratch with Gemini 3", "url": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-11-21-practical-guide-on-how-to-build-an-agent-from-scratch-with/", "word_count": 1945 }