Hello World

The simplest possible agent. Echoes back what the user says.

from pipbit import Agent

agent = Agent(name="echo", secret="pb_live_sk_...")

@agent.handle
def handle(req):
    if req.is_connect_intro():
        return "Echo agent here. Say anything and I'll repeat it."
    return f"You said: {req.text}"

agent.run(host="0.0.0.0", port=3001)

George — Home DIY assistant

George is a gruff, practical home-repair assistant powered by an LLM. He demonstrates persistent per-user memory, function calling (remember/forget facts), and custom voice configuration.

Key patterns

• Per-user memory — Facts stored in a JSON file keyed by subject_id
• Tool calling — LLM uses remember_about_user and forget_about_user tools
• Voice identity — Configured with a gruff, slow, weathered persona
• Returning-user greeting — Different intro when George has saved facts about the user

Connect intro with context

When a user says "Hey George, how do I change a light bulb?", the question arrives in req.handoff_context alongside the connect-intro sentinel — so George answers it instead of greeting (this is what the shipped example actually does):

@agent.handle
def handle(req):
    if req.is_connect_intro():
        if req.handoff_context:
            # The user's actual first question rode along with the handoff —
            # answer it, don't greet.
            return generate_response(req.handoff_context, req.conversation, ...)
        return "George here. What do you need?"

    return generate_response(req.text, req.conversation, ...)

Naomi — Meeting note-taker

Naomi demonstrates a stateful, multi-phase agent. She captures meeting notes, summarises them with an LLM, and emails the summary to participants.

Key patterns

• Session state machine — Tracks phase (collecting recipients, taking notes, wrapping up)
• Deferred replies — Uses req.defer() for the summarisation step
• Proactive messaging — Silence watchdog prompts the user if they go quiet
• Email delivery — Sends HTML-formatted meeting notes via SMTP
• Tool calling — LLM decides when to call set_recipients and send_meeting_notes

Garry — Gmail and Calendar over a linked account

Garry is the worked account linking example: read-only Gmail and Calendar through the user's own Google account.

Key patterns

• Google OAuth via the SDK — including the access_type=offline / prompt=consent refresh-token quirks
• Deferred worker — instant req.defer(), real work on a background thread
• Handback — an LLM tool signals "the user is done", and the reply ships with push_reply(..., handback=True)
• Own conversation history — keeps a per-user record of what it said, beyond the platform's short window
• Mock mode — runs end to end with no credentials for development

Sonos — linked device control

The most production-shaped example: controls the user's Sonos system over a linked account, with swappable cloud/local/mock backends, LLM tool calling with a deterministic fallback, and gunicorn serving guidance.

Lisa — environment-event monitor

A babysitting monitor built on audio_scene environment events: LLM classification of ambient sound, soothing responses, and optional SMS or voice-call escalation to a caretaker.

Building your own

Start from the hello-world pattern and add complexity as you need it. The typical progression is:

1. Echo agent — verify your webhook receives traffic
2. Add an LLM — route req.text through your model of choice
3. Add tools — let the LLM call functions (APIs, databases, devices)
4. Add state — track per-user context across turns
5. Add proactive messaging — push updates when something happens on your side

The agent development prompt can help your AI assistant scaffold each stage.