ספריית Pydantic AI היא ספריית פיתוח סוכנים בפייתון אגנוסטית למודל. מבחינה רעיונית היא לוקחת את הפשטות מ OpenAI Agents SDK ואת הגמישות והפתיחות להתחבר לכל הספקים מ LangGraph. ב 12 הימים הקרובים אפרסם פה 12 מדריכים קצרים לבניית סוכנים עם הספריה.

מעבר להנאה בעבודה עם Pydantic AI נרצה לשים לב לרעיונות הבסיסיים בפיתוח סוכנים: הפעלת כלים, קבלת פלט מובנה, לולאת הסוכן, דפי הוראות, פרמטרים ספציפיים למודל ועוד. כל דוגמה מציגה רעיון או שיטת עבודה שיעזרו גם אם תכתבו את הסוכן שלכם בספריה אחרת.

הסוכנים לכל הדוגמאות כבר עלו לגיטהאב בריפו:

https://github.com/ynonp/pydanticai-demos

כך שתוכלו להוריד את הפרויקט ולהריץ עם המדריכים.

1. מה אנחנו בונים

אני מחלק סוכנים חכמים לשני סוגים - יש סוכנים אינטרקטיביים שמנהלים שיחות עם משתמשים או מבצעים פעולות לאורך זמן, ויש תהליכי עבודה שעולים, מבצעים פעולה מסוימת או סדרה של פעולות ומסיימים.

דוגמאות של תהליכי עבודה יהיו: תהליך עבודה שמנקה את תיבת המייל שלכם מדואר לא מעניין, תהליך שעולה כל בוקר ושולח תקציר חדשות יומי, תהליך שמופעל בתגובה להודעה נכנסת ומתחיל לקודד פיצ'ר ובסוף ישלח PR, תהליך שמופעל בתגובה לאימייל נכנס ומשיב לאותו מייל.

דוגמאות של סוכנים אינטרקטיביים יהיו: תיבת שיחה בצד של מערכת שמאפשרת להפעיל את המערכת בממשק שיחה ולא רק דרך ה GUI, סוכן קידוד שכותב קוד ומאפשר לכם לתקשר איתו דרך פרומפטים, ממשק השיחה של ChatGPT או קלוד.

בדוגמה של היום נבנה תהליך עבודה אג'נטי שמופעל מסקריפט בצורה יזומה משורת הפקודה. התהליך מקבל כתובת של מאמר באינטרנט, מושך את הטקסט ממנו ומבקש ממודל שפה לכתוב 10 שאלות על המאמר כדי לעזור לנו ללמוד אותו.

2. פתיחת פרויקט Pydantic AI חדש

אני יוצר פרויקט פייתון חדש עם uv. הכלי uv הוא הדרך המודרנית לעבוד עם סביבות וירטואליות בפייתון ואם עדיין אין לכם אותו מותקן תצטרכו להתקין אותו בנפרד מכאן:

https://docs.astral.sh/uv/

אחרי התקנת uv אני נכנס לתיקיה חדשה ריקה ומפעיל:

$ uv init

פקודה זו יוצרת בתיקייה מבנה של פרויקט uv ריק עם קובץ pyproject.toml המתאר את התלויות של הפרויקט. אני מוסיף את התלויות שאני צריך לפרויקט עם הפקודה:

$ uv add pydantic-ai python-dotenv trafilature

אחרי הפעלת הפקודה הקובץ pyproject.toml נראה כך:

[project]
name = "01-testme-agent"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14.3"
dependencies = [
    "pydantic-ai>=2.0.0",
    "python-dotenv>=1.0.0",
    "trafilatura>=2.1.0",
]

ולידו נוצר לי גם קובץ uv.lock שמתאר את הגרסאות שהותקנו וכל התלויות שלהן כולל גרסאות. הספריה trafilature היא ספריית פייתון שלוקחת קובץ HTML ומוציאה ממנו את הטקסט הראשי.

החלק השני של אתחול הפרויקט הוא החשוב. ספריית pydantic ai מגיעה עם Agent Skill שזה בעצם דפי התיעוד של הספריה בצורה ידידותית לסוכני קידוד. אפשר לקרוא על הסקיל כאן:

https://pydantic.dev/docs/ai/overview/coding-agent-skills/

אני מתקין את הסקיל עם הפקודה:

$ npx skills add pydantic/skills

ואחרי ההפעלה בוחר להתקין את building-pydantic-ai-agents ואם צריך גם את התמיכה בקלוד קוד. אחרי ההתקנה תוכלו לראות את התיעוד של הספריה בתיקיית .agents/skills ובתיקיית .cladue/skills.

