My First AI Agent: Building with Python & OpenAI Assistants

Hey there, agent builders! Emma Walsh here, back from my little corner of the internet at agent101.net. Today, I want to chat about something that’s been buzzing around my brain (and my laptop) lately: getting started with AI agent development *without* needing a supercomputer or a PhD in theoretical physics. Specifically, I’m talking about building a simple, useful agent using a tool that’s probably already in your developer toolkit: Python, and a little help from OpenAI’s Assistants API.

I remember my first foray into AI agents. It felt like trying to climb Mount Everest in flip-flops. Every tutorial assumed I already knew what an LLM was, how to finetune a model, and the difference between an agent and a chatbot (hint: it’s all about autonomy and tools!). It was overwhelming, and honestly, a bit disheartening. I mean, I love a good challenge, but I also appreciate a clear path forward.

That’s why I’m so excited about the Assistants API. It’s not just another API; it’s a simplification layer that lets us focus on the *agentic* part of the agent – defining its purpose, giving it tools, and letting it figure out how to use them – rather than getting bogged down in the minutiae of prompt engineering or managing long conversation histories. It’s like having a skilled assistant who handles all the underlying complexity so you can focus on the high-level strategy. And for us beginners, that’s a massive win.

My “Aha!” Moment with the Assistants API

I’ve been tinkering with various AI tools for a while now, always looking for that sweet spot between power and approachability. I tried building agents from scratch with raw LLM calls, and while educational, it was… a lot of boilerplate. Managing context windows, parsing outputs, remembering past interactions – it quickly spiraled into a project management task rather than an AI development one.

Then, the Assistants API came along. I was skeptical at first. Another OpenAI product? Would it really be different? My “aha!” moment came when I was trying to build a simple “recipe planner” agent. My goal was straightforward: tell it what ingredients I had, and it would suggest a recipe. Easy, right?

With just raw LLM calls, I had to manually feed it the history of our conversation, ensure my prompts were perfectly structured to extract the ingredients, and then figure out how to make it *search* for recipes. It felt clunky. With the Assistants API, I defined an Assistant, gave it a simple instruction, and then, crucially, I taught it how to use a “tool” – in this case, a mock function that would simulate looking up recipes.

The Assistant suddenly had a brain *and* hands. It could understand my request, realize it needed to use its “recipe lookup” tool, call that tool with the right ingredients, and then interpret the results. It was like magic, but it was just good abstraction. And that, my friends, is what makes it perfect for us.

Why the Assistants API is Your Beginner’s Best Friend

Let’s break down why this API is such a game-changer for someone just starting out:

• State Management is Handled: You don’t need to manually pass the entire conversation history with each turn. The Assistant remembers! This is HUGE for building multi-turn interactions.
• Tool Use Abstraction: Defining functions (tools) that your agent can call is incredibly straightforward. You just describe the function, and the Assistant figures out when and how to use it.
• Persistent Assistants: You define an Assistant once, and it retains its instructions, models, and tools across multiple user interactions.
• Built-in File Handling: Need your agent to analyze a document? Upload it, link it, and the Assistant can access it. No more trying to cram an entire PDF into a prompt.
• Code Interpreter: This is the secret sauce for many powerful agents. Give your Assistant access to a Python interpreter, and it can write and execute code to solve problems, perform calculations, or analyze data.

This means you can focus on *what* you want your agent to do, rather than *how* to make the LLM do it. It’s a higher level of abstraction that empowers you to build more sophisticated agents sooner.

Building Your First “Smart Note-Taker” Agent: A Practical Tutorial

Let’s get our hands dirty. We’re going to build a simple “Smart Note-Taker” agent. Its job will be to take raw notes, summarize them, and if we ask it to, categorize them using a specific tool. This will demonstrate core Assistant API concepts: defining an Assistant, adding instructions, enabling a tool, and interacting with it.

What you’ll need:

