senior-prompt-engineer

Senior Prompt Engineer

Repo-adapted prompt and agent design guidance for blu-mono.

This skill is tuned to the prompt and agent architecture that actually exists in this monorepo:

• Single prompt entry point: build_prompt(name, variables) from blu_prompt_management — compose_prompt is REMOVED, do not use it
• Langfuse-first prompt management with production labels and builtin fallback in templates.py
• LangGraph agents built via AgentBuilder in libs/blu_agent_framework
• Layer 4 Orchestrator (use_orchestrator_graph) — decomposes multi-step requests, routes to L3 specialists
• Layer 3 domain agents registered in AgentTypeRegistry (registry.py) — always use prompt_name, never fragments
• Layer 2 ephemeral skills registered in SKILL_REGISTRY (skills.py), executed by SkillFactory
• UnifiedAgentFactory in services/agent_api — session-scoped agent assembly
• Supervisor fan-out in libs/blu_agent_framework/supervisor.py — _WorkerInvoker._get_prompt() injects schema/KB context from BluClientContext
• Context assembly through ContextService (libs/blu_context_service)
• Tool execution via MCP protocol against services/tool_pool_api
• Dynamic context injection via VariableExtractor in libs/blu_prompt_management/src/blu_prompt_management/variables.py

Use this skill when you are:

• designing or refactoring system prompts, skill prompts, or tool prompts
• adding or changing AgentTypeConfig or SkillDefinition
• evaluating prompt quality for SQL, RAG, reporting, or procurement flows
• wiring new context variables from ContextService or BluClientContext into prompt assembly
• deciding whether logic belongs in prompts, graph nodes, tool contracts, or context assembly
• pushing new prompts to Langfuse or auditing the production label state

---

Architecture Layers

