AI Bot Builder

Use this skill to build, ship, and iterate on conversational AI bots — support, sales, or domain-specific — using pure Python frameworks and AI coding agents.

This skill absorbs ai-langgraph-bots and is the single entry point for stateful bot implementation, including LangGraph graph design, checkpoints, and human-in-the-loop.

Default posture: explicit conversation state, typed tool contracts, deterministic escalation rules, guardrails before launch, compliance filtering before responses reach users, and analytics from day one. No visual workflow tools — code-first only.

When to Use This Skill

• Building a support bot, sales bot, or domain-specific conversational agent
• Designing conversation flows, fallback trees, and state machines
• Choosing a Python bot framework (LangGraph, Claude Agent SDK, Pydantic AI); voice frameworks belong to ai-voice-bots
• Migrating a bot from visual workflow tools (n8n, Langflow) to native Python
• Integrating bots with ticketing, CRM, knowledge bases, or booking systems
• Designing human handoff and escalation protocols
• Adding post-generation compliance/safety filtering to bot responses
• Planning bot analytics, A/B testing, and improvement loops
• Implementing LangGraph graph state, checkpoints, and human approval for bots
• Testing multi-turn conversation quality and regressions

When NOT to Use This Skill

Quick Reference

Default Workflow

1. Classify the bot type (support, sales, or custom domain) and identify the primary user task.
2. Define persona — tone, brand voice, safety boundaries, and guardrailed behavior.
3. Design conversation flow — state machine with happy path, fallbacks, slot filling, and escalation triggers.
4. Choose framework — select from pure Python options based on state needs, tool integration, and deployment target.
5. Integrate domain tools — ticketing, CRM, knowledge base, calendar, or custom APIs via MCP or direct SDK.
6. Add guardrails — input validation, output filtering, PII handling, topic boundaries, and abuse prevention.
7. Build evaluation suite — multi-turn evals, edge cases, adversarial inputs, and regression baselines.
8. Deploy with analytics — instrument containment rate, CSAT, escalation rate, cost per conversation, and set up improvement loops.

Bot Type Decision Tree

What is the bot's primary job?
├── Answer questions / resolve issues
│   ├── Has a knowledge base or help center? → Support Bot (KB-grounded)
│   └── Needs to query live systems (orders, accounts)? → Support Bot (tool-using)
├── Qualify leads / book meetings / handle objections
│   └── Sales Bot
├── Execute workflows (approvals, scheduling, data entry)
│   └── Workflow Bot — consider LangGraph graph-shaped orchestration
└── Multi-domain or unclear
    └── Start with the dominant use case; add domains incrementally

Framework Selection

Voice frameworks (Pipecat, LiveKit Agents) are owned by ../ai-voice-bots/SKILL.md — this skill is not voice/STT/TTS. Go there for framework choice, imports, and pipeline code; come back here for conversation state, persona, and guardrails once the graph/agent "brain" is decided.

Default: LangGraph for complex stateful bots, Claude Agent SDK for simpler tool-using bots, ai-voice-bots' pick when voice is primary. For linear decision cascades without cycles or checkpoints, consider plain async Python — LangGraph's dependency chain (langchain-core and its transitive packages) may not be worth the overhead.

Pydantic AI: its major-version rewrite moved extension points to a composable capabilities=[...] API and removed history_processors=, event_stream_handler= and prepare_tools= from the Agent constructor. Check which major version you have installed before copying an example, and read the current upgrade guide at ai.pydantic.dev. Migration notes → references/framework-selection.md.

Full comparison → references/framework-selection.md

LangGraph for Bots

Reach for LangGraph when the bot needs cycles, explicit state, checkpoints, or human approval — not as a default. For a linear cascade (spam → router → support → reply) with no cycles or HITL, plain async Python with if/elif routing is simpler and has zero framework overhead.

Key guardrails:

• Python compatibility: look up the Python range your LangGraph release supports on the LangGraph releases page before upgrading Python. The framework ships minor releases often, so any "safe ceiling" copied from a doc goes stale within months; pin the version your CI tests.
• Use START for new code. set_entry_point() is still documented as equivalent to add_edge(START, key), but the START edge is clearer and matches current examples. Import from langgraph.graph import StateGraph, START, END.
• State before nodes. TypedDict with total=False, reducer-annotated fields for accumulated data.
• Pure nodes. (state, *, clients) -> dict via functools.partial — testable without monkey-patching.
• Place node boundaries around recoverable work and approval gates. With a checkpointer, LangGraph persists state at super-step boundaries; choose the required durability mode and make side effects idempotent. Put approval gates before destructive, financial, or irreversible actions. See references/state-checkpoints-and-hitl.md.

