DEV Community: Adarsh D

Introducing SerpApi’s Hermes Agent Plugin

Adarsh D — Wed, 29 Jul 2026 02:46:53 +0000

Hermes Agent is an open-source AI agent from Nous Research that can work from the terminal, desktop, and messaging platforms. You can learn more in the Hermes Agent documentation or explore its source code on GitHub.

Today, we are releasing the open-source SerpApi plugin for Hermes Agent. It connects Hermes's built-in web search to SerpApi and adds dedicated tools for local places, current news, and product research. The plugin is available now on PyPI.

What the Plugin Adds

Hermes already knows when it needs to search. The plugin gives it four SerpApi search paths to choose from:

What you ask for	Hermes tool	SerpApi engine
General web research	`web_search`	Google Light
Places and local businesses	`serpapi_maps_search`	Google Maps
Current and recent news	`serpapi_news_search`	Google News Light
Products, prices, and merchants	`serpapi_shopping_search`	Google Shopping Light

For a normal web query, Hermes continues to use its familiar web_search tool; the plugin supplies the SerpApi backend. For a local, news, or shopping request, Hermes can call the matching specialized tool. You can ask naturally without remembering an engine name or tool name.

Google Light is the default for general web search because its compact response and low latency are a good fit for agent workflows. The specialized tools keep the useful structured fields from their respective engines, such as addresses and ratings for places, publishers and dates for news, and prices and merchants for products.

Key Features

Native Hermes integration. The package uses Hermes's Python plugin and web-search provider interfaces. There is no separate server process to run.
Natural tool selection. Hermes chooses general web, Maps, News, or Shopping search from the user's request.
One API key. SERPAPI_API_KEY authenticates every search path in the plugin.
Focused responses. Each search path returns the fields Hermes needs instead of passing an entire raw search response into the agent's context.
Open source and pip-installable. The code is available on GitHub, and the package is distributed through PyPI.

Getting Started

You need a working Hermes Agent installation and a SerpApi account. If you are new to Hermes, follow its installation guide and quickstart first.

For complete step-by-step instructions, including custom Hermes installations and manual configuration, see the repository README.

Install it yourself

For a standard Hermes installation on macOS or Linux, install the package into Hermes's Python environment:

cd ~/.hermes/hermes-agent
uv pip install --python venv/bin/python serpapi-hermes-plugin
hermes plugins enable serpapi
hermes tools

Select SerpApi under Web Search & Extract , then enter the Private API Key from your SerpApi dashboard. Restart any Hermes session that was already running.

Let Hermes install it for you

You can also share our installation instructions with Hermes and let the agent install, enable, configure, and verify the plugin. Paste this into a Hermes chat:

Install and configure serpapi-hermes-plugin by following the instructions at:
https://github.com/serpapi/serpapi-hermes-plugin#ask-hermes-to-install-it

Approve the installation commands when Hermes prompts you, then provide your Private API Key. The ready-to-copy installation prompt in the README contains the full workflow and safety instructions.

Use and Test the Plugin in Hermes

Use case 1: Create a current AI news briefing

You can start with a prompt as short as:

Find latest AI news

In the example below, Hermes turns that request into several focused news searches. It broadens the query to cover major AI companies, chips, safety, and regulation, then uses its other browsing tools to inspect sources and prepare a dated briefing.

Hermes Agent conversation using SerpApi for the prompt: Find latest AI news.

Hermes uses SerpApi for discovery, then combines the search results with its other tools to check sources and write the final briefing. The stories shown in this example reflect the time of the search and will change.

For a more repeatable briefing, give Hermes a little more direction:

Find the latest AI news. Use multiple focused news searches, verify the leading stories against reputable or primary sources, and give me a concise dated briefing with source links.

This is where an agent-native search integration becomes useful: Hermes can run more than one query, refine its search as it learns, and organize the results around the task instead of returning a single page of links.

Use case 2: Find the best cafés across Paris

A local search can be just as simple:

Find best Cafes in Paris

Rather than treating the whole city as one search, Hermes can explore different neighborhoods and intents. In this example, it searches for specialty coffee and cafés in Le Marais, Saint-Germain-des-Prés, Montmartre, Canal Saint-Martin, and the Latin Quarter before compiling a shortlist.

Hermes Agent conversation using SerpApi for the prompt: Find best Cafes in Paris

The resulting shortlist brings together useful Google Maps details such as ratings, review counts, addresses, price levels, and map references. Local business data can change, so check the live results when planning a visit.

For a more specific recommendation, try:

Find the best cafés in Paris. Search specialty coffee and notable neighborhoods separately, then return a varied shortlist with ratings, review counts, addresses, price levels, and Google Maps links.

Hermes can make several focused serpapi_maps_search calls, compare the structured place results, and turn them into one useful answer.

More prompt ideas

Try these prompts for the remaining search paths:

Web: "Search the web for the latest Python 3.14 release notes and summarize the important changes with source links."
News: "Show me the most important reusable-rocket news from the past week. Group related coverage and cite the publishers."
Shopping: "Find well-reviewed laptops under $1,200 with free shipping. Compare prices, ratings, and merchants."

Together, these prompts also work as quick smoke tests after installation. Hermes should use web_search for general research and the dedicated Maps, News, and Shopping tools for their respective requests. Search results change over time, so verify the tool selected and the shape of the response rather than expecting the same listings on every run.

If Hermes does not find the plugin, check these three points:

The package was installed into the Python environment that runs Hermes.
serpapi is enabled in hermes plugins.
SERPAPI_API_KEY is available to the Hermes process and SerpApi is selected as the web search backend.

How It Works

The PyPI package publishes a hermes_agent.plugins entry point. When Hermes discovers and enables the package, the plugin:

Registers SerpApi as a web_search provider.
Registers separate Maps, News, and Shopping tools with schemas that describe their supported inputs.
Selects the corresponding SerpApi engine and validates the request.
Converts the API response into a compact, predictable result for Hermes.

This keeps the integration native to Hermes while preserving the structured search data that makes SerpApi useful for agent workflows.

What's Next

The SerpApi plugin for Hermes Agent is available now on PyPI, and its source code is open on GitHub.

If you find a bug or have an idea for another Hermes-native search capability, open an issue or pull request in the repository. If you have not tried SerpApi yet, create an account and give Hermes live search data in a few minutes.

Build Smarter Pydantic AI Agents with Real-Time Search

Adarsh D — Tue, 28 Jul 2026 07:56:25 +0000

Building AI agents in Python can quickly get messy. You need to manage prompts, models, tools, structured outputs, validation, dependencies, and external integrations. As the agent grows, the code can become harder to reason about, test, and maintain.

Pydantic AI helps solve that problem. This Python framework from the Pydantic team helps us build AI agents and generative AI applications with a clean, Pythonic developer experience. If you are already comfortable with Python type hints, Pydantic models, and function-based APIs, Pydantic AI will feel familiar.

Pydantic AI Landing Page

In this tutorial, we will start with the basics of Pydantic AI and then build toward a more practical agent that can use real-time search to answer questions with fresh, grounded information. We will start small and improve the agent step by step:

Start with a simple local model-backed agent.
Add a tool to fetch the current date and time.
Add SerpApi search so the agent can look up live information.
Package search behavior as a reusable Pydantic AI capability.
Connect the agent to SerpApi through MCP, giving the agent access to real-time search data.

Prefer watching instead? We also have a video version of this tutorial, where we walk through building a Pydantic AI agent with real-time search using SerpApi.

Watch the Video on YouTube

Why raw LLMs struggle with current facts

LLMs are trained on large amounts of data, but that training has a cutoff. The model does not automatically know today's date, the latest product releases, live prices, breaking news, or current hotel availability.

For example, a local model may give a confident answer when asked about a current product, price, policy, event, or travel detail. The answer may sound plausible because the model is continuing a pattern from its training data, but it is not grounded in live information. The model can sound confident even when it is hallucinating or relying on outdated information. It generates answers from patterns in its training data, but it does not automatically know whether those answers are still true. For time-sensitive questions, that makes live search essential.

For time-sensitive questions, the agent needs two things:

a way to understand the current date and time
a way to search live data before answering

This is where tools become useful.

In Pydantic AI, a tool is a Python function that the model can call. The model decides when it needs the function; Pydantic AI validates the arguments; runs the function; and the result is passed back to the model.

Project setup

For these examples, I am using:

Python 3.13+
Pydantic AI (pip install or uv add pydantic-ai-slim)
SerpApi (live API calls using httpx)
Qwen 3.6 35B running locally through LM Studio

The example agent scripts are available on our GitHub repo for you to test and play around with.

For the SerpApi examples below, I am using SERPAPI_API_KEY as the environment variable:

export SERPAPI_API_KEY="your_serpapi_api_key"