• A Python environment (3.9+)
• An OpenAI API key
• The openai Python library (pip install openai)

Step 1: Setting Up Your Assistant

First, we need to initialize our client and create our Assistant. This is where we give it its personality and initial instructions.

import openai
import os
import json # For handling tool outputs

# Set your OpenAI API key
# It's best practice to load this from an environment variable
openai.api_key = os.getenv("OPENAI_API_KEY")

# 1. Define the tool our agent can use
# This function will simulate categorizing notes
def categorize_note_tool(note_content: str):
 """
 Categorizes the given note content into predefined categories.
 Available categories: 'Meeting Notes', 'Idea Brainstorm', 'Task List', 'Research', 'General'.
 """
 # In a real scenario, this would be a more sophisticated model or lookup
 # For this example, we'll do a simple keyword-based categorization
 note_content_lower = note_content.lower()
 if "meeting" in note_content_lower or "attendees" in note_content_lower:
 category = "Meeting Notes"
 elif "idea" in note_content_lower or "brainstorm" in note_content_lower or "concept" in note_content_lower:
 category = "Idea Brainstorm"
 elif "todo" in note_content_lower or "task" in note_content_lower or "action item" in note_content_lower:
 category = "Task List"
 elif "research" in note_content_lower or "study" in note_content_lower or "data" in note_content_lower:
 category = "Research"
 else:
 category = "General"
 return {"category": category, "original_note": note_content}

# Map tool names to their actual Python functions
available_functions = {
 "categorize_note_tool": categorize_note_tool,
}

# 2. Create the Assistant (or retrieve an existing one)
# I usually put this in a conditional to avoid creating new assistants every time I run the script
assistant_id = None # Set this if you have an existing assistant ID
if assistant_id:
 assistant = openai.beta.assistants.retrieve(assistant_id)
 print(f"Retrieved existing Assistant with ID: {assistant.id}")
else:
 assistant = openai.beta.assistants.create(
 name="Smart Note-Taker",
 instructions=(
 "You are a helpful note-taking assistant. "
 "Your primary goal is user-provided notes. "
 "If the user asks you to categorize a note, you should use the 'categorize_note_tool' to do so. "
 "Always aim for concise and clear summaries. "
 "If asked to categorize, always provide the category and then the summary."
 ),
 model="gpt-4o", # Or gpt-3.5-turbo, gpt-4-turbo, etc.
 tools=[
 {
 "type": "function",
 "function": {
 "name": "categorize_note_tool",
 "description": "Categorizes a given note content into predefined categories.",
 "parameters": {
 "type": "object",
 "properties": {
 "note_content": {
 "type": "string",
 "description": "The content of the note to be categorized."
 }
 },
 "required": ["note_content"]
 }
 }
 }
 ]
 )
 print(f"Created new Assistant with ID: {assistant.id}")
 # Save this ID for future use!
 # assistant_id = assistant.id

A few things to note here:

• We define a Python function categorize_note_tool. This is the *actual* logic.
• We then describe this function to the Assistant API in the tools array. This is how the LLM understands what the tool does, its name, and its parameters.
• The instructions are crucial. This is your agent’s overarching directive.

Step 2: Creating a Thread and Adding Messages

A “Thread” is a conversation session. Each user interaction happens within a thread.

# 3. Create a Thread for the conversation
thread = openai.beta.threads.create()
print(f"Created new Thread with ID: {thread.id}")

# 4. Add a user message to the Thread
user_note = (
 "Meeting with John and Sarah about the Q3 marketing strategy. "
 "Action items: 1. Draft email to sales team. 2. Prepare presentation slides. "
 "Discussed budget allocation for social media campaigns."
)
message = openai.beta.threads.messages.create(
 thread_id=thread.id,
 role="user",
 content=f"Please summarize this note: {user_note}"
)
print("User message added to thread.")

Step 3: Running the Assistant and Handling Tool Calls

This is the core interaction loop. We run the Assistant, check its status, and if it needs to call a tool, we execute that tool and feed the result back.

