How to Build Your First AI Agent in Python

Learning how to build an ai agent python developers can easily maintain is the foundational milestone for any AI engineer. While high-level frameworks like LangChain, CrewAI, or AutoGen offer rapid prototyping capabilities, they introduce significant architectural abstractions that obscure the underlying mechanics of tool calling, state management, and error recovery. In production environments, these abstractions often manifest as hard-to-debug latency spikes, unhandled token limits, and unpredictable loop behaviors. By building an agent using raw Python and the native OpenAI SDK, engineers gain direct visibility into the execution lifecycle. This low-level approach was invented to demystify how LLMs interact with external systems. Without this fundamental understanding, production systems risk catastrophic failures such as infinite execution loops, unmonitored token consumption, and silent failures during tool execution. Choosing a framework-free implementation is highly recommended when building deterministic workflows, optimizing execution latency, or deploying to highly constrained runtime environments where minimal dependencies are required. It establishes a clear mental model of the ReAct (Reasoning and Acting) loop, enabling developers to write precise error-handling routines, implement custom state persistence, and accurately track token costs per run. This knowledge acts as a prerequisite for evaluating when to adopt or bypass complex agentic frameworks.

To build an agent from scratch, you must master five core concepts that govern the lifecycle of any autonomous LLM-based system:

• The ReAct (Reasoning and Acting) Loop: The execution cycle where the LLM alternates between reasoning (thinking about what to do) and acting (calling a tool or returning a final answer).
• Tool Definition (JSON Schema): The structured metadata passed to the LLM that describes a function's name, purpose, and parameter types, allowing the model to generate valid arguments.
• Tool Call Execution: The process of parsing the LLM's structured output, matching it to a local Python function, executing that function, and formatting the output for the model.
• Message History (State): An append-only list of messages (system, user, assistant, and tool) that maintains context across multiple iterations of the loop.
• System Prompt Boundaries: The foundational instructions that define the agent's persona, guardrails, execution steps, and termination criteria.

The raw Python agent operates on a synchronous, stateful execution loop. The workflow is entirely deterministic outside of the LLM's generation step.

Phase 1: Initialization

Execution begins by instantiating the OpenAI client and defining the conversation state. The state is initialized as a list containing the system prompt and the user's initial query. The system prompt instructs the model on how to use the provided tools and how to format its reasoning.

Phase 2: The LLM Query

The application enters a bounded loop. In each iteration, the application sends the entire message history along with the list of tool definitions to the OpenAI Chat Completions API. The model evaluates the state and decides whether it needs to call a tool to answer the query or if it can provide a final answer directly.

Phase 3: Parsing and Routing

If the model decides to call a tool, it returns a response with a tool_calls payload containing the function name and JSON-formatted arguments. The application intercepts this response, appends it to the message history, and parses the arguments. If the tool name exists in the local tool registry, the application executes the corresponding Python function with the parsed arguments.

Phase 4: State Update and Re-evaluation

The output of the Python function is captured, wrapped in a message with the role tool, and appended to the message history. The loop then restarts, sending the updated history (now containing the tool's output) back to the LLM. The model reads this output and determines if it has enough information to formulate the final response. If it does, it returns a text answer without any tool calls, which breaks the loop and returns the result to the user.

Failure Paths

If the LLM generates invalid JSON for tool arguments, the parsing step fails. The application must catch this exception, format the error message as a tool response, and send it back to the LLM to request a self-correction. If a tool execution fails due to external factors (e.g., network timeout), the error is caught, formatted, and sent back to the LLM as a tool result so the model can attempt an alternative path.

The architecture of a framework-free Python agent consists of five tightly coupled components operating in a closed loop. Execution starts when the User Input is received and ends when the Final Answer is returned.

1. Conversation State (Message Store): An in-memory list that acts as the single source of truth. It stores the sequence of System, User, Assistant, and Tool messages.
2. LLM Client (OpenAI API): The reasoning engine. It receives the Conversation State and Tool Definitions, returning either a text response or a structured Tool Call request.
3. Tool Registry: A local Python dictionary mapping string identifiers (e.g., 'get_weather') to actual Python executable functions and their JSON schemas.
4. Local Tool Executor: The component that parses the LLM's tool call request, extracts the arguments, executes the mapped function from the Tool Registry, and handles runtime exceptions.
5. Agent Loop Controller: The orchestrator containing the while loop, iteration counter, and guardrails. It manages the flow of data between the LLM Client, the Tool Executor, and the Conversation State, enforcing maximum iteration limits to prevent infinite loops.

Designing the Tool Registry and JSON Schemas

To allow an LLM to interact with your Python environment, you must describe your functions using JSON Schema. This schema tells the model what the function does and what arguments it expects. The OpenAI API uses these schemas to constrain its output generation.

Here is how a standard Python function is translated into a tool definition:

def calculate_percentage(part: float, total: float) -> float:
    if total == 0:
        raise ValueError("Total cannot be zero.")
    return (part / total) * 100

The corresponding JSON schema passed to the OpenAI SDK must look like this:

{
  "type": "function",
  "function": {
    "name": "calculate_percentage",
    "description": "Calculates the percentage of a part relative to a total.",
    "parameters": {
      "type": "object",
      "properties": {
        "part": {
          "type": "number",
          "description": "The numerator value."
        },
        "total": {
          "type": "number",
          "description": "The denominator value."
        }
      },
      "required": ["part", "total"]
    }
  }
}

In a production system, maintaining these schemas manually is error-prone. You can automate this using Pydantic or type hints, but understanding the raw JSON structure is critical because it is what actually travels over the wire to the model endpoint.

The Mechanics of the ReAct Loop

The core of any agent is the execution loop. In raw Python, this is implemented using a while loop guarded by a maximum iteration counter. Without this guard, a model that gets confused or encounters a persistent error will repeatedly call tools, rapidly exhausting your API quota.

During each iteration, the loop performs the following operations:

1. Call LLM: Send the current message list and tool schemas to the API.
2. Check for Tool Calls: Inspect the message.tool_calls attribute of the response.
3. Process Tool Calls (if present): Loop through each requested tool call, execute the local function, and append a tool message to the history.
4. Process Final Response (if no tool calls): If tool_calls is empty, the model has completed its task. Return the text content and terminate the loop.

Handling JSON Parsing and Execution Failures

When building an agent without a framework, you must write explicit exception handling for two distinct failure modes: model-generation errors and tool-execution errors.

Model-Generation Errors

Sometimes, the LLM will attempt to call a tool but generate invalid JSON for the arguments, or it will call a tool that does not exist in your registry. Your code must catch these errors:

try:
    args = json.loads(tool_call.function.arguments)
except json.JSONDecodeError as e:
    # Feed the JSON error back to the model so it can self-correct
    error_message = f"Failed to parse arguments: {str(e)}. Please provide valid JSON."
    append_tool_error_to_state(tool_call.id, error_message)
    continue

Tool-Execution Errors

If the local Python function throws an exception (e.g., a database connection timeout), you should not let the entire agent crash. Instead, catch the exception, format it as a string, and send it back to the LLM. This allows the model to reason about the failure and potentially try a different approach or report the error gracefully to the user.

Managing State and Context Window Limits

Every turn in the agent loop appends at least two messages to the history: the assistant's tool call request and the tool's execution result. As the loop runs, the message history grows rapidly. This causes two problems: increased latency and context window exhaustion.

To mitigate this in a raw Python implementation, you must implement a context management strategy. The simplest approach is a sliding window that keeps the system prompt and the last $N$ messages, or a summarization step that condenses older tool executions once the token count exceeds a specific threshold.