andrewyng--aisuite/examples/agents/agent_api_quickstart.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# aisuite Agent API quickstart\n",
        "\n",
        "This notebook shows the smallest useful shape for creating agents with aisuite.\n",
        "\n",
        "The core idea is intentionally small:\n",
        "\n",
        "```python\n",
        "agent = ai.Agent(...)\n",
        "result = ai.Runner.run_sync(agent, \"...\")\n",
        "```\n",
        "\n",
        "Set `OPENAI_API_KEY` before running the model-backed cells."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import os\n",
        "from IPython.display import Markdown, display\n",
        "\n",
        "import aisuite as ai"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 1. Create a basic agent\n",
        "\n",
        "Start with just a name, model, and instructions. Then pass the agent and a user message to `Runner.run_sync`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "if not os.getenv(\"OPENAI_API_KEY\"):\n",
        "    display(Markdown(\"`OPENAI_API_KEY` is not set. Set it and rerun this cell.\"))\n",
        "else:\n",
        "    agent = ai.Agent(\n",
        "        name=\"quickstart_assistant\",\n",
        "        model=\"openai:gpt-4o-mini\",\n",
        "        instructions=\"Be concise and practical.\",\n",
        "    )\n",
        "\n",
        "    result = ai.Runner.run_sync(\n",
        "        agent,\n",
        "        \"Explain aisuite agents in one friendly sentence.\",\n",
        "    )\n",
        "\n",
        "    display(Markdown(result.final_output))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 2. Add a Python function as a tool\n",
        "\n",
        "Tools can be plain Python functions. The agent can call them when they help answer the user."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "def get_city_fact(city: str) -> str:\n",
        "    \"\"\"Return one short fact about a city.\"\"\"\n",
        "    facts = {\n",
        "        \"san francisco\": \"San Francisco is known for the Golden Gate Bridge and steep hills.\",\n",
        "        \"new york\": \"New York City has five boroughs and one of the world's busiest subway systems.\",\n",
        "        \"seattle\": \"Seattle is known for coffee, rain, and views of Mount Rainier.\",\n",
        "    }\n",
        "    return facts.get(city.lower(), f\"I do not have a saved fact for {city}.\")\n",
        "\n",
        "if not os.getenv(\"OPENAI_API_KEY\"):\n",
        "    display(Markdown(\"`OPENAI_API_KEY` is not set. Set it and rerun this cell.\"))\n",
        "else:\n",
        "    city_agent = ai.Agent(\n",
        "        name=\"city_fact_assistant\",\n",
        "        model=\"openai:gpt-4o-mini\",\n",
        "        instructions=\"Use the city fact tool when the user asks for a city fact.\",\n",
        "        tools=[get_city_fact],\n",
        "    )\n",
        "\n",
        "    tool_result = ai.Runner.run_sync(\n",
        "        city_agent,\n",
        "        \"Use the tool to tell me one fact about San Francisco.\",\n",
        "    )\n",
        "\n",
        "    display(Markdown(tool_result.final_output))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 3. Continue a conversation\n",
        "\n",
        "Use `Runner.continue_sync` when the user sends another message in the same conversation."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "if \"result\" not in globals():\n",
        "    display(Markdown(\"Run the basic agent cell first.\"))\n",
        "else:\n",
        "    next_result = ai.Runner.continue_sync(\n",
        "        result,\n",
        "        \"Now make that explanation even shorter.\",\n",
        "    )\n",
        "\n",
        "    display(Markdown(next_result.final_output))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## What this demonstrates\n",
        "\n",
        "- `Agent` defines behavior, model, and optional tools.\n",
        "- `Runner.run_sync` runs the agent for a user message.\n",
        "- `Runner.continue_sync` continues from a prior result.\n",
        "- You can start simple and add tools only when needed.\n",
        "\n",
        "For observability and local viewer examples, see `local_observability_demo.ipynb`."
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "pygments_lexer": "ipython3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}