For the AI Model, I am using a locally running model so that the examples can be run without any API subscriptions, such as OpenAI or Anthropic. I am using the OpenAI-compatible endpoint exposed by LM Studio:

from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "qwen/qwen3.6-35b-a3b",
    provider=OpenAIProvider(base_url="http://localhost:1234/v1"),
)

LM Studio serving Qwen 3.6 model via local API

This gives us a local model while still using the OpenAI-compatible interface.

A simple Pydantic AI agent

Let's start with the smallest useful agent:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "qwen/qwen3.6-35b-a3b",
    provider=OpenAIProvider(base_url="http://localhost:1234/v1"),
)

agent = Agent(
    model,
    instructions=(
        "You are a helpful assistant. Help the user with their questions and requests. "
    ),
)

app = agent.to_web(models={"Qwen 3.6 35B (LM Studio)": model})

The agent.to_web() call creates a simple web chat UI for the agent. This is helpful while experimenting because we can ask a question and inspect how the model responds.

At this stage, the agent has no tools. It can only use the model's internal knowledge. If we ask:

What is the latest iPhone model?

The model may answer confidently, but there is no guarantee that the answer is current. The agent has no access to today's date, Apple's current product pages, live search results, or prices.

When I tested the example using the Chat UI, the model gave the below response:

The model responds that the latest iPhone lineup is the iPhone 18 series, which is unreleased as of this writing. The model's confusion can be seen when we go through its reasoning/thinking traces:

The model was confused and was guessing based on the iPhone's normal release schedule. Without tools, the model cannot access the current date/time. So the first improvement is to give it a clock.

Add a time tool

Some queries are time-sensitive even if they do not look like search queries.

Examples:

"What is the latest iPhone?"
"What happened yesterday?"
"Find hotels for next weekend."
"What are the best coding models right now?"

Before answering these, the model should know the current date.

We can expose a small Python function as a Pydantic AI tool:

from datetime import datetime

TIME_SENSITIVE_INSTRUCTION = (
    "Always call get_time before answering relative-date or time-sensitive queries."
)

agent = Agent(
    model,
    instructions=(
        "You are a helpful assistant. Help the user with their questions and requests. "
        f"{TIME_SENSITIVE_INSTRUCTION}"
    ),
)


@agent.tool_plain
def get_time() -> dict[str, str]:
    """Return the current local date and time."""
    now = datetime.now().astimezone()
    return {
        "date": now.date().isoformat(),
        "time": now.strftime("%H:%M:%S"),
        "day_of_week": now.strftime("%A"),
        "timezone": now.tzname() or str(now.tzinfo),
        "utc_offset": now.strftime("%z"),
        "iso_datetime": now.isoformat(timespec="seconds"),
    }

This is a small change, but it improves the agent's behavior. The model can now anchor relative-date questions to the current day instead of guessing. When the model sees a time-sensitive question, it can request a tool call, and Pydantic AI executes the get_time() function we defined and feeds back the result to the model.

Let's test this with the Web UI:

The model called the get_time tool and understands that the current month is July. Based on this info, it was able to correctly answer that the iPhone 17 series is the latest iPhone lineup.

However, time alone is not enough. The current date can tell the model that it should not rely only on training data, but it still needs a way to look up facts.

So the next step is search.

Add real-time search with SerpApi

SerpApi gives us structured search engine results through an API. Instead of scraping search result pages, we can call SerpApi and return a compact result set to the model.

Here is a simple search tool:

import os

import httpx


@agent.tool_plain
def search_serpapi(query: str) -> dict:
    """Search Google Light with SerpApi and return a compact result set."""
    params = {
        "engine": "google_light",
        "q": query,
        "api_key": os.environ["SERPAPI_API_KEY"],
        "num": 10,
    }
    response = httpx.get("https://serpapi.com/search.json", params=params, timeout=20)
    response.raise_for_status()
    data = response.json()

    return {
        "answer_box": data.get("answer_box"),
        "organic_results": [
            {
                "title": item.get("title"),
                "link": item.get("link"),
                "snippet": item.get("snippet"),
            }
            for item in data.get("organic_results", [])[:10]
        ],
    }

Then we update the agent instructions:

agent = Agent(
    model,
    instructions=(
        "You are a helpful assistant. Help the user with their questions and requests. "
        "Always use search_serpapi when the user asks for current information, "
        "products, companies, places, or news. "
        f"{TIME_SENSITIVE_INSTRUCTION}"
    ),
)

Now the agent has two useful tools:

get_time() for current date and time
search_serpapi() for live search results

With these tools, the agent can answer time-sensitive product questions more reliably.

Let's try asking the model the same question:

What is the latest iPhone?

With the help of the search tool, the agent could provide a detailed answer that includes all the models in the latest lineup.

Equipped with SerpApi, the agent is even more helpful. For example, let's ask the model to find the prices of these models:

The final answers are now grounded in live search results instead of just the model's memory. This is the key idea behind tool-using agents: the model should not be expected to know everything. It should know when to ask for the right tool.

How to save AI token usage

When building search tools for agents, it is tempting to return the entire API response. That can make the agent worse by taking up too much of the context window.

Search API responses can be large. They can include metadata, pagination, related questions, ads, inline widgets, thumbnails, and other fields. If we pass everything to the model, we spend more tokens and make the useful parts harder to find.

For most agent workflows, a compact response is better:

return {
    "answer_box": data.get("answer_box"),
    "organic_results": [
        {
            "title": item.get("title"),
            "link": item.get("link"),
            "snippet": item.get("snippet"),
        }
        for item in data.get("organic_results", [])[:10]
    ],
}

This gives the model enough context to answer while keeping the tool output short and readable.

Instead of filtering on the client side, we can also use SerpApi's JSON Restrictor feature to fetch only the required fields from the API. To achieve a result similar to the above, add a json_restrictor param to the SerpApi request with the value: organic_results, answer_box, which will give us a clean response with other fields omitted.

The same principle applies to any agent tool:

return the fields the model needs
avoid large raw payloads
keep the shape predictable

Good tool outputs are part of good prompt engineering.

Move from one search call to deep research

A single search call is useful for many questions. But some user requests need more coverage. For example:

Do deep research and find the best AI models for coding.

This type of query should not depend on one Google result. The agent should search across multiple engines, use different query terms, compare sources, and then summarize.

Pydantic AI capabilities are useful here. A capability can bundle instructions and tools into a reusable unit that can be attached to an agent.

Here is a deep_research capability:

from pydantic_ai.capabilities import Capability

deep_research = Capability(
    id="deep_research",
    description=(
        "Use for research tasks that need multiple live search calls across Google, Bing, "
        "Yahoo, Google news, and DuckDuckGo"
    ),
    instructions=(
        "For deep research, call serpapi_search several times before answering. You can "
        "call different engines as well as call the same engine multiple times with "
        "different queries and search params to get a variety of results. Useful engines "
        "include google, bing, yahoo, duckduckgo, google_news, duckduckgo_news, "
        "bing_news, and google_trends."
    ),
    defer_loading=True,
)

The important part is defer_loading=True.

This lets the agent keep the capability available without always loading all of its instructions and tools into every request. The model sees that the capability exists and can load it when the task needs deep research. This saves the model's context window.

Now we can define a search tool inside that capability:

from typing import Literal

SearchEngine = Literal[
    "google",
    "bing",
    "yahoo",
    "duckduckgo",
    "google_news",
    "duckduckgo_news",
    "bing_news",
    "google_trends",
]

@deep_research.tool_plain
def serpapi_search(
        query: str,
        engine: SearchEngine,
        location: str | None = None,
        gl: str | None = None,
        hl: str | None = None,
        page: int | None = None,
) -> dict:
    """Search one SerpAPI engine with optional search params and return compact results.

    page is a 1-based page number. gl and hl are mapped to each engine's SerpAPI
    locale parameters when supported.
    """
    params = _serpapi_params(query, engine, location, gl, hl, page)

    response = httpx.get("https://serpapi.com/search.json", params=params, timeout=20)
    response.raise_for_status()
    data = response.json()

    result_keys = (
        "organic_results",
        "shopping_results",
        "inline_shopping_results",
        "product_results",
        "news_results",
        "local_results",
    )
    results = {}
    for key in result_keys:
        compact_results = _compact_items(_items_for_result_key(data, key))
        if compact_results:
            results[key] = compact_results

    if engine == "google_trends":
        results.update(_compact_google_trends(data))

    return {
        "engine": engine,
        "query": query,
        "params_used": {key: value for key, value in params.items() if key != "api_key"},
        "results": results,
    }

This version is more flexible than the earlier search_serpapi() tool.

It allows the model to choose the search engine and optional parameters. It also handles multiple result types such as organic results, shopping results, product results, news results, and local results.

Then we attach the capability to the agent:

