AI Agents & Chatbots – AI GUY in LA

This build delivers a support/billing agent you can actually ship. It follows Brain+Hands separation, explicit tool contracts, a deterministic state machine, and secure backend tools. Stack: WordPress (frontend), Python FastAPI (tools + orchestrator), Redis (state/cache), Postgres (KB + logs), vector DB (memory), OpenAI/Groq/Anthropic (LLM).

1) Architecture overview
– Brain (LLM policy): Plans, chooses tools, reasons. No direct DB/API access.
– Hands (tools): Idempotent HTTP endpoints with strict schemas. Observable, rate-limited, auditable.
– Orchestrator: State machine controlling turns, tool calls, retries, and timeouts.
– Memory:
– Short-term: per-session scratchpad (Redis).
– Knowledge: vector search over product docs/FAQ.
– Facts: authoritative store lookups (billing, orders).
– Guardrails: auth, PII redaction, tool allowlist, cost/time budgets, circuit breakers.
– Integration: WordPress plugin sends chat events to orchestrator; streaming tokens back to UI.

2) Contracts first (make tools boring and safe)
Define JSON schemas for every tool. Keep them narrow, idempotent, and testable.

Example tool manifest (slice):
{
“name”: “get_order_status”,
“description”: “Return current order state for a given order_id.”,
“method”: “POST”,
“url”: “https://api.example.com/tools/get_order_status”,
“input_schema”: {
“type”: “object”,
“properties”: {
“order_id”: {“type”: “string”, “pattern”: “^[A-Z0-9-]{6,}$”}
},
“required”: [“order_id”],
“additionalProperties”: false
},
“output_schema”: {
“type”: “object”,
“properties”: {
“status”: {“type”: “string”},
“updated_at”: {“type”: “string”, “format”: “date-time”}
},
“required”: [“status”]
},
“timeouts_ms”: 2500,
“retries”: 1
}

3) Hands: secure Python FastAPI tools
– Enforce schema at the edge.
– Require JWT with narrow scopes.
– Add rate limits and audit logs.

from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel, Field
import time

app = FastAPI(title=”SupportAgentTools”)

class OrderReq(BaseModel):
order_id: str = Field(min_length=6, pattern=r”^[A-Z0-9-]{6,}$”)

class OrderResp(BaseModel):
status: str
updated_at: str | None = None

def auth(scope: str):
def _auth(token=Depends(…)): # your JWT dependency
if scope not in token.scopes:
raise HTTPException(403, “forbidden”)
return token.sub
return _auth

@app.post(“/tools/get_order_status”, response_model=OrderResp)
def get_order_status(req: OrderReq, _=Depends(auth(“order:read”))):
start = time.time()
# query read replica; maintain SLO use respective tools.
– General product usage -> retrieve_docs.
– Anything else -> answer concisely or ask a clarifying question.

6) Orchestrator: a small, reliable state machine
States:
– RECEIVE -> PLAN -> EXECUTE_TOOL? -> OBSERVE -> RESPOND -> END

Pseudo:
def handle_turn(msg, session_id):
budget = Budget(tokens=3000, tools=3, wall_ms=8000)
state = “PLAN”
memory = load_session(session_id)
while budget.ok() and state != “END”:
if state == “PLAN”:
action = llm_policy(memory, tool_manifest)
if action.type == “tool”:
state = “EXECUTE_TOOL”
else:
state = “RESPOND”
elif state == “EXECUTE_TOOL”:
result = call_tool(action.name, action.args, timeout=manifest[action.name].timeouts_ms)
record_observation(result)
state = “OBSERVE”
elif state == “OBSERVE”:
memory.update_with_observation(result)
if need_more_tools(result): state = “PLAN”
else: state = “RESPOND”
elif state == “RESPOND”:
reply = llm_response(memory)
emit_stream(reply)
state = “END”

Controls:
– Max 2 tool calls/turn for latency.
– Tool circuit breaker after 2x p95 failures.
– Token + time budgets enforced per turn.