Layer	What it is	Config	Prompt
L4 — Orchestrator	Meta-agent: parse_intent → decompose → plan → execute_step → synthesize	use_orchestrator_graph() in builder.py	orchestrator/* in Langfuse
L3 — Domain Specialist	Stateful LangGraph agent, Redis checkpointer, fan-out worker	AgentTypeConfig in registry.py	agents/<slug> in Langfuse
L2 — Skill	Ephemeral sub-agent, no checkpointer, tool subset	SkillDefinition in skills.py	skill:<name>:system in Langfuse
Supervisor	Routes to domain agents via delegation tools	route_after_supervisor in supervisor.py	fragment/supervisor-role in Langfuse
Tool prompts	Internal LLM calls inside tools (tool_pool_api)	n/a	tool/<name> — builtins only

---

Tech Stack

Language: Python Agent runtime: LangGraph + blu_agent_framework Prompt management: Langfuse + blu_prompt_management — build_prompt only Context layer: blu_context_service — Redis cache + Supabase (sql_table_config, agent_sessions) Variable extraction: VariableExtractor in blu_prompt_management/variables.py — renders sql_schema_context and kb_context from BluClientContext Observability: Langfuse traces Tool execution: MCP protocol → tool_pool_api Primary services: agent_api (frontdesk + standalone + supervisor), tool_pool_api (tools)

---

Key File Locations

Prompt loading

libs/blu_prompt_management/src/blu_prompt_management/
  __init__.py          — exports build_prompt() — THE ONLY prompt entry point
  loader.py            — PromptLoader: Langfuse-first with builtin fallback + circuit breaker
  templates.py         — BUILTIN_TEMPLATES dict: all builtin PromptTemplateConfig entries
  variables.py         — VariableExtractor: render_sql_schema(), render_kb_context()
                         PromptVariables: sql_schema_context, kb_context fields
  prompts/             — source .md files pushed to Langfuse at deploy
    orchestrator/      — L4 orchestrator prompts (parse-intent, decompose, plan, synthesize)
    specialists/       — agents/<slug> prompts (L3 specialists)
    skills/            — skill:<name>:system prompt fallbacks
    fragment/          — shared fragments (supervisor-role, sql-schema, context-gatherer-*)
    tool/              — internal tool LLM call prompts

Agent and skill registry

libs/blu_agent_framework/src/blu_agent_framework/
  registry.py          — AgentTypeConfig + AgentTypeRegistry (Layer 3)
  skills.py            — SkillDefinition + SKILL_REGISTRY (Layer 2)
  skill_factory.py     — SkillFactory runtime
  builder.py           — AgentBuilder fluent API; execute_worker_node_impl passes client_context
  nodes.py             — NodeRegistry decorator pattern
  state.py             — AgentState TypedDict; key fields: client_context, nome_empresa, tier
  supervisor.py        — _WorkerInvoker: invoke() + _get_prompt() with VariableExtractor
  orchestrator.py      — make_execute_step_node(): passes client_context to _WorkerInvoker

Tool registry

libs/blu_tool_registry/src/blu_tool_registry/
  registry.py          — BUILTIN_TOOLS + ToolMetadata (name, category, tier_required, tags)

Factory (session-scoped agent assembly)

services/agent_api/src/agent_api/core/factory.py   — UnifiedAgentFactory
  get_frontdesk_graph(tier, ctx_service)  — Frontdesk graph cached per tier; uses use_default_graph()
  get_supervisor_graph(tier, ctx_service) — Supervisor fan-out graph cached per tier; uses use_supervisor_graph()
  build_frontdesk_prompt(nome_empresa, ctx_service, client_context)
                                          — Builds agents/frontdesk prompt; variables: nome_empresa,
                                            tools_description, company_profile, schema_description
  get_standalone_agent(session_id, client_id, agent_catalog_id)
                                          — Per-session compiled graph from agent_catalog table

BuiltAgent contains graph + system_prompt + client_context + metadata.

Context service

libs/blu_context_service/src/blu_context_service/
  context_service.py   — ContextService: get_client_context_by_id(), get_sql_table_configs()
                         Returns BluClientContext with data_schema.table_schemas

Prompt management scripts

scripts/audit_langfuse_prompts.py        — audit production labels across all prompts
scripts/verify_standalone_prompts.py     — verify prompt compilation
scripts/create_supervisor_prompts.py     — seed supervisor fragments in Langfuse
scripts/create_analytics_prompts.py      — seed SQL/analytics fragments in Langfuse
scripts/create_rfq_prompts.py            — seed RFQ fragments in Langfuse

---

Prompt Loading Resolution

Managed prefixes (Langfuse-first)

These prefixes try Langfuse (label=production, cache_ttl=300s, circuit breaker on connection errors) and fall back to BUILTIN_TEMPLATES:

orchestrator/    → orchestrator/*.md source files
agents/          → specialists/*.md source files
skill:           → skills/<name>/system.md source files

Non-managed (builtins only — skip Langfuse)

fragment/*       → BUILTIN_TEMPLATES only (no Langfuse lookup)
classify/*       → BUILTIN_TEMPLATES only
tool/*           → BUILTIN_TEMPLATES only
atendente/*      → BUILTIN_TEMPLATES only

Critical: fragment/* prompts pushed to Langfuse (supervisor-role, sql-schema, context-gatherer-*) are NOT loaded via build_prompt. They are stored in Langfuse for reference and content management but loaded as builtins at runtime. Only orchestrator/, agents/, and skill: prefixes trigger Langfuse lookups.

---

AgentBuilder Graph Topologies

AgentBuilder is a fluent API in libs/blu_agent_framework/src/blu_agent_framework/builder.py. Choose the topology that matches the layer:

Method	Layer	When to use
use_default_graph()	L3 / standalone	Default ReAct loop: init → classify_intent → context_enrichment → elicit/respond/select_skill/run_skill
use_specialist_graph(cfg)	L3	Specialist invoked by orchestrator; adds classify_skill_intent node that selects from SKILL_REGISTRY filtered by cfg.tags
use_fanout_graph()	L3	Parallel tool fan-out via Send; use when a single request spawns independent tool calls
use_supervisor_graph(tier)	Frontdesk/supervisor	Supervisor LLM routes via delegate_to_* tools; workers run as fan-out parallel loops
use_orchestrator_graph(tier)	L4	Meta-skill: parse_intent → gather_context → decompose → plan → execute_step (loops) → synthesize
use_skill_graph()	L2	Minimal: START → respond ↔ execute_tool → END; no init/classify; used by SkillFactory._build_skill_graph()
use_custom_graph(graph_def)	standalone	Compiled from agent_catalog.workflow_graph JSON; used for catalog-driven agent definitions

---

Content truncated.