DEV Community: Srujana Maddula

Introducing SerpApi's OpenCode Plugin

Srujana Maddula — Tue, 06 Oct 2026 10:03:36 +0000

OpenCode is an open-source, model-agnostic AI coding agent that runs locally on your machine. It can edit files, run terminal commands, and work across multiple repos at once. Because it's model-agnostic, a lot of developers pair it with local LLMs like Ollama or LM Studio, so their code and data never leave their machine.

But OpenCode can't search the web for live data unless you give it access. You can do that with the SerpApi OpenCode plugin. It gives OpenCode access to Google, YouTube, Amazon, Walmart, and dozens of other search engines through a single tool call.

What is an OpenCode Plugin?

Plugins and Skills sound similar, but they do different jobs. Skills automate boring workflows, tasks where you'd otherwise repeat the same instructions every time. Plugins give OpenCode a new capability it didn't have before, a new tool, feature, or integration with an outside service.

SerpApi has released one such plugin, giving OpenCode real-time web search. It provides access to multiple SerpApi engines like Google, Bing, Yahoo, YouTube, and many others. It also ships with skills that guide OpenCode in selecting appropriate engine and parameters for each query.

So when a task needs live web data, OpenCode reaches for the SerpApi plugin, runs the search, and returns the results. Say OpenCode needs to find a current public GitHub repository for a coding task. It searches for it with the SerpApi plugin instead of guessing from training memory.

Why Use SerpApi Opencode Web Search Plugin?

Without the plugin, giving OpenCode web access means building a separate API integration yourself: handling auth, setting parameters, and parsing responses.

The SerpApi OpenCode plugin replaces all of that with one integration. Install it once, and OpenCode gets dedicated access to specific engines and search verticals instead of just generic web search.

Here are some of the popular engines the plugin supports:

Vertical	Supported engines	Use cases
Web Search	Google, Bing, DuckDuckGo, Yahoo, Yandex, Baidu, Naver	Full-featured web search with knowledge graph, ads, and SERP extras
AI Search	Google AI Mode, Google AI Overview, Bing Copilot, Brave AI Mode	AI search results, brand monitoring in AI results, and AI-generated summaries
Shopping	Amazon, Walmart, eBay, Google Shopping, Home Depot	Product search, listings, and pricing
Local	Google Maps	Local business listings and place reviews
News & Trends	Google News, Google Trends	Current news articles and search trend data
Media	Google Images, Google Videos, Google Lens, YouTube	Image search, video search, reverse image search, and video rankings
Travel	Google Flights, Google Hotels, Google Travel Explore	Flight deals, hotel reviews, and travel destination search
Jobs, Finance & Apps	Google Jobs, Google Finance, Google Play, Apple App Store	Job search, stock tracking, finance data analysis, and app store data
SEO	Google Autocomplete	Keyword research

Each engine returns data shaped for the question you're asking. For instance, searching Amazon returns product listings and pricing in clean JSON. You also don't need to remember engine names or query formats. OpenCode picks the right engine and parameters based on the query.

Installing the OpenCode SerpApi Plugin

The OpenCode SerpApi plugin is available as an npm package, so setup is really just a config change plus an API key.

1. Add the plugin to your config

In your project root, open opencode.json (or opencode.jsonc). If neither file exists, create opencode.json. Then add opencode-serpapi to the plugin array:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-serpapi"]
}

Want it available across all your projects instead of just one? Add the same block to your global config at ~/.config/opencode/opencode.json instead.

OpenCode installs it automatically from npm the next time you run opencode in that project; doesn’t require a separate npm i command.

2. Set your SerpApi API key

Grab a key from your SerpApi dashboard and export it as an environment variable:

export SERPAPI_API_KEY="add_your_api_key"

3. Start OpenCode

On startup, OpenCode caches the plugin and registers the serpapi_search tool for your session.

Ask OpenCode something that needs a live web search, e.g.:

"Search Google for the latest news on the Fed rate decision"

It returns live search results, as shown in the image below:

OpenCode web search plugin

How OpenCode uses SerpApi under the hood?

The plugin has three parts, each with a clear job: a connection to SerpApi's MCP server, a native search tool as a backup, and a skill that tells OpenCode which search engine to use.

1. The MCP connection

When OpenCode starts, the plugin automatically registers SerpApi's hosted MCP server as a remote MCP server. You don't need to add it to your config by hand.