agent = Agent(
    model,
    capabilities=[deep_research],
    instructions=(
        "You are a careful research assistant. For simple questions, answer briefly. "
        "For deep research, call get_time to get current date/time and load the "
        "deep_research capability. "
        f"{TIME_SENSITIVE_INSTRUCTION}"
    ),
)

Now the agent can decide when the deep research workflow is needed.

For a simple question, it can answer briefly. For a research task, it can load the capability and call serpapi_search() several times before producing a final answer.

Let's test the capability. We can ask the agent to do a deep research to find the best AI coding model:

Multiple searches are used by the Deep Research capability for finding the best AI model for coding

The model performs multiple search requests, using different search terms and on different SerpApi engines, so as to gather detailed information.

Using the search data, the Agent is able to accurately present the user with a range of options:

Deep research results for the best AI Coding models

Using the search tool, the agent correctly identified and listed new models released well after the underlying model's knowledge cutoff.

Capabilities in Pydantic AI provide an important design pattern for agents. As the agent grows, we should not throw every tool and every instruction into the model context all the time. Instead, we should group related behavior into capabilities and load them when needed.

Use the right SerpApi engine for the task

Generic web search is useful, but agents become more powerful when they can choose specialized engines.

For example:

Use google or google_light for general web results
Use google_news, bing_news, or duckduckgo_news for news
Use shopping engines for product prices
Use engines like google_hotels, google_flights, and tripadvisor for travel planning
Use google_trends engines for popularity and interest over time

This matters because "search" is not one task.

If the user asks for the latest iPhone models, a general web search may be enough. If the user asks for prices, a shopping result is more useful. If the user asks for hotels in Goa next weekend, a hotel-specific engine is better than a normal web result.

That is why the deep research tool accepts an engine argument instead of hardcoding one search backend. The model can choose the right tool call for the job, and our code can keep the response structure compact.

Connect SerpApi through MCP

Custom tools are great when you want full control over behavior. But sometimes you do not want to define every tool yourself.

MCP, or Model Context Protocol, gives us a standard way to connect an agent to external tools and data sources. Instead of writing a Python wrapper for every search capability, we can connect the agent to an MCP server and let it discover the available tools.

The SerpApi MCP setup is short:

import os

from dotenv import load_dotenv
from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

load_dotenv()

serpapi_mcp_url = f"https://mcp.serpapi.com/{os.environ['SERPAPI_API_KEY']}/mcp"

model = OpenAIChatModel(
    "qwen/qwen3.6-35b-a3b",
    provider=OpenAIProvider(base_url="http://localhost:1234/v1"),
)

agent = Agent(
    model,
    capabilities=[MCP(url=serpapi_mcp_url)],
    instructions="You are a helpful assistant. Use available MCP search tools for current facts.",
)

With this setup, the agent can use the tools exposed by the MCP server.

This is useful for broader workflows. For example, a travel query may need hotel search first, then price lookup, then filtering by location or dates. If the MCP server exposes those tools, the agent can use them without us having to write each function in the client application.

Let's test this with a travel search query:

Results for Goa hotels search using SerpApi MCP

SerpApi MCP supports all SerpApi engines by default. So it can do tasks like travel searches, shopping research, news search, and more.

Here, the agent was able to provide Hotel suggestions based on the user's query.

It can successfully answer follow-up questions, for example, to get price details as well.

Hotel costs obtained via SerpApi MCP

MCP makes it easier for the model to identify supported tools and call them as needed, and abstracts away the complexity from the user by avoiding tool definitions. As seen in the example above, the agent can obtain real-time results from multiple SerpApi-supported engines with minimal client-side configuration. The client-side code becomes smaller, while the agent still gets access to real-time data.

What improved in the final agent

We started with a simple Pydantic AI agent that could only answer based on the model's internal knowledge.

Then we added:

a time tool for date-aware answers
SerpApi search for live web results
compact tool outputs to reduce context noise
a deep research capability for multi-search tasks
MCP support for reusable search integrations

The result is not just an agent that "knows more". It is an agent that has a better process.

When a query depends on current information, the agent can check the current time, search live sources, compare results, and then answer. That makes the answer more useful and reduces the chance of hallucination.

Notes for building reliable search agents

A few practical lessons from these examples:

Give the model explicit instructions about when to use tools.
Keep tool outputs compact and structured.
Use specialized search engines when the task needs them.
Use capabilities for creating reusable and lazy-loadable workflows that have their own tools and instructions.
Use MCP when you want reusable tools without writing all client-side wrappers.
Always test with questions where the answer changes over time.

The last point is important. A question like "What is the latest iPhone?" is a better test for a real-time agent than a static question like "What is Python?".

Static questions test the model. Current questions test the agent.

Summary

Pydantic AI gives us a clean way to build Python agents with typed tools, instructions, capabilities, web UI support, and MCP integrations.

On its own, an LLM is limited by its training data. With tools, it can call Python functions. With SerpApi, it can search live data. With Pydantic AI capabilities, it can load specialized workflows only when needed. With MCP, it can connect to reusable external tool servers.

That combination is what makes the agent smarter. Not because the model magically knows everything, but because the system around the model gives it the context and tools needed to answer better.

Building AI Agents in Python

Adarsh D — Thu, 04 Jun 2026 12:14:22 +0000

2026 is shaping up to be a big year for AI agents. We are seeing more products where the AI not only answers a question but also does some work for the user.

You have probably used ChatGPT or a similar AI tool to answer a question, help with writing, or explain some code. You type something, the AI responds, and the conversation goes back and forth. That is powerful, but it is also limited. The AI is essentially stuck in a chat box - it can only talk to you; it cannot do anything on your behalf.

AI agents change that. An agent is an AI that can actually take actions - browse the web, read and write files, run code, call APIs, and more. It does not just answer your question; it works toward a goal, step by step, using whatever tools it needs. Tools like Lovable, Cursor, and Claude Code are examples of this in practice.

In this article, we will explore the concepts behind building an AI agent in Python. We will use the OpenAI Python SDK (Responses API) for the examples, but the same ideas can be generalized to any other LLM SDK. We will use a low-level SDK with minimal abstractions so we can observe and implement most of the agent's behavior on our end.

TL;DR

This tutorial explains how AI agents work by building a simple one in Python.

We will cover the core pieces: LLMs, prompts, context, memory, the agent loop, tools, MCP, and skills:

Component	What it does
LLM	Acts as the reasoning engine that understands the user request and decides what to do next.
System prompt	Defines the agent’s role, behavior, boundaries, and response style.
Context window	Controls how much information the model can see at once, including prompts, history, tool results, and files.
Memory	Helps the agent remember useful information across steps or conversations.
Agent loop	Repeats the process of thinking, acting, observing results, and deciding the next step.
Tool calling	Lets the agent use external functions such as APIs, web search, file access, or code execution.
MCP	Provides a standard way to connect agents to reusable tools and data sources.
Skills	Package reusable instructions, workflows, examples, and scripts for specific tasks.

What are Agents?

An AI agent is an AI system that can autonomously plan and execute multi-step actions toward a goal.

To understand agents, it helps to first understand what is powering them under the hood - a large language model, or LLM. For example, ChatGPT is a product built on top of OpenAI GPT LLMs. When you type a message and get a response, an LLM is doing the heavy lifting. It takes text as input and generates text as output.

On their own, LLMs are impressive but limited. They can only respond with text. They cannot open your browser, read a file on your computer, or send an email. They also do not know what happened yesterday, because their knowledge comes from training data with a cutoff date, not a live connection to the world.

Agents fix this by giving LLMs access to tools. A tool is just a function your code exposes to the model - something like "search the web" or "read this file." The model can decide to call a tool when it needs to, and your code actually runs it. This turns a passive text generator into something that can act.

A good way to see the difference is to compare using ChatGPT with using Claude Code for a coding task. With ChatGPT, you describe the problem, copy the suggested code, paste it into your editor, run it, copy the error back, and repeat. The model has no idea what is actually in your project. Claude Code is different - it is powered by an LLM but also has access to tools like bash and file reading. You describe what you want, and it reads your files, writes code, runs tests, and fixes errors on its own. You just watch and steer.

The simplest way to understand an agent is:

The user gives a goal.
The model decides what step to take.
The agent runs that step using a tool.
The model looks at the result.
The process continues until the task is complete.

This is different from a normal chatbot. A chatbot mainly responds. An agent can respond and act.

In a simple agent, the model may only call one tool and return the result. In a more capable agent, the model may make a plan, call multiple tools, observe the results, adjust the plan, and continue until the task is complete.

Before we build this kind of system, we need to choose the model that will drive it.

LLMs

LLMs are trained on massive amounts of text data - entire open source repositories on GitHub, books, articles, websites, and more. Through training, the model learns patterns in language well enough to generate coherent, useful responses. The scale of this training is what makes them surprisingly capable across such a wide range of tasks.