Full depth:

• Graph patterns (state schemas, routers, subgraphs, anti-patterns) → references/graph-design-patterns.md
• Checkpoints + HITL (interrupt, Command resume, replay, audit) → references/state-checkpoints-and-hitl.md
• Testing (three-tier pyramid, red-team pack) → references/testing-and-production.md

Conversation Design Principles

1. State machine, not script. Model conversations as states with transitions, not linear scripts. Every state has: entry conditions, expected user inputs, bot actions, and exit transitions.
2. Fallback hierarchy. Unknown input → clarify → rephrase → offer alternatives → escalate. Never dead-end.
3. Slot filling over free chat. When collecting structured data, use explicit slots with validation. Confirm before committing.
4. Escalation is not failure. Design escalation as a first-class path with context transfer, not a last resort.
5. Turn budget. Set maximum turns before forced escalation from the p90 turns-to-resolution in your own logs, per bot type, and use the same number as max_turns in the conversation_eval.py rubric.

Full depth → references/conversation-design.md

Production Defaults

• Language: Python, async by default. Pin whatever your CI actually tests, not whatever the docs said last quarter — see the LangGraph Python-compatibility note above.
• Framework: FastAPI for serving, selected bot framework for orchestration
• Streaming: SSE or WebSocket for real-time responses
• Cost tracking: Token counting per conversation, cost per resolution metric
• Prompt-prefix caching: the main multi-turn cost lever, because every turn resends the history. Keep the system prompt and tool definitions byte-stable and first (no timestamps or per-user values in them, tools in a fixed order) and put the cache breakpoint at the end of the history. Summarizing or rewriting history invalidates the cached prefix, so summarize only at a planned cache break. scripts/bot_cost_estimator.py --cache models this write-then-read pattern.
• Guardrails: Input validation (max length, encoding, null bytes), output filtering, PII detection, topic boundaries
• Bot-identity disclosure (EU AI Act Art. 50(1), applies from 2 Aug 2026): tell users they are talking to an AI at the latest at the first interaction, not only "when asked". The exception covers only cases where this is obvious to a reasonably well-informed, observant person given the context, so do not rely on it by default. See startup-compliance-enterprise-readiness/references/regulatory-overlays.md for the full obligation set and dates.
• Compliance filter: Post-generation check before any response reaches the user — block investment advice, tipping-off language, unmasked PII. Use regex for fast checks; LLM call only for ambiguous cases. Essential for regulated industries (finance, healthcare).
• PII scrubbing: Run card number regex before phone regex — phone patterns are greedy and consume card numbers if run first. Order: URLs → emails → card numbers → phone numbers.
• Human escalation: Always-available path with context transfer. Prepare operator-facing summary (structured handoff) alongside user-facing confirmation.
• Dedup: Redis TTL keys, not in-memory. Two levels: exact event ID, with a TTL at least the channel provider's maximum webhook redelivery window (look it up in that provider's webhook docs), and a text hash with a TTL about as long as the double-submit window you see in your logs. Survives restarts, scales across instances.
• Rubric-graded outcomes (when output quality is load-bearing): for structured reports, formal/regulated responses, or document generation, add a revision loop — the task agent produces output, an isolated grader agent scores it against a rubric in its own context window (no access to the writer's chain-of-thought), the writer revises until the rubric passes or max_iterations is hit. See references/testing-and-production.md for the pattern, which is framework-agnostic; check whether your agent runtime has a native outcome or grader hook before building the loop yourself.
• Conversation memory: Extract structured facts from each turn, not raw message logs (blocks anti-pattern A1 from ai-context-layer). Pick a memory pattern: P2 (support bots), P4 (sales bots with temporal facts), P6 (episodic-semantic for general bots) from ai-context-layer/patterns-catalog.md. Wire the remember / recall loop per references/bot-memory-integration.md. Load recalled facts only for support tiers — spam filter and router stay single-turn to avoid history-bias.
• Domain knowledge: Keep curated knowledge retrieval separate from operational truth, memory, safety, and tone. If the bot uses SQL-backed RAG, stage database rollout before semantic retrieval: schema/RLS, minimal lexical search, content seed, ranking tuning, evals, then vector or full-text indexes after capability probes. Keep simple lexical retrieval when evals pass; defer embeddings, editor workflows, localization, and search infrastructure until traffic, corpus size, quality, or audit triggers justify them.
• Testing: Three-tier test pyramid — unit tests for pure nodes, integration tests with mocked HTTP (respx), golden eval harness split into deterministic (regex/fast-path) and LLM tiers. Run deterministic tests in CI on every push; LLM eval on demand.
• Analytics: Containment rate, CSAT, escalation rate, cost per conversation from day one. Write every decision to an analytics table (conversation_id, decision, route, confidence, tier, latency).
• Docker: Non-root user, minimal base image (Alpine or distroless), read-only filesystem, no-new-privileges, secrets from manager not env files in production.
• Model identifiers: Keep the model ID in config/env, not hardcoded in prompts or code samples — provider families rename and reprice on a cadence of months, not years (tiering, tier names, and prices have all shifted materially within a single year across major vendors). Pin the exact ID your CI tests in one place (MODEL_ID env var or a config file), and re-verify it against the vendor's current model list before every deploy, not from memory.

Intent Automation Gate

Classify each supported intent as answer, read, propose, mutate, or handoff, then give it an explicit tool allowlist, confirmation rule, fallback, and success signal. Unknown intents and failed preconditions must take the handoff or safe-answer path; they must not inherit the nearest intent's tools. Before launch, measure wrong-action and failed-handoff rates per intent alongside containment, because higher containment can hide harmful automation.

Known Traps

• Treating escalation as a fallback only. Support and sales bots need an operator path that is designed upfront, instrumented, and tested like any other successful outcome.
• Hiding orchestration inside one giant prompt or one giant LangGraph node. That makes handoff, retries, and root-cause analysis much harder when the bot misroutes or loops.
• Letting curated knowledge, user memory, live account state, safety policy, and tone collapse into one prompt block. Mature bots assemble typed slices with evidence and trust levels so each concern can be tested separately.
• Adding semantic search, long-term memory, or editorial workflow before the bot has eval failures, corpus pressure, real usage, or an operating team that needs those controls.
• Sharing one conversation state model across web chat, email, SMS, and messaging channels without channel-specific limits. Attachment handling, latency expectations, and retry semantics differ materially.
• Applying compliance, policy, or PII checks after tools have already fired or messages have already been queued. Guardrails must sit before side effects and before user-visible output.
• Treating synthetic "happy path" transcripts as production proof. Multi-turn regressions usually appear in recovery paths, partial-tool failures, and human-handoff boundaries.
• Treating prompt injection as a content-moderation problem instead of a security problem. The LLM is not a security boundary — defense lives in code around it: spotlighting, canary tokens, tool-output sanitization, privilege separation, and a red-team pack in CI. See references/injection-and-jailbreak-defense.md.
• Wiring a managed memory vendor (Mem0, Zep, Letta, Cognee) directly into bot core logic with vendor-specific calls scattered across nodes/tools. Memory vendors churn on schema and pricing; put a thin MemoryService interface between the bot and the vendor SDK so a vendor swap is a one-file change, not a rewrite.

Common Anti-Patterns

• Using LangGraph by default for short linear bots where plain async Python would be simpler, easier to test, and easier to operate.
• Letting one prompt own routing, retrieval, tool planning, tone, and policy at the same time instead of separating those concerns.
• Rebuilding ticketing, CRM, or booking semantics inside prompt text instead of using typed tool contracts and explicit field validation.
• Measuring success only with aggregate CSAT or containment while ignoring escalation quality, incorrect automation, and cost per resolved conversation.

Navigation

References

• references/index.md — Reference navigation map
• references/framework-selection.md — Pure Python framework comparison
• references/conversation-design.md — State machines, fallback trees, multi-turn flows
• references/persona-design.md — Bot personality, tone, brand voice
• references/support-bot-patterns.md — Support bot integration patterns
• references/sales-bot-patterns.md — Sales bot integration patterns
• references/handoff-to-human.md — Escalation orchestration
• references/channel-routing.md — Omnichannel routing
• references/bot-memory-integration.md — Persistent memory wiring (remember/recall loop, pattern selection, anti-pattern blocks)
• references/injection-and-jailbreak-defense.md — Direct/indirect injection, spotlighting, canary, red-team pack
• references/migration-from-n8n.md — Migration from n8n/Langflow/Agent Builder to native Python
• references/bot-analytics-improvement.md — Metrics and improvement loops
• references/production-deployment.md — Serving and scaling
• references/secret-rotation-and-model-fallback.md — Secret rotation and model fallback
• references/stateful-rollout-and-blue-green.md — Stateful rollout and blue-green deployment
• references/graph-design-patterns.md — LangGraph state, nodes, edges, subgraphs
• references/state-checkpoints-and-hitl.md — LangGraph persistence, replay, approval
• references/testing-and-production.md — LangGraph testing and observability

Assets

• assets/support-bot-spec.md — Support bot specification template
• assets/sales-bot-spec.md — Sales bot specification template
• assets/conversation-flow-template.md — Conversation state machine template
• assets/bot-safety-checklist.md — Pre-launch safety gate
• assets/handoff-protocol.md — Human handoff contract template
• assets/pricing-template.json — Empty --pricing rates file for bot_cost_estimator.py
• assets/templates/end-to-end-bot-recipe.md — Zero-to-shipped walkthrough (LangGraph + Twilio); voice pipelines belong to ai-voice-bots

Scripts

• python3 scripts/conversation_eval.py --input conversations.jsonl [--min-pass-rate 1.0] [--warnings-fail] — Multi-turn conversation evaluator. Have the bot record each confirmation it asks for as a request_confirmation tool call ({"action": "issue_refund", "args": {"order_id": "55"}}). The evaluator then fails any state-changing call that no confirmed request covers, and exits 1 when the pass rate is below --min-pass-rate (default 1.0). Set require_confirmation_tool: true in the rubric once the bot emits the call, so a transcript without it fails instead of passing. Without the call, a text heuristic reports warnings only; pass --warnings-fail to make those warnings fail the gate too
• python3 scripts/bot_cost_estimator.py --pricing rates.json --model <name> --avg-turns 8 — Per-conversation cost estimator. Ships no prices: copy assets/pricing-template.json, fill in rates from each provider's pricing page, and pass it with --pricing; without it the script exits 2 and prints no estimate. It also accepts the dated price file of ops-cost-optimization's cost_estimator.py (checked date plus models with input_per_1m/output_per_1m and optional cache rates), so one file can feed both the per-call and the per-conversation estimate
• python3 scripts/red_team_pack.py --input responses.jsonl — Prompt-injection, PII-leak, and jailbreak detection against bot responses

Data

• data/sources.json — Curated external sources

Related Skills

• ../ai-agents/SKILL.md — Agent architecture and build-vs-not decisions
• ../ai-voice-bots/SKILL.md — Voice pipeline engineering (STT/TTS, telephony)
• ../ai-rag/SKILL.md — Retrieval and grounding for KB-powered bots
• ../ai-context-layer/SKILL.md — User profiles, memory, context assembly
• ../ai-context-layer/references/conversational-surfaces-cross-platform.md — Cross-platform composition recipe: how a Telegram/Discord/WhatsApp/Slack bot composer relates to iOS/Android/web composers via a shared EvidenceBundle and typed answer contract; LangGraph + Mem0 baseline; with-model and without-model paths
• ../ai-prompt-engineering/SKILL.md — System prompts and structured outputs
• ../agents-mcp/SKILL.md — MCP tool integration
• ../agents-subagents/SKILL.md — Specialist sub-bot delegation
• ../agents-hooks/SKILL.md — Bot safety hooks and guardrails
• ../software-ai-integration/SKILL.md — Chat UI, streaming, multi-provider routing
• ../software-backend/SKILL.md — FastAPI serving patterns
• ../software-realtime/SKILL.md — WebSocket/SSE transport
• ../qa-agent-testing/SKILL.md — Eval harnesses and regression packs
• ../product-help-center/SKILL.md — Help center design for bot grounding

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.