The plugin reads your SERPAPI_API_KEY environment variable and sends it as an Authorization: Bearer header with each request.

The server then checks the engine and its parameters, and runs the search. When OpenCode doesn't need the full JSON, it sets the engine's output parameter to Markdown, which uses about half the tokens for the same task.

2. The serpapi_search fallback

If the MCP server isn't available, OpenCode can still search. The plugin exposes a native serpapi_search tool that calls SerpApi's search.json endpoint directly, using the runtime's built-in fetch. The tool takes a single q argument and maps it to the field each engine expects.

3. The serpapi-web-search skill

The connection gives OpenCode access to various engines. The skill tells it which one fits the task, using bundled routing guidance and engine reference files.

Ask OpenCode to find standing desks under $300 on Walmart, and the skill points it to the Walmart engine and its parameters. Without it, OpenCode might run a generic Google search and get blog posts and ads instead of product listings.

Conclusion

This SerpApi plugin makes web search a native capability for OpenCode. It's open source, and setup just takes a config change and an API key.

Check out theGitHub repo if you want to see how it's built, report an issue, or request a feature.

We are continuing to expand SerpApi integrations to make sure AI can access live search data, whether that is through MCP, Claude Code, and many other AI integrations. If you dont find a SerpApi integration for the tool you work in, contact us at contact@serpapi.com

How to Give Hermes Agent Real-Time Web Search Results

Srujana Maddula — Sat, 26 Sep 2026 16:57:05 +0000

Ask an AI agent about something that happened this morning, a stock price, a breaking headline, or a product launch. Without access to real-time data, it either admits it doesn't know or, worse, gives you a confident answer that is completely wrong.

That's the problem with AI agents that can't access the live web: they only know what the model learned during training. Hermes Agent's built-in web tools solve this. They let Hermes access live web data and use it for research, real-time monitoring, and scheduled tasks.

In this post, I'll walk you through how to connect Hermes Agent to real-time web search, how its web tools work, and a few practical use cases.

What is Hermes Agent?

Hermes Agent is an autonomous AI agent that isn't tied to any IDE. You can run it on your laptop for local tasks or host it on a virtual server so it keeps running around the clock.

Hermes has a built-in learning loop. It creates and updates its own skills as it works through your requests. Say you ask it to build a Python chatbot. To do that, it might create files, edit code, run tests, and fix whatever breaks along the way. Hermes then turns what it learns from that process into a skill it can reuse later.

A week later, when you ask it to add a feature or deploy the app as a Docker container, it won't make you re-explain your stack from scratch. It recalls the project context from its persistent memory and reuses the skill it built the first time around. Over time, this compounds, every session adds to what Hermes knows about your setup, preferences, and workflows, so its understanding keeps deepening with each conversation.

Hermes Agent works anywhere. Connect it to Slack, Telegram, WhatsApp, or your terminal. You can start a conversation on Telegram, and pick it up later from your Mac. If you host it on an always-on server, you can chat over WhatsApp or trigger a workflow via Slack, even when your laptop is off.

How do Hermes Agent web tools work?

Hermes Agent has two web tools: web_search and web_extract. The web_search tool searches the web and gives the search results to the agent, while web_extract extracts the web page content and provides that context to Hermes Agent.

Basically, Hermes Agent exposes these tools to the AI model. The model then decides when to call a tool, passes in a search query, gets the results back, and uses those results in the next steps of the task.

For example, say you ask Hermes, “What are the latest AI trends?”. The model sees that web_search tool is available, along with the arguments "query" and "limit".

The "limit" parameter defines the maximum number of search results the tool returns in a single call. "query" is the search query (whether that's the original user's query or an agent-refined query) that gets passed to the search provider.

The model then generates a structured tool call, something like this:

{
  "name": "web_search",
  "arguments": {
    "query": "latest AI agent developments",
    "limit": 5
  }
}

Hermes Agent then executes this tool call. Each result comes back with a title, URL, description, and position in the ranking.

For this to work, you need to configure Hermes Agent with a backend provider that performs the actual search and returns the results. SerpApi offers 250 free searches per month. So you can configure web_search to use SerpApi, and whenever Hermes Agent makes that tool call, SerpApi searches the web and returns the results to the agent.

Hermes Agent also ships with browser tools. Suppose you need to fill in a form to get the content, click a button to go to the next page, or scroll to load more content. Hermes provides tools like browser_navigate, browser_snapshot, browser_click, browser_type, browser_scroll, and browser_vision.