At their core, LLMs are text-in, text-out systems. You send them a block of text (called a prompt), and they generate a response. Everything that happens - reasoning, answering questions, writing code, making decisions - is expressed through that text interface. When an agent calls a tool, it is really the model writing out a structured text request, and your code intercepts that and actually runs the function.

The key limitation to keep in mind: LLMs only know what they were trained on. They have no awareness of events after their training cutoff and no way to look things up in real time unless they are given a tool to do so. This is part of what makes tools so valuable - they extend the model's reach into the real world.

Choosing an LLM

For an AI agent, the LLM is its brain. The quality of the model affects how well the agent understands instructions, chooses tools, handles errors, and completes multi-step tasks.

At the same time, the most powerful model is not always the right choice. We also need to think about cost, speed, context window, reasoning ability, and where the model is hosted.

Benchmarks

Benchmarks are standardized tests used to compare the performance of different models. For coding tasks, there is SWE-bench. For general reasoning, there is MMLU. Each benchmark tests the model on a specific type of problem and gives it a score. A higher score generally means the model will perform better on that type of task.

Benchmarks are a useful starting point when choosing a model, but they are not the whole story. A model that scores well on a benchmark may still behave unexpectedly in your specific use case, so it is always worth testing with your actual workload.

Costs

Choosing the best-scoring model from a benchmark may not always be the most intelligent decision.

Cost is a real factor, especially at scale. Most providers charge per token, which is the basic unit of text the model processes. A token is roughly four characters, or about three-quarters of a word on average. Both what you send to the model (input) and what it generates back (output) count toward your token usage.

For an agent that runs multiple steps in a loop, token usage adds up quickly. A good approach is to start with a capable model and then see if a smaller or cheaper one can do the same job well enough. Sometimes a smaller model handles simple tasks just fine.

(Model costs table from https://github.com/simonw/llm-prices)

Reasoning Level

Some models are designed to think before they answer. These reasoning models break complex problems into smaller steps internally, often called reasoning traces. You can think of it as the model working through a scratchpad before writing its final response. This can improve performance for tasks that need planning, debugging, tool use, or careful decision-making.

More reasoning effort usually means higher cost, higher response time, and better accuracy for complex tasks.

Not every request needs high reasoning. If the task is simple, we can use a lower reasoning level or a cheaper model. If the task involves multiple steps, unknown errors, or important decisions, more reasoning can be useful.

(Conversation with GPT-OSS LLM showing reasoning/thought traces)

Hosted vs Local

Most people start with a hosted model - one that runs on a provider's servers and is accessed via an API. These are easy to set up, well-maintained, and generally the most capable options available. The trade-off is that you pay per token, and your data is processed by a third party.

There are also open models that can run entirely on your own machine/server. They can avoid per-token API costs and give you more control over data. The downside is that they require capable hardware and are generally less powerful than the best hosted models today. That said, local models are getting better quickly. Previous generation frontier capabilities are being replicated in the next generation of local models, and this gap will continue to close. Examples of open-weight models that can be self-hosted, depending on hardware and quantization, include Gemma 4 series and Kimi K2.6.

There are already decent local coding models that people use for simple code generation and verification. In the coming years, this will improve, and stronger models will become available on consumer devices.

Hosted models are still easier to use for many applications. They usually provide better quality, higher reliability, larger context windows, and managed infrastructure.

Local models give more control over data, cost, and deployment. But they also require more setup, hardware, monitoring, and optimization.

Configuring the LLM

Once you have picked a model, there are two things you set up before the agent starts running: the system prompt and the context window.

System Prompt

A system prompt is the model's top-level instruction that guides its behavior during a conversation.

It can set rules such as:

what role the AI should play
what tone it should use
what it should or should not do
how it should handle tools
how it should handle safety and user requests
how it should format the final answer

For an agent, the system prompt is very important. It tells the model how to behave while using tools. It can also define boundaries, such as asking for permission before destructive actions or avoiding actions outside the user's request.

Let's see an example of this in practice:

import os

if __name__ == '__main__':
    from openai import OpenAI

    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    response = client.responses.create(
        model="gpt-5.4-mini",
        input=[
            {
                "role": "system",
                "content": "You are a friendly Python tutor. Refuse all requests unrelated to Python coding",
            },
            {
                "role": "user",
                "content": input("Enter your Python question: "),
            },
        ],
    )
    print(response.output_text)

In the above script, we initialize an OpenAI client and use client.responses.create to send a message to gpt-5.4-mini model. The system prompt is specified in the input list as the first entry. "role": "system" designates the entry as the system prompt. In the above example, the model is instructed to act as a Python tutor and refuse requests unrelated to Python. As the next entry, we accept the user prompt via input() and pass it to the LLM for answering.

If the script is run and any unrelated queries are passed to the LLM, we get a refusal response similar to the below one:

Enter your Python question: How many states are there in the US?

Model response: I’m here to help with Python coding questions only. If you have a Python-related question, feel free to ask!

Even though the underlying large language model knows the answer to the user's query, it refuses to answer as per direction in the system prompt.

Context Window

The context window is the model's working memory. It is the amount of information the model can see in one request.

The context can include the user message, conversation history, system prompt, tool results, files, documentation, and any other information we provide.

Most of the latest flagship models support up to 1M tokens, which is roughly 750,000 words or about 15 books. Older models like GPT-4 series models had a 128K token window, around 2 books' worth. For agents that run long tasks or work with large documents, context window size matters a lot. When the context fills up, older information gets dropped, which can cause the agent to lose track of earlier steps in a long task.

A larger context window is useful, but it is not free. More context usually means more cost and slower responses. Also, just because a model can accept a lot of context does not mean every token is equally important.

Good agents manage context carefully. They include what is needed, summarize old information, and avoid filling the context with unnecessary data.

Once we understand the model and its context window, the next question is what the agent should remember across steps and conversations.

Memory

Memory helps an agent remember useful information.

Short-term memory helps the agent remember what the user said earlier in the same conversation. This usually lives inside the context window.

Let's consider an example. The snippet below accepts a user query inside a loop and sends it to a model to get the response:

import os

if __name__ == '__main__':
    from openai import OpenAI

    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    while True:
        user_query = input("You: ")

        if user_query.lower() in ["exit", "quit"]:
            break

        response = client.responses.create(
            model="gpt-5.4-mini",
            input=user_query,
        )

        assistant_reply = response.output_text
        print(f"Model: {assistant_reply}")

The code works, but there are issues:

You: Tell me about Taj Mahal in 1 sentence
Model: The Taj Mahal is a magnificent white marble mausoleum in Agra, India, built by Emperor Shah Jahan in memory of his wife Mumtaz Mahal, and is one of the world’s most famous symbols of love.

You: When was it built?
Model: I can help, but I need to know **what “it” refers to**.  
Please share the name, photo, or location of the building/structure/object, and I’ll tell you when it was built.

As seen from the transcript, the model fails to answer the user's follow-up prompt. This is because, we did not implement short term memory. For the model to be able to respond to follow-ups properly, we need to store and pass the conversation history to LLM calls. The snippet improves on the above script with short term memory implementation:

import os
if __name__ == '__main__':
    from openai import OpenAI

    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    conversation_history = []

    while True:
        user_query = input("You: ")

        if user_query.lower() in ["exit", "quit"]:
            break

        conversation_history.append({
            "role": "user",
            "content": user_query,
        })

        response = client.responses.create(
            model="gpt-5.4-mini",
            input=conversation_history,
        )

        assistant_reply = response.output_text
        print(f"Model: {assistant_reply}")

        conversation_history.append({
            "role": "assistant",
            "content": assistant_reply,
        })

We introduced a conversation_history list that stores previous messages. User messages are appended to this list with "role": "user" and model responses are appended with "role": "assistant". This way, whenever a request is sent to the model, it gets the entire message history through the input argument and will be able to respond to follow-up prompts correctly.

You: Tell me about Taj Mahal in 1 sentence
Model: The Taj Mahal is a stunning white marble mausoleum in Agra, India, built by Emperor Shah Jahan in memory of his wife Mumtaz Mahal.

You: When was it built?
Model: It was built between 1632 and 1653.

Long-term memory stores information beyond one conversation and persists even after the current chat or task ends. This is useful when you want the agent to remember user preferences, past decisions, or domain-specific facts across sessions. Common approaches include RAG (retrieval-augmented generation), where relevant information is fetched from a database and added to the context as needed, and built-in memory systems like ChatGPT Memories, where key facts are stored and automatically recalled in future conversations.

Agent Loop

The agent loop is the core flow of an agent.

A simple loop looks like this:

User sends a message.
Agent adds the message to the conversation context.
Agent sends the context and system prompt to the LLM.
LLM decides what to do next.
If needed, the LLM calls a tool.
Agent runs the tool and sends the result back to the LLM.
LLM decides whether more steps are needed.
When done, the LLM generates the final response.
Agent sends the response to the user.

This loop is what makes agents feel different from normal chatbots. A chatbot usually gives one response. An agent can act, observe, and continue.

In practice, the intermediate steps are where the interesting work happens. The model may call a tool, wait for the result, process that result, decide to call another tool, and keep going before it gives a final answer. The loop runs as many times as needed until the model decides the task is complete or the user stops it. This brings us to tools - what they are and how they actually work.

Tool Calling

Tools are external capabilities that the agent can use.

Tools (also called functions) let an AI agent do things beyond generating text. They can be used to take actions or get information.

Examples of tools:

search the web
call an API
read files
edit files
run code
send emails
query a database
create calendar events

The agent chooses a tool when needed. The tool has a name, a description, and input parameters. The model decides which tool to call and what arguments to pass.

Tool descriptions are important. If a tool description is unclear, the model may call it at the wrong time or pass the wrong input. We should describe tools in simple language and make their inputs strict.

Here is an important detail: the model does not run the tool itself. When it decides to use a tool, it outputs a structured request with the tool name and the arguments it wants to pass. Your code intercepts this, runs the actual function, and passes the result back to the model. The model then reads the result and decides what to do next. This back-and-forth between the model and your code is what makes the agent loop so powerful.

Let's see an example of tool calling in action:

import json
import os
from dotenv import load_dotenv

load_dotenv()


def get_weather(location):
    return {
        "location": location,
        "temperature": "24 C",
        "condition": "Sunny",
        "humidity": "52%",
        "wind": "11 km/h",
    }


if __name__ == '__main__':
    from openai import OpenAI

    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    tools = [
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather for a destination.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city or destination, e.g. Paris or Tokyo",
                    }
                },
                "required": ["location"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    ]

    input_list = [
        {
            "role": "system",
            "content": "You are Safar, a travel planning AI agent",
        },
        {
            "role": "user",
            "content": input("Ask you travel questions: "),
        },
    ]

    response = client.responses.create(
        model="gpt-5.4-mini",
        input=input_list,
        tools=tools,
        tool_choice="required",
    )

    print("The model responded with:")
    print(response.output)

    input_list += response.output

    for item in response.output:
        if item.type != "function_call":
            continue

        if item.name == "get_weather":
            args = json.loads(item.arguments)
            print(f"The model wants to call get_weather with: {args}")

            weather = get_weather(args["location"])
            print(f"The local Python function returned: {weather}")

            input_list.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather),
            })

    print("Sending the tool result back to the model")
    final_response = client.responses.create(
        model="gpt-5.4-mini",
        input=input_list,
        tools=tools,
    )

    print("Final answer:")
    print(f"Model response: {final_response.output_text}")