בנקודה הזאת כבר אפשר לכתוב לקלוד קוד פרומפט כמו "תכתוב לי סוכן ב pydantic ai שלוקח URL למאמר, לוקח את הטקסט שלו עם trafilatura ובעזרת Gemini יוצר לי 10 שאלות הבנה לגביו". בואו נראה את הקוד שיכול היה להיווצר.

3. מימוש הפונקציה שמורידה את המאמר

את הקוד כולו אני (או קלוד) כותב בקובץ main.py הפונקציה הראשונה שם לוקחת url ומחזירה את הטקסט של המאמר שבו:

def fetch_article(url: str) -> str:
    """Download a URL and extract its main text content."""
    downloaded = trafilatura.fetch_url(url)
    if downloaded is None:
        raise RuntimeError(f"Could not download: {url}")
    text = trafilatura.extract(downloaded)
    if not text:
        raise RuntimeError(f"Could not extract article text from: {url}")
    return text

זאת פונקציית פייתון רגילה, סינכרונית, שבסך הכל קוראת לשתי פונקציות מתוך trafilatura, פונקציית fetch_url שמורידה דף ו extract שמחזירה את הטקסט הראשי ממנו.

4. יצירת הסוכן

הפונקציה השניה היא כבר יותר מעניינת והיא משתמשת בספריית הסוכנים:

def build_agent() -> Agent:
    provider = GoogleProvider(api_key=os.environ["GEMINI_API_KEY"])
    model = GoogleModel("gemini-3-flash-preview", provider=provider)
    return Agent(
        model,
        instructions=(
            "You are a teacher. Given the text of an article, write exactly 10 "
            "comprehension questions that test whether a reader understood it. "
            "Cover the main ideas and key details. Output a numbered list (1-10), "
            "one question per line, and nothing else."
        ),
    )

פידנטיק AI מגדירה 3 אבסטרקציות: Provider, Model ו Agent.

פרוביידר מייצג את הקשר לספק מודלים מסוים, מודל מייצג את המודל בתוך אותו ספק ו Agent מייצג את הלוגיקה של העבודה. כל התוכנית תעבוד עם Agent ולכן היא אגנוסטית לבחירת המודל או הספק.

מפתח הגישה GEMINI_API_KEY מוגדר במשתנה סביבה בקובץ .env אותו לא העליתי לריפו. בשביל להריץ את הסוכן תצטרכו ליצור מפתח גישה בעצמכם ולשמור אותו בקובץ .env בתיקיה של הסוכן.

סוכן ב Pydantic AI מקבל פרמטר instructions שמייצג את הוראות המערכת הבסיסיות לעבודה. בדוגמה הראשונה ההוראות הן ליצור 10 שאלות הבנה.

5. חיבור הכל לפונקציית main

עכשיו שיש את שתי הפונקציות אפשר לחבר את שתיהן בפונקציית main שתריץ את התהליך:

def main():
    if len(sys.argv) != 2:
        print(f"Usage: {sys.argv[0]} <article-url>")
        sys.exit(1)

    load_dotenv()
    url = sys.argv[1]

    article = fetch_article(url)
    agent = build_agent()
    result = agent.run_sync(article)
    print(result.output)


if __name__ == "__main__":
    main()

אנחנו מוודאים שקיבלנו URL, טוענים את משתני הסביבה מקובץ .env, לוקחים את ה URL לפונקציה הראשונה, בונים סוכן ומפעילים את פונקציית הסוכן:

result = agent.run_sync(article)

בדוגמאות הבאות נראה יכולות נוספות של סוכנים לדוגמה את התמיכה בהפעלה אסינכרונית. בסיום אפשר להדפיס את הפלט שהסוכן החזיר ולראות את השאלות.

6. עכשיו אתם

רוצים ללמוד באמת ולא רק לקרוא? הדרך הכי טובה היא לקחת את התוכנית ולהרחיב אותה. הנה כמה רעיונות:

1. הריצו את התוכנית ובדקו שאתם מקבלים שאלות הבנה טובות על מאמרים מהרשת.

2. הוסיפו סוכן דירוג שפועל לפני סוכן יצירת השאלות שתפקידו להבין אם הטקסט בכלל מעניין ובכלל יש מה לשאול עליו. אם סוכן הדירוג יגיד שהטקסט לא מספיק טוב לא נעביר בכלל את המאמר לסוכן יצירת השאלות.

3. את הדבר שסוכן יצירת השאלות החזיר שמרתי במשתנה result והדפסתי רק את שדה output שלו. הדפיסו את ה result המלא. מה עוד יש בו?