# 5. Run the Assistant
run = openai.beta.threads.runs.create(
 thread_id=thread.id,
 assistant_id=assistant.id
)
print(f"Assistant Run initiated with ID: {run.id}")

# 6. Polling loop to check run status and handle tool calls
while run.status != "completed":
 run = openai.beta.threads.runs.retrieve(
 thread_id=thread.id,
 run_id=run.id
 )
 print(f"Run status: {run.status}")

 if run.status == "requires_action":
 print("Assistant requires action (tool call).")
 tool_outputs = []
 for tool_call in run.required_action.submit_tool_outputs.tool_calls:
 function_name = tool_call.function.name
 arguments = json.loads(tool_call.function.arguments)
 
 print(f"Assistant wants to call function: {function_name} with args: {arguments}")
 
 if function_name in available_functions:
 function_to_call = available_functions[function_name]
 # Execute the function
 function_response = function_to_call(**arguments)
 print(f"Tool '{function_name}' responded: {function_response}")
 
 tool_outputs.append({
 "tool_call_id": tool_call.id,
 "output": json.dumps(function_response) # Output must be a string
 })
 else:
 print(f"Error: Function {function_name} not found.")
 tool_outputs.append({
 "tool_call_id": tool_call.id,
 "output": "Error: Function not found."
 })
 
 # Submit the tool outputs back to the Assistant
 run = openai.beta.threads.runs.submit_tool_outputs(
 thread_id=thread.id,
 run_id=run.id,
 tool_outputs=tool_outputs
 )
 elif run.status == "failed":
 print(f"Run failed: {run.last_error}")
 break
 elif run.status == "cancelled":
 print("Run cancelled.")
 break
 elif run.status == "expired":
 print("Run expired.")
 break
 
 # Small delay to avoid hammering the API
 import time
 time.sleep(1)

# 7. Retrieve and print messages after the run completes
if run.status == "completed":
 messages = openai.beta.threads.messages.list(
 thread_id=thread.id,
 order="asc" # Get messages in chronological order
 )
 
 print("\n--- Conversation History ---")
 for msg in messages.data:
 if msg.role == "user":
 print(f"User: {msg.content[0].text.value}")
 elif msg.role == "assistant":
 print(f"Assistant: {msg.content[0].text.value}")

Trying the Categorization

Now, let’s try asking it to categorize. We’ll add a new message to the *same thread*.

print("\n--- Testing Categorization ---")

# Add another message to the same thread, this time asking to categorize
message_categorize = openai.beta.threads.messages.create(
 thread_id=thread.id,
 role="user",
 content=f"Please categorize and summarize this note: 'Had a brilliant idea for a new blog post series about beginner AI agents. Need to outline topics and research keywords.'"
)

# Run the Assistant again on the updated thread
run_categorize = openai.beta.threads.runs.create(
 thread_id=thread.id,
 assistant_id=assistant.id
)
print(f"Categorization Run initiated with ID: {run_categorize.id}")

# Re-use the polling logic
while run_categorize.status != "completed":
 run_categorize = openai.beta.threads.runs.retrieve(
 thread_id=thread.id,
 run_id=run_categorize.id
 )
 print(f"Categorization Run status: {run_categorize.status}")

 if run_categorize.status == "requires_action":
 print("Assistant requires action (tool call) for categorization.")
 tool_outputs_categorize = []
 for tool_call in run_categorize.required_action.submit_tool_outputs.tool_calls:
 function_name = tool_call.function.name
 arguments = json.loads(tool_call.function.arguments)
 
 print(f"Assistant wants to call function: {function_name} with args: {arguments}")
 
 if function_name in available_functions:
 function_to_call = available_functions[function_name]
 function_response = function_to_call(**arguments)
 print(f"Tool '{function_name}' responded: {function_response}")
 
 tool_outputs_categorize.append({
 "tool_call_id": tool_call.id,
 "output": json.dumps(function_response)
 })
 else:
 print(f"Error: Function {function_name} not found.")
 tool_outputs_categorize.append({
 "tool_call_id": tool_call.id,
 "output": "Error: Function not found."
 })
 
 run_categorize = openai.beta.threads.runs.submit_tool_outputs(
 thread_id=thread.id,
 run_id=run_categorize.id,
 tool_outputs=tool_outputs_categorize
 )
 elif run_categorize.status == "failed":
 print(f"Categorization Run failed: {run_categorize.last_error}")
 break
 elif run_categorize.status == "cancelled":
 print("Categorization Run cancelled.")
 break
 elif run_categorize.status == "expired":
 print("Categorization Run expired.")
 break
 
 time.sleep(1)