7) Retrieval that doesn’t hallucinate
– Chunk docs to 300–500 tokens with overlap 50–100.
– Store title, URL, product tags, and last_updated.
– Rerank top 20 -> 5 with a fast cross-encoder or LLM-judge at small context.
– In answers, include “According to ()” and quote minimal lines. – Evict stale docs with last_updated TTL checks. 8) Error handling and fallbacks – Tool error classes: 4xx user-fixable (show guidance), 5xx transient (retry with jitter), timeout (offer manual escalation). – If tools unavailable, switch to knowledge-only mode and surface a status note to the user. – Log: request_id, user_hash, tool_calls, latencies, token_usage, model, success_flag. 9) WordPress integration (plugin sketch) – Shortcode [aiguy_chat] renders chat UI. – Frontend calls /wp-json/aiguy/v1/chat (nonce protected). – Server proxy signs JWT to orchestrator and streams chunks back. PHP (very abbreviated): add_action(‘rest_api_init’, function () { register_rest_route(‘aiguy/v1’, ‘/chat’, [‘methods’=>’POST’,’callback’=>’aiguy_chat’,’permission_callback’=>’__return_true’]); }); function aiguy_chat(WP_REST_Request $r) { $jwt = make_scoped_jwt([‘aud’=>’orchestrator’,’scopes’=>[‘chat:send’]]); $resp = wp_remote_post(‘https://agent.example.com/chat’, [ ‘headers’=>[‘Authorization’=>”Bearer $jwt”], ‘body’=>[‘session_id’=>get_session_id(), ‘message’=>$r->get_param(‘message’)], ‘timeout’=>15 ]); return rest_ensure_response(wp_remote_retrieve_body($resp)); } 10) Models and performance – Use fast model for planning (e.g., gpt-4o-mini, llama-3.1-70b-instruct via Groq) and a stronger model for final generation when needed. – Target p95 < 2.5s single-turn with 0–1 tool; < 4.5s with 2 tools. – Cache retrieval and deterministic tool schemas to reduce tokens. 11) Security checklist – Tool allowlist + strict JSON schemas. – JWT with narrow scopes + rotation. – PII redaction before logs; encrypt sensitive fields at rest. – Separate read/write tools; require user confirmation for writes. – Rate limit per IP/user/session; WAF on tool API. 12) Observability – OpenTelemetry spans: plan, tool call, observe, generate. – Emit metrics: latency p50/p95, tool error rate, deflection rate, CSAT. – Log all prompts/responses with redaction; enable replay in a sandbox. 13) Deployment – Dockerize orchestrator + tools. Separate autoscaling for tools with spiky I/O. – Blue/green deploy; health checks include LLM warmup and tool canary. – Backpressure: queue requests when model or DB under load; shed load gracefully with a user-facing “email me results” fallback. 14) Minimal smoke test – Happy path: “Where is my order ABC123?” – Tool timeout path: inject 2s delay; verify graceful message. – Hallucination guard: ask for unavailable feature; ensure denial with doc citation. Deliverables you can ship this week – Tool API (FastAPI) with 3 tools: get_order_status, get_invoice_pdf, retrieve_docs. – Orchestrator with state machine, budgets, and streaming. – WordPress plugin with nonce-protected REST route and basic chat UI. – Vector index with top 20 support articles and citations in answers. – Dashboards: latency, tool errors, deflection, cost. </div> </article> <article id="post-240" class="post-240 post type-post status-publish format-standard has-post-thumbnail hentry category-ai-agents-chatbots"> <h1 style="margin-bottom: 20px; color: var(--primary);">Shipping a Production-Ready Support Agent (Brain + Hands) with WordPress Frontend and Django Backend</h1> <div class="entry-content"> This post shows how to ship a real support agent that answers questions and takes actions (tickets, refunds, account checks) using a WordPress frontend and a Django/Celery backend. It follows a Brain + Hands architecture with strict contracts, scalable orchestration, and production safety. Use case – Customer support assistant for ecommerce SaaS – Must answer FAQs, retrieve orders, open tickets, issue refunds (with approval), and post internal notes to Slack – Runs in WordPress, backed by a Django API and Celery workers – Auditable, rate-limited, and fault-tolerant Architecture (Brain + Hands) – Brain (policy/planner): – LLM with tool calling and JSON schema guarantees – Tasks: classify intent, plan minimal actions, call tools, summarize results, ask for approval when needed – Prompt enforces allowed tools, budgets, and safety – Hands (tools/microservices): – shopify_get_order, zendesk_create_ticket, stripe_issue_refund, slack_post_message, knowledge_search – Each is an HTTP endpoint or Python function with strict IO schema, timeouts, retries, and idempotency – Orchestrator: – Django REST API receives messages, persists state in Postgres – Celery workers execute tool calls with backoff and circuit breakers – Redis for short-lived state and rate limiting – pgvector for semantic memory and knowledge embeddings – Frontend (WordPress): – Minimal plugin posts chat turns to /api/agent/messages – Streams token output back via SSE or polling – Observability: – Structured events (message, tool_invocation, tool_result, error, approval_request) – OpenTelemetry traces tagged with case_id/session_id Core data models – Conversation: id, user_id, channel, created_at – Turn: id, conversation_id, role (user/ai/tool/system), content, tokens_in/out, cost_estimate, tool_name, tool_args, tool_result_ref, error – Memory: – episodic_memory (Redis, TTL 24h, last 20 turns) – semantic_memory (Postgres+pgvector): id, embedding, text, source, tags – business_facts (YAML/JSON in Postgres or S3): SLAs, refund_policy, playbooks Tool contract (example) – Tool: shopify_get_order – Input schema: { order_id: string } – Output schema: { order_id: string, status: string, items: [{sku, qty, price}], customer_email: string, created_at: string } – Timeouts: 3s connect, 10s total – Retries: 2 with jittered backoff – Idempotency-Key: conversation_id + turn_id + tool_name + hash(args) – Tool: stripe_issue_refund – Input: { charge_id: string, amount_cents: integer, reason: enum[requested_by_customer, duplicate, fraudulent] } – Output: { refund_id: string, status: enum[pending,succeeded,failed] } – Requires approval: true when amount_cents > 10000 System prompt (abbreviated) – Role: You are the Support Agent Brain. You can call only the registered tools. Always return JSON conforming to the response schema. Use the minimal set of tools to resolve the user’s request. Ask for approval before irreversible actions or refunds > $100. – Policies: Do not invent data. If a tool fails twice, escalate with a clear message and log error. Respect budgets: max 2 tools per turn, max 800 output tokens. – Memory: Retrieve top 5 knowledge_search contexts when the question is informational. For account-specific questions, attempt shopify_get_order first if the user provides an order id or email. Response envelope (from Brain to Orchestrator) – type: either “final_message” or “tool_call” – tool_call: { name: string, arguments: JSON } – final_message: { text: string, citations?: [source_ids], approvals_needed?: [{action, reason, suggested_args}] } Orchestration flow 1) Intake: POST /api/agent/messages {conversation_id, user_text, session_meta} 2) Retrieve episodic context (Redis) + semantic memory (pgvector top-k) 3) Brain call with tools manifest and context 4) If tool_call: – Enqueue Celery task hands.execute with idempotency – On success/failure, write Turn with tool_result/tool_error – Re-enter Brain with tool_result to continue the plan 5) If approvals_needed: – Emit approval card to WordPress, pause plan until POST /api/agent/approvals 6) Final_message streams to WordPress 7) Log events, update analytics, enforce cost limits Safety and guardrails – Least privilege API keys per tool; no cross-tool credential reuse – PII redaction before logging; encrypt at rest for sensitive payloads – Circuit breaker per tool: open after 5 errors/60s; degrade gracefully to “ticket only” – Human-in-the-loop for refunds > $100 and any failed KYC/AVS signals – Output verification: validate Brain JSON against schema before executing WordPress integration (minimal) – Frontend: a shortcode [ai_support_chat] renders a chat box – JS posts to /api/agent/messages with wp_nonce and user_id – SSE endpoint /api/agent/stream?conversation_id=… streams tokens – Admin settings: backend_base_url, api_key, streaming_on, approvals_webhook_url – Webhook: when approval requested, WP shows an approval card with Approve/Deny that hits /api/agent/approvals Backend routes (Django REST) – POST /api/agent/conversations -> {conversation_id} – POST /api/agent/messages -> creates Turn; triggers orchestrator; returns stream_url – GET /api/agent/stream -> SSE tokens with event types: chunk, tool, approval, end – POST /api/agent/approvals -> {conversation_id, turn_id, approved: bool, notes} – POST /api/agent/tools/callback (optional for async tools) – POST /internal/ingest-knowledge -> upsert documents and embeddings Memory strategy – Short-term: last 8-12 relevant turns (Redis) – Long-term: semantic facts and resolved tickets (pgvector, cosine; k=5-8) – Business facts: YAML playbooks (refund thresholds, outage responses) loaded into prompt header; versioned and cachable – Eviction: TTL for episodic; archive older embeddings monthly Error handling patterns – Tool execution: – Try/except with structured errors {type, message, retriable} – Retry retriable up to 2x; otherwise escalate with user-safe message – LLM failures: – If schema invalid, repair with a “validator-repair” pass (cheap model) then continue – Fallback model if primary degraded – Timeouts: – Brain call: 20s; tools: 10s; overall turn SLA: 30s – Idempotency: dedupe by (conversation_id, user_turn_id) Cost and performance controls – Cache knowledge answers for 30 minutes keyed by question hash – Compress history to summaries after 10 turns – Token budgets: truncate context to budget; prefer citations over long paraphrases – Batch embeddings; upsert via COPY for large loads – Prefer JSON mode/tool calling models to reduce hallucinations and token waste Deployment notes – Containers: nginx (TLS) | django (gunicorn) | celery-worker | celery-beat | redis | postgres+pgvector – Env: ENV=prod, OPENAI_API_KEY, SHOPIFY_KEY, ZENDESK_KEY, STRIPE_KEY, SLACK_TOKEN, WORDPRESS_SHARED_SECRET – Migrations enable pgvector: CREATE EXTENSION IF NOT EXISTS vector; – Health checks and liveness probes for each service – Backups: Postgres daily; object storage for logs and embeddings – Observability: OpenTelemetry + OTLP exporter; dashboards for token usage, tool error rate, approval queue age Example tool manifest (Brain-visible) – name: “shopify_get_order” – description: “Fetch an order by id or customer email. Use before refunding.” – input_schema: { order_id?: string, customer_email?: string } (at least one required) – name: “zendesk_create_ticket” – input_schema: { subject: string, body: string, requester_email: string, priority: enum[low,normal,high] } – name: “stripe_issue_refund” – input_schema: { charge_id: string, amount_cents: integer, reason: enum[requested_by_customer,duplicate,fraudulent] } – approvals: “required if amount_cents > 10000” – name: “knowledge_search” – input_schema: { query: string, top_k: integer } Quick test plan – Happy path: “Refund order 1234 for $50.” -> fetch order -> approval not needed -> refund -> confirm – Approval path: “Refund $200.” -> approval card rendered -> approve -> refund -> confirm – Failure path: Shopify outage -> circuit open -> create Zendesk ticket with context -> notify user – Informational: “What’s the SLA?” -> knowledge_search -> cite policy doc What to log per turn – latency_ms, model, tokens_in/out, cost_estimate_usd – user_intent, selected_tools, retry_count – approval_required, approval_decision_time – tool_errors and circuit state When to ship – You have passing e2e tests for the four test paths above – Tool timeouts and retries verified – Approval flow exercised in staging WordPress – Dashboards show stable p95 latencies and <2% tool error rate over 48 hours This pattern is production-ready, debuggable, and safe. You can extend it with more tools (CRM, shipping) without changing the Brain contract—just register new Hands with schemas and policies. </div> </article> <article id="post-226" class="post-226 post type-post status-publish format-standard has-post-thumbnail hentry category-ai-agents-chatbots"> <h1 style="margin-bottom: 20px; color: var(--primary);">Shipping a Production-Ready WordPress Support Agent (Brain + Hands, Secure Tools, Real Logs)</h1> <div class="entry-content"> This post walks through a production-ready support agent for a WooCommerce WordPress site. It follows a Brain + Hands architecture, uses secure tool calls, and ships with observability and guardrails. The goal: cut response time and ticket volume without risking data leaks or hallucinated actions. Use case – Answer product FAQs from docs – Check order status – Create/assign support tickets – Escalate when confidence is low – Log everything for audit and iteration High-level architecture (Brain + Hands) – Brain (LLM policy + reasoning): – Interprets user intent – Plans which tools to call and in what order – Produces final response or escalation note – Hands (tools + services): – read_kb: product/FAQ retrieval (RAG) – get_order_status: query WooCommerce/DB – create_ticket: issue system – send_email/update_user_note: notification – Orchestrator: – Validates tool requests (schema, authz) – Executes tools with timeouts/retries – Maintains short-term memory and trace – Enforces rate limits and cost caps Data flows – Public content: vector store from docs, product pages, and how-tos – Private content: order and ticket data via API with scoped tokens – No raw PII in prompts; use stable IDs and redact before logging Core components – LLM: gpt-4.1-mini or equivalent, with tool/function calling – Vector store: pgvector or Pinecone – App server: Python (FastAPI) or Node (Express) behind API gateway – Queue: Redis or SQS for deferred tasks (emails, ticket creation) – WordPress bridge: minimal plugin that proxies chat to backend with JWT Prompt design (Brain) – System role: – You are the Support Agent for [Brand]. Be concise, cite sources when from the KB, never guess order data, never disclose internal IDs. If confidence [{chunk, source, score}] – get_order_status(order_id: string, user_token: string) -> {status, eta, items[]} – create_ticket(subject: string, body: string, user_id: string) -> {ticket_id, url} Memory strategy – Short-term (per session): last 10 turns, anonymized entities – Long-term: none by default; persist resolved FAQs as “suggested macros” – Tool memory: cache recent order lookups by order_id (5 min TTL) Error handling and retries – Tool timeouts: 3s read_kb, 2s get_order_status, 5s create_ticket – Retries: exponential backoff 2 attempts, idempotency keys for write ops – Fallbacks: – If read_kb fails → return minimal fallback FAQ – If get_order_status fails → offer escalation with ticket creation – If LLM call fails → canned message + queue a “human follow-up” task Security and privacy – JWT from WP session maps to a short-lived backend token (5 min) – Tool-level authorization checks (RBAC): support.read_kb, orders.read_own, tickets.create – PII scrubbing: – Replace emails/phones with tokens before logging – Mask order_id except last 4 in user-facing responses – Prompt guards: – Block tool calls that include secrets or raw SQL-like input – Refuse to exfiltrate data not tied to the user Implementation sketch (Python FastAPI) from fastapi import FastAPI, Depends, HTTPException import httpx, time, uuid app = FastAPI() class ToolError(Exception): pass async def read_kb(query, top_k=4): # call vector store async with httpx.AsyncClient(timeout=3) as c: r = await c.post(“https://vec/search”, json={“q”: query, “k”: top_k}) r.raise_for_status() return r.json()[“hits”] async def get_order_status(order_id, user_token): async with httpx.AsyncClient(timeout=2, headers={“Authorization”: f”Bearer {user_token}”}) as c: r = await c.get(f”https://woo/api/orders/{order_id}”) if r.status_code == 403: raise ToolError(“not_authorized”) r.raise_for_status() return r.json() async def create_ticket(subject, body, user_id): idemp = str(uuid.uuid4()) async with httpx.AsyncClient(timeout=5, headers={“Idempotency-Key”: idemp}) as c: r = await c.post(“https://tickets/new”, json={“subject”: subject, “body”: body, “user_id”: user_id}) r.raise_for_status() return r.json() async def orchestrate(message, session, user_ctx): # 1) build tool-available prompt with redacted context prompt = build_prompt(message, session, user_ctx) # 2) call LLM with tools plan = await llm_call_with_tools(prompt) # 3) validate tool calls for call in plan.tool_calls: validate_schema(call) if call.name == “get_order_status”: assert user_ctx.scopes.contains(“orders.read_own”) assert call.args[“order_id”].startswith(user_ctx.allowed_order_prefix) # 4) execute tools with retries results = {} for call in plan.tool_calls: results[call.id] = await run_with_retry(call) # 5) final response final = await llm_finalize(prompt, plan, results) return final def run_with_retry(call): async def run(): if call.name == “read_kb”: return await read_kb(**call.args) if call.name == “get_order_status”: return await get_order_status(**call.args) if call.name == “create_ticket”: return await create_ticket(**call.args) raise ToolError(“unknown_tool”) delay = 0.3 for _ in range(3): try: return await run() except (httpx.TimeoutException, ToolError): await asyncio.sleep(delay); delay *= 2 raise WordPress plugin bridge (minimal) – Enqueue a chat widget. – Proxy /wp-json/agent/v1/chat to backend with user JWT. – Never store API keys in PHP. PHP (excerpt) add_action(‘rest_api_init’, function() { register_rest_route(‘agent/v1’, ‘/chat’, [ ‘methods’ => ‘POST’, ‘permission_callback’ => function() { return is_user_logged_in() || true; }, ‘callback’ => ‘aig_chat_proxy’ ]); }); function aig_chat_proxy(WP_REST_Request $req) { $token = wp_create_nonce(‘aig_session_’ . get_current_user_id()); $body = [ ‘message’ => $req->get_param(‘message’), ‘session_id’ => aig_get_session_id(), ‘wp_user’ => get_current_user_id() ]; $resp = wp_remote_post(‘https://api.aiguy.la/agent/chat’, [ ‘headers’ => [‘X-WP-Token’ => $token], ‘body’ => wp_json_encode($body) ]); return rest_ensure_response(json_decode(wp_remote_retrieve_body($resp), true)); } RAG setup – Ingest: – Crawl /docs and /products/*.md – Chunk at 500–800 tokens with overlap 50 – Store URL slugs and titles for citations – Retrieval: – Hybrid (BM25 + vector) to reduce misses – Filter by product tags if user context includes product_id – Post-retrieval: – Deduplicate by URL; keep top_k=5; force at least one “policy” doc when user asks for returns/warranty Guardrails and refusal policy – If user asks for actions outside scope (refunds, edits to orders): – Explain limitation and offer to create a ticket with required info – If confidence low on KB answers: – Return best-effort summary + references + invitation to escalate Monitoring and analytics – Capture per-turn: – user_id (hashed), session_id, tool_calls[], tokens_in/out, latency_ms, confidence, outcome – Dashboards: – Deflection rate (answered without ticket) – First response time vs. baseline – Tool error rates – Cost per conversation – Alerting: – Spike in get_order_status 403s – LLM finalize error rate > 2% – P95 latency > 5s Cost controls – Use small model for planning; larger for finalize only when confidence < 0.7 – Cache KB responses by canonical question – Hard cap tokens/session and auto-escalate when reached Evaluation loop – Weekly batch: – 100 sampled chats → rubric scoring (accuracy, citation quality, action correctness) – Auto-generate new tests from real failures – Synthetic tests: – Red-team prompts (prompt injection, data exfiltration) – Tool chaos (forced timeouts) to verify fallbacks Deployment checklist – [ ] Staging + prod environments with separate keys – [ ] WP plugin only calls backend; no secrets in WordPress – [ ] Tool auth scopes enforced server-side – [ ] Logs PII-scrubbed and encrypted at rest – [ ] Rate limiting by IP + user + session – [ ] Runbooks for LLM outage and ticket system outage – [ ] AB test widget vs. contact form default Example user flow – User: “Where’s order #1234?” – Brain: – Validate session, find user_id matches order prefix – Call get_order_status – If success, summarize items + ETA (mask ID) – If fail 403, offer ticket creation – Response: – “Your order ending in 1234 is Shipped via USPS. ETA: Mar 9. Want tracking via email?” What actually ships – A small WP plugin that renders the chat widget and proxies to an external agent API – A FastAPI/Express backend that owns tools, auth, and logs – A vector store for docs – Observability dashboards – Guardrails and policies treated as code alongside prompts If you want the minimal viable slice, ship only: – read_kb + create_ticket – No order access yet – Logging + dashboards from day one Then add get_order_status with strict auth and red-team it before enabling. </div> </article> <article id="post-212" class="post-212 post type-post status-publish format-standard has-post-thumbnail hentry category-ai-agents-chatbots"> <h1 style="margin-bottom: 20px; color: var(--primary);">Building a Production-Ready Support Agent for WordPress (Brain + Hands Architecture)</h1> <div class="entry-content"> This post walks through building a production-grade support agent that runs on your WordPress site. It uses a Brain + Hands architecture, retrieval grounding, safe tool execution, and an ops-friendly deployment you can ship today. Use case – 24/7 support on a WordPress site – Answers grounded in your docs, knowledge base, and order/ticket data – Creates tickets, fetches order status, and escalates when needed – Auditable, rate-limited, cost-capped, and safe by default Architecture (Brain + Hands) – Brain: Router and policy LLM. Decides intent, plans steps, calls tools, composes final answer. – Hands: Strict tools with input/output schemas and timeouts. Examples: – retrieve_kb(query) → list[doc] – get_order_status(order_id) → status – create_ticket(subject, body, user_id) → ticket_id – wp_lookup_user(email) → user_id – Memory: – Short-term: rolling chat window + compact summaries – Long-term: vector store (pgvector) with namespaces (public docs, private org, tickets) – Orchestration: – API service (FastAPI) – Worker (Celery) for tool calls and long tasks – Message bus (Redis) + idempotency keys – Retries with jitter, circuit breakers, dead-letter queue – Guardrails: – Tool allowlist by tenant and role – PII redaction before logging – Spend caps per session – Audit log of prompts, tool I/O, and final answer – Deployment: – Docker Compose: api, worker, postgres+pgvector, redis, nginx – Horizontal scale on api/worker – Observability via OpenTelemetry, Prometheus, and dashboards Minimal data flow 1) Frontend (WP) posts user_message to /chat.create. 2) Brain classifies intent and selects tools. 3) Worker executes tools with timeouts and idempotency. 4) Brain composes grounded answer, returns JSON. 5) Logs, metrics, and cost counters are flushed asynchronously. Prompts (policy + tool primer) System (policy): – You are a support agent. Only answer using verified sources and allowed tools. – If retrieval returns low confidence, ask a clarifying question or escalate via create_ticket. – Never invent order or account details. Use wp_lookup_user and get_order_status. – Keep answers under 150 words. Provide exact steps when relevant. – Stop after you complete the task or create a ticket with a summary. Tool primer (append once at session start): – Tools are authoritative. Handle errors gracefully. On tool failure: retry once with backoff; otherwise escalate. – Sensitive data: do not echo PII. Replace with [redacted] in responses. Memory plan – Short-term: – Keep last 8 turns + rolling summary capped to 1,200 tokens. – Long-term: – pgvector schema: docs(id, tenant, chunk, embedding, metadata, updated_at) – Namespace by tenant. Tag privacy: public | internal. – Retrieval: – Hybrid search: BM25 + cosine. Rerank top 50 → top 8 with a small reranker or LLM scoring. – Attach citations (url/title) to the Brain context. Include only top 3. API skeleton (FastAPI, Python) – Uses any function-calling LLM client. Replace llm.* with your provider. from fastapi import FastAPI, HTTPException from pydantic import BaseModel import uuid, time app = FastAPI() class ChatIn(BaseModel): session_id: str user_id: str | None = None message: str tenant: str class ToolError(Exception): pass def retrieve_kb(tenant: str, query: str) -> list[dict]: # 1) embed query 2) pgvector ANN search 3) BM25 4) rerank # return [{title, url, text, score}] … def wp_lookup_user(email: str) -> dict | None: … def get_order_status(order_id: str) -> dict: … def create_ticket(subject: str, body: str, user_id: str | None) -> dict: … TOOL_REGISTRY = { “retrieve_kb”: retrieve_kb, “wp_lookup_user”: wp_lookup_user, “get_order_status”: get_order_status, “create_ticket”: create_ticket, } def call_tool(name, args, idempotency_key: str): # enforce allowlist, timeouts, and idempotency # store result keyed by (name, idempotency_key) to avoid duplicates … def brain_policy(state): # state: {messages, tenant, memory_summary, budget_left} # 1) classify intent 2) plan 3) decide tools 4) compose answer # Use LLM function-calling with tool schema mirroring TOOL_REGISTRY … @app.post(“/chat.create”) def chat_create(inp: ChatIn): session = hydrate_session(inp.session_id, inp.tenant) # memory + budget plan = brain_policy(session | {“latest_user”: inp.message}) tool_calls = plan.get(“tool_calls”, []) results = [] for tc in tool_calls: key = f”{inp.session_id}:{tc[‘name’]}:{uuid.uuid4()}” try: res = call_tool(tc[“name”], tc[“arguments”], key) results.append({“name”: tc[“name”], “result”: res}) except Exception as e: results.append({“name”: tc[“name”], “error”: str(e)}) answer = brain_compose(session, inp.message, results) # grounded final log_audit(inp, plan, results, answer) return {“answer”: answer[“text”], “citations”: answer.get(“citations”, [])} Retries and timeouts – Default tool timeout: 4s (short I/O) and 15s (ticketing). – Retries: 1 retry with exponential backoff (200–1200ms jitter). – Circuit breaker: open after 5 failures/min per tool; auto half-open after 60s. – Dead-letter: push failed jobs with payload and reason. WordPress integration (minimal plugin) – Adds a secure endpoint that proxies chat to the API with user/session info. – Uses WP nonce + JWT for auth. Stores session_id in user meta. add_action(‘rest_api_init’, function () { register_rest_route(‘aiguy/v1’, ‘/chat’, [ ‘methods’ => ‘POST’, ‘callback’ => function ($req) { $user_id = get_current_user_id(); $session_id = get_user_meta($user_id, ‘agent_session’, true); if (!$session_id) { $session_id = wp_generate_uuid4(); update_user_meta($user_id, ‘agent_session’, $session_id); } $body = [ ‘session_id’ => $session_id, ‘user_id’ => $user_id ?: null, ‘tenant’ => get_bloginfo(‘url’), ‘message’ => sanitize_text_field($req->get_param(‘message’)), ]; $resp = wp_remote_post(‘https://api.yourdomain.com/chat.create’, [‘headers’=>[‘Authorization’=>’Bearer ‘.YOUR_JWT],’body’=>wp_json_encode($body),’timeout’=>10]); return rest_ensure_response(json_decode(wp_remote_retrieve_body($resp), true)); }, ‘permission_callback’ => ‘__return_true’ ]); }); Guardrails and policies – Tool allowlist per tenant and role. Example: guests cannot call get_order_status. – PII handling: mask emails, phone numbers in logs; hash user IDs. – Cost guard: $0.50 per session default cap; block further LLM calls and ask for escalation. – Content policy: refuse medical/financial advice; offer handoff. Observability – OpenTelemetry traces: chat.create → brain_policy → tool_calls → compose. – Events: – agent.tokens_prompt, agent.tokens_completion – tool.duration_ms, tool.error_rate – retrieval.latency_ms, retrieval.disjointness_score – Dashboards: – Answer accuracy vs. retrieval overlap – Ticket creation rate – Cost per conversation and per tenant Scalability playbook – API: uvicorn workers = CPU cores * 2; keep-alive 60s. – Worker: concurrency tuned to I/O bound tasks; start with 2x CPU. – Cache: L2 cache embeddings and retrieval via Redis; TTL 10m. – Rate limit: 10 req/min per IP, 60/min per tenant burst with token bucket. – Batch embeddings and precompute doc chunk vectors in ingestion jobs. Testing checklist – Golden set of Q&A with expected citations (pass@1 ≥ 0.75) – Tool chaos tests: 20% forced 500s on get_order_status; verify backoff/handoff – Latency SLO: p95 ≤ 2.5s without tool calls, ≤ 4.5s with retrieval – Cost SLO: ≤ $0.03 per turn on average – Security: ensure tools cannot reach arbitrary URLs; static allowlist only Costs and performance tips – Use a small reasoning model for policy and a cheaper model for drafting; only upgrade on ambiguity. – Compress context with structured summaries of past steps. – Limit retrieval to 8 chunks max, 800 tokens cap. – Cache rewritten queries and last 3 answers per session. Deployment (Docker Compose) – Services: api, worker, redis, postgres(pgvector), nginx – Environment: – LLM_API_KEY, OPENAI_API_BASE or other provider – PG_DSN, REDIS_URL – ALLOWED_TOOLS, COST_CAP_USD – Rolling updates with zero downtime; keep migrations backward compatible. What to ship first (MVP) – One tool: retrieve_kb – One action: create_ticket on low confidence – Short-term memory – Token/cost logging – WordPress proxy endpoint Then iterate: – Add account/order tools – Introduce allowlists and spend caps – Add hybrid retrieval and reranking – Harden retries and circuit breakers If you want the reference repo with the minimal stack (FastAPI + Celery + pgvector + WP plugin scaffold), reply with “Send the repo link.” </div> </article> <article id="post-190" class="post-190 post type-post status-publish format-standard has-post-thumbnail hentry category-ai-agents-chatbots"> <h1 style="margin-bottom: 20px; color: var(--primary);">Shipping a Brain+Hands Support Agent on WordPress: A Production Blueprint</h1> <div class="entry-content"> This post shows a concrete way to ship a customer support chatbot on WordPress using a Brain+Hands architecture. It focuses on reliable tool use, fast responses, and safe fallbacks—so it works in production, not just demos. High-level goals – Sub-2s median response on cached answers; proxies to FastAPI with service token. – Admin settings: API base URL, agent_id, public rate caps, UI messages. System prompt (trimmed) – “You are the Support Agent for . Objectives: resolve safely, be concise, cite sources if RAG used, never invent order data. – Tools are authoritative. If a tool returns empty, ask a targeted follow-up. – Prefer RAG answers for product info; use order API only when the user provides email + order number. – If confidence {items: [{title, url, snippet, score}]} – get_order_status(order_id: string, email: string) -> {status, items: […], eta, support_url} – create_ticket(subject: string, body: string, user_email: string) -> {ticket_id, url} – wp_get_article(slug: string) -> {title, url, excerpt} – wp_create_draft(title: string, content: string, tags: [string]) -> {post_id, url} All tools: – 3 attempts with exponential backoff (100ms, 300ms, 900ms) on 5xx/timeouts – Per-tool timeouts (1.5–3.0s) – Circuit breaker after 5 failures/60s; Brain receives tool_unavailable=true – Input validation + PII redaction in logs – Idempotency keys for writes (hash of normalized input) RAG design – Index: product docs, policies, shipping/returns, how-tos – Chunking: 600–800 tokens with overlap 80; hybrid search (BM25 + vector) – Metadata: section, updated_at, policy_version, locale – Freshness: prefer updated_at within 90 days; demote stale content – Response shaping: cite top 1–2 sources with URLs; never paste long chunks Conversation memory – Short-term: last 8–12 turns in Redis keyed by session_id – Long-term: None by default; only store minimal derived facts with TTL (e.g., locale=en-US, product=Model-X) – PII policy: Do not persist emails/order IDs beyond session TTL unless ticket is created Orchestration logic (pseudo) – If user intent ∈ {order_status, refund, return} and has required fields -> call appropriate tool – Else if intent ∈ {product_info, how_to} -> RAG then answer – Else -> clarify with a single follow-up question – If total budget > $0.04/turn or total time > 7s -> return concise fallback + offer ticket – If tool_unavailable -> skip tool path, provide safe guidance, suggest ticket Guardrails – Schema-enforced tool inputs (pydantic) – Output moderation on Brain final answer for PII leakage – Allowlist of domains for citations – Cost guard: token + tool meter per session; degrade to smaller model if exceeded – Red-team prompts stored as regression tests Prompt templates (snippets) – Tool-use meta instruction: “Before calling a tool, state your intent in one sentence. After tool result, summarize and answer. Do not call the same tool twice with identical params.” – Clarifier: “Ask exactly one targeted question if required fields are missing.” – Citation rule: “If using RAG, include ‘Sources: ’ on one line.” Error handling patterns – Tool 4xx: user-correctable -> ask for missing fields – Tool 5xx/timeout: retry; if still failing -> graceful degradation path + ticket option – JSON parse errors: re-ask model with constrained tool schema and lower temperature – Hallucination guard: if tool not called where required -> reject answer and replan Performance tuning – Use smaller model for planning (e.g., 4o-mini) and larger model for final answer only when needed – Semantic cache: cache final answers for RAG-only turns with TTL 24h and versioned by doc hashes – Parallelize independent tools (e.g., FAQ + inventory check) with a 2.5s overall soft budget – Stream tokens to frontend; show “retrieving order…” status on tool calls Deployment – FastAPI behind API Gateway + Lambda or ECS Fargate – Postgres + pgvector on RDS; Redis on ElastiCache – CI/CD: run unit tests for tools, contract tests, and evaluation suites before deploy – Observability: traces per turn, tool-level spans, model cost metrics, drop rates, p95 latency Evaluation suite – 50–100 scripted conversations covering: missing-order-id, stale-RAG, tool-500, policy-edge, refund vs exchange – Metrics: exactness (domain rubric), tool accuracy, escalation rate, latency, cost/turn – Canary: 5% live traffic for 48h with auto-rollback thresholds Minimal FastAPI skeleton (abridged) – POST /chat – Validate session_id, rate limit – Load context + RAG if needed – Call Brain (choose model based on budget) – Execute tools via router with retries – Stream final tokens – Log trace + metrics Security notes – Service-to-service auth (JWT) between WP and FastAPI – Do not expose vendor API keys to the browser – Encrypt all logs at rest; redact PII – WordPress nonce for front-end requests When to escalate – Low confidence + sensitive requests (refund exceptions, legal) – Repeated tool failures – High-friction tasks better handled by humans – Provide ticket link and SLA Outcome This blueprint is the shortest path we’ve found to a reliable, fast, and safe support agent on WordPress. Start with RAG-only answers, then add high-value tools with strict contracts and clear fallbacks. Measure everything. </div> </article> <article id="post-53" class="post-53 post type-post status-publish format-standard has-post-thumbnail hentry category-ai-agents-chatbots"> <h1 style="margin-bottom: 20px; color: var(--primary);">AI Agents & Chatbots Overview</h1> <div class="entry-content"> AI agents and chatbots are software systems that simulate conversation and perform tasks using natural language. They can be rule-based or use machine learning models such as large language models (LLMs) to understand user input, maintain context, and generate relevant responses. As they evolve, chatbots are being deployed across websites and messaging platforms to provide customer service, lead generation, scheduling, and more. First, an agent collects a user question or command and classifies the intent using natural language understanding. It then retrieves information from knowledge bases or connected applications (CRM, calendars, email). Modern chatbots also use generative models to craft personalized responses rather than generic scripted answers. By connecting to APIs, these agents can perform tasks such as placing orders, booking appointments, or updating records. Building an effective chatbot requires careful planning. Start by defining your goals and audience: do you want a lead-generation bot, a support assistant, or a general FAQ chatbot? Map out key user journeys and decide which tasks can be automated. Then design conversation flows with fallback options for ambiguous questions. If using generative AI, consider guardrails to prevent off-topic or unsafe responses. Integration is essential. Chatbots are most valuable when connected to CRM systems, calendars, email platforms, and databases. For example, a real-estate chatbot can automatically log inquiries in a CRM, send property details from a Google Sheet, and schedule viewings on a calendar. APIs and automation platforms make it easier to orchestrate these flows. When deploying chatbots, test them extensively with real users. Iterate on the design based on conversation logs. Train models on domain-specific data to improve understanding of industry terminology. Provide a way for users to speak to a human if needed. Monitor analytics such as resolution rate, drop-off points, and conversion metrics to continuously optimize. As generative AI becomes more powerful, chatbots are evolving from simple question-answering tools to proactive digital assistants. With retrieval-augmented generation, agents can search live data sources and compose answers on the fly. They can summarize long documents, rewrite text for different reading levels, and generate personalized marketing copy. Combined with speech synthesis, they can serve as voice assistants. Security and ethics are also important. Ensure that sensitive data (personal information, financial details) is handled securely and that chatbots do not share private information. Provide transparency that users are interacting with an AI. Use bias-mitigation techniques to prevent discriminatory responses. Comply with relevant regulations such as GDPR and the California Consumer Privacy Act (CCPA). In summary, AI agents and chatbots offer tremendous potential to automate workflows, improve customer experiences, and scale service delivery. By planning thoughtfully, integrating with existing systems, and leveraging the latest advances in conversational AI, businesses can deploy chatbots that drive engagement and efficiency while lea ving human staff free to focus on high-value tasks. </div> </article> <article id="post-25" class="post-25 post type-post status-publish format-standard has-post-thumbnail hentry category-ai-agents-chatbots"> <h1 style="margin-bottom: 20px; color: var(--primary);">AI Agents & Chatbots Overview</h1> <div class="entry-content"> Deploying a chatbot on your website or connecting it to your CRM can dramatically reduce manual work. An agent can greet new visitors, capture lead information, book appointments and send smart follow‑ups automatically. For service requests, chatbots can route inquiries to the right department or perform actions such as checking order status and updating account details. They can also deliver personalized recommendations by integrating with product catalogs and user data. When paired with email or SMS automation, agents ensure that your communications are timely and consistent, improving customer satisfaction and conversion rates. Designing an effective AI agent requires thoughtful planning. Start by outlining the primary goals—are you trying to answer frequently asked questions, schedule appointments or qualify leads? Use clear, friendly language and provide quick reply buttons to guide users. Incorporate fallback responses when the agent doesn’t understand a query, and always offer an option to connect with a human. Continuous improvement is crucial: analyze chat logs to identify gaps, refine training data and update your flows. As the technology evolves, consider adding voice interfaces or connecting your agent to multiple channels like Facebook Messenger, Slack and WhatsApp. By investing in a well‑designed chatbot, you’ll create a scalable touchpoint that works for you 24/7. Another advantage of modern AI agents is their ability to learn from interactions. With access to transcripts, you can identify common pain points and adjust your product or service accordingly. You can also use chatbots to conduct surveys or gather feedback at the end of an interaction. For sales teams, an agent can qualify leads by asking targeted questions, scoring them based on responses and updating your CRM automatically. This ensures your team spends time on the most promising opportunities. When integrating AI agents into your workflow, security and privacy must be top priorities. Use secure authentication methods when connecting to your CRM, scheduling system or payment gateway. Limit the data your bot collects to what’s necessary and be transparent with users about how their information will be used. Finally, remember that a chatbot should complement, not replace, your human team. Offering a seamless handoff to a person when needed creates trust and ensures complex issues are handled appropriately. With a strategic approach, AI agents become not just a tool but a key partner in scaling your business. By embedding an AI chatbot on your website or connecting it to your CRM, you can capture leads, book appointments and send smart follow‑ups automatically. Chatbots can be trained to provide tailored answers, route inquiries to the right person and summarise interactions. For small businesses, AI agents free up time and reduce response delays. They are perfect for handling frequently asked questions, qualifying prospects or generating meeting summaries so you can focus on higher‑value work. </div> </article> </div> </section> <footer> <div class="container"> <div class="footer-grid"> <div class="footer-col"> <h4>GravityExpert</h4> Based in Westwood, Los Angeles. Solving WordPress data problems since 2014. </div> <div class="footer-col" style="text-align: right;"> <h4>Quick Links</h4> <ul> <li><a href="https://aiguyinla.com/plugin">Anti-Spam Addon</a></li> <li><a href="https://aiguyinla.com/services">Custom Development</a></li> </ul> </div> </div> <div class="copyright"> © 2026 Ai Guy in LA. All rights reserved. </div> </div> </footer> <script> document.addEventListener('DOMContentLoaded', function() { const toggleBtn = document.getElementById('mobile-toggle'); const navMenu = document.getElementById('mobile-menu'); if(toggleBtn && navMenu) { toggleBtn.addEventListener('click', function() { // Toggle the 'active' class on both the button and the menu toggleBtn.classList.toggle('active'); navMenu.classList.toggle('active'); }); } }); </script> <script type="speculationrules"> {"prefetch":[{"source":"document","where":{"and":[{"href_matches":"/*"},{"not":{"href_matches":["/wp-*.php","/wp-admin/*","/wp-content/uploads/*","/wp-content/*","/wp-content/plugins/*","/wp-content/themes/gravity-expert-theme/*","/*\\?(.+)"]}},{"not":{"selector_matches":"a[rel~=\"nofollow\"]"}},{"not":{"selector_matches":".no-prefetch, .no-prefetch a"}}]},"eagerness":"conservative"}]} </script> <script id="wp-emoji-settings" type="application/json"> {"baseUrl":"https://s.w.org/images/core/emoji/17.0.2/72x72/","ext":".png","svgUrl":"https://s.w.org/images/core/emoji/17.0.2/svg/","svgExt":".svg","source":{"concatemoji":"https://aiguyinla.com/wp-includes/js/wp-emoji-release.min.js?ver=6.9.4"}} </script> <script type="module"> /* <![CDATA[ */ /*! This file is auto-generated */ const a=JSON.parse(document.getElementById("wp-emoji-settings").textContent),o=(window._wpemojiSettings=a,"wpEmojiSettingsSupports"),s=["flag","emoji"];function i(e){try{var t={supportTests:e,timestamp:(new Date).valueOf()};sessionStorage.setItem(o,JSON.stringify(t))}catch(e){}}function c(e,t,n){e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(t,0,0);t=new Uint32Array(e.getImageData(0,0,e.canvas.width,e.canvas.height).data);e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(n,0,0);const a=new Uint32Array(e.getImageData(0,0,e.canvas.width,e.canvas.height).data);return t.every((e,t)=>e===a[t])}function p(e,t){e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(t,0,0);var n=e.getImageData(16,16,1,1);for(let e=0;e<n.data.length;e++)if(0!==n.data[e])return!1;return!0}function u(e,t,n,a){switch(t){case"flag":return n(e,"\ud83c\udff3\ufe0f\u200d\u26a7\ufe0f","\ud83c\udff3\ufe0f\u200b\u26a7\ufe0f")?!1:!n(e,"\ud83c\udde8\ud83c\uddf6","\ud83c\udde8\u200b\ud83c\uddf6")&&!n(e,"\ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc65\udb40\udc6e\udb40\udc67\udb40\udc7f","\ud83c\udff4\u200b\udb40\udc67\u200b\udb40\udc62\u200b\udb40\udc65\u200b\udb40\udc6e\u200b\udb40\udc67\u200b\udb40\udc7f");case"emoji":return!a(e,"\ud83e\u1fac8")}return!1}function f(e,t,n,a){let r;const o=(r="undefined"!=typeof WorkerGlobalScope&&self instanceof WorkerGlobalScope?new OffscreenCanvas(300,150):document.createElement("canvas")).getContext("2d",{willReadFrequently:!0}),s=(o.textBaseline="top",o.font="600 32px Arial",{});return e.forEach(e=>{s[e]=t(o,e,n,a)}),s}function r(e){var t=document.createElement("script");t.src=e,t.defer=!0,document.head.appendChild(t)}a.supports={everything:!0,everythingExceptFlag:!0},new Promise(t=>{let n=function(){try{var e=JSON.parse(sessionStorage.getItem(o));if("object"==typeof e&&"number"==typeof e.timestamp&&(new Date).valueOf()<e.timestamp+604800&&"object"==typeof e.supportTests)return e.supportTests}catch(e){}return null}();if(!n){if("undefined"!=typeof Worker&&"undefined"!=typeof OffscreenCanvas&&"undefined"!=typeof URL&&URL.createObjectURL&&"undefined"!=typeof Blob)try{var e="postMessage("+f.toString()+"("+[JSON.stringify(s),u.toString(),c.toString(),p.toString()].join(",")+"));",a=new Blob([e],{type:"text/javascript"});const r=new Worker(URL.createObjectURL(a),{name:"wpTestEmojiSupports"});return void(r.onmessage=e=>{i(n=e.data),r.terminate(),t(n)})}catch(e){}i(n=f(s,u,c,p))}t(n)}).then(e=>{for(const n in e)a.supports[n]=e[n],a.supports.everything=a.supports.everything&&a.supports[n],"flag"!==n&&(a.supports.everythingExceptFlag=a.supports.everythingExceptFlag&&a.supports[n]);var t;a.supports.everythingExceptFlag=a.supports.everythingExceptFlag&&!a.supports.flag,a.supports.everything||((t=a.source||{}).concatemoji?r(t.concatemoji):t.wpemoji&&t.twemoji&&(r(t.twemoji),r(t.wpemoji)))}); //# sourceURL=https://aiguyinla.com/wp-includes/js/wp-emoji-loader.min.js /* ]]> */ </script> </body> </html>

Shipping a Production Support Agent: Brain + Hands with Django, Redis, and WordPress

Building a Production-Ready Support Agent for WordPress (Brain + Hands Architecture)

Shipping a Production-Ready Support Agent: Brain + Hands Architecture with Django, Celery, and Redis

Shipping a Production-Ready Brain+Hands Support Agent (WordPress + Python API)