In the tools list, we have defined a function named get_weather according to OpenAI function calling guidelines and have specified the parameters that the model accepts using the parameters key. This definition follows JSON Schema specification.

Since, we add this tools list when making calls to OpenAI, the model will know that it has access to a weather tool and will be able to request a function call when needed.

In the script, you can see that when we receive a response from the model, we always check if the response type is a function call or not (item.type != "function_call") and if the response is a request to call get_weather tool, we call the get_weather() Python function and send it back to the model:

weather = get_weather(args["location"])
input_list.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather),
            })

Let's run the script and ask the agent a question that would require a weather tool call:

Ask you travel questions: Sunscreen needed in Goa?

The model responded with:
[ResponseFunctionToolCall(arguments='{"location":"Goa"}', call_id='call_X9OBZhGwT3yhfmTAOclefWE8', name='get_weather', type='function_call', id='fc_05ba95ec38f46f7f006a17ce9e3bb0819a9a0b430001f7bd91', namespace=None, status='completed')]

The model wants to call get_weather with: {'location': 'Goa'}
The local Python function returned: {'location': 'Goa', 'temperature': '24 C', 'condition': 'Sunny', 'humidity': '52%', 'wind': '11 km/h'}

Sending the tool result back to the model

Final answer:
Model response: Yes — sunscreen is a good idea in Goa. It’s sunny there right now, so UV exposure can be strong even if it feels pleasant.

Quick tips:
- Use broad-spectrum SPF 30+ (SPF 50 if you’ll be at the beach a lot)
- Reapply every 2 hours, and after swimming/sweating
- Don’t forget ears, neck, hands, and feet
- A hat and sunglasses help too

If you want, I can also suggest a Goa beach-day packing list.

For our query, the model initially responds with a ResponseFunctionToolCall item. This requests our get_weather function to be called with location argument set as Goa.

Responding to this request, our script executes the function call and sends the function call response back to the model for getting the final response. The function call always returns temperature as 24 degree Celsius with condition as sunny. Trusting this data, the model produces its final response, suggesting the user to use a sunscreen.

The weather function defined in the above script is not a very useful one, it returns a hardcoded weather data for all requests. In a practical scenario, the function should make an actual call to a real Weather API to fetch data.

The above script illustrates the concept of an agent loop. Even though the example involves just one user request and model response, the agent takes intermediary steps (tool calls) before returning the final response.

Now let's move to a real world example involving tools. We will provide web search capability to our agent by defining a custom SerpApi web search tool.

Providers usually have their own built-in tools for web search. However, these tools can be slow or unreliable at times. To get live search data from search engines reliably, we can write a custom tool/function using SerpApi Python SDK.

import json
import os


def google_search(query):
    import serpapi

    client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])

    results = client.search({
        "engine": "google",
        "q": query,
    })

    return [
        {
            "title": result.get("title"),
            "link": result.get("link"),
            "snippet": result.get("snippet"),
        }
        for result in results.get("organic_results", [])[:5]
    ]


if __name__ == '__main__':
    from openai import OpenAI

    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    tools = [
        {
            "type": "function",
            "name": "google_search",
            "description": "Search Google with SerpApi and return web search results.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The Google search query to run",
                    }
                },
                "required": ["query"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    ]

    input_list = [
        {
            "role": "system",
            "content": "You are Safar, a travel planner. Use Google search when current destination information would improve your answer.",
        },
        {
            "role": "user",
            "content": input("What travel question should I research? "),
        },
    ]

    response = client.responses.create(
        model="gpt-5.4-mini",
        input=input_list,
        tools=tools,
        tool_choice="required",
    )

    print("The model responded with:")
    print(response.output)

    input_list += response.output

    for item in response.output:
        if item.type != "function_call":
            continue

        if item.name == "google_search":
            args = json.loads(item.arguments)
            print(f"The model wants to call google_search with: {args}")

            search_results = google_search(args["query"])
            print(f"Step 7: SerpApi returned {len(search_results)} search results")

            input_list.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(search_results),
            })

    final_response = client.responses.create(
        model="gpt-5.4-mini",
        input=input_list,
        tools=tools,
    )

    print(f"Model response: {final_response.output_text}")

Here, we define a google_search() that accepts a query and performs a Google search with the query using SerpApi Python SDK. The function returns the first five search results obtained from Google.

Let's see the results in action:

What travel question should I research? When is the Tomato festival - La Tomatina happening this year?

The model responded with:
[ResponseFunctionToolCall(arguments='{"query":"La Tomatina 2026 date official"}', call_id='call_mk2KL4xnvR0mexyt2lXFTHgE', name='google_search', type='function_call', id='fc_01af4c5fc07e8479006a192316ab20819bb10273439c89fb9a', namespace=None, status='completed')]

The model wants to call google_search with: {'query': 'La Tomatina 2026 date official'}
Step 7: SerpApi returned 5 search results

Model response: La Tomatina is happening on **Wednesday, August 26, 2026** in **Buñol, Spain**.

If you want, I can also help with:
- tickets
- how to get there from Valencia
- where to stay nearby

This is the core idea behind tool calling. The model does not directly browse the web or fetch data by itself. Instead, it identifies when a tool is needed, asks for that tool to be called, and then uses the returned result to continue the conversation. This separation is useful because the model can focus on reasoning, while tools provide access to external systems and real-time information.

Without the google_search tool, the model would not be able to answer questions that require live data. It should respond with something like: “I don’t have access to real-time information.” By defining the tool, we give the model a safe and structured way to request the information it needs.

MCP

As you build more agents with more tools, a new problem emerges: every tool integration is custom-built and cannot easily be reused elsewhere. If you build a GitHub integration for one agent, you would have to rebuild it from scratch for another. That is where MCP comes in.

Model Context Protocol (MCP) is like USB-C for AI integrations. It is a standard protocol that lets models connect to external tools and data sources in a consistent, reusable way. Instead of building a custom integration for every tool, you write an MCP server once, and any model that supports MCP can use it.

Examples include:

GitHub MCP
Figma MCP
SerpApi MCP
database MCP servers
browser MCP servers
file system MCP servers

With MCP, the model can discover supported functionality and call tools when needed. This makes integrations reusable across different models, clients, and applications. For a small agent, normal tool calling may be enough. For larger systems with many integrations, MCP can make the architecture cleaner.

Let's see an example of MCP usage in practice. The script below uses the SerpApi MCP server - using this, the agent will be able to call all the SerpApi supported engines like google, google_shopping, amazon, etc.

import os

if __name__ == '__main__':
    from openai import OpenAI

    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    serpapi_mcp_url = f"https://mcp.serpapi.com/{os.environ['SERPAPI_KEY']}/mcp"

    response = client.responses.create(
        model="gpt-5.4",
        tools=[
            {
                "type": "mcp",
                "server_label": "serpapi",
                "server_description": "SerpApi MCP server",
                "server_url": serpapi_mcp_url,
                "require_approval": "never",
            }
        ],
        input=[
            {
                "role": "system",
                "content": "You are Cartwise, a shopping assistant. Help users compare products, prices, reviews, and buying options.",
            },
            {
                "role": "user",
                "content": input("What do you want to shop for? "),
            },
        ],
    )

    print("Full model response (includes MCP operations): ")
    print(response.output)

    print(f"Model response: {response.output_text}")

SerpApi exposes the MCP server via the URL https://mcp.serpapi.com/. Users can supply the API Key via the URL path as seen in the example: https://mcp.serpapi.com/{os.environ['SERPAPI_KEY']}/mcp.

The code here is relatively simpler compared to the tool calling example. We just need to provide the MCP server info via the tools argument:

tools=[
            {
                "type": "mcp",
                "server_label": "serpapi",
                "server_description": "SerpApi MCP server",
                "server_url": serpapi_mcp_url,
                "require_approval": "never",
            }
        ]

From this definition alone, the model can discover supported MCP functionalities and it will be able to autonomously call the MCP server tools based on the user request.

Let's ask the agent a shopping query. Here, I am asking it to find the price of a mobile device:

What do you want to shop for? Find best price for Moto Razr Ultra phone

