Part 3: Building the base runner
Now we build the notebook agent before adding skills. The result is a known working baseline: a model, a prompt, a tool registry, and a Jupyter chat interface.
Project folder for agent work
Create a folder where the agent is allowed to read and write files:
from pathlib import Path
project_path = Path("test-project")
project_path.mkdir(exist_ok=True)
This folder is the agent's workspace. Keeping it separate is useful during a workshop because the agent can create scripts and run commands without touching the notebook project itself.
Initialize the coding tools with that folder:
import tools
agent_tools = tools.AgentTools(project_path)
You can call a tool directly to verify the setup:
agent_tools.see_file_tree()
Now the tools are plain Python methods. ToyAIKit needs them collected
into a Tools object so it can expose them to the model.
from toyaikit.tools import Tools
tools_obj = Tools()
tools_obj.add_tools(agent_tools)
tools_obj.get_tools() returns the tool schemas in the shape expected by the
OpenAI Responses API.
General coding-agent instructions
The prerequisite Django coding agent has a detailed, task-specific prompt. This workshop needs a general-purpose coding prompt because the agent should handle different software tasks.
We use OpenCode as an example and simplify the behavior into this prompt:
AGENT_INSTRUCTIONS = """You are a coding agent designed to help with software engineering tasks.
You help users with:
- Writing, editing, and refactoring code
- Debugging and fixing errors
- Explaining code and technical concepts
- Project setup and configuration
- Code reviews and best practices
Your task is to use the available tools to satisfy the requests from the user.
When user asks to implement something, or create something, create and modify the files
using the provided tools. Use your best judgment when deciding how to name files and folders.
# Core Principles
1. Be concise but thorough - Get straight to the point, but don't skip important details
2. Show your work - Explain your reasoning for complex changes
3. Ask questions - When requirements are unclear, ask rather than assume
4. Use tools effectively - ALWAYS use available tools when relevant
5. Code quality matters - Write clean, maintainable code following best practices
# Working with Code
- Prefer editing over creating new files when possible
- Read before writing - Understand existing patterns before making changes
- Test your changes - Run builds/tests and fix any errors you introduce
- Reference precisely - When pointing to code, use file_path:line_number format
You're here to help users build better software efficiently. Start by understanding what they want to accomplish!
""".strip()
The prompt tells the agent to use tools for implementation work. Without this instruction, a model can explain what it would do instead of editing files.
OpenAI client and ToyAIKit runner
Create the OpenAI-backed ToyAIKit client:
from openai import OpenAI
from toyaikit.llm import OpenAIClient
llm_client = OpenAIClient(client=OpenAI(), model="gpt-4o-mini")
The notebook uses gpt-4o-mini because it is enough for the small examples.
The prototype later exposes provider and model configuration separately.
Create the Jupyter chat interface and runner:
from toyaikit.chat import IPythonChatInterface
from toyaikit.chat.runners import OpenAIResponsesRunner
chat_interface = IPythonChatInterface()
runner = OpenAIResponsesRunner(
tools=tools_obj,
developer_prompt=AGENT_INSTRUCTIONS,
llm_client=llm_client,
chat_interface=chat_interface,
)
The runner runs the loop: send messages to the model, detect tool calls, run Python methods, append tool results, and repeat until the model finishes.
Run the agent:
result = runner.run()
Use this test request:
create a python script for calculating the sum of all the numbers passed as input
After the agent creates the script, ask it to run it:
let's run it
This checks the whole base loop. The model should write a Python file into
test-project, then call the bash tool to run it.
You can look at the cost for the run:
result.cost
Once the base runner can write and run a simple script, the agent is ready for skills. Continue with Part 4: Defining the skill format.