Build Your First AI Agent with Python

import json
from typing import Any

from openai import OpenAI


MODEL = "gpt-5-mini"
MAX_TOOL_ROUNDS = 5

client = OpenAI()


def calculate_project_cost(
    hours: float,
    hourly_rate: float,
) -> dict[str, float]:
    """Calculate the estimated cost of a project."""

    if hours <= 0:
        raise ValueError("hours must be greater than zero")

    if hourly_rate <= 0:
        raise ValueError("hourly_rate must be greater than zero")

    return {
        "hours": hours,
        "hourly_rate": hourly_rate,
        "total": round(hours * hourly_rate, 2),
    }


TOOLS = [
    {
        "type": "function",
        "name": "calculate_project_cost",
        "description": (
            "Calculate the estimated project cost from working hours "
            "and an hourly rate."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "hours": {
                    "type": "number",
                    "description": "Estimated number of working hours.",
                },
                "hourly_rate": {
                    "type": "number",
                    "description": "Cost per working hour.",
                },
            },
            "required": ["hours", "hourly_rate"],
            "additionalProperties": False,
        },
        "strict": True,
    }
]


def execute_tool(
    name: str,
    arguments: dict[str, Any],
) -> dict[str, Any]:
    """Execute one approved tool."""

    if name == "calculate_project_cost":
        return calculate_project_cost(
            hours=float(arguments["hours"]),
            hourly_rate=float(arguments["hourly_rate"]),
        )

    raise ValueError(f"Unknown tool: {name}")


def run_agent(user_goal: str) -> str:
    """Run a small agent until it returns a final answer."""

    response = client.responses.create(
        model=MODEL,
        instructions=(
            "You are a project-estimation assistant. "
            "Use the calculator tool for cost calculations. "
            "Never estimate arithmetic mentally when the tool can be used. "
            "Ask for missing information instead of inventing it. "
            "Explain the final result clearly and concisely."
        ),
        input=user_goal,
        tools=TOOLS,
    )

    for _ in range(MAX_TOOL_ROUNDS):
        tool_calls = [
            item
            for item in response.output
            if item.type == "function_call"
        ]

        if not tool_calls:
            return response.output_text

        tool_outputs: list[dict[str, str]] = []

        for tool_call in tool_calls:
            try:
                arguments = json.loads(tool_call.arguments)

                result = execute_tool(
                    name=tool_call.name,
                    arguments=arguments,
                )

                output = json.dumps(
                    {
                        "ok": True,
                        "result": result,
                    }
                )

            except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
                output = json.dumps(
                    {
                        "ok": False,
                        "error": str(exc),
                    }
                )

            tool_outputs.append(
                {
                    "type": "function_call_output",
                    "call_id": tool_call.call_id,
                    "output": output,
                }
            )

        response = client.responses.create(
            model=MODEL,
            previous_response_id=response.id,
            input=tool_outputs,
            tools=TOOLS,
        )

    raise RuntimeError(
        "Agent stopped because the maximum number of tool rounds was reached."
    )


if __name__ == "__main__":
    goal = (
        "A project needs 42 hours of work at an hourly rate "
        "of 85 euros. Calculate the estimated cost and explain it."
    )

    try:
        answer = run_agent(goal)
        print(answer)
    except Exception as exc:
        print(f"Agent failed: {exc}")