Giving PydanticAI Agents an Event Mailbox with FetchHook

PydanticAI is excellent for structured agentic logic, but handling real-time webhooks in an ephemeral agent loop is difficult. FetchHook provides the persistent 'Inbox' that your PydanticAI agents need to react to external events.

PydanticAI Tool Definition

python

from pydantic_ai import Agent, RunContext
import requests

agent = Agent('openai:gpt-4o', deps_type=MyDeps)

@agent.tool
def check_for_webhooks(ctx: RunContext[MyDeps]) -> str:
    """Check the FetchHook mailbox for new events like payments or alerts."""
    r = requests.get(f"https://api.fetchhook.app/api/v1/{ctx.deps.stash_id}", 
                     headers={"Authorization": f"Bearer {ctx.deps.api_key}"})
    return str(r.json())

#How do I trigger PydanticAI from a webhook?

Instead of trying to host a listener inside your PydanticAI agent, give the agent a 'tool' to check its mailbox. This aligns with the 'Thinking' phase of PydanticAI: the agent can decide when it needs to check for new external events (e.g., 'Is there any new feedback from the user via the Typeform webhook?').

#The Asynchronous Agent Pattern

Because FetchHook stashes events for 24 hours, your PydanticAI agent doesn't need to be running continuously. You can spin up the agent on a schedule or in response to a user prompt, have it check the mailbox, process all pending events with its structured logic, and then exit.

Agent Protocol Instruction

When using PydanticAI, define the FetchHook check as a tool. This allows the model to autonomously determine if external context (from webhooks) is required to complete its current task.