Building real agents

Recipes for the question everyone asks next: "OK, but how do I ship something useful?" Every example below uses only the public API — Agent, @tool, handoffs, mcp — glued to the outside world with ordinary webhook code.

A WhatsApp agent

NobelAgentic doesn't care where messages come from. Point any webhook at an Agent and reply with the result. Here's a WhatsApp support agent using the WhatsApp Cloud API and FastAPI:

import os, httpx
from fastapi import FastAPI, Request
from nobelagentic import Agent, tool

@tool
def order_status(order_id: str) -> dict:
    """Look up an order's status and ETA by its ID."""
    r = httpx.get(f"https://api.yourshop.com/orders/{order_id}",
                  headers={"Authorization": f"Bearer {os.environ['SHOP_API_KEY']}"})
    return r.json()

agent = Agent(
    "You are the support agent for YourShop. Be warm and brief — "
    "answers go to WhatsApp, so no markdown, short paragraphs.",
    tools=[order_status, "time"],
)

app = FastAPI()
WA_TOKEN = os.environ["WHATSAPP_TOKEN"]
PHONE_ID = os.environ["WHATSAPP_PHONE_ID"]

@app.post("/webhook")
async def webhook(req: Request):
    data = await req.json()
    msg = data["entry"][0]["changes"][0]["value"]["messages"][0]
    reply = agent.run(msg["text"]["body"])
    httpx.post(
        f"https://graph.facebook.com/v21.0/{PHONE_ID}/messages",
        headers={"Authorization": f"Bearer {WA_TOKEN}"},
        json={"messaging_product": "whatsapp", "to": msg["from"],
              "text": {"body": str(reply)}},
    )
    return {"status": "ok"}

That's the whole bot. The same shape works for Telegram, Slack, Discord, SMS via Twilio — swap the webhook parsing and the send call.

Any third-party API as a tool

A tool is just a function. Type hints and the docstring become the schema the model sees, so wrapping any SDK or REST API is one decorator:

import httpx
from nobelagentic import Agent, tool

@tool
def search_crm(query: str) -> list:
    """Search customers in the CRM by name or email."""
    return httpx.get("https://api.crm.example.com/search",
                     params={"q": query}).json()

@tool
async def create_ticket(title: str, body: str, priority: str = "normal") -> dict:
    """Open a support ticket. Priority: low, normal, or urgent."""
    async with httpx.AsyncClient() as c:
        r = await c.post("https://api.ticketing.example.com/tickets",
                         json={"title": title, "body": body, "priority": priority})
        return r.json()

agent = Agent("You handle inbound support requests end to end.",
              tools=[search_crm, create_ticket])

agent.run("jane@acme.co says checkout is broken — file an urgent ticket")

Sync and async functions both work. Raise an exception and the model sees the error message and can recover.

A support team with handoffs

Split responsibilities across agents and let a triage agent route:

from nobelagentic import Agent

billing = Agent("You resolve billing questions. You can issue refunds up to $50.",
                name="billing", tools=[search_crm, "math"])
tech    = Agent("You debug technical issues. Ask for error messages early.",
                name="tech", tools=[create_ticket, "web"])

triage = Agent(
    "Classify the user's problem and hand off to billing or tech immediately. "
    "Never answer yourself.",
    name="triage",
    handoffs=[billing, tech],
)

result = triage.run("I was charged twice for my subscription this month")
print(result.agent, "→", result.output)   # billing → ...

Third-party services via MCP

Anything with an MCP server — GitHub, Postgres, Stripe, your own internal tools — plugs in without writing a wrapper:

Agent("You triage bug reports into GitHub issues.",
      mcp=["github"])                                  # registry name

Agent("You answer questions about our production data. Read-only.",
      mcp=["postgres"])

Agent("...", mcp=["https://mcp.yourcompany.com/mcp"])  # any remote server

Register a server once with nobelagentic mcp add myserver "npx -y some-mcp-server" and every project can use it by name.

TypeScript: a Telegram bot

The TypeScript package has the same API. A long-polling Telegram bot, no framework needed:

import { Agent, tool, z } from "nobelagentic";

const fx = tool({
  name: "fx_rate",
  description: "Current exchange rate between two currencies",
  parameters: z.object({ from: z.string(), to: z.string() }),
  execute: async ({ from, to }) =>
    (await fetch(`https://api.frankfurter.app/latest?from=${from}&to=${to}`)).json(),
});

const agent = new Agent("You are a concise personal finance assistant.", {
  tools: [fx, "math", "time"],
});

const API = `https://api.telegram.org/bot${process.env.TELEGRAM_TOKEN}`;
let offset = 0;
while (true) {
  const { result } = await (await fetch(`${API}/getUpdates?timeout=30&offset=${offset}`)).json();
  for (const u of result) {
    offset = u.update_id + 1;
    if (!u.message?.text) continue;
    const reply = await agent.run(u.message.text);
    await fetch(`${API}/sendMessage`, {
      method: "POST", headers: { "content-type": "application/json" },
      body: JSON.stringify({ chat_id: u.message.chat.id, text: String(reply) }),
    });
  }
}

Keeping context between messages

Chat platforms deliver one message at a time. Every run accepts history= — the full typed transcript, tool calls included — and returns the updated one on the result:

sessions: dict[str, list] = {}          # user_id → message history

def handle(user_id: str, text: str) -> str:
    result = agent.run(text, history=sessions.get(user_id))
    sessions[user_id] = [m for m in result.messages if m.role != "system"]
    return str(result)

Swap the dict for Redis in production and you have a stateful bot today. First-class sessions — agent.run(text, session="user-123") with pluggable storage — land in v0.2 (see the roadmap).