# Retrieve and print messages after the categorization run completes
if run_categorize.status == "completed":
 messages_categorize = openai.beta.threads.messages.list(
 thread_id=thread.id,
 order="asc"
 )
 
 print("\n--- Categorization Conversation History ---")
 for msg in messages_categorize.data:
 if msg.role == "user":
 print(f"User: {msg.content[0].text.value}")
 elif msg.role == "assistant":
 print(f"Assistant: {msg.content[0].text.value}")

When you run this, you’ll see the Assistant first summarize your meeting notes. Then, when you ask it to categorize the blog post idea, it will pause, call your categorize_note_tool, get the “Idea Brainstorm” category back, and then deliver both the category and a summary!

This might seem like a lot of code, but the *logic* of building the agent is relatively simple: define, instruct, and provide tools. The boilerplate is just handling the API interaction – something you’ll get used to quickly.

Beyond the Basics: What’s Next for Your Agents?

Once you’ve got this down, the world opens up. Here are a few ideas for where to go next:

Real Tools, Real Impact

Our categorize_note_tool is basic. Imagine if it connected to:

• A Notion/Evernote API: To actually save categorized notes.
• A calendar API: To schedule follow-up meetings from action items.
• A CRM: To log interactions with clients.

That’s where agents go from cool demos to truly helpful allies.

The Power of the Code Interpreter

I didn’t use the code interpreter in our example, but it’s incredibly powerful. Imagine an agent that:

• Analyzes a CSV file you upload and generates charts.
• Writes and executes Python code to perform complex calculations based on your input.
• Debugs simple code snippets you provide.

Just enable "code_interpreter": {} in your Assistant’s tools array, and the LLM will decide when to write and run code.

Refining Instructions and Prompt Engineering

While the Assistants API handles a lot, your initial instructions are still key. Experiment with different phrasings, clarify ambiguities, and tell your agent what its “persona” should be. For instance, “You are a highly efficient and concise assistant” versus “You are a friendly and verbose assistant.”

Actionable Takeaways for Aspiring Agent Builders

Alright, before I sign off, here are my top three takeaways for anyone looking to dip their toes into AI agent development with the Assistants API:

1. Start Small, Think Big: Don’t try to build Skynet on your first try. Pick a tiny, clear problem – like our note-taker – and iterate. Once you understand the mechanics, you can swap out simple tools for more complex, real-world integrations.
2. Embrace the “Tool-First” Mindset: The real power of agents isn’t just their ability to talk, but their ability to *do*. Think about what actions your agent needs to perform. Can it search a database? Send an email? Generate an image? Each of these can be a “tool.”
3. Read the Docs (Seriously!): The OpenAI Assistants API documentation is actually pretty good. It covers concepts like messages, runs, steps, and file handling in detail. A quick read-through can save you hours of head-scratching.

Building AI agents might seem daunting, but with tools like the OpenAI Assistants API, the barrier to entry has never been lower. You don’t need to be a machine learning expert; you just need to be a curious developer ready to experiment. So go forth, build your first agent, and let me know what amazing things you create!

Happy building,

Emma Walsh

agent101.net

🕒 Published: April 15, 2026