IT wizard

Assistants vs. Agents: Exploring Two Approaches to the OpenAI API

12.03.2025

When diving into the OpenAI API documentation, you'll notice there are two main ways to interact with the service. In previous examples, we focused on "assistants," which use API version 2—a feature still in beta. Alongside that, there's another option: the Agent SDK, a Python-based toolkit. Both approaches share some similarities, but depending on your needs, the Agent SDK can sometimes be simpler.

Assistants vs. Agents

  • Assistants (API v2 in Beta)
    Designed for generating conversational responses. They focus on advanced dialogue features and leverage the latest (though still evolving) API capabilities.

  • Agent SDK (Python)
    A Python-based toolkit that streamlines tasks like semantic search, conversation handling, and more. Because it's built in Python, it can integrate easily with existing Python projects.

Semantic Search with the Agent SDK

Curious about how to get started with semantic search using the Agent SDK? Below is an example of the simplest case scenario. With just a few lines of code, you can query your documents by semantic similarity, returning the most relevant chunks of text based on your user's query.

from agents import Agent, FileSearchTool, Runner, WebSearchTool
import asyncio
from agents import set_default_openai_key
set_default_openai_key("sk-proj-......")
agent = Agent(
     name="Assistant",
     tools=[
          FileSearchTool(
               max_num_results=3,
              vector_store_ids=["vs_....."],
          ),
     ],
)
async def main():
     result = await Runner.run(agent, "How to add user to administrators?")
     print(result.final_output)

if __name__ == "__main__":
     asyncio.run(main())

In this snippet, we initialize an Agent with our API key, provide a list of documents, and then perform a semantic search. The results object will contain chunks of text ranked by their relevance to the query.

Which Approach Should You Choose?

  • Assistants
    If you need complex conversational features or want to experiment with the newest releases (knowing they may still be in beta), assistants might be the right path.

  • Agents
    If you're comfortable with Python and prefer a straightforward integration—especially for tasks like semantic search—the Agent SDK can be a quick win.

In many cases, the best choice depends on your project requirements and how much control you need over the conversation flow or data retrieval. Both methods can be used side-by-side, so don't hesitate to experiment and find the right balance for your use case!

The link to the code is here: https://github.com/jaroslavcech/aiblog/blob/main/09OpenAIVectorStore.py. If you have any questions or suggestions, feel free to contact me.


Share