Full model response (includes MCP operations): 
[ 
  McpListTools(id='mcpl_06176a7178fb9f5c006a17f6c23578819ab2c977e7bc2b0bc7', server_label='serpapi', ..., 

McpCall(id='mcp_06176a7178fb9f5c006a17f6c40930819aac6136e6a0f0ced8', arguments='{"params":{"q":"Moto Razr Ultra phone price","engine":"google_shopping","num":10},"mode":"compact"}', name='search', server_label='serpapi', type='mcp_call', approval_request_id=None, error=None, output='{"shopping_results": [{"position": 1, "title": "Motorola Razr Ultra 2025", "product_id": "14521999409488109662", "product_link": ...]}]}', status='completed'), 
  ResponseOutputMessage(id='msg_06176a7178fb9f5c006a17f6cc3e68819aa688012defa9cf78', content=[ResponseOutputText(annotations=[], text='Best price I found for a **new Moto Razr Ultra** is:...'
]

Model response: Best price I found for a **new Moto Razr Ultra** is:

- **$699.99 at Best Buy** — Motorola Razr Ultra 2025  
  - was **$1,300**
  - rating: **4.0/5** from **520 reviews**
  - free delivery by Sat

Also matching:
- **$699.99 at Motorola US** — Motorola Razr 2025
- **$764.00 at Etoren** — Motorola Razr 50 Ultra
- **$1,049.99+** for some Razr 60 Ultra / 2026 variants

The model response includes a series of operations:

McpListTools: This is the request from the model sent to the MCP server to list available operations. From this call, the model will know that SerpApi has a google_shopping engine for shopping searches.
McpCall: Based on the above response, the model calls MCP servers google_shopping engine with the query Moto Razr Ultra phone price. This call will fetch the shopping results via SerpApi MCP.
ResponseOutputMessage: Once the above response is obtained, the model has enough information regarding the prices to formulate its response to the user. The model responds by listing the device price across a number of retailers.

If we omitted the SerpApi MCP definition in the above script, the model should have responded with something like: “I cannot access real-time prices.” This is because the model itself does not have live data access unless we explicitly connect it to external tools or systems. MCP is one way to provide that connection in a standard way.

Now that we have seen how MCP connects agents to external capabilities, let’s look at another way to extend agent behavior: skills.

Skills

While tools handle actions, skills handle behavior. A skill is a reusable set of instructions or a workflow that tells an agent how to perform a specific type of task well.

We have seen tools and MCP which are code-heavy. Tools are code that gets called by the model whereas MCP requires a server implementation according to the Model Context Protocol spec. Skills are relatively simple and can just be a plain text markdown file.

A skill can include:

steps to follow
rules
examples
output formats
scripts
templates
best practices

Skills are useful for repeated tasks. Examples include writing reports, analyzing PDFs, creating slides, debugging code, or handling customer support. Skills make agents more specialized.

Instead of putting every instruction into the system prompt, we can use skills where the model receives just the skill metadata in the context and will be able to load and use the full skill when the current task needs it.

A skill file is just a markdown file with the below format:

---
name: skill-name
description: A description of what this skill does and when to use it.
---
Skill contents in markdown

Let's see a real-world example: The SerpApi Search Skill provides instructions for the agent to interact with SerpApi realtime search APIs. You can see the skill.md file, which provides instruction to the model to invoke various SerpApi API calls.

You can see a usage example below, where we use SerpApi skill to build a travel planning agent.

import os
import subprocess
from pathlib import Path

from openai import OpenAI


MODEL = os.getenv("OPENAI_MODEL", "gpt-5.4-mini")
SKILL_PATH = Path(__file__).resolve().parent / "skills" / "serpapi-web-search"


def run_shell_call(shell_call):
    print(f"\nModel requested shell call: {shell_call.call_id}")
    print(f"Commands: {shell_call.action.commands}")

    command_outputs = []
    for command in shell_call.action.commands:
        print(f"\n[script] Running command: {command}")

        result = subprocess.run(
            command,
            shell=True,
            executable="/bin/zsh",
            capture_output=True,
            text=True,
            check=False,
        )

        print(f"[script] Exit code: {result.returncode}")
        if result.stdout:
            print(f"[script] stdout:\n{result.stdout[:1500]}")
        if result.stderr:
            print(f"[script] stderr:\n{result.stderr[:1500]}")

        command_outputs.append({
            "stdout": result.stdout,
            "stderr": result.stderr,
            "outcome": {
                "type": "exit",
                "exit_code": result.returncode,
            },
        })

    output_item = {
        "type": "shell_call_output",
        "call_id": shell_call.call_id,
        "output": command_outputs,
    }

    if shell_call.action.max_output_length is not None:
        output_item["max_output_length"] = shell_call.action.max_output_length

    return output_item


if __name__ == "__main__":
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    input_list = [
        {
            "role": "system",
            "content": "You are Safar, a travel planning assistant.",
        }
    ]

    tools = [
        {
            "type": "shell",
            "environment": {
                "type": "local",
                "skills": [
                    {
                        "name": "serpapi-web-search",
                        "description": "Search current travel information with the SerpApi CLI.",
                        "path": str(SKILL_PATH),
                    }
                ],
            },
        }
    ]

    print("Type 'exit' or 'quit' to stop.\n")

    waiting_for_user = True

    while True:

        if waiting_for_user:
            user_query = input("You: ")

            if user_query.lower() in ["exit", "quit"]:
                break

            input_list.append({
                "role": "user",
                "content": user_query,
            })
            waiting_for_user = False

        print("\n[script] Sending request to the model.")
        response = client.responses.create(
            model=MODEL,
            input=input_list,
            tools=tools,
        )

        input_list += response.output

        shell_calls = [item for item in response.output if item.type == "shell_call"]
        print(f"[script] Shell calls requested: {len(shell_calls)}")

        if not shell_calls:
            print(f"Model response: {response.output_text}\n")
            waiting_for_user = True
            continue

        for shell_call in shell_calls:
            input_list.append(run_shell_call(shell_call))

        print("\n[script] Sending shell output back to the model.")

The script uses local skills capability of OpenAI SDK - we have the skill files added in skills/serpapi-web-search folder relative to the scripts parent directory.

Skills can be specified using the below format:

tools = [
        {
            "type": "shell",
            "environment": {
                "type": "local",
                "skills": [
                    {
                        "name": "serpapi-web-search",
                        "description": "Search current travel information with the SerpApi CLI.",
                        "path": str(SKILL_PATH),
                    }
                ],
            },
        }
    ]

We provide the skill name, description and path to the agent. When using skills, OpenAI SDK will emit shell calls that must be run in the terminal. This is needed so that the agent can list and view the full skill file contents that are present locally. We have a run_shell_call() function defined for this. Whenever the model requests for a shell call, we will run this function and pass back the shell results to the model.

Since this example lets the model request shell commands, only run it in a trusted, sandboxed environment. Do not give shell access to untrusted prompts, repositories, or skill files without review.

Now let's run the agent and ask it a travel planning question. We will ask the model about hotel prices in Goa, India:

Type 'exit' or 'quit' to stop.
You: Find Goa hotel prices for a vacation: two nights from 10 June 26

[script] Sending request to the model.
[script] Shell calls requested: 1

Model requested shell call: call_Cgs0D4tNOZFPZ30GNVJzJNHZ
Commands: ['cd .../skills/serpapi-web-search && cat SKILL.md']

[script] Running command: cd .../skills/serpapi-web-search && cat SKILL.md
[script] Exit code: 0
[script] stdout:
---
name: serpapi-web-search
description: >-
  Search the web using SerpApi's 100+ search engines. Use this skill whenever
  the user needs current or web-sourced information: ...

[script] Sending shell output back to the model.

[script] Sending request to the model.
[script] Shell calls requested: 1

Model requested shell call: call_Y2PGcBkpSEkzIikqu1H30uRW
Commands: ["cd .../skills/serpapi-web-search && sed -n '1,220p' rules/ENGINES.md"]

[script] Running command: cd .../skills/serpapi-web-search && sed -n '1,220p' rules/ENGINES.md
[script] Exit code: 0
[script] stdout:
# SerpApi Search Engines Catalog

Complete list of 107 SerpApi search engines. Use the `engine` parameter to select the desired search engine.
...

[script] Sending shell output back to the model.

[script] Sending request to the model.
[script] Shell calls requested: 1

Model requested shell call: call_oncTqSWJWQoDbqJS06aJP1OD
Commands: ['cd .../skills/serpapi-web-search && serpapi search engine=google_hotels q="Goa" check_in_date=2026-06-10 check_out_date=2026-06-12 --fields \'properties[0:20]\'']

[script] Running command: cd .../skills/serpapi-web-search && serpapi search engine=google_hotels q="Goa" check_in_date=2026-06-10 check_out_date=2026-06-12 --fields 'properties[0:20]'
[script] Exit code: 0
[script] stdout:
{
  "properties": [
    {
      "type": "hotel",
      "name": "Vivanta Goa, Miramar",
      "description": "Swanky hotel across from the beach featuring a rooftop pool, a stylish restaurant & a 24-hour gym.",
      ...


[script] Sending shell output back to the model.

[script] Sending request to the model.
[script] Shell calls requested: 0

Model response: I found live Goa hotel prices for **2 nights: 10 Jun 2026 to 12 Jun 2026**.

Sample prices from Google Hotels:
- **Vivanta Goa, Miramar** — **$82/night**, **$164 total**
- **Aloha Holiday Resort** — **$17/night**, **$33 total**
- Other properties in the Goa search were showing a wide range, from budget stays to luxury resorts.

A few notes:
- These are **current live rates** and can change quickly.
- The prices shown are from hotel search results and may be **before taxes/fees**.
- I searched broadly for **Goa**; if you want, I can narrow it down by:
  - **North Goa / South Goa**
  - **Budget / mid-range / luxury**
  - **Beachfront**
  - **2 adults vs family**

If you want, I can make a short list of the **best 10 Goa hotels under a budget you choose**.

As seen from the output, the model initially requested a shell call that runs cat SKILL.md which is to read the skill contents.

With the skill contents obtained, the model proceeds with another shell call sed -n '1,220p' rules/ENGINES.md which lists all SerpApi supported engines. With this data, the model will be able to get all supported SerpApi search engines and choose the best one for the task.

Next, model requests running the command serpapi search engine=google_hotels q="Goa" check_in_date=2026-06-10 check_out_date=2026-06-12 --fields 'properties[0:20]' which uses SerpApi CLI to get results from Google Hotels. We run this shell command on our end and pass the results to the model that includes JSON results from Google Hotels API.

With this data obtained, the model was able to generate its final response and give us suggestions for Hotels to book in Goa along with the prices.

Now that we have seen prompts, memory, tools, MCP, and skills, we can put these pieces into one simple stack.

Agent Capability Stack

An agent can be understood as a stack of capabilities. We have seen the core building blocks of an agent: system prompts, tools, MCP, and skills. Now, let’s compare how they fit together in the agent capability stack.

At the bottom, we have the system prompt. This defines global behavior and constraints.

Then we have skills. Skills provide packaged procedures for specific task types.

Then we have tools. Tools let the agent do things in the world.

Then we have MCP. MCP gives us a standard way to connect models to tools, files, APIs, databases, IDEs, browsers, and other systems.

We can think about the stack like this:

Layer	Purpose	Use when
System prompt	Global behavior and constraints	You want rules that apply every turn
Skills	Reusable workflows	You want the model to follow a repeatable process
Tools	External actions and information	You want the model to call APIs, read files, run code, or fetch live state
MCP	Standard integration layer	You want reusable integrations across models and clients

Use a system prompt for safety boundaries, tone, refusal style, and stable rules.

Use a skill when you want the model to follow a repeatable workflow or use scripts and templates.

Use tools when the model must call external services, fetch live state, create side effects, or interact with the environment.

Use MCP when you want to expose tools and resources through a standard protocol.

Summary and Next Steps

In this tutorial, we started out with the components of an AI agent and built a few simple agents for use cases such as shopping and travel. We provided capabilities to agents using tool calling, MCP, and Skill files.

To explore on your own, you can find the code snippets used in the tutorial in this GitHub repo.

If you are looking for a different SDK or tool to start with like the Claude agent SDK or n8n, we have you covered:

Even though we covered the basics for building simple agents, some important next steps to learn more about are:

multi-agent systems
observability
error handling
permissions
context compaction
evaluation

A multi-agent system has multiple agents, where each agent can be specialized for a specific goal. These agents can communicate with each other. We can also have verifier models that check the output from other models.

Similar to building a backend application, we need observability and error handling for agents. The model can hallucinate, choose the wrong tool, pass bad arguments, or get stuck in a loop. We need a way to monitor this behavior and improve the system over time.

Permissions are also important. An agent that can read files is useful. An agent that can delete files or send emails should be more carefully controlled. We should decide which actions require user approval.

Context compaction is another important idea. As the conversation grows, the agent cannot keep everything forever. It needs to summarize old information and keep only what is useful for the next step.

Evaluation helps us understand whether the agent is actually doing a good job. We can test the agent on sample tasks, check if it used the right tools, verify whether the final answer is correct, and compare outputs across different prompts or models. Without evaluation, it is hard to know if the agent is improving or just producing confident-looking answers.

The best way to understand agents is to build small ones, give them real tasks, inspect their tool calls, and evaluate their outputs. Start with a simple loop, add tools carefully, introduce memory only when needed, and add observability before trusting the agent with important actions. And if your agent needs real-time data access, you can explore SerpApi APIs to extend its capabilities.

Partition method of Python strings

Adarsh D — Thu, 25 Jan 2024 08:19:34 +0000

The partition method of str covers a niche use case - It is useful when a string needs to be split into exactly two parts based on a separator. It returns a three-membered tuple containing the part before, the separator itself, and the part after the separator.

The split method is commonly used for splitting strings, which returns a list whose length can change based on the number of times the separator is present.

host = "localhost:8000"
print(host.split(":"))  # Output: ['localhost', '8000']

host = "localhost"
print(host.split(":"))  # Output:['localhost']

host = ""
print(host.split(":"))  # Output: ['']

partition is helpful when we need to get precisely two parts from a string using a separator.

server_name = "localhost:5000"
print(server_name.partition(":"))  # Output: ('localhost', ':', '5000')

server_name = "localhost"
print(server_name.partition(":"))  # Output: ('localhost', '', '')

server_name = ""
print(server_name.partition(":"))  # Output: ('', '', '')

Using partition instead of split saves us from additional checks on the result's length when exactly two parts are required.

Flask uses the partition method to determine the host and port to use when running the Flask app. You can see the source code here.

A simplified version of the code is added as below:

def run(
    self,
    host: str | None = None,
    port: int | None = None,
    debug: bool | None = None,
    load_dotenv: bool = True,
    **options: t.Any,
) -> None:
    ...

    server_name = self.config.get("SERVER_NAME")
    sn_host = sn_port = None

    if server_name:
        sn_host, _, sn_port = server_name.partition(":")
        # The `partition` method will always return a three-membered tuple

    if not host:
        if sn_host:
            host = sn_host
        else:
            host = "127.0.0.1"

    if port or port == 0:
        port = int(port)
    elif sn_port:
        port = int(sn_port)
    else:
        port = 5000

In the example above, the server_name string is partitioned into host and port values.

I share interesting Python snippets 🐍 like this from open-source projects illustrating Python language features. Subscribe to my newsletter (https://adarshd.substack.com/) to receive new posts to your email 💌🚀.

Thread Safety in Python

Adarsh D — Wed, 11 Oct 2023 05:11:29 +0000

Before getting started with Thread safety, let's look into race conditions.

Race Conditions

From Wikipedia:

A race condition or race hazard is the condition of an electronics, software, or other system where the system's substantive behavior is dependent on the sequence or timing of other uncontrollable events. It becomes a bug when one or more of the possible behaviors is undesirable.

Race conditions can occur especially in logic circuits, multithreaded, or distributed software programs.

For an example of a race condition on a real-world web app, see this disclosed security bug: https://hackerone.com/reports/759247

Here the hacker could redeem a gift card (intended for single use) multiple times.

A developer may think of implementing a gift card redemption flow like below:

Get a gift card code from the user
Validate the code: Check if it exists in DB, is not expired, and is not used.
If validation succeeds, add the gift card value to the user's wallet and mark the gift card as used in the DB.

Think of the case where a user sends multiple requests at the same time. All parallel requests arriving before the execution of step 3, could succeed and can result in adding the gift card amount to the user's wallet once per request. This might have happened in the case of the above bug.

Threading in Python

Threading is a method to implement concurrency in Python programs. Due to the presence of CPython's GIL, threading is helpful in the case of I/O Bound programs.

threading module and concurrent.future's ThreadPoolExecutor helper is commonly used to implement multithreading in Python.

Let's dive into some Python examples after exploring the levels of thread safety.

Levels of thread safety

From Wikipedia, levels of thread safety:

Thread safe: Implementation is guaranteed to be free of race conditions when accessed by multiple threads simultaneously.

Conditionally safe: Different threads can access different objects simultaneously, and access to shared data is protected from race conditions.

Not thread-safe: Data structures should not be accessed simultaneously by different threads.

Race conditions in Python Threaded Programs

Example 1: Incrementing a counter

import concurrent.futures

count = 0


def increase_counter():
    global count
    for i in range(1000):
    count += 1

with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
    for _ in range(10_000):
        executor.submit(increase_counter)

print(F"{count=}")

The expected value of the count is 10,000 * 1000.

Running with Python 3.9, the program output varies per execution and gives outputs like below:

count=2163149
count=5642376

From this, we can conclude that the program is not thread-safe, since it gives unexpected results when run using multiple threads.

In the above examples, there are at most 10 parallel threads working since we have given max_workers=10

On adjusting max_workers value,

When max_workers=3, the output varies like below:

count=10000000
count=9999000

On reducing max_workers, which is the number of threads running in parallel, there is a visible reduction in errors, and at times, the expected output is also returned.

Consider the above scenario where each thread reads a variable and increments its value with 1. Between reads and writes, context switches to different threads can happen.
With multiple threads, the following scenario may be possible:

Thread_1 reads the value of count, gets 0
At the same time thread 2 reads count, and gets 0
Thread_1 sets count=count+1, as 1.
Thread_3 reads count, gets 1.
Thread_3 sets count=count+1, as 2
Thread_2 sets count=count+1, as 1 (since thread_2 holds a stale value of count, i.e., 0)

This explains the counter value being far less than expected.

Example 2: Singleton class in Python

Let's take an example of a Singleton class created using Python.
Singleton pattern is used to make sure that only one instance is created for a class. This can be used in cases where the class initialization performs some steps which should be performed exactly once. Singletons are useful in cases where there are restrictions on certain resource usage such as concurrent connection limits.

Below is a commonly used example for a Singleton class in Python:

class SingletonClass:
    def __new__(cls):
        if not hasattr(cls, 'instance'):
            cls.instance = super(SingletonClass, cls).__new__(cls)
        return cls.instance


obj1 = SingletonClass()
obj2 = SingletonClass()

print(obj1 is obj2) # True
print(id(obj1)) # 2402721138768
print(id(obj2)) # 2402721138768

In the above example, it is possible because two threads can evaluate the if check for instance (if not hasattr(cls, 'instance')) at near similar times and proceed to create two new objects.

Example 3: The print function

from concurrent import futures

def printer():
    print('testing thread safety of print')


with futures.ThreadPoolExecutor(max_workers=10) as executor:
    for _ in range(10):
        executor.submit(printer)

Output can vary from expected:

testing thread safety of print
testing thread safety of print
testing thread safety of printtesting thread safety of print
testing thread safety of print

testing thread safety of printtesting thread safety of print
testing thread safety of print
testing thread safety of print

testing thread safety of print

Before printing ending newlines, context switches happen sometimes printing output from another thread.

Making programs thread-safe

Synchronization primitives

The below synchronization primitives can be used to make a program thread safe.

Lock

A lock can be used for exclusive access to a resource. Once a thread acquires a lock, no other threads can acquire it (and proceed further) unless the lock is released.

RLock

RLock is a re-entrant lock. It allows when a holding thread requests the lock again.
The simple lock is not aware of the current locking thread and this can lead to deadlocks.

import threading

num = 0
lock = Threading.Lock()

lock.acquire()
num += 1
lock.acquire() # This will block. The program goes into a deadlock after this.
num += 2
lock.release()


# With RLock, that problem doesn't happen.
lock = Threading.RLock()

lock.acquire()
num += 3
lock.acquire() # This won't block.
num += 4
lock.release()
lock.release() # We need to call release once for each call to acquire

For brevity, let's skip the other primitives (Semaphore & Barrier, Events & Conditions).

Lock acquisition and release can be managed using context managers.

lock = Threading.Lock()

lock.acquire()
num += 1
lock.release()

is equivalent to:

lock = Threading.Lock()

with lock:
    num += 1

Thread safe counter implementation

We can use a lock at places of code where race conditions(simultaneous modifications in this case) should be avoided.

import concurrent.futures
import dis
import time
from threading import Lock

count = 0
lock = Lock()


def increase_counter():
    global count
    for i in range(1000):

        lock.acquire()
        count += 1
        lock.release()

        """
        or:
        with lock:
        count += 1
        """


with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    for _ in range(10_000):
        executor.submit(increase_counter)

print(F"{count=}") # count=10000000, for all executions

Thread-safe singleton implementation

class Singleton:
  _instance = None
  _lock = threading.Lock()

  def __new__(cls):
      if cls._instance is None:
        with cls._lock:

          if cls._instance is None:
              cls._instance = super().__new__(cls)

    return cls._instance

After acquiring the lock (using with), we are rechecking the presence of an instance to prevent the below-race condition.

Consider two threads thread1 and thread2.

Both execute new dunder of singleton class at the same time.
cls_.instance is currently None, so both thread tries to acquire the lock
thread1 gets the lock while thread2 is blocked waiting.
thread1 creates the singleton instance and completes execution inside the context manager. Once it exits the with block, the lock (cls._lock) is released.
Now, thread2 is unblocked and enters the context manager body by acquiring the lock. Since the None check for cls._instance fails, thread2 leaves execution and the already existing instance is returned.

Thread safe print implementation

Similar to the previous examples, we can use a lock here.

from concurrent import futures
from threading import Lock

lock = Lock()

def printer():
    with lock:
        print('testing thread safety of print')


with futures.ThreadPoolExecutor(max_workers=10) as executor:
    for _ in range(100):
        executor.submit(printer)

Context switching & Thread switch interval

The switch interval in Python specifies how long the Python interpreter will allow a Python thread to run, after which it is forced for a context switch.

Since only one thread runs at a time due to GIL, the interpreter tries to switch threads after this interval.

The default interval is 5 milliseconds.

>>> import sys
>>> sys.getswitchinterval()
0.005

We can set custom thread switch interval using sys.setswitchinterval

If the threads are waiting (e.g.: for IO operations) this switching allows for a parallel execution-like effect. If threads are running any CPU-bound operations, this context switch causes a performance penalty.

Eg: Network IO blocked tasks:

import time

import requests

start = time.perf_counter()
req1 = requests.get("https://reqres.in/api/users?delay=3")
req2 = requests.get("https://reqres.in/api/users?delay=3")
end = time.perf_counter()

print(end-start, " seconds") # 6.9710999 seconds

Using threads:

import threading
import time
import requests


def make_request():
    return requests.get("https://reqres.in/api/users?delay=3")


start = time.perf_counter()

t1 = threading.Thread(target=make_request)
t2 = threading.Thread(target=make_request)

t1.start()
t2.start()

t1.join()
t2.join()

end = time.perf_counter()

print(end-start, " seconds") # 3.494618 seconds

In case of CPU Blocked tasks:

import time

start = time.perf_counter()

s1 = sum(range(100000000))
s2 = sum(range(100000000))

end = time.perf_counter()

print(end-start, " seconds") # 3.8891145 seconds