browser_navigate opens the specified URL and initializes the browser session. Then browser_snapshot captures the interactive elements on the page and assigns them reference IDs, like @e1 and @e2. Hermes can then use those IDs with tools like browser_click or browser_scroll to interact with the page. Like web tools, you need to configure these browser tools with the supported backend providers like Browserbase, Browser Use, or others.

Choosing the right web search provider for Hermes Agent

You can configure the web_search and web_extract tools with any supported provider, and they don't have to be the same one. You could use one provider for search and another one for extraction. SerpApi, Firecrawl, Tavily, and Brave Search are some popular providers you can use with Hermes.

The main difference between providers is where the results come from and how they're shaped for the agent. SerpApi returns live results from Google, the same ones a person would see in their browser, instead of results from a separate search index. The SerpApi plugin also goes beyond general web search. It adds dedicated tools that Hermes picks automatically based on your request:

web_search uses the Google Light API for general queries, chosen for its compact responses and low latency.
serpapi_maps_search pulls Google Maps results with addresses, ratings, and review counts for queries like "coffee shops near me."
serpapi_news_search pulls Google News results with publishers and dates.
serpapi_shopping_search pulls Google Shopping results with prices and merchants.

Each tool returns only the fields Hermes needs, rather than a full raw response, which keeps the agent's context window lean. All four run on a single API key.

Backend search provider	`web_search`	`web_extract`	Free tier	Best for
SerpApi	Yes	No	250 free searches/month	Google Search, Maps, News, and Shopping results in Markdown format for AI applications
Firecrawl	Yes	Yes	500 credits/month	Generic research
Brave Search	Yes	No	2,000 queries/month	Lightweight generic search
Tavily	Yes	Yes	Keyless option	Pre-chunked, ready-to-use data for AI
Exa	Yes	Yes	Keyless free tier	Semantic search to find relevant web pages
Perplexity	Yes	Yes	Paid	Pre-summarized answers instead of raw pages

Power your Hermes AI agent with real-time web search

You should already have Hermes Agent installed before connecting it to web search. If you're on a Mac, install it with a simple curl command:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

It's also available on Windows or virtual servers. Follow this quick installation guide to install it in your preferred environment.

Once Hermes Agent is active, connect it to the open-source SerpApi plugin to give it real-time web search access.

Just go to Hermes chat mode and type:

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

Hermes Agent will install and configure the plugin for you. It then asks for your SerpApi API key. If you don't have one yet, sign up for a SerpApi account and get your API key from the dashboard. Once you have it, paste it into the terminal.

To see if it works, I asked, “What is the current NVIDIA stock price?” and it returned the price accurately for that day.

Hermes Agent real-time web search

It’s not just for one-off questions. You can also schedule recurring workflows using simple natural language prompts. For example, you can ask, “Give me news updates every morning,” and Hermes will create a cron job to run the workflow and deliver the updates to you every day.

Hermes Agent use cases

Hermes Agent handles everything from serious coding to creating bedtime stories for your kids. I've picked out a few use cases where Hermes excels.

AI research agent

Hermes Agent's web search and extraction tools let it search the web in real time, analyze the information, summarize content, and pull out key insights. The engine you point it at shapes the results. For a broad question, Hermes starts with SerpApi Google Search to find relevant pages. For academic topics, Google Scholar returns papers and citations. For anything that happened this week, Google News API surfaces recent coverage that general search results might bury.

So you can give Hermes a research task, and it can work through the web, gather information, and bring back the findings without you having to guide it through every step.

Competitor research

Freeze a watchlist of competitors, their domains, and a list of what you want to track: new hires, product launches, pricing changes, or major announcements. Then ask Hermes, “Every Monday morning, monitor these competitors and save the updates in a Markdown file.” Hermes Agent creates a cron job that runs this workflow automatically every Monday.

Cold outreach

Ask Hermes to scrape the internet for doctors in Boston, find leads who don’t have a website, and return 10 qualified leads to pitch your web development service.

Hermes spawns multiple parallel agents, scrapes Google Maps results, filters for qualified leads, then searches for their websites in Google Search, and returns their profiles and customized pitch angles for each of them.

Conclusion

SerpApi's Google Search, Maps, News, and Shopping APIs provide real-time data across web results, local places, breaking news, and product prices. Connect them through the SerpApi plugin, and Hermes pulls the live information it needs and provide that context to the LLM. Since SerpApi offers 250 free searches per month, set up the SerpApi plugin as your search provider and power Hermes Agent with real-time web access.

How to Scrape YouTube Channel Results Using a Simple API

Srujana Maddula — Fri, 25 Sep 2026 16:50:24 +0000

If you’re tracking YouTube channels for competitor research, content strategy, or creator partnerships, you probably want answers for: How often is a competitor uploading? Are shorter videos performing better? Is a creator’s subscriber count actually growing?

The data is all there on YouTube. But tracking all of it manually for multiple channels isn’t practical. That’s where scraping YouTube channel data can make the process much easier.

In this guide, I'll show how to use the SerpApi YouTube Channel API to scrape channel data. We’ll also look at what data you can collect and where to use it.

Scraping YouTube channel data with an API call

Step 1: Get an API key

Step 2: Send a GET request

Send a GET request to SerpApi with engine parameter set to youtube_channel and add the channel_id of the YouTube channel you want to scrape.

You have two options to get the channel_id. You can use the channel handle, which is the value you see after the @ in the YouTube channel URL. To target the SerpApi channel, for example, use serpapi.

Alternately, you can use the channel’s raw ID. These IDs start with UC, and you can find them on the channel page like in the below image. For example, this one is UCUgIHlYBOD3yA3yDIRhg_mg.

YouTube Channel ID

Once you have the channel ID, you can make a simple GET request to retrieve the channel data as JSON:

https://serpapi.com/search?engine=youtube_channel&channel_id=serpapi&api_key=YOUR_API_KEY

The response includes channel metadata in channel_results and a videos_results array containing the channel's videos. Here's what an abridged version of that response looks like:

{
  "search_metadata": {
    "id": "6aa77d5d3047f3a1de527a65",
    "status": "Success"
  },
  "channel_results": {
    "title": "SerpApi, LLC",
    "handle": "@serpapi",
    "description": "Access real-time results from Google and 100+ search engines with a simple API. No proxies, CAPTCHAs, or parsing required.",
    "external_id": "UCUgIHlYBOD3yA3yDIRhg_mg",
    "link": "https://www.youtube.com/channel/UCUgIHlYBOD3yA3yDIRhg_mg",
    "subscribers": 2840,
    "video_count": 186
  },
  "videos_results": [
    {
      "position": 1,
      "title": "Supercharge Your AI Agents with Live Google Search Results (in Markdown)",
      "link": "https://www.youtube.com/watch?v=beqoAVXz7iA",
      "video_id": "beqoAVXz7iA",
      "views": "23 views",
      "published_date": "7 hours ago",
      "length": "4:23"
    }
  ],
  "serpapi_pagination": {
    "next_page_token": "4qmFsgLZCRIYVUNVZ0lIbFlCT0Qz...",
    "next": "https://serpapi.com/search.json?channel_id=serpapi&engine=youtube_channel&next_page_token=4qmFsgLZCRIYVUNVZ0lIbFlCT0Qz..."
  }
}

Step 3. Explore API parameters

You can also play around with different parameters in the SerpApi Playground to see how the response changes, and build the request for your use case.

If you need more videos than the first page returns, you’ll find a page_token in the JSON response. Pass it to your next request and collect videos from the next page.

What YouTube Channel Data can you extract using this API?

If you send a request with default parameters, you’ll get the full JSON response with information about the channel and its videos as a list.

If you want to see the Shorts, Podcasts, Posts, or other tabs data on the channel, you just need to tweak the tab parameter to shorts, streams, podcasts, playlists, or others to get the data in those tabs.

YouTube tabs scraper

The overview below shows what information you’ll get for each of these tab results.

Field	What it contains
`channel_results`	Channel title, description, subscriber count, joined date, country, total views, and other channel information.
`videos_results`	Video position, title, description, views, length, and other video information.
`shorts_results`	Short position, title, link, views, and thumbnail details.
`streams_results`	Stream position, title, link, waiting users, scheduled time, length, published date, and views.
`podcasts_results`	Title, last updated information, episode count, and thumbnail details.
`playlists_results`	Playlist position, playlist ID, video count, link, and other playlist information.
`posts_results`	Post ID, author, text, published date, votes, attached video information, and other post details.

The API also supports a search_query parameter that let's you add the text that you would normally search for within a YouTube channel. It then returns the matching videos and playlists in the search_results field of the JSON response.

Scraping YouTube Playlist Results

Let’s look at some code examples to scrape YouTube channel data. We’ll tweak the tab parameter to scrape playlist results from any YouTube channel.

Using Python

import serpapi

client = serpapi.Client(api_key="SerpApi_API_KEY")

results = client.search(
    {
        "engine": "youtube_channel",
        "channel_id": "serpapi",
        "tab": "playlists"
    }
)

playlists = results.get("playlists_results", {})

for playlist in playlists:
    print("Position:", playlist.get("position"))
    print("Playlist:", playlist.get("title"))
    print("URL:", playlist.get("link"))
    print("Last updated:", playlist.get("last_updated"))
    print("Number of videos:", playlist.get("video_count"))
    print("---")

This example prints the playlist’s position on the channel, the playlist link, when it was last updated, and the number of videos in the playlist. You can also modify the code to save the results to an Excel file or CSV.

Scrape YouTube playlist results in Python

For YouTube search results instead of just channel results, check out our tutorial on how to scrape YouTube data in Python.

Using Ruby

require 'serpapi'

client = SerpApi::Client.new(api_key: "SerpApi_API_KEY")

results = client.search(
  engine: "youtube_channel",
  channel_id: "serpapi",
  tab: "playlists"
)

playlists = results[:playlists_results] || []

playlists.each do |playlist|
  puts "Position: #{playlist[:position]}"
  puts "Playlist: #{playlist[:title]}"
  puts "URL: #{playlist[:link]}"
  puts "Last updated: #{playlist[:last_updated]}"
  puts "Number of videos: #{playlist[:video_count]}"
  puts "---"
end

Output:

Scrape YouTube playlist results in Ruby

What can you do with YouTube Channel Data?

YouTube is the second most visited search engine and it has a goldmine of public data for analytics. On average, over 20 million videos get uploaded daily, with nearly 2.5 billion active users per month watching videos, subscribing to channels, and leaving their comments. You can use all this data to understand different channels or audience in your niche.

Build competitor monitoring tools: Schedule a regular data extraction workflow to monitor your competitors’ subscriber growth, views, and compare them against yours.

Prepare data backed content strategy: Analyse your competitors’ top-performing Shorts, videos, or playlists. Look at their upload frequency, video length, and the number of episodes in their top-performing playlists, then use those insights to shape your content plan.

Research market trends: You can combine data across top channels and analyse their YouTube stats to get broader market trends in your niche.

Spend your collaboration budget wisely: You can extract the subscriber count, growth metrics, posting frequency, and audience engagement of potential creators, compare them, and pick the right one to collaborate with.

If you also need to scrape individual video details like the description, likes, and comments, here’s a full tutorial on the YouTube Video API.

Conclusion

YouTube is a valuable source of data for understanding a channel’s credibility, audience engagement, and video performance. In this blog, you saw how to use the YouTube Channel API to collect channel-level data with a simple API call.

SerpApi also provides other YouTube APIs for different use cases. For example, the YouTube Search API to scrape search results, the YouTube Video API to extract video details, and the YouTube Video Transcript API to extract video transcripts.

A Beginner’s guide to Instructor: Get Structured Outputs From LLMs

Srujana Maddula — Fri, 24 Apr 2026 13:31:11 +0000

LLM responses are unstructured text. That works fine when a human is reading the output. But when you need to feed it into an API, store it in a database, or pass it to another agent, you need specific fields, typed values, and a consistent structure.

Thinking about writing a JSON parser for this? The problem is the model returns unpredictable text. It might skip fields, add extra text, or change the structure across calls, and you can't build a parser for output you can't predict.

By the end of this tutorial, you'll know how to handle this using Instructor library. I'll also walk through a real-world use case so you can adapt it to your own projects.

What is Instructor and How Does it Work?

Instructor is an open-source Python library for getting structured output from LLMs. It supports many providers (OpenAI, Anthropic, Gemini, Ollama, DeepSeek, etc.) and guides them to return responses in a format you define.

Here's the basic flow:

You define your output format as a Pydantic model.
Instructor derives a schema from that model and includes it in the LLM request.
The model generates a response guided by that schema.
Instructor validates the response and maps it to your Pydantic model.
If validation fails, it retries with the error fed back to the model.

Install and Setup Instructor

Install Instructor using pip:

pip install instructor

This installs Instructor with the OpenAI client by default. If you're using a different provider, install the relevant extra:

pip install "instructor[anthropic]"    # Anthropic
pip install "instructor[google-genai]"    # Google/Gemini

Also, make sure you have these installed before you start:

Python 3.9+
Your model provider's client (e.g. openai, anthropic)
Python-dotenv (recommended to manage API keys)

Get Structured Outputs with Instructor and Pydantic Models

Say you're building a customer support ticket routing system. A user submits a query and you want to extract specific fields from it: the order ID, issue type, priority, and requested action, then pass them to your routing logic. That's the use case we'll build here.

1. Load your API key

To call OpenAI models, you need an API key. Get it from the OpenAI platform and store it in a .env file.

OPENAI_API_KEY=your_api_key_here

If you're using a different provider, store their API key here instead.

Then load it in your Python script:

from dotenv import load_dotenv  
load_dotenv()

2. Define a Pydantic Model

Instructor needs to know your expected output structure. You define that using a Pydantic model, a Python class with typed fields.

from pydantic import BaseModel  
from typing import Literal, Optional

class SupportTicket(BaseModel):
   order_id: Optional[str] = None
   issue_type: Literal["delivery_issue", "technical_issue", "billing_issue", "product_issue", "others"]
   priority: Literal["high", "low", "medium"]
   requested_action: Literal["refund", "support", "replacement", "status_check", "others"]

In this code, SupportTicket inherits from Pydantic's BaseModel. Literal restricts issue_type, priority, and requested_action fields to a fixed set of values, so if the model returns something outside that list, validation fails. Optional on order_id means it can be a string or None since not every ticket will have order ID information.

Pydantic converts these type hints into validation rules at runtime. If the LLM returns a field with the wrong type, Pydantic either coerces it to the right type or flags it as invalid, which triggers Instructor's retry mechanism.

3. Call the Model

To call the model, first patch the OpenAI client with Instructor:

client = instructor.from_openai(OpenAI())

Then call client.chat.completions.create() with one addition: response_model=SupportTicket.

result = client.chat.completions.create(
   model="gpt-4o-mini",
   response_model=SupportTicket,
   messages=[
       {
           "role": "user",
           "content": "It says my account is disabled. Can you unlock it?"
       }
   ]
)

print(result)

The model generates a response, Instructor parses it into the SupportTicket schema and returns a validated SupportTicket instance. If parsing or validation fails, it feeds the error back to the model and retries.

Here's the full code together:

import instructor
from pydantic import BaseModel
from openai import OpenAI
from typing import Literal, Optional
from dotenv import load_dotenv

load_dotenv()


class SupportTicket(BaseModel):
    order_id: Optional[str] = None
    issue_type: Literal["delivery_issue", "technical_issue", "billing_issue", "product_issue", "others"]
    priority: Literal["high", "low", "medium"]
    requested_action: Literal["refund", "support", "replacement", "status_check", "others"]


client = instructor.from_openai(OpenAI())

result = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=SupportTicket,
    messages=[
        {
            "role": "user",
            "content": "It says my account is disabled. Can you unlock it?",
        }
    ],
)

print(result)

Output:

The model classified the query as a technical issue with high priority, set the requested action to support, and left order_id empty since no order was mentioned. That's a usable object your routing logic can act on directly.

What to Explore Next

This tutorial covered the basics, but there's more to Instructor. A few things worth adding to your implementation:

Error handling: API calls can fail for a number of reasons: network issues, invalid API keys, or hitting the token limit. Wrap your calls in try/except blocks and handle each failure case with a clear error message so your app doesn't break silently.
Retry limits: Set the max_retries parameter to control how many times Instructor retries before giving up. Pick a reasonable number that gives the model enough attempts to handle vague queries without burning through tokens.
System prompts: A system prompt is how you tell the model who it is and what it's supposed to do. Without one, the model just sees the user message and the schema with no context. For simple queries that's fine, but for vague inputs like "I need help" the model starts guessing. Adding something like "You are a support ticket classifier. Extract structured information from the user's message." tells the model exactly how to interpret the input and keeps classification consistent across different queries.
Nested models: Once you're comfortable with flat models, try nesting Pydantic models inside each other. For example, a SupportTicket model can include a nested CustomerDetails model and a list of IssueMetadata entries.

For more advanced topics, check out Pydantic AI to build type-safe agents. If you're focused on OpenAI specifically, learn how to integrate the ChatGPT API into your Python projects